@orchestrator-claude/definitions 3.34.0 → 3.36.0

package/hooks/pre-agent-dispatch.ts

@@ -0,0 +1,287 @@
+/**
+ * pre-agent-dispatch.ts — PreToolUse hook for the Agent tool
+ *
+ * NON-BLOCKING (always exits 0; only injects advisory context). Two responsibilities:
+ *
+ *  1. (RFC-027 Sprint 4) Warn when a known agent is dispatched WITHOUT subagent_type,
+ *     so frontmatter (model/tools) loads correctly.
+ *
+ *  2. (TD-171) Branch-before-dispatch ALERT. When the orchestrator dispatches a
+ *     COMMITTING agent — one whose tool list holds `mcp__orchestrator-tools__createCheckpoint`,
+ *     so it may make local checkpoint commits — while sitting on a PROTECTED branch
+ *     (main/master), warn it to check out a feature branch FIRST. Root cause of the
+ *     S289 breach `4f1f4f37`: an implementer was dispatched from `main`, so its local
+ *     commit landed directly on the protected branch. agent-git-guard (TD-169) blocks
+ *     push/merge but intentionally ALLOWS local commit, so a local commit on `main`
+ *     slips through. The real fix is branch-before-dispatch (orchestrator owns the
+ *     branch); this hook is the non-blocking backstop. Per the user directive it ALERTS
+ *     (not blocks) — the hard stop on the unrecoverable vector stays in agent-git-guard.
+ *
+ *  3. (TD-205) Dispatch-intent stamp. This hook fires SYNCHRONOUSLY at
+ *     PreToolUse[Agent] — before the sub-agent spawns / before the turn yields — so it
+ *     is the guaranteed-present signal for the bg-dispatch race: when the orchestrator
+ *     dispatches a sub-agent in the BACKGROUND and yields immediately, dangling-guard's
+ *     Stop hook can fire before subagent-start.ts's ASYNC startInvocation()+
+ *     writeInvocationState() has landed, producing a false-positive BLOCK on a
+ *     genuinely active workflow. Stamping a dispatch-intent marker for the active
+ *     workflow here gives dangling-guard a short (seconds), self-expiring grace-window
+ *     signal to cover that race without opening a hole in the rule-9 zombie safety net.
+ *     Best-effort / fail-open in every dimension (missing deps, no active workflow,
+ *     resolution timeout, filesystem error) — never blocks the dispatch.
+ *
+ * Design note (TD-171): the committing-agent set mirrors the `createCheckpoint` tool
+ * holders in `.claude/agents/*.md`. Keep it in sync with that ground truth and with the
+ * orchestrator SKILL §2c.1 Commit-Policy scope.
+ */
+
+import { execFileSync } from 'node:child_process';
+import {
+  log,
+  readStdin,
+  getField,
+  outputContext,
+  getActiveWorkflow,
+  writeDispatchIntent,
+} from './lib/api-client.js';
+
+const HOOK = 'PRE-AGENT-DISPATCH';
+
+// Known workflow agents (RFC-027 Sprint 4 — subagent_type presence check).
+const KNOWN_AGENTS = [
+  'implementer',
+  'planner',
+  'specifier',
+  'reviewer',
+  'task-generator',
+  'researcher',
+];
+
+const KNOWN_AGENTS_REGEX = new RegExp(`\\b(${KNOWN_AGENTS.join('|')})\\b`, 'i');
+
+/**
+ * Agents whose tool list includes `mcp__orchestrator-tools__createCheckpoint` (ground
+ * truth: grep `createCheckpoint` over `.claude/agents/*.md`). These may make local
+ * checkpoint commits during their phase, so dispatching them on a protected branch is
+ * the branch-before-dispatch hazard. Keep in sync with orchestrator SKILL §2c.1.
+ */
+export const COMMITTING_AGENTS: readonly string[] = [
+  'implementer',
+  'azure-devops-engineer',
+  'presentation-engineer',
+  'operational-artifact-builder',
+  'cicd-platform-engineer',
+  'python-data-engineer',
+  'frontend-engineer',
+];
+
+const PROTECTED_BRANCHES: readonly string[] = ['main', 'master'];
+
+// ─────────────────────────────────────────────────────────────
+// Pure helpers (exported for testing)
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Strip the plugin namespace from a dispatch name.
+ *
+ * Under plugin scope the harness namespaces every agent (`orchestrator:implementer`
+ * — measured in the S398 sandbox, RFC-040 §18.14); in project scope the same agent
+ * arrives bare (`implementer`). A guard that compares against the bare name only
+ * answers `false` for the namespaced form — and since hooks fail open, it disables
+ * itself in silence. Both forms MUST resolve to the same decision.
+ */
+export function normalizeAgentName(subagentType: string): string {
+  const i = subagentType.lastIndexOf(':');
+  return i === -1 ? subagentType : subagentType.slice(i + 1);
+}
+
+export function isCommittingAgent(subagentType: string): boolean {
+  if (!subagentType) return false;
+  const t = normalizeAgentName(subagentType).toLowerCase();
+  if (!t) return false;
+  return COMMITTING_AGENTS.some((a) => a.toLowerCase() === t);
+}
+
+export function isProtectedBranch(branch: string): boolean {
+  return PROTECTED_BRANCHES.includes(branch);
+}
+
+/** Parse `.git/HEAD` contents → branch name, or '' for detached HEAD / junk. */
+export function parseBranchFromHead(headContents: string): string {
+  const m = /^ref:\s*refs\/heads\/(.+)$/.exec(headContents.trim());
+  return m ? (m[1] ?? '').trim() : '';
+}
+
+export function detectKnownAgentInPrompt(prompt: string): string | null {
+  const match = KNOWN_AGENTS_REGEX.exec(prompt);
+  return match ? (match[1] ?? '').toLowerCase() : null;
+}
+
+export function branchBeforeDispatchMessage(subagentType: string, branch: string): string {
+  return (
+    `[BRANCH-BEFORE-DISPATCH][TD-171] About to dispatch committing agent '${subagentType}' while on ` +
+    `protected branch '${branch}'. This agent can make LOCAL checkpoint commits, and agent-git-guard ` +
+    `(TD-169) blocks push/merge but ALLOWS commit — so a local commit would land directly on '${branch}' ` +
+    `(root cause of the S289 '4f1f4f37' breach). Check out a feature branch BEFORE dispatching; the ` +
+    `orchestrator owns push after its independent assert.`
+  );
+}
+
+export interface DispatchContext {
+  subagentType: string;
+  prompt: string;
+  branch: string;
+}
+
+/**
+ * Pure decision. Returns the list of advisory warning lines (possibly empty).
+ *  - missing subagent_type + a known agent named in the prompt → RFC-027 warn
+ *  - committing agent dispatched on a protected branch → TD-171 branch-before-dispatch warn
+ */
+export function evaluateDispatch(ctx: DispatchContext): string[] {
+  const warnings: string[] = [];
+  const { subagentType, prompt, branch } = ctx;
+
+  if (!subagentType) {
+    const detected = detectKnownAgentInPrompt(prompt);
+    if (detected) {
+      warnings.push(
+        `[WARN] Agent dispatched without subagent_type. Known agent detected: "${detected}". ` +
+          `Add subagent_type for proper frontmatter loading.`
+      );
+    }
+  }
+
+  if (isCommittingAgent(subagentType) && isProtectedBranch(branch)) {
+    warnings.push(branchBeforeDispatchMessage(subagentType, branch));
+  }
+
+  return warnings;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Dependency injection interface (enables testing without IO)
+// ─────────────────────────────────────────────────────────────
+
+export interface HookDeps {
+  readStdin: () => Promise<Record<string, unknown>>;
+  outputContext: (hookEvent: string, context: string) => void;
+  log: (prefix: string, msg: string) => void;
+  readBranch: () => string;
+  /**
+   * TD-205: resolves the active workflow so the dispatch-intent marker can be
+   * workflow-scoped. Optional so pre-TD-205 test doubles keep working —
+   * stampDispatchIntent() no-ops (fail-open) when this is absent. Production
+   * defaultDeps below always provides it.
+   */
+  getActiveWorkflow?: () => Promise<{ id: string } | null>;
+  /** TD-205: stamps the dispatch-intent marker for workflowId. See getActiveWorkflow doc. */
+  writeDispatchIntent?: (workflowId: string) => boolean;
+}
+
+function readBranchFromGit(): string {
+  try {
+    // Fixed args, no shell (execFile, not exec) — no interpolation, no injection surface.
+    return execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+const defaultDeps: HookDeps = {
+  readStdin,
+  outputContext,
+  log,
+  readBranch: readBranchFromGit,
+  getActiveWorkflow,
+  writeDispatchIntent,
+};
+
+/**
+ * TD-205: internal resolve timeout for stampDispatchIntent's getActiveWorkflow()
+ * call — seconds, bounded well within this hook's own 5000ms PreToolUse
+ * timeout (settings.json) so a slow/unavailable API degrades gracefully
+ * (marker simply isn't stamped for that dispatch) rather than ever blocking
+ * the dispatch itself.
+ */
+const DISPATCH_INTENT_RESOLVE_TIMEOUT_MS = 3000;
+
+/**
+ * TD-205: stamps a dispatch-intent marker for the currently active workflow,
+ * if one is resolvable within DISPATCH_INTENT_RESOLVE_TIMEOUT_MS. Fail-open
+ * in every dimension — missing deps (pre-TD-205 test doubles), no active
+ * workflow, a rejected/never-resolving getActiveWorkflow(), or a filesystem
+ * failure inside writeDispatchIntent() all silently skip the stamp. This is
+ * a best-effort advisory signal, never a blocking step (matches this hook's
+ * existing non-blocking posture).
+ */
+export async function stampDispatchIntent(
+  deps: Pick<HookDeps, 'getActiveWorkflow' | 'writeDispatchIntent' | 'log'>
+): Promise<void> {
+  if (!deps.getActiveWorkflow || !deps.writeDispatchIntent) return;
+
+  try {
+    const workflow = await Promise.race([
+      deps.getActiveWorkflow(),
+      new Promise<null>((resolve) => {
+        setTimeout(() => {
+          resolve(null);
+        }, DISPATCH_INTENT_RESOLVE_TIMEOUT_MS);
+      }),
+    ]);
+    if (workflow?.id) {
+      const stamped = deps.writeDispatchIntent(workflow.id);
+      deps.log(HOOK, `[TD-205] dispatch-intent stamped=${String(stamped)} workflow=${workflow.id}`);
+    }
+  } catch (err) {
+    deps.log(HOOK, `[TD-205] stampDispatchIntent failed (fail-open): ${String(err)}`);
+  }
+}
+
+// ─────────────────────────────────────────────────────────────
+// Core logic (exported for testing)
+// ─────────────────────────────────────────────────────────────
+
+export async function mainWithDeps(deps: HookDeps): Promise<void> {
+  const stdin = await deps.readStdin();
+
+  const toolInput = getField(stdin, 'tool_input') || '';
+  const subagentType =
+    getField(stdin, 'tool_input.subagent_type') || getField(stdin, 'tool_input.subagentType') || '';
+  const prompt =
+    getField(stdin, 'tool_input.prompt') ||
+    getField(stdin, 'tool_input.description') ||
+    (typeof toolInput === 'string' ? toolInput : JSON.stringify(toolInput));
+
+  const branch = deps.readBranch();
+
+  const warnings = evaluateDispatch({ subagentType, prompt, branch });
+
+  // TD-205: stamp the dispatch-intent marker regardless of whether a warning
+  // fires — a dispatch is happening either way, and the marker exists purely
+  // to cover the bg-dispatch race for dangling-guard's Stop hook.
+  await stampDispatchIntent(deps);
+
+  if (warnings.length > 0) {
+    deps.outputContext(HOOK, warnings.join('\n'));
+    deps.log(
+      HOOK,
+      `${warnings.length} warning(s) (agent="${subagentType || '?'}" branch="${branch}")`
+    );
+    return;
+  }
+
+  deps.log(HOOK, `OK (agent="${subagentType || '?'}" branch="${branch}")`);
+}
+
+// ─────────────────────────────────────────────────────────────
+// Entry point (production use)
+// ─────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  await mainWithDeps(defaultDeps);
+}
+
+main().catch(() => process.exit(0));

package/hooks/session-start.mjs

@@ -7881,7 +7881,6 @@ function readSessionSelection(stateDir, sessionId) {
 var HOOK = "SESSION-START";
 var __filename2 = fileURLToPath2(import.meta.url);
 var __dirname2 = dirname3(__filename2);
-var GRAPHRAG_TIMEOUT_MS = 2e3;
 var PROJECT_ROOT2 = resolveHookProjectRoot(process.cwd());
 var PROJECT_ID2 = process.env.ORCHESTRATOR_PROJECT_ID ?? "";
 var HOME = process.env.HOME ?? process.env.USERPROFILE ?? "/home/user";
@@ -7960,7 +7959,7 @@ function readBacklogFallback() {
     const latestSession = sessionMatches.sort((a, b) => b.num - a.num || a.idx - b.idx)[0];
     const lastSession = latestSession?.line.replace(/\*\*/g, "").slice(0, 120) || "";
     const nextLine = allLines.find((l) => /^\*\*proximo passo/i.test(l) || /^\*\*next/i.test(l));
-    const next = nextLine?.replace(/.*\*\*(proximo passo|next):?\*\*:?\s*/i, "").replace(/\s*$/, "").slice(0, 120) || "see BACKLOG.md";
+    const next = nextLine?.replace(/.*\*\*(proximo passo|next):?\*\*:?\s*/i, "").replace(/\s*$/, "").slice(0, 120) || "BACKLOG.md has no next-step line (legacy parser; see project-guidelines/project-state.yaml)";
     log(
       HOOK,
       `BACKLOG.md fallback parsed: version=${version} next=${next.slice(0, 50)} lastSession=${lastSession.slice(0, 50)}`
@@ -7968,7 +7967,12 @@ function readBacklogFallback() {
     return { version, next, status, lastSession };
   } catch (err) {
     log(HOOK, `BACKLOG read failed: ${err}`);
-    return { version: "v?.?.?", next: "see BACKLOG.md", status: "", lastSession: "" };
+    return {
+      version: "v?.?.?",
+      next: "no session state (project-guidelines/project-state.yaml missing or invalid, BACKLOG.md unreadable)",
+      status: "",
+      lastSession: ""
+    };
   }
 }
 function getBacklogSummary() {
@@ -8128,34 +8132,6 @@ function checkSprintInbox() {
     return "";
   }
 }
-async function getGraphContext(token, fetcher) {
-  if (token === null || token === "") return "";
-  const defaultFetcher = async (path, tok, timeoutMs = GRAPHRAG_TIMEOUT_MS) => {
-    const resp = await fetch(`http://localhost:3000${path}`, {
-      headers: { Authorization: `Bearer ${tok}` },
-      signal: AbortSignal.timeout(timeoutMs)
-    });
-    if (!resp.ok) return null;
-    return resp.json();
-  };
-  const fetch_ = fetcher ?? defaultFetcher;
-  try {
-    const [statsRaw, atRiskRaw] = await Promise.all([
-      fetch_("/api/v1/graphrag/stats", token, GRAPHRAG_TIMEOUT_MS),
-      fetch_("/api/v1/graphrag/at-risk", token, GRAPHRAG_TIMEOUT_MS)
-    ]);
-    const stats = statsRaw;
-    if (stats?.nodeCount === void 0) return "";
-    const atRiskData = atRiskRaw;
-    const components = String(stats.nodeCount);
-    const edges = String(stats.edgeCount ?? 0);
-    const hotPaths = (stats.hotPaths ?? []).join(",");
-    const atRisk = (atRiskData?.atRisk ?? []).join(",");
-    return `[GRAPH-CONTEXT] components=${components} edges=${edges} hot_paths=[${hotPaths}] at_risk=[${atRisk}]`;
-  } catch {
-    return "";
-  }
-}
 async function main() {
   log(HOOK, "SessionStart hook triggered");
   if (PROJECT_ROOT2 === null) {
@@ -8172,8 +8148,7 @@ async function main() {
   const tierSegment = formatTierSegment(tierInfo);
   const capabilityContext = buildCapabilityMatrixContext();
   const sprintInboxContext = checkSprintInbox();
-  const token = await getToken();
-  const graphContext = await getGraphContext(token);
+  await getToken();
   const selection = PROJECT_SELECTION_ENABLED && sessionId ? readSessionSelection(SESSION_SELECTION_STATE_DIR, sessionId) : void 0;
   const projectBinding = resolveSessionProjectBinding({
     envOverride: PROJECT_ID2,
@@ -8198,7 +8173,6 @@ async function main() {
         "Do NOT invoke /orchestrator skill for the greeting \u2014 use AskUserQuestion directly.",
         "Invoke /orchestrator skill only when the user chooses to start a workflow.",
         capabilityContext,
-        graphContext,
         sprintInboxContext,
         projectSelectionPrompt
       ].filter(Boolean).join("\n")
@@ -8216,7 +8190,6 @@ async function main() {
       "Do NOT invoke /orchestrator skill for the greeting \u2014 use AskUserQuestion directly.",
       "Invoke /orchestrator skill when the user chooses to continue the workflow.",
       capabilityContext,
-      graphContext,
       projectSelectionPrompt
     ].filter(Boolean).join("\n")
   );
@@ -8227,7 +8200,6 @@ export {
   formatProjectBindingSegment,
   formatSessionNumberSegment,
   formatTierSegment,
-  getGraphContext,
   readProjectState,
   resolveSessionProjectBinding,
   synthesizeStatus

package/hooks/session-start.ts

@@ -37,7 +37,6 @@ import { readSessionSelection } from './lib/session-selection.js';
 const HOOK = 'SESSION-START';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const GRAPHRAG_TIMEOUT_MS = 2000;
 // RFC-040 Operator Multi-Project — Slice 5 (C5), S358/S361: cwd-aware
 // resolution (walks up for the .orchestrator sentinel) replaces the
 // __dirname-hardcoded path. `null` means an unregistered cwd — deliberately
@@ -208,7 +207,8 @@ function readBacklogFallback(): BacklogSummary {
       nextLine
         ?.replace(/.*\*\*(proximo passo|next):?\*\*:?\s*/i, '')
         .replace(/\s*$/, '')
-        .slice(0, 120) || 'see BACKLOG.md';
+        .slice(0, 120) ||
+      'BACKLOG.md has no next-step line (legacy parser; see project-guidelines/project-state.yaml)';
 
     log(
       HOOK,
@@ -217,7 +217,12 @@ function readBacklogFallback(): BacklogSummary {
     return { version, next, status, lastSession };
   } catch (err) {
     log(HOOK, `BACKLOG read failed: ${err}`);
-    return { version: 'v?.?.?', next: 'see BACKLOG.md', status: '', lastSession: '' };
+    return {
+      version: 'v?.?.?',
+      next: 'no session state (project-guidelines/project-state.yaml missing or invalid, BACKLOG.md unreadable)',
+      status: '',
+      lastSession: '',
+    };
   }
 }
 
@@ -371,9 +376,9 @@ export function formatProjectBindingSegment(binding: SessionProjectBinding): str
  * registered project this session belongs to, listing every registered
  * project by name/id/rootPath.
  *
- * Fail-open (Class C benign degrade, mirrors buildCapabilityMatrixContext
- * / getGraphContext): returns "" on any error — a failed project-list
- * fetch must never block or crash the hook.
+ * Fail-open (Class C benign degrade, mirrors buildCapabilityMatrixContext):
+ * returns "" on any error — a failed project-list fetch must never block
+ * or crash the hook.
  */
 export async function buildProjectSelectionPrompt(): Promise<string> {
   try {
@@ -504,66 +509,6 @@ function checkSprintInbox(): string {
   }
 }
 
-// ─── Graph Context (RFC-021 T-G4-06) ──────────────────────────────────────────
-
-type GraphFetcher = (path: string, token: string, timeoutMs?: number) => Promise<unknown>;
-
-interface GraphStatsResponse {
-  nodeCount?: number;
-  edgeCount?: number;
-  hotPaths?: string[];
-}
-
-interface AtRiskResponse {
-  atRisk?: string[];
-}
-
-/**
- * Fetch graph stats and at-risk components from the GraphRAG API.
- * Uses Promise.all for parallel calls with a 2s AbortController timeout.
- * Fail-open: returns "" on any error so session-start never blocks.
- *
- * @param token - JWT token (null → skip API calls, return "")
- * @param fetcher - injectable fetch function (default: real HTTP via api-client pattern)
- */
-export async function getGraphContext(
-  token: string | null,
-  fetcher?: GraphFetcher
-): Promise<string> {
-  if (token === null || token === '') return '';
-
-  const defaultFetcher: GraphFetcher = async (path, tok, timeoutMs = GRAPHRAG_TIMEOUT_MS) => {
-    const resp = await fetch(`http://localhost:3000${path}`, {
-      headers: { Authorization: `Bearer ${tok}` },
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-    if (!resp.ok) return null;
-    return resp.json() as Promise<unknown>;
-  };
-
-  const fetch_ = fetcher ?? defaultFetcher;
-
-  try {
-    const [statsRaw, atRiskRaw] = await Promise.all([
-      fetch_('/api/v1/graphrag/stats', token, GRAPHRAG_TIMEOUT_MS),
-      fetch_('/api/v1/graphrag/at-risk', token, GRAPHRAG_TIMEOUT_MS),
-    ]);
-
-    const stats = statsRaw as GraphStatsResponse | null;
-    if (stats?.nodeCount === undefined) return '';
-
-    const atRiskData = atRiskRaw as AtRiskResponse | null;
-    const components = String(stats.nodeCount);
-    const edges = String(stats.edgeCount ?? 0);
-    const hotPaths = (stats.hotPaths ?? []).join(',');
-    const atRisk = (atRiskData?.atRisk ?? []).join(',');
-
-    return `[GRAPH-CONTEXT] components=${components} edges=${edges} hot_paths=[${hotPaths}] at_risk=[${atRisk}]`;
-  } catch {
-    return '';
-  }
-}
-
 async function main(): Promise<void> {
   log(HOOK, 'SessionStart hook triggered');
 
@@ -586,15 +531,15 @@ async function main(): Promise<void> {
   // Sprint inbox check (RFC-027 S4 — only for sprint panes)
   const sprintInboxContext = checkSprintInbox();
 
-  // Graph context (RFC-021 T-G4-06) — fail-open, 2s timeout. RFC-040 TD-206
-  // (S372): this getToken() call MUST stay HERE, before
+  // RFC-040 TD-206 (S372): this getToken() call MUST stay HERE, before
   // resolveSessionProjectBinding() below — it is what bootstraps the
   // cwd-hint tier (getToken -> ensureProjectIdResolved ->
   // getEffectiveProjectId() reads the resolved value just below). Moving
   // getActiveWorkflow()/getNextAction() later (see below) must not remove
   // this bootstrap, or the cwd-hint tier would regress to reading '' .
-  const token = await getToken();
-  const graphContext = await getGraphContext(token);
+  // Return value no longer consumed directly (TD-211 F9 — getGraphContext,
+  // its sole prior consumer, was removed along with the graph-context surface).
+  await getToken();
 
   // RFC-040 TD-204 ⑤-C: read a previously-persisted selection for THIS
   // sessionId — feature-flagged (default OFF, kill-switch). With the flag
@@ -670,7 +615,6 @@ async function main(): Promise<void> {
         'Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.',
         'Invoke /orchestrator skill only when the user chooses to start a workflow.',
         capabilityContext,
-        graphContext,
         sprintInboxContext,
         projectSelectionPrompt,
       ]
@@ -696,7 +640,6 @@ async function main(): Promise<void> {
       'Do NOT invoke /orchestrator skill for the greeting — use AskUserQuestion directly.',
       'Invoke /orchestrator skill when the user chooses to continue the workflow.',
       capabilityContext,
-      graphContext,
       projectSelectionPrompt,
     ]
       .filter(Boolean)

package/hooks/subagent-stop.mjs

@@ -7595,16 +7595,6 @@ function getField(obj, path) {
   }
   return current != null ? String(current) : "";
 }
-function outputContext(hookEvent, context) {
-  console.log(
-    JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: hookEvent,
-        additionalContext: context
-      }
-    })
-  );
-}
 
 // hooks/lib/git-checkpoint.ts
 import { execSync } from "node:child_process";
@@ -7766,14 +7756,6 @@ async function main() {
     );
   }
   const commitHash = await createCheckpointIfNeeded(workflow.id, workflow.currentPhase);
-  const parts = [
-    `[ORCHESTRATOR] Agent '${agentType}' completed for workflow ${workflow.id}.`
-  ];
-  if (commitHash) {
-    parts.push(`Checkpoint: ${commitHash}.`);
-  }
-  parts.push("Proceed to gate check via AskUserQuestion before advancing phase.");
-  outputContext("SubagentStop", parts.join(" "));
   try {
     const sessionId = getField(stdin, "session_id") || getField(stdin, "claude_session_id") || "";
     const memoryBaseDir = resolveAgentMemoryBaseDir(process.cwd());

package/hooks/subagent-stop.ts

@@ -13,7 +13,6 @@ import {
   readStdin,
   getField,
   getActiveWorkflow,
-  outputContext,
   readInvocationState,
   consumeInvocationState,
   completeAgentInvocation,
@@ -82,18 +81,35 @@ async function main(): Promise<void> {
   // 2. Git checkpoint if phase changed
   const commitHash = await createCheckpointIfNeeded(workflow.id, workflow.currentPhase);
 
-  // 3. Guide main conversation — NO ping-pong, main IS the orchestrator
-  const parts: string[] = [
-    `[ORCHESTRATOR] Agent '${agentType}' completed for workflow ${workflow.id}.`,
-  ];
-
-  if (commitHash) {
-    parts.push(`Checkpoint: ${commitHash}.`);
-  }
-
-  parts.push('Proceed to gate check via AskUserQuestion before advancing phase.');
-
-  outputContext('SubagentStop', parts.join(' '));
+  // 3. NO context emission on SubagentStop — see below.
+  //
+  // This block used to call outputContext('SubagentStop', "[ORCHESTRATOR] Agent 'X'
+  // completed... Proceed to gate check via AskUserQuestion before advancing phase.").
+  // The intent was to guide the MAIN conversation (RFC-022: main IS the orchestrator).
+  // That intent is UNREACHABLE from this event, and the attempt was actively harmful:
+  //
+  //   outputContext() emits hookSpecificOutput.additionalContext. On SubagentStop that
+  //   context is injected into the SUB-AGENT's turn, not the orchestrator's — so the
+  //   sub-agent was handed an orchestrator-addressed instruction naming a tool it does
+  //   not have (AskUserQuestion). It cannot comply and cannot decline; it replies, stops
+  //   again, the hook re-fires with the identical message, and the cycle repeats.
+  //
+  // MEASURED (S400, .orchestrator/.state/hook-debug.log): exactly 9 re-fires per dispatch,
+  // for `specifier`, `planner` AND — in logs predating this session — `implementer`. The
+  // sub-agent's final report is consumed by the loop (the orchestrator receives only the
+  // agent handle), while the real work survives because it lands via artifactStore.
+  // The planner of workflow 8f149ec6 self-reported the loop from inside it.
+  //
+  // Do NOT reintroduce an additionalContext emission here. Any payload on this event
+  // re-prompts the sub-agent — the defect is the emission itself, not its wording.
+  // The orchestrator already receives the sub-agent's result directly and owns the gate
+  // check unconditionally (orchestrator Skin, MUST #2). The RFC-034 post-implement signal
+  // is unaffected: it lives in post-implement.ts on PostToolUse[advancePhase], which fires
+  // in the MAIN conversation's context, where additionalContext is the correct mechanism.
+  //
+  // The side effects above (invocation-completion safety net, git checkpoint) and the
+  // observation below are unaffected — they are writes, not context injection.
+  // (commitHash is still consumed by the observation payload below.)
 
   // 4. Write Tier B observation (fail-open)
   try {