MLD-1307 - Auto-run plugin mcp.json align

[arielamitjfrog]

Summary

Wire Claude Code SessionStart / FileChanged hooks so installed-plugin .mcp.json files are auto-aligned through @jfrog/agent-guard --align-plugin-mcps.

• claude-align-plugin-mcps.mjs - Claude adapter: spawn npx @jfrog/agent-guard --align-plugin-mcps --format hook-session-start|hook-file-changed, passthrough stdout (watchPaths / systemMessage / additionalContext owned by agent-guard), never fail the session.
• claude-register-align-watch-paths.mjs - fast SessionStart companion: emit FileChanged watchPaths for installed_plugins.json / known_marketplaces.json before the slower npx align finishes, so mid-session plugin installs are watched while Agent Guard is still downloading.
• hooks/hooks.json - register both on SessionStart; re-run align on FileChanged when those metadata files change.
  Discovery + rewrite stay in agent-guard (--align-plugin-mcps). This PR only owns Claude hook UX, env forwarding, soft-fail, and early watchPath registration.

Goal

• Auto-run plugin MCP align on every Claude session start.
• Re-align when Claude plugin install metadata changes mid-session.
• Keep the session usable even if npx / agent-guard fails (exit 0 always; SessionStart still registers watchPaths).
• Share kill switch + registry / project / config-dir forwarding with agent-guard.

Assumptions

This adapter does not rewrite mcp.json itself and does not invent Claude hook payload shapes. Agent Guard owns discovery, transform, and hook stdout. The Claude plugin must:

• Invoke npx --yes --registry <...> @jfrog/agent-guard --align-plugin-mcps --format hook-...
• Forward optional JF_PROJECT -> --project, CLAUDE_CONFIG_DIR -> --claude-config-dir, JFROG_AGENT_GUARD_REPO -> npx registry + agent-guard --registry
• Soft-fail: never exit non-zero; on SessionStart failure / empty stdout, still emit fallback watchPaths
• Honor JF_AGENT_ALIGN_PLUGIN_MCPS_DISABLE=1 (no-op, no stdout)
  Remote MCP entries remain agent-guard's concern (never rewritten there).

Happy flow

SessionStart:

1. claude-register-align-watch-paths.mjs prints Claude SessionStart JSON with watchPaths for ~/.claude/plugins/installed_plugins.json and known_marketplaces.json (or $CLAUDE_CONFIG_DIR/plugins/...).
2. claude-align-plugin-mcps.mjs session-start runs agent-guard with --format hook-session-start.
3. Agent-guard discovers installed-plugin .mcp.json paths, rewrites stdio MCPs to launch via Agent Guard, and prints Claude hook stdout (watchPaths + optional reload guidance).
4. Adapter passthroughs that stdout unchanged.

FileChanged (matcher: installed_plugins.json|known_marketplaces.json):

1. claude-align-plugin-mcps.mjs file-changed runs with --format hook-file-changed.
2. Same rewrite core; stdout passthrough.

Idempotency / drift (owned by agent-guard; adapter just re-invokes):

• Re-run with the same args -> rewritten: 0 (idempotent).
• Change project/registry/server -> rewrite again (drift).

Kill switch:
JF_AGENT_ALIGN_PLUGIN_MCPS_DISABLE=1 -> both hooks exit 0 with no stdout / no spawn.

Non-happy flows

Expected behavior / exit (adapter always exit 0):

• Kill switch set -> no spawn, no stdout (exit 0).
• Unknown mode arg -> no-op, no spawn (exit 0).
• agent-guard / npx fails on SessionStart -> log error; emit fallback watchPaths so FileChanged still works (exit 0).
• agent-guard exits 0 but empty SessionStart stdout -> emit fallback watchPaths (exit 0).
• agent-guard / npx fails on FileChanged -> log error; write nothing (exit 0).
• Missing JF_PROJECT -> still invoke agent-guard (no --project); agent-guard decides whether project is required for rewrite (exit 0).
• Private registry via JFROG_AGENT_GUARD_REPO -> used for both npx --registry and agent-guard --registry.

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[arielamitjfrog]

I have read the CLA Document and I hereby sign the CLA