@orchestrator-claude/definitions 3.34.0 → 3.35.0

package/hooks/pre-agent-dispatch.mjs

@@ -0,0 +1,346 @@
+import { createRequire as __createRequireShim } from 'node:module'; const require = __createRequireShim(import.meta.url);
+
+// hooks/pre-agent-dispatch.ts
+import { execFileSync } from "node:child_process";
+
+// hooks/lib/api-client.ts
+import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync, readdirSync } from "node:fs";
+import { join as join2, dirname as dirname2 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../project-root-resolver/dist/index.js
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+function resolveProjectRoot(cwd, sentinel = ".orchestrator") {
+  let currentDir = cwd;
+  for (; ; ) {
+    if (existsSync(join(currentDir, sentinel))) {
+      return currentDir;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+    currentDir = parentDir;
+  }
+}
+
+// hooks/lib/api-client.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname2(__filename);
+var PROJECT_ROOT = join2(__dirname, "..", "..", "..");
+var STATE_DIR = join2(PROJECT_ROOT, ".orchestrator", ".state");
+var JWT_CACHE = join2(STATE_DIR, "jwt-token");
+var DEBUG_LOG = join2(STATE_DIR, "hook-debug.log");
+mkdirSync(STATE_DIR, { recursive: true });
+var API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
+var AUTH_EMAIL = process.env.ORCHESTRATOR_ADMIN_EMAIL || process.env.ORCHESTRATOR_AUTH_EMAIL || "system@orchestrator.local";
+var AUTH_PASSWORD = process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || "system123";
+var PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || "";
+function resolveHookProjectRoot(cwd) {
+  return resolveProjectRoot(cwd);
+}
+var projectIdResolutionAttempted = false;
+async function ensureProjectIdResolved(token) {
+  if (PROJECT_ID || projectIdResolutionAttempted) return;
+  projectIdResolutionAttempted = true;
+  try {
+    const rootPath = resolveHookProjectRoot(process.cwd());
+    if (rootPath === null) {
+      log(
+        "API-CLIENT",
+        "ensureProjectIdResolved: cwd not registered (.orchestrator sentinel not found) \u2014 skipping"
+      );
+      return;
+    }
+    const resolved = await resolveProjectIdByPath(rootPath, token);
+    if (resolved) {
+      PROJECT_ID = resolved;
+      log(
+        "API-CLIENT",
+        `ensureProjectIdResolved: resolved projectId=${resolved} rootPath=${rootPath}`
+      );
+    } else {
+      log(
+        "API-CLIENT",
+        `ensureProjectIdResolved: rootPath=${rootPath} not registered to any project \u2014 skipping`
+      );
+    }
+  } catch (err) {
+    log(
+      "API-CLIENT",
+      `ensureProjectIdResolved: unexpected failure \u2014 ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function log(prefix, msg) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+  try {
+    const line = `[${ts}] ${prefix}: ${msg}
+`;
+    writeFileSync(DEBUG_LOG, line, { flag: "a" });
+  } catch {
+  }
+}
+function getCachedToken() {
+  try {
+    const stat = statSync(JWT_CACHE);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < 35e5) {
+      return readFileSync(JWT_CACHE, "utf-8").trim();
+    }
+  } catch {
+  }
+  return null;
+}
+async function login() {
+  try {
+    const resp = await fetch(`${API_URL}/api/v1/auth/login`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Project-ID": PROJECT_ID
+      },
+      body: JSON.stringify({ email: AUTH_EMAIL, password: AUTH_PASSWORD }),
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (!resp.ok) return null;
+    const data = await resp.json();
+    const token = data.accessToken || data.data?.accessToken || "";
+    if (token) {
+      writeFileSync(JWT_CACHE, token);
+    }
+    return token || null;
+  } catch {
+    return null;
+  }
+}
+async function getToken() {
+  const token = getCachedToken() || await login();
+  if (token) {
+    await ensureProjectIdResolved(token);
+  }
+  return token;
+}
+async function apiGet(path, token, timeoutMs = 5e3) {
+  try {
+    const resp = await fetch(`${API_URL}${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "X-Project-ID": PROJECT_ID
+      },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!resp.ok) return null;
+    return await resp.json();
+  } catch {
+    return null;
+  }
+}
+async function resolveProjectIdByPath(rootPath, token) {
+  const resp = await apiGet(
+    `/api/v1/projects/resolve?rootPath=${encodeURIComponent(rootPath)}`,
+    token
+  );
+  return resp?.projectId ?? null;
+}
+async function getActiveWorkflow() {
+  const token = await getToken();
+  if (!token) return null;
+  for (const status of ["in_progress", "awaiting_agent", "awaiting_approval"]) {
+    const resp = await apiGet(
+      `/api/v1/workflows?status=${status}&limit=1`,
+      token,
+      3e3
+    );
+    const list = resp?.data || (Array.isArray(resp) ? resp : null);
+    const wf = list?.[0];
+    if (wf?.id) return wf;
+  }
+  return null;
+}
+var LAST_COMPLETED_FILE = join2(STATE_DIR, "last-completed-workflow.json");
+var LAST_COMPLETED_TTL_MS = 60 * 60 * 1e3;
+var INVOCATIONS_DIR = join2(STATE_DIR, "invocations");
+var INVOCATION_STATE_TTL_MS = 4 * 60 * 60 * 1e3;
+var DISPATCH_INTENT_DIR = join2(STATE_DIR, "dispatch-intent");
+function buildDispatchIntentPath(stateDir, workflowId) {
+  return join2(stateDir, "dispatch-intent", `${workflowId}.json`);
+}
+function writeDispatchIntent(workflowId) {
+  try {
+    mkdirSync(DISPATCH_INTENT_DIR, { recursive: true });
+    const path = buildDispatchIntentPath(STATE_DIR, workflowId);
+    const payload = { workflowId, stampedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    writeFileSync(path, JSON.stringify(payload), "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function getField(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return "";
+    current = current[part];
+  }
+  return current != null ? String(current) : "";
+}
+function outputContext(hookEvent, context) {
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: hookEvent,
+        additionalContext: context
+      }
+    })
+  );
+}
+
+// hooks/pre-agent-dispatch.ts
+var HOOK = "PRE-AGENT-DISPATCH";
+var KNOWN_AGENTS = [
+  "implementer",
+  "planner",
+  "specifier",
+  "reviewer",
+  "task-generator",
+  "researcher"
+];
+var KNOWN_AGENTS_REGEX = new RegExp(`\\b(${KNOWN_AGENTS.join("|")})\\b`, "i");
+var COMMITTING_AGENTS = [
+  "implementer",
+  "azure-devops-engineer",
+  "presentation-engineer",
+  "operational-artifact-builder",
+  "cicd-platform-engineer",
+  "python-data-engineer",
+  "frontend-engineer"
+];
+var PROTECTED_BRANCHES = ["main", "master"];
+function normalizeAgentName(subagentType) {
+  const i = subagentType.lastIndexOf(":");
+  return i === -1 ? subagentType : subagentType.slice(i + 1);
+}
+function isCommittingAgent(subagentType) {
+  if (!subagentType) return false;
+  const t = normalizeAgentName(subagentType).toLowerCase();
+  if (!t) return false;
+  return COMMITTING_AGENTS.some((a) => a.toLowerCase() === t);
+}
+function isProtectedBranch(branch) {
+  return PROTECTED_BRANCHES.includes(branch);
+}
+function parseBranchFromHead(headContents) {
+  const m = /^ref:\s*refs\/heads\/(.+)$/.exec(headContents.trim());
+  return m ? (m[1] ?? "").trim() : "";
+}
+function detectKnownAgentInPrompt(prompt) {
+  const match = KNOWN_AGENTS_REGEX.exec(prompt);
+  return match ? (match[1] ?? "").toLowerCase() : null;
+}
+function branchBeforeDispatchMessage(subagentType, branch) {
+  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 \u2014 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.`;
+}
+function evaluateDispatch(ctx) {
+  const warnings = [];
+  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;
+}
+function readBranchFromGit() {
+  try {
+    return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+var defaultDeps = {
+  readStdin,
+  outputContext,
+  log,
+  readBranch: readBranchFromGit,
+  getActiveWorkflow,
+  writeDispatchIntent
+};
+var DISPATCH_INTENT_RESOLVE_TIMEOUT_MS = 3e3;
+async function stampDispatchIntent(deps) {
+  if (!deps.getActiveWorkflow || !deps.writeDispatchIntent) return;
+  try {
+    const workflow = await Promise.race([
+      deps.getActiveWorkflow(),
+      new Promise((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)}`);
+  }
+}
+async function mainWithDeps(deps) {
+  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 });
+  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}")`);
+}
+async function main() {
+  await mainWithDeps(defaultDeps);
+}
+main().catch(() => process.exit(0));
+export {
+  COMMITTING_AGENTS,
+  branchBeforeDispatchMessage,
+  detectKnownAgentInPrompt,
+  evaluateDispatch,
+  isCommittingAgent,
+  isProtectedBranch,
+  mainWithDeps,
+  normalizeAgentName,
+  parseBranchFromHead,
+  stampDispatchIntent
+};

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));