@orchestrator-claude/definitions 3.32.2 → 3.33.0

package/hooks/workflow-guard.ts

@@ -4,22 +4,39 @@
  *
  * Blocks writes to src/ and tests/ without active workflow.
  *
- * Allow paths (in evaluation order):
+ * RFC-040 TD-204 §⑤-A (S366): Classe-A asset-safety gate, made
+ * "cwd-scoped-safe" — resolves the OWNING project of the write TARGET
+ * (file_path), not the session's cwd (per TD-204 §"cwd não some, rebaixa":
+ * "o guard Classe-A ainda resolve file_path -> projeto pra autorizar cada
+ * Write contra o projeto selecionado"). Today, in this repo (a registered
+ * project with an `.orchestrator` sentinel), targetProjectRoot always
+ * resolves non-null, so every write still falls through to the pre-existing
+ * mode/sub-agent logic (rules 6/7 below) — byte-equivalent to pre-⑤-A
+ * behavior. The two NEW branches (4, 5) are dormant-but-tested until this
+ * hook is installed globally (future installer) against an unregistered or
+ * foreign (trc/red-bull) cwd, where they become load-bearing: a Classe-A
+ * gate NEVER no-ops silently on an unrecognized project path.
+ *
+ * Allow paths (in evaluation order — see decideWorkflowGuardAction):
  *   1. SKIP_WORKFLOW_GUARD=true (explicit bypass, all paths)
  *   2. Non-guarded path (file outside src/ or tests/)
  *   3. Config/doc file extension (.json|.yaml|.yml|.md|.env*)
- *   4. Active workflow + mode='quick' (main agent writes allowed by design)
- *   5. Active workflow + mode='interactive' (writes unexpected, but allowed)
- *   6. Active workflow + mode='direct' (ADR-017 Phase 3 — tracked via startDirectExecution)
- *   7. Active workflow + caller is sub-agent (agent_id present in stdin)
- *   8. Active workflow + SKIP_SUBAGENT_GUARD=true (DEPRECATED — ADR-013 §6.5.3, telemetered to observations.yaml)
+ *   4. [TD-204 ⑤-A] `.orchestrator/.unmanaged` sentinel present at the
+ *      target's resolved project root — explicit, auditable opt-out.
+ *   5. [TD-204 ⑤-A, deny] target path resolves to NO registered project
+ *      (targetProjectRoot === null) — instructs registration or the
+ *      `.unmanaged` opt-out. NEVER a silent no-op.
+ *   6. Active workflow + mode='quick'|'interactive'|'direct', or caller is
+ *      a sub-agent (agent_id present), or SKIP_SUBAGENT_GUARD=true
+ *      (DEPRECATED — ADR-013 §6.5.3, telemetered to observations.yaml)
  * Deny paths:
- *   - Active workflow + standard/full/legacy mode + main agent direct write (no agent_id, no bypass)
- *   - No active workflow
+ *   - Active workflow + standard/full/legacy mode + main agent direct write
+ *     (no agent_id, no bypass)
+ *   - No active workflow (target project IS registered)
  */
 
-import { join } from 'node:path';
-
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
 import {
   log,
   readStdin,
@@ -27,153 +44,377 @@ import {
   getActiveWorkflow,
   getWorkflowMode,
   outputPreToolUse,
+  resolveAgentMemoryBaseDir,
+  resolveHookProjectRoot,
 } from './lib/api-client.js';
 import { appendObservation } from './lib/observations-helper.js';
 
 const HOOK = 'WORKFLOW-GUARD';
 
-async function main(): Promise<void> {
-  const stdin = await readStdin();
-  const filePath =
-    getField(stdin, 'tool_input.file_path') ||
-    getField(stdin, 'file_path') ||
-    getField(stdin, 'input.file_path');
+// ---------------------------------------------------------------------------
+// TD-204 ⑤-A: cwd-scoped-safe block-decision (pure, unit-testable)
+// Mirrors the TD-203 dangling-guard.ts pattern: decideWorkflowGuardAction()
+// takes ONLY injected inputs (zero fs/API), main() gathers signals and
+// delegates.
+// ---------------------------------------------------------------------------
 
-  log(HOOK, `file_path=${filePath}`);
+export type WorkflowGuardAction = 'allow' | 'deny';
+
+export interface WorkflowGuardOutput {
+  decision: WorkflowGuardAction;
+  reason?: string;
+  context?: string;
+}
+
+/** Mirrors ObservationEntry minus timestamp/session_id (added by main()). */
+export interface WorkflowGuardObservation {
+  phase: string;
+  workflow_id: string;
+  summary: string;
+  tags: string[];
+}
+
+export interface WorkflowGuardDecision {
+  /**
+   * 1-7, matches the numbered precedence in TD-204 ⑤-A. Rule 6 covers every
+   * "active workflow" sub-branch (quick/interactive/direct/sub-agent/
+   * SKIP_SUBAGENT_GUARD/main-agent-deny) — they all require a REAL fetched
+   * workflow to distinguish, unlike rule 7 (no active workflow) which a
+   * `workflow: null` trial call can already prove correctly. main() uses
+   * `matchedRule === 7` as the sole signal for whether the (network) active
+   * workflow must actually be fetched to confirm the decision — see main().
+   */
+  matchedRule: 1 | 2 | 3 | 4 | 5 | 6 | 7;
+  /** Whether outputPreToolUse must be called. Rules 2/3 are silent pass-throughs (pre-existing behavior — no hookSpecificOutput emitted). */
+  emitOutput: boolean;
+  output?: WorkflowGuardOutput;
+  logMessages: string[];
+  observation?: WorkflowGuardObservation;
+}
+
+export interface WorkflowGuardWorkflowInput {
+  id: string;
+  /** getWorkflowMode() result: executionMode ?? mode ?? null. */
+  mode: string | null;
+  /** WorkflowStatus.currentPhase — required upstream, defensively `|| 'unknown'` at use-site (mirrors pre-⑤-A code). */
+  currentPhase: string;
+}
+
+export interface WorkflowGuardDecisionInput {
+  filePath: string;
+  skipWorkflowGuard: boolean;
+  skipSubagentGuard: boolean;
+  /**
+   * TD-204 ⑤-A: resolved via resolveHookProjectRoot(dirname(filePath)) — the
+   * file_path's OWNING project root, NOT the session's cwd. `null` means the
+   * write target does not belong to any project with an `.orchestrator`
+   * sentinel in its ancestry.
+   */
+  targetProjectRoot: string | null;
+  /**
+   * True iff `<targetProjectRoot>/.orchestrator/.unmanaged` exists (explicit,
+   * auditable opt-out sentinel, TD-204 ⑤-A). Always false when
+   * targetProjectRoot is null (the marker itself lives inside `.orchestrator`,
+   * so a null root implies no `.orchestrator` dir was found at all).
+   */
+  isUnmanaged: boolean;
+  /**
+   * `null` covers BOTH "genuinely no active workflow" and "not yet fetched"
+   * (see WorkflowGuardDecision.matchedRule doc — main() distinguishes the two
+   * via a cheap trial call before paying for the network fetch).
+   */
+  workflow: WorkflowGuardWorkflowInput | null;
+  /** getField(stdin, 'agent_id') — empty string when absent (never fetched over network). */
+  agentId: string;
+  /** getField(stdin, 'agent_type') — empty string when absent. */
+  agentType: string;
+}
+
+const CONFIG_DOC_RE = /\.(json|ya?ml|md|env(\..*)?)$/;
+
+/**
+ * Pure decision function for the workflow-guard PreToolUse[Write|Edit] hook
+ * (TD-204 ⑤-A). Evaluates precedence rules 1-7 top-down, first match wins.
+ * Takes only injected inputs — no fs/API calls — so every branch is
+ * independently testable and deterministic.
+ */
+export function decideWorkflowGuardAction(
+  input: WorkflowGuardDecisionInput
+): WorkflowGuardDecision {
+  const {
+    filePath,
+    skipWorkflowGuard,
+    skipSubagentGuard,
+    targetProjectRoot,
+    isUnmanaged,
+    workflow,
+    agentId,
+    agentType,
+  } = input;
 
-  // Explicit bypass
-  if (process.env.SKIP_WORKFLOW_GUARD === 'true') {
-    log(HOOK, 'ALLOW (SKIP_WORKFLOW_GUARD=true)');
-    outputPreToolUse({
-      decision: 'allow',
-      context: 'Workflow guard bypassed via SKIP_WORKFLOW_GUARD=true.',
-    });
-    return;
+  // Rule 1: explicit global bypass
+  if (skipWorkflowGuard) {
+    return {
+      matchedRule: 1,
+      emitOutput: true,
+      output: {
+        decision: 'allow',
+        context: 'Workflow guard bypassed via SKIP_WORKFLOW_GUARD=true.',
+      },
+      logMessages: ['ALLOW (SKIP_WORKFLOW_GUARD=true)'],
+    };
   }
 
-  // Only guard src/ and tests/ paths
+  // Rule 2: non-guarded path (outside src/ or tests/) — silent pass-through
   if (!filePath.includes('/src/') && !filePath.includes('/tests/')) {
-    log(HOOK, 'ALLOW (non-guarded path)');
-    return;
+    return { matchedRule: 2, emitOutput: false, logMessages: ['ALLOW (non-guarded path)'] };
+  }
+
+  // Rule 3: config/doc file extension — silent pass-through
+  if (CONFIG_DOC_RE.test(filePath)) {
+    return { matchedRule: 3, emitOutput: false, logMessages: ['ALLOW (config/doc file)'] };
   }
 
-  // Allow config/doc files
-  if (/\.(json|ya?ml|md|env(\..*)?)$/.test(filePath)) {
-    log(HOOK, 'ALLOW (config/doc file)');
-    return;
+  // Rule 4 [TD-204 ⑤-A]: explicit, auditable unmanaged opt-out sentinel
+  if (isUnmanaged) {
+    return {
+      matchedRule: 4,
+      emitOutput: true,
+      output: {
+        decision: 'allow',
+        context: `Workflow guard bypassed via .orchestrator/.unmanaged sentinel at ${String(targetProjectRoot)}. Explicit, auditable opt-out (RFC-040 TD-204 Classe-A asset-safety gate).`,
+      },
+      logMessages: [`ALLOW (.orchestrator/.unmanaged sentinel at ${String(targetProjectRoot)})`],
+    };
   }
 
-  // Check for active workflow
-  const workflow = await getActiveWorkflow();
+  // Rule 5 [TD-204 ⑤-A, deny]: write target does not belong to ANY registered
+  // project. Branches the block message ("não-registrado") — NEVER a silent
+  // no-op, per TD-204's Classe-A contract.
+  if (targetProjectRoot === null) {
+    return {
+      matchedRule: 5,
+      emitOutput: true,
+      output: {
+        decision: 'deny',
+        reason:
+          'Workflow Guard: target path does not belong to any registered project (no .orchestrator sentinel found).',
+        context: [
+          `The file ${filePath} is outside any project registered with the Orchestrator — no .orchestrator sentinel was found walking up from its directory.`,
+          '',
+          'You MUST either:',
+          "  1. Register this project: mcp__orchestrator-tools__registerProject({ rootPath: '<project-root>', ... }) — see the registration runbook, or",
+          "  2. Mark it explicitly unmanaged (opt out of this guard): create an empty file at '<project-root>/.orchestrator/.unmanaged'.",
+          '',
+          'The workflow-guard hook NEVER no-ops silently on an unrecognized project path (RFC-040 TD-204 Classe-A asset-safety gate).',
+        ].join('\n'),
+      },
+      logMessages: [`DENY (unregistered target path, file=${filePath})`],
+    };
+  }
 
+  // Rules 6/7: from here on, targetProjectRoot is a REGISTERED project —
+  // behavior is byte-equivalent to pre-⑤-A workflow-guard.ts.
   if (workflow) {
-    const mode = await getWorkflowMode(workflow.id);
-    log(HOOK, `workflow=${workflow.id} mode=${mode || 'legacy'}`);
+    const mode = workflow.mode;
+    const modeLogLine = `workflow=${workflow.id} mode=${mode || 'legacy'}`;
 
+    // Rule 6a: mode='quick' — main agent writes allowed by design
     if (mode === 'quick') {
-      outputPreToolUse({
-        decision: 'allow',
-        context: `Active workflow: ${workflow.id} (mode: quick). Direct writes allowed in quick mode.`,
-      });
-      return;
+      return {
+        matchedRule: 6,
+        emitOutput: true,
+        output: {
+          decision: 'allow',
+          context: `Active workflow: ${workflow.id} (mode: quick). Direct writes allowed in quick mode.`,
+        },
+        logMessages: [modeLogLine],
+      };
     }
 
+    // Rule 6b: mode='interactive' — writes unexpected, but allowed
     if (mode === 'interactive') {
-      outputPreToolUse({
-        decision: 'allow',
-        context: `Active workflow: ${workflow.id} (mode: interactive). Note: code writes are unexpected in interactive/analysis workflows.`,
-      });
-      return;
+      return {
+        matchedRule: 6,
+        emitOutput: true,
+        output: {
+          decision: 'allow',
+          context: `Active workflow: ${workflow.id} (mode: interactive). Note: code writes are unexpected in interactive/analysis workflows.`,
+        },
+        logMessages: [modeLogLine],
+      };
     }
 
-    // ADR-017 Phase 3: direct execution mode — main agent writes without sub-agent required
+    // Rule 6c: mode='direct' — ADR-017 Phase 3
     if (mode === 'direct') {
-      log(HOOK, `ALLOW (executionMode=direct, workflow: ${workflow.id})`);
-      outputPreToolUse({
-        decision: 'allow',
-        context: `Active workflow: ${workflow.id} (executionMode: direct). Direct writes allowed — record will be tracked via startDirectExecution/completeDirectExecution.`,
-      });
-      return;
+      return {
+        matchedRule: 6,
+        emitOutput: true,
+        output: {
+          decision: 'allow',
+          context: `Active workflow: ${workflow.id} (executionMode: direct). Direct writes allowed — record will be tracked via startDirectExecution/completeDirectExecution.`,
+        },
+        logMessages: [modeLogLine, `ALLOW (executionMode=direct, workflow: ${workflow.id})`],
+      };
     }
 
-    // Check if running inside a sub-agent
-    const agentId = getField(stdin, 'agent_id');
+    // Rule 6d: caller is a sub-agent (agent_id present in stdin)
     if (agentId) {
-      const agentType = getField(stdin, 'agent_type');
-      log(HOOK, `ALLOW (sub-agent: ${agentType || 'unknown'}, workflow: ${workflow.id})`);
-      outputPreToolUse({
-        decision: 'allow',
-        context: `Active workflow: ${workflow.id}. Sub-agent ${agentType || 'unknown'} write allowed.`,
-      });
-      return;
+      return {
+        matchedRule: 6,
+        emitOutput: true,
+        output: {
+          decision: 'allow',
+          context: `Active workflow: ${workflow.id}. Sub-agent ${agentType || 'unknown'} write allowed.`,
+        },
+        logMessages: [
+          modeLogLine,
+          `ALLOW (sub-agent: ${agentType || 'unknown'}, workflow: ${workflow.id})`,
+        ],
+      };
     }
 
-    // Main agent writing directly — check SKIP_SUBAGENT_GUARD
-    // DEPRECATED per ADR-013 §6.5.3 — preferred replacements are mode='quick'
-    // (single-phase, main-agent writes) or mode='direct' (ADR-017 Phase 3,
-    // multi-phase main-agent writes with startDirectExecution audit trail).
-    // Each bypass is recorded to .claude/agent-memory/main/observations.yaml
-    // (RFC-027 Sprint 3) so usage can be measured before full removal.
-    if (process.env.SKIP_SUBAGENT_GUARD === 'true') {
-      log(HOOK, `ALLOW (SKIP_SUBAGENT_GUARD=true, workflow: ${workflow.id}) [DEPRECATED]`);
-
-      // Fail-open observation for cross-session telemetry
-      try {
-        const sessionId =
-          getField(stdin, 'session_id') || getField(stdin, 'claude_session_id') || '';
-        const memoryBaseDir = join(process.cwd(), '.claude', 'agent-memory');
-        appendObservation(memoryBaseDir, 'main', {
-          timestamp: new Date().toISOString(),
-          session_id: sessionId,
+    // Rule 6e: main agent direct write, SKIP_SUBAGENT_GUARD=true (DEPRECATED,
+    // ADR-013 §6.5.3). Telemetered via an observation for cross-session usage
+    // review.
+    if (skipSubagentGuard) {
+      return {
+        matchedRule: 6,
+        emitOutput: true,
+        output: {
+          decision: 'allow',
+          context: [
+            `Active workflow: ${workflow.id}. Direct write allowed via SKIP_SUBAGENT_GUARD.`,
+            '',
+            '⚠️ DEPRECATED per ADR-013 §6.5.3. Prefer:',
+            "  • mode:'quick' (startWorkflow({ mode: 'quick' })) — single-phase, main-agent writes allowed by design",
+            "  • mode:'direct' (ADR-017 Phase 3) — multi-phase, main-agent writes with startDirectExecution audit trail",
+            'Bypass logged to .claude/agent-memory/main/observations.yaml for usage review (S200+ remediation decision).',
+          ].join('\n'),
+        },
+        logMessages: [
+          modeLogLine,
+          `ALLOW (SKIP_SUBAGENT_GUARD=true, workflow: ${workflow.id}) [DEPRECATED]`,
+        ],
+        observation: {
           phase: workflow.currentPhase || 'unknown',
           workflow_id: workflow.id,
           summary: `SKIP_SUBAGENT_GUARD bypass triggered. file=${filePath} mode=${mode || 'legacy'}. Prefer mode:'quick' or mode:'direct' (ADR-013 §6.5.3).`,
           tags: ['skip_subagent_guard_bypass', 'deprecated_bypass', `mode:${mode || 'legacy'}`],
-        });
-      } catch {
-        // fail-open — never block on telemetry
-      }
-
-      outputPreToolUse({
-        decision: 'allow',
-        context: [
-          `Active workflow: ${workflow.id}. Direct write allowed via SKIP_SUBAGENT_GUARD.`,
-          '',
-          '⚠️ DEPRECATED per ADR-013 §6.5.3. Prefer:',
-          "  • mode:'quick' (startWorkflow({ mode: 'quick' })) — single-phase, main-agent writes allowed by design",
-          "  • mode:'direct' (ADR-017 Phase 3) — multi-phase, main-agent writes with startDirectExecution audit trail",
-          'Bypass logged to .claude/agent-memory/main/observations.yaml for usage review (S200+ remediation decision).',
-        ].join('\n'),
-      });
-      return;
+        },
+      };
     }
 
-    // Main agent direct write — DENY
-    log(HOOK, `DENY (main agent direct write, mode=${mode || 'legacy'})`);
-    outputPreToolUse({
+    // Rule 6f: main agent direct write — DENY
+    return {
+      matchedRule: 6,
+      emitOutput: true,
+      output: {
+        decision: 'deny',
+        reason:
+          'Workflow Guard: Direct code writes are blocked. You must invoke a sub-agent (e.g. implementer) to write code. The sub-agent will have write access.',
+        context:
+          'Use the Agent tool to spawn an implementer sub-agent for code changes. The workflow-guard allows writes only from sub-agents (identified by agent_id in hook input).',
+      },
+      logMessages: [modeLogLine, `DENY (main agent direct write, mode=${mode || 'legacy'})`],
+    };
+  }
+
+  // Rule 7: no active workflow (target project IS registered) — DENY
+  return {
+    matchedRule: 7,
+    emitOutput: true,
+    output: {
       decision: 'deny',
-      reason:
-        'Workflow Guard: Direct code writes are blocked. You must invoke a sub-agent (e.g. implementer) to write code. The sub-agent will have write access.',
-      context:
-        'Use the Agent tool to spawn an implementer sub-agent for code changes. The workflow-guard allows writes only from sub-agents (identified by agent_id in hook input).',
-    });
-    return;
+      reason: 'Workflow Guard: No active workflow. Direct implementation is not allowed.',
+      context: [
+        'You MUST start a workflow before writing code:',
+        '1. mcp__orchestrator-tools__detectWorkflow({ prompt: "..." })',
+        '2. mcp__orchestrator-tools__startWorkflow({ workflowType: "...", prompt: "..." })',
+        '3. Follow the nextStep returned by startWorkflow',
+        '',
+        'The workflow-guard hook blocks all writes to src/ and tests/ without an active workflow.',
+      ].join('\n'),
+    },
+    logMessages: ['DENY (no active workflow)'],
+  };
+}
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+  const filePath =
+    getField(stdin, 'tool_input.file_path') ||
+    getField(stdin, 'file_path') ||
+    getField(stdin, 'input.file_path');
+
+  log(HOOK, `file_path=${filePath}`);
+
+  const skipWorkflowGuard = process.env.SKIP_WORKFLOW_GUARD === 'true';
+  const skipSubagentGuard = process.env.SKIP_SUBAGENT_GUARD === 'true';
+  const agentId = getField(stdin, 'agent_id');
+  const agentType = getField(stdin, 'agent_type');
+
+  // RFC-040 TD-204 ⑤-A: resolve the OWNING project of the write TARGET
+  // (file_path), not the session's cwd. Cheap fs walk-up (no network) — safe
+  // to compute unconditionally for every Write/Edit.
+  const targetDir = filePath.length > 0 ? dirname(filePath) : process.cwd();
+  const targetProjectRoot = resolveHookProjectRoot(targetDir);
+  const isUnmanaged =
+    targetProjectRoot !== null &&
+    existsSync(join(targetProjectRoot, '.orchestrator', '.unmanaged'));
+
+  const baseInput: Omit<WorkflowGuardDecisionInput, 'workflow'> = {
+    filePath,
+    skipWorkflowGuard,
+    skipSubagentGuard,
+    targetProjectRoot,
+    isUnmanaged,
+    agentId,
+    agentType,
+  };
+
+  // Two-pass evaluation: try with workflow=null first. Rules 1-5 never
+  // inspect `workflow`, so a `null` trial resolves them correctly WITHOUT
+  // any network I/O — preserving the pre-⑤-A short-circuit that skips
+  // getActiveWorkflow()/getWorkflowMode() for non-guarded, config-doc,
+  // unmanaged, and unregistered paths. Only when the trial itself lands on
+  // rule 7 ("no active workflow") do we actually need the network fetch to
+  // confirm — at most one real fetch, matching original behavior exactly.
+  let decision = decideWorkflowGuardAction({ ...baseInput, workflow: null });
+
+  if (decision.matchedRule === 7) {
+    const activeWorkflow = await getActiveWorkflow();
+    let workflow: WorkflowGuardWorkflowInput | null = null;
+    if (activeWorkflow) {
+      const mode = await getWorkflowMode(activeWorkflow.id);
+      workflow = { id: activeWorkflow.id, mode, currentPhase: activeWorkflow.currentPhase };
+    }
+    decision = decideWorkflowGuardAction({ ...baseInput, workflow });
+  }
+
+  for (const line of decision.logMessages) {
+    log(HOOK, line);
+  }
+
+  if (decision.observation) {
+    try {
+      const sessionId = getField(stdin, 'session_id') || getField(stdin, 'claude_session_id') || '';
+      // RFC-040 Operator Multi-Project — Slice 5 (C5): resolves under the
+      // project root walked up from cwd (falls back to cwd when unregistered).
+      const memoryBaseDir = resolveAgentMemoryBaseDir(process.cwd());
+      appendObservation(memoryBaseDir, 'main', {
+        timestamp: new Date().toISOString(),
+        session_id: sessionId,
+        ...decision.observation,
+      });
+    } catch {
+      // fail-open — never block on telemetry
+    }
   }
 
-  // No active workflow — DENY
-  log(HOOK, 'DENY (no active workflow)');
-  outputPreToolUse({
-    decision: 'deny',
-    reason: 'Workflow Guard: No active workflow. Direct implementation is not allowed.',
-    context: [
-      'You MUST start a workflow before writing code:',
-      '1. mcp__orchestrator-tools__detectWorkflow({ prompt: "..." })',
-      '2. mcp__orchestrator-tools__startWorkflow({ workflowType: "...", prompt: "..." })',
-      '3. Follow the nextStep returned by startWorkflow',
-      '',
-      'The workflow-guard hook blocks all writes to src/ and tests/ without an active workflow.',
-    ].join('\n'),
-  });
+  if (decision.emitOutput && decision.output) {
+    outputPreToolUse(decision.output);
+  }
 }
 
 main().catch(() => process.exit(0));

package/hooks-settings-template.json

@@ -0,0 +1,63 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          { "type": "command", "command": "hooks/session-start.mjs", "timeout": 10000 },
+          { "type": "command", "command": "hooks/sprint-registry.mjs", "timeout": 5000 }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "hooks/user-prompt.mjs", "timeout": 10000 }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "mcp__orchestrator-tools__advancePhase",
+        "hooks": [{ "type": "command", "command": "hooks/gate-guardian.mjs", "timeout": 15000 }]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [{ "type": "command", "command": "hooks/workflow-guard.mjs", "timeout": 10000 }]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "implementer|specifier|planner|task-generator|reviewer|researcher",
+        "hooks": [{ "type": "command", "command": "hooks/subagent-start.mjs", "timeout": 10000 }]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "implementer|specifier|planner|task-generator|reviewer|researcher",
+        "hooks": [{ "type": "command", "command": "hooks/subagent-stop.mjs", "timeout": 30000 }]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "hooks/dangling-guard.mjs", "timeout": 15000 }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "hooks/mailbox-listener.mjs", "timeout": 5000 }]
+      },
+      {
+        "matcher": "mcp__orchestrator-tools__advancePhase",
+        "hooks": [{ "type": "command", "command": "hooks/post-implement.mjs", "timeout": 15000 }]
+      }
+    ],
+    "PostCompact": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "hooks/post-compact.mjs", "timeout": 5000 }]
+      }
+    ]
+  }
+}