@mmerterden/multi-agent-pipeline 20.33.0 → 20.35.0

package/install/templates/claude-hooks.json

@@ -1,5 +1,5 @@
 {
-  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. `install` registers the pre-commit and agent-guard gates, the run-scoped run-stop-guard / run-scope-guard hooks and the task-mirror hook itself (install/claude.mjs configureSettings, RUN_HOOKS); /multi-agent:setup offers to merge the rest of this block. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic PreToolUse gates real (exit 2 blocks the tool call). A PreToolUse matcher is a regex over the TOOL NAME, so each gate registers on a tool name and reads the command from its stdin payload. Three PreToolUse gates ship here: (1) pre-commit-check.sh on Bash, which acts only on a `git commit` and blocks a secret in the staged diff; (2) agent-guard.sh on Bash, on Edit|Write|NotebookEdit, and on WebFetch plus every multi-agent-toolkit tool (WebFetch|mcp__multi-agent-toolkit__.*). Always, it blocks AI/assistant attribution in a commit message and a force-push, delete or mirror push to a protected branch (main/master/develop), including one inside a subshell or a `bash -c` / `eval` line. With MULTI_AGENT_UNATTENDED=1 in the hook's environment it also applies the unattended policy: no push, PR or tracker write, no Keychain read, no fetch outside the host allowlist (curl, WebFetch, the toolkit's web tools, agent_run_steps and open_url), no package install, and no write into a protected path (features/unattended-security.md); (3) check-read-size.sh on Read|Bash, which inspects Read plus the shell commands that read a file whole (cat/head/tail/sed), returns immediately for everything else, and routes an oversized read to a cheap worker instead of the caller's own rung; it is inert until `prefs.global.bulkRead.mode` is set to observe or enforce. Failure behaviour: pre-commit-check.sh and check-read-size.sh fail open on an internal error. agent-guard.sh fails open when attended, so a guard bug cannot break a legitimate tool call, and fails closed under MULTI_AGENT_UNATTENDED=1, where nobody is there to notice a gap. None of the three executes the inspected command, and none needs run-specific arguments. The other deterministic gates (evidence, consensus, intent, learnings) take run-specific arguments and are phase-enforced by the pipeline instead. Three capture hooks ship alongside them and block nothing: (4) SessionEnd runs capture-flush.sh --if-stale, which writes a run's triage findings and durable learnings into the per-repo stores when the run ended before Phase 5, where those writes otherwise happen; the same hook runs note-session.sh, which records the mechanical shape of a session outside the pipeline (tools used, commands that failed, calls the user refused). (5) PreCompact runs capture-flush.sh without --if-stale: a compaction summarizes the conversation mid-phase, so it is the moment unflushed findings are at risk, and both writes are idempotent, so a finished run costs two no-op writes. The staleness test exists only so a session exit does not re-flush a run that already finished. (6) SessionStart runs capture-resume.sh, which prints at most two lines: an unfinished run and how to resume it, and a stale pipeline-observation queue. No capture hook calls a model or reads a payload - note-session.sh keeps a command's first word and an exit code, never an argument or any output - and all exit 0 on every path, because a hook that fails a session over bookkeeping costs more than the bookkeeping. A run-scoped PreToolUse gate ships too: (2b) run-scope-guard.sh on every Figma MCP tool (mcp__.*[Ff]igma.*) denies a Figma call above phases.json thresholds.mcpAllowedThroughPhase for the run bound to the session, unless the run is in analysis mode, and records each allowed call into telemetry.mcpCalls[]; on Edit|Write|NotebookEdit the same script warns, attended only, when the target is outside the bound run's worktree (additionalContext for the model, systemMessage for the user; the call proceeds). Outside a run it is silent, and it fails open. One PostToolUse hook ships as well and blocks nothing: (7) edit-syntax-gate.sh on Edit|Write|MultiEdit parses the file the edit just wrote (swiftc -parse, node --check, py_compile into a temp dir, JSON.parse, bash -n; Kotlin skipped) under a 2 s deadline and, when it no longer parses, hands the model the error as PostToolUse additionalContext; it exits 0 on every path, stays silent when a parser is missing or slow, and is inert until `prefs.global.editSyntaxGate.enabled` is true. A second PostToolUse hook blocks nothing either: (7b) task-mirror.sh on TaskCreate|TaskUpdate mirrors the native task list into the tracker of the run bound to the session (phase-tracker.sh task, tracker-contract.md, \"Mirroring the host's task list\"), skipping phase tiles, so the office panel shows the same list; silent outside a run, exit 0 on every path. One Stop hook ships as well: (8) run-stop-guard.sh answers {\"decision\":\"block\"} when the session driving an active pipeline run (bound through agent-state.json sessionId or hostSessionId, never by a worktree match) tries to stop while the run is in_progress below its mode's last phase with no haltReason or waitingFor; the reason says to finish the current phase, record the wait, or record a halt. A turn that ends on a question to the user, a session with background tasks or crons, and prefs.global.stopGuard.enabled false are never held, and SubagentStop is not registered: a subagent's stop is the dispatching session's business. After three consecutive blocks it records the halt itself (status paused, haltReason <phase>:stop-guard), which write-state clears when the run advances a phase. It never blocks outside a run and fails open, with a line in <log root>/hook-failures.log, on any error. These registrations are Claude Code's; README \"Hooks per host\" lists which have no equivalent elsewhere. On Codex only the syntax gate is offered, from codex-hooks.json through host-hooks.mjs; Copilot CLI gets none, since as of 1.0.45 it discards postToolUse output; the other gates are Claude Code only. multi-agent:setup offers to merge this block.",
+  "_readme": "Recommended Claude Code hooks for multi-agent-pipeline. `install` registers the pre-commit and agent-guard gates, the run-scoped run-stop-guard / run-scope-guard hooks, the task-mirror hook and the file-context hook itself (install/claude.mjs configureSettings, RUN_HOOKS); /multi-agent:setup offers to merge the rest of this block. Merge the `hooks` object into your ~/.claude/settings.json to make these deterministic PreToolUse gates real (exit 2 blocks the tool call). A PreToolUse matcher is a regex over the TOOL NAME, so each gate registers on a tool name and reads the command from its stdin payload. Three PreToolUse gates ship here: (1) pre-commit-check.sh on Bash, which acts only on a `git commit` and blocks a secret in the staged diff; (2) agent-guard.sh on Bash, on Edit|Write|NotebookEdit, and on WebFetch plus every multi-agent-toolkit tool (WebFetch|mcp__multi-agent-toolkit__.*). Always, it blocks AI/assistant attribution in a commit message and a force-push, delete or mirror push to a protected branch (main/master/develop), including one inside a subshell or a `bash -c` / `eval` line. With MULTI_AGENT_UNATTENDED=1 in the hook's environment it also applies the unattended policy: no push, PR or tracker write, no Keychain read, no fetch outside the host allowlist (curl, WebFetch, the toolkit's web tools, agent_run_steps and open_url), no package install, and no write into a protected path (features/unattended-security.md); (3) check-read-size.sh on Read|Bash, which inspects Read plus the shell commands that read a file whole (cat/head/tail/sed), returns immediately for everything else, and routes an oversized read to a cheap worker instead of the caller's own rung; it is inert until `prefs.global.bulkRead.mode` is set to observe or enforce. Failure behaviour: pre-commit-check.sh and check-read-size.sh fail open on an internal error. agent-guard.sh fails open when attended, so a guard bug cannot break a legitimate tool call, and fails closed under MULTI_AGENT_UNATTENDED=1, where nobody is there to notice a gap. None of the three executes the inspected command, and none needs run-specific arguments. The other deterministic gates (evidence, consensus, intent, learnings) take run-specific arguments and are phase-enforced by the pipeline instead. Three capture hooks ship alongside them and block nothing: (4) SessionEnd runs capture-flush.sh --if-stale, which writes a run's triage findings and durable learnings into the per-repo stores when the run ended before Phase 5, where those writes otherwise happen; the same hook runs note-session.sh, which records the mechanical shape of a session outside the pipeline (tools used, commands that failed, calls the user refused). (5) PreCompact runs capture-flush.sh without --if-stale: a compaction summarizes the conversation mid-phase, so it is the moment unflushed findings are at risk, and both writes are idempotent, so a finished run costs two no-op writes. The staleness test exists only so a session exit does not re-flush a run that already finished. (6) SessionStart runs capture-resume.sh, which prints at most two lines: an unfinished run and how to resume it, and a stale pipeline-observation queue. No capture hook calls a model or reads a payload - note-session.sh keeps a command's first word and an exit code, never an argument or any output - and all exit 0 on every path, because a hook that fails a session over bookkeeping costs more than the bookkeeping. A run-scoped PreToolUse gate ships too: (2b) run-scope-guard.sh on every Figma MCP tool (mcp__.*[Ff]igma.*) denies a Figma call above phases.json thresholds.mcpAllowedThroughPhase for the run bound to the session, unless the run is in analysis mode, and records each allowed call into telemetry.mcpCalls[]; on Edit|Write|NotebookEdit the same script warns, attended only, when the target is outside the bound run's worktree (additionalContext for the model, systemMessage for the user; the call proceeds). On Bash|WebFetch|AskUserQuestion it denies a question from a bound autopilot run, a Figma read over HTTP (figma.com or api.figma.com) under the same phase rule, and, in any session, a direct write to agent-state.json or tracker-state.json (Edit/Write, a shell redirect or tee), since write-state.mjs is their only writer; the shell wrapper starts node only when the payload mentions Figma or a state file. Outside a run it is silent, and it fails open. One PostToolUse hook ships as well and blocks nothing: (7) edit-syntax-gate.sh on Edit|Write|MultiEdit parses the file the edit just wrote (swiftc -parse, node --check, py_compile into a temp dir, JSON.parse, bash -n; Kotlin skipped) under a 2 s deadline and, when it no longer parses, hands the model the error as PostToolUse additionalContext; it exits 0 on every path, stays silent when a parser is missing or slow, and is inert until `prefs.global.editSyntaxGate.enabled` is true. A second PostToolUse hook blocks nothing either: (7b) task-mirror.sh on TaskCreate|TaskUpdate mirrors the native task list into the tracker of the run bound to the session (phase-tracker.sh task, tracker-contract.md, \"Mirroring the host's task list\"), skipping phase tiles, so the office panel shows the same list; silent outside a run, exit 0 on every path. A third blocks nothing: (7c) file-context.sh on Read hands the model, once per file per session, what the repo's memory says about the file it just read (ledger facts whose scope covers it, its latest review findings, its open known limits from debt-ledger.mjs) as PostToolUse additionalContext inside an <untrusted-data> block, after the secret scan; inside a run bound to the session by default, everywhere with prefs.global.fileContext.enabled true, never with it false; exit 0 on every path. A fourth blocks nothing: (7d) answer-check.sh on AskUserQuestion names, as PostToolUse additionalContext, every question the user submitted without a choice, so an empty answer is asked again instead of resolved to the Recommended option; it runs in every session, since it only adds context, and exits 0 on every path. One Stop hook ships as well: (8) run-stop-guard.sh answers {\"decision\":\"block\"} when the session driving an active pipeline run (bound through agent-state.json sessionId or hostSessionId, never by a worktree match) tries to stop while the run is in_progress below its mode's last phase with no haltReason or waitingFor; the reason says to finish the current phase, record the wait, or record a halt. A turn that ends on a question to the user, a session with background tasks or crons, and prefs.global.stopGuard.enabled false are never held, and SubagentStop is not registered: a subagent's stop is the dispatching session's business. After three consecutive blocks it records the halt itself (status paused, haltReason <phase>:stop-guard), which write-state clears when the run advances a phase. It never blocks outside a run and fails open, with a line in <log root>/hook-failures.log, on any error. These registrations are Claude Code's; README \"Hooks per host\" lists which have no equivalent elsewhere. On Codex only the syntax gate is offered, from codex-hooks.json through host-hooks.mjs; Copilot CLI gets none, since as of 1.0.45 it discards postToolUse output; the other gates are Claude Code only. multi-agent:setup offers to merge this block.",
   "hooks": {
     "PreToolUse": [
       {
@@ -47,6 +47,17 @@
           }
         ]
       },
+      {
+        "matcher": "Bash|WebFetch|AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$HOME/.claude/scripts/run-scope-guard.sh\"",
+            "timeout": 10,
+            "statusMessage": "Checking the call against the run's phase and state file..."
+          }
+        ]
+      },
       {
         "matcher": "Read|Bash",
         "hooks": [
@@ -92,6 +103,28 @@
             "statusMessage": "Mirroring the task list into the run tracker..."
           }
         ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$HOME/.claude/scripts/answer-check.sh\"",
+            "timeout": 10,
+            "statusMessage": "Checking every question got an answer..."
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$HOME/.claude/scripts/file-context.sh\"",
+            "timeout": 10,
+            "statusMessage": "Looking up what the repo's memory says about this file..."
+          }
+        ]
       }
     ],
     "PreCompact": [