infraweaver 0.1.0

package/src/agents/claudePretoolGate.ts

@@ -0,0 +1,286 @@
+/**
+ * Claude Code `PreToolUse` hook source — written into `ctx.tmpdir` at runtime
+ * and registered via a tmpdir-scoped `settings.json` referenced by
+ * `--settings <path>` (see action/agents/claude.ts).
+ *
+ * Closes the subagent → state-mutating MCP tool path that motivated the
+ * 2026-05-18 zed-industries/cloud incident (`terralens` lens called
+ * `checkout_pr` mid-review and the orchestrator's next push clobbered an
+ * unrelated branch). Pairs with the `tool.execute.before` hook in
+ * action/agents/opencodePlugin.ts; both runtimes embed the same per-run deny
+ * set, derived from each MCP tool's `mutates` flag (`subagentDeniedToolNames`
+ * in action/mcp/server.ts).
+ *
+ * PreToolUse hook contract (verified against yasasbanukaofficial/claude-code
+ * `src/utils/hooks/hooksConfigManager.ts` and `src/utils/hooks.ts`):
+ *   - stdin: JSON with `hook_event_name: "PreToolUse"`, `tool_name`,
+ *     `tool_input`, `tool_use_id`, `session_id`, `cwd`, `transcript_path`,
+ *     and crucially `agent_id` / `agent_type` populated when the call
+ *     originates from a subagent (set by the SDK when a Task/Agent
+ *     dispatches a tool — see `createBaseHookInput` in claude-code source).
+ *   - exit 0 → allow, no output shown
+ *   - exit 2 → block tool call AND show stderr to model (this is the path
+ *     we want for the deny case — the subagent gets a clear refusal it can
+ *     reason about and pick a different action)
+ *   - other → show stderr to user only, continue with tool call
+ *
+ * The hook itself is intentionally tiny: stdin → JSON → check `agent_id`
+ * presence + `tool_name` against the deny list → exit 0 or 2. No deps.
+ *
+ * Why the script source is a string template, not a separate `.ts` file
+ * shipped with the action: the action runs as a published npm package; at
+ * install time we don't have the source on disk in a stable place. Embedding
+ * the source into `dist/main.mjs` and writing it out per-run keeps the path
+ * inside `ctx.tmpdir` (where `--settings` can find it) and survives bundle
+ * minification.
+ */
+
+import { WRITE_GATE_HELPERS_SOURCE } from "#app/agents/writeGateSource";
+import { PRODUCT_NAME } from "#app/brand";
+
+/**
+ * The pinned `@anthropic-ai/claude-code` version against which the subagent
+ * gate's `agent_id` discriminator was last verified (see the contract notes in
+ * the gate source below). The gate fails OPEN for subagents if claude-code ever
+ * stops populating `agent_id` in the PreToolUse hook payload, so a version bump
+ * must be paired with a re-verification of `createBaseHookInput`.
+ *
+ * `claudePretoolGate.test.ts` asserts this equals the version pinned in
+ * `package.json` — that test fails on any bump, forcing the re-verification
+ * before the pin and this constant are updated together.
+ *
+ * 2.1.220 verified 2026-07-28 against the schema embedded in the shipped
+ * binary: the base hook input still declares `agent_id` as
+ * `string().optional().describe("Subagent identifier. Present only when the
+ * hook fires from within a subagent (e.g., a tool called by an AgentTool
+ * worker). Absent for the main thread, even in --agent sessions. Use this
+ * field (not agent_type) to distinguish subagent calls from main-thread
+ * calls.")` — exactly the discriminator the gate relies on, byte-for-byte
+ * unchanged from the 2.1.198 verification (2026-07-10), itself unchanged from
+ * 2.1.195 (2026-07-01) and 2.1.190 (2026-06-25), which was more explicit than
+ * the 2.1.177 schema it replaced. The 2.1.220 pass additionally confirmed the
+ * field is still POPULATED and not merely declared — the minified bundle
+ * assigns `agent_id` from real identifier sources (`e.agentId`,
+ * `e.parentAgentId`, `e.data.agentId`), not a hardcoded empty value.
+ *
+ * Scope of this verification, stated honestly: it is static inspection of the
+ * shipped binary. No CI job exercises the Claude subagent gate against a live
+ * agent — `security-tests.yml` is deliberately opencode-only (free keyless
+ * model; Claude Code cannot use an `opencode/*` gateway model). So this pin,
+ * plus the tripwire test, IS the contract check. Keep both.
+ */
+export const CLAUDE_CODE_AGENT_ID_VERIFIED_VERSION = "2.1.220" as const;
+
+/**
+ * Source written to `<ctx.tmpdir>/infraweaver-pretool-gate.mjs`. Plain ESM,
+ * no TypeScript, no dependencies — node executes it directly via the
+ * `#!/usr/bin/env node` shebang and the executable bit set by the harness.
+ *
+ * `deniedTools` is the per-run deny set derived from each MCP tool's `mutates`
+ * flag (see `subagentDeniedToolNames`), embedded into the hook's `Set` literal so
+ * the gate fences exactly the mutating tools registered for this run — no
+ * hand-maintained list to drift.
+ */
+export const CLAUDE_PRETOOL_GATE_FILENAME =
+  "infraweaver-pretool-gate.mjs" as const;
+
+/**
+ * Claude Code's native file-writing tools. The gate intercepts these to enforce
+ * `allowed_paths` / `protected_paths` at WRITE time; without them the only
+ * enforcement is the push-time diff scan, which lets a disallowed file exist in
+ * the tree for the rest of the run (see action/agents/writePolicy.ts).
+ *
+ * `MultiEdit` is included even though recent claude-code folds it into `Edit` —
+ * an extra name in the matcher is inert, a missing one is a hole.
+ */
+export const CLAUDE_WRITE_TOOL_NAMES = [
+  "Write",
+  "Edit",
+  "MultiEdit",
+  "NotebookEdit",
+] as const;
+
+export function buildClaudePretoolGateSource(
+  deniedTools: readonly string[],
+  writePolicyAbsolutePath: string,
+): string {
+  return `#!/usr/bin/env node
+// AUTOGENERATED by ${PRODUCT_NAME}. PreToolUse hook that (a) hard-blocks
+// state-mutating MCP tool calls from subagents and (b) enforces the
+// allowed_paths / protected_paths policy at write time.
+// See action/agents/claudePretoolGate.ts.
+
+const SUBAGENT_DENIED_TOOLS = new Set(${JSON.stringify(deniedTools)});
+const WRITE_TOOLS = new Set(${JSON.stringify(CLAUDE_WRITE_TOOL_NAMES)});
+const WRITE_POLICY_PATH = ${JSON.stringify(writePolicyAbsolutePath)};
+${WRITE_GATE_HELPERS_SOURCE}
+function stripMcpPrefix(toolName) {
+  if (toolName.startsWith("mcp__infraweaver__")) return toolName.slice("mcp__infraweaver__".length);
+  return toolName;
+}
+
+/** the write path a given tool call targets, across the write-tool shapes. */
+function targetPathOf(toolInput) {
+  if (!toolInput || typeof toolInput !== "object") return "";
+  if (typeof toolInput.file_path === "string") return toolInput.file_path;
+  if (typeof toolInput.notebook_path === "string") return toolInput.notebook_path;
+  return "";
+}
+
+let stdin = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  stdin += chunk;
+});
+process.stdin.on("end", () => {
+  let payload;
+  try {
+    payload = JSON.parse(stdin);
+  } catch {
+    // malformed input — exit non-blocking so the run continues. user-only
+    // stderr per the hook contract.
+    process.stderr.write("infraweaver-pretool-gate: malformed stdin JSON\\n");
+    process.exit(1);
+  }
+  const toolName = typeof payload?.tool_name === "string" ? payload.tool_name : "";
+
+  // claude-code populates agent_id whenever a tool call originates inside
+  // a Task/Agent subagent dispatch (createBaseHookInput in claude-code
+  // source) — see the full contract note above the MCP deny branch below.
+  const agentId = typeof payload?.agent_id === "string" ? payload.agent_id : "";
+
+  // write-path enforcement. deliberately BEFORE the subagent MCP deny
+  // below: a disallowed write is disallowed whoever makes it, and the
+  // orchestrator does most of the writing. no guarded mode selected yet (or a
+  // non-guarded mode) leaves ORCHESTRATOR writes untouched.
+  if (WRITE_TOOLS.has(toolName)) {
+    // subagents are read-only, unconditionally — before the path policy, which
+    // only constrains paths for guarded modes and would otherwise let a
+    // Task-dispatched lens Write/Edit the orchestrator's tree mid-review (the
+    // read-only contract was previously prose-only for native file writes).
+    if (agentId) {
+      process.stderr.write(
+        "subagent attempted a native file write via '" + toolName + "'. " +
+          "subagents are read-only: they share the orchestrator's in-process working tree, " +
+          "and file mutations are reserved for the orchestrator. " +
+          "report findings back to the orchestrator and let it perform the write.\\n"
+      );
+      process.exit(2);
+    }
+    let refusal = null;
+    try {
+      const policy = readWritePolicy(WRITE_POLICY_PATH);
+      if (!policy) process.exit(0);
+      const rawPath = targetPathOf(payload?.tool_input);
+      // a write tool with no resolvable path (an unexpected shape from a future
+      // claude-code version) is passed through — the push-time guardrails still
+      // catch it, and failing closed on an unknown shape would break the run.
+      if (!rawPath) process.exit(0);
+      refusal = refuseWrite(policy, rawPath, policy.root);
+    } catch (err) {
+      // an unexpected fault while DECIDING must not become an allow. exit 1
+      // would mean "show the user and continue with the tool call" per the
+      // hook contract, so refuse explicitly instead.
+      process.stderr.write("write blocked (guardrail fault): " + String(err && err.message) + "\\n");
+      process.exit(2);
+    }
+    if (!refusal) process.exit(0);
+    process.stderr.write(refusal + "\\n");
+    process.exit(2);
+  }
+
+  // subagent discriminator: on the orchestrator's main thread agent_id is
+  // undefined. agent_type can be set on the orchestrator itself via --agent,
+  // so it's not a reliable subagent discriminator on its own; agent_id is.
+  // contract verified against @anthropic-ai/claude-code 2.1.220 (pinned in
+  // package.json; see CLAUDE_CODE_AGENT_ID_VERIFIED_VERSION + the version
+  // tripwire in claudePretoolGate.test.ts); re-verify createBaseHookInput if
+  // that bumps — if agent_id ever stops being populated the gate fails OPEN.
+  if (!agentId) process.exit(0);
+  const bare = stripMcpPrefix(toolName);
+  if (!SUBAGENT_DENIED_TOOLS.has(bare)) process.exit(0);
+  process.stderr.write(
+    "subagent attempted to call denied tool '" + bare + "'. " +
+      "subagents share the orchestrator's in-process working tree and toolState; " +
+      "state-changing MCP tools (checkout_pr, push_branch, create_pull_request_review, " +
+      "report_progress, etc.) are reserved for the orchestrator. " +
+      "report findings back to the orchestrator and let it perform the mutation.\\n"
+  );
+  process.exit(2);
+});
+`;
+}
+
+/**
+ * Settings JSON shape registered via `claude --settings <path>`. The
+ * matcher `^mcp__infraweaver__` is treated as a regex by claude-code's
+ * `matchesPattern` helper (anything outside `[a-zA-Z0-9_|]` triggers the
+ * regex branch — verified in src/utils/hooks.ts), so this anchors at the
+ * start of the tool name and fires for every Infraweaver MCP tool. We narrow
+ * inside the script itself rather than declaring per-tool matchers because
+ * the deny list is the source of truth.
+ *
+ * The hook process inherits the parent's PATH, so `node` resolves to the
+ * runner's node binary; the `--settings` flag accepts either a path or a
+ * literal JSON string per claude-code source `src/main.tsx` (`Path to a
+ * settings JSON file or a JSON string`), but we use a path so the script
+ * and its config sit side-by-side under `ctx.tmpdir`.
+ *
+ * `execToolDenyRules` are the native exec tools (Bash/Monitor/REPL/Workflow +
+ * their `Agent(...)` forms) to deny at a settings-source rule — the
+ * authoritative, bypass-immune layer. `--disallowedTools` alone (a `cliArg`
+ * deny) was observed to leak under `--dangerously-skip-permissions`, so the
+ * deny is carried here too. Both consumers use both returned fields: the flag
+ * `--settings` JSON (covers non-CI runs) writes the whole object, and
+ * `buildManagedSettings` (CI, /etc managed settings) spreads `hooks` and folds
+ * `permissions.deny` into its richer deny list.
+ */
+export function buildClaudePretoolGateSettings(
+  scriptAbsolutePath: string,
+  execToolDenyRules: string[],
+): {
+  hooks: {
+    PreToolUse: Array<{
+      matcher: string;
+      hooks: Array<{ type: "command"; command: string; timeout?: number }>;
+    }>;
+    /** layered in by writePretoolGateAssets so non-CI runs (no managed
+     * settings) still fire the gate-server Stop hook. */
+    Stop?: Array<{ hooks: Array<{ type: "command"; command: string }> }>;
+  };
+  permissions: { deny: string[] };
+} {
+  // shell-quote-safe because tmpdir paths created via node:fs.mkdtempSync
+  // don't contain spaces, but pass via a literal that node parses as a single
+  // argv entry to be defensive against future tmpdir layout changes.
+  const invoke = [
+    {
+      type: "command" as const,
+      command: `node ${JSON.stringify(scriptAbsolutePath)}`,
+      timeout: 5,
+    },
+  ];
+  return {
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: "^mcp__infraweaver__",
+          hooks: invoke,
+        },
+        {
+          // the native write tools, gated for allowed_paths / protected_paths.
+          // Built from CLAUDE_WRITE_TOOL_NAMES so the matcher and the set the
+          // script checks can't drift apart. Anchored `^(...)$` keeps the
+          // regex branch of claude-code's matchesPattern and avoids matching
+          // an unrelated tool that merely starts with "Edit".
+          matcher: `^(${CLAUDE_WRITE_TOOL_NAMES.join("|")})$`,
+          hooks: invoke,
+        },
+      ],
+    },
+    // copy so callers that extend the deny list (writePretoolGateAssets adds
+    // the harness-tmpdir fence) can't mutate the shared CLAUDE_EXEC_TOOL_DENY_RULES
+    // constant, which would grow it every run and leak into --disallowedTools.
+    permissions: { deny: [...execToolDenyRules] },
+  };
+}

package/src/agents/dispatchMetrics.ts

@@ -0,0 +1,162 @@
+/**
+ * Specialist-dispatch instrumentation.
+ *
+ * WHY THIS EXISTS. Review routing moved from a **count-parity** gate ("0 or 2+
+ * lenses, never exactly 1", gated on diff size) to **hypothesis coverage**
+ * (one specialist per falsifiable, load-bearing question, no size threshold).
+ * The evaluation that adopted it named its own risk plainly: the bar to
+ * dispatch *something* drops, each specialist re-reads the diff, so cost is
+ * "plausibly neutral-to-slightly-up" — and the recommendation was to ship it
+ * "behind a close watch on dispatch-rate/cost". See `docs/AGENT-HARDENING.md`.
+ *
+ * That watch never existed. Tokens were summed for the whole run with no split
+ * between the orchestrator and the subagents it dispatched, so the one number
+ * that would settle the question — what share of a run the specialists cost —
+ * was not observable at any point. "Plausibly neutral" was an assumption with
+ * no instrument behind it.
+ *
+ * WHAT IS MEASURED, AND HOW MUCH IT CAN BE TRUSTED. Two different qualities of
+ * signal, deliberately kept apart rather than blended into one number:
+ *
+ *   - **Dispatch counts are exact.** They are recorded from the actual Task
+ *     tool call, one per dispatch, not inferred from the event stream.
+ *   - **The token split is robust but coarse.** Tokens are attributed to
+ *     "orchestrator" vs "subagents", never per-lens. Per-session labels come
+ *     from `SessionLabeler`, whose own contract says its FIFO dispatch↔session
+ *     pairing is for log readability and is not depended on for correctness.
+ *     A mis-paired label would corrupt a *per-lens* number — but both sides of
+ *     a mis-pairing are still subagents, so the orchestrator/subagent split is
+ *     unaffected by exactly the weakness the labeler warns about. That is why
+ *     this file reports the split and not the breakdown.
+ *
+ * Deliberately NOT a database column. A new `WorkflowRun` field needs manual
+ * production DDL, and a metric nobody looks at is not a watch. This surfaces
+ * where the comparison actually gets made — the run's own log line and job
+ * summary — so "before/after the routing change" is two runs side by side.
+ */
+
+import { ORCHESTRATOR_LABEL } from "#app/agents/sessionLabeler";
+
+export interface DispatchTally {
+  /** subagent dispatches this run — exact, counted at the Task call. */
+  dispatches: number;
+  /** dispatch count per resolved label, e.g. `lens:iam-blast-radius`. */
+  byLabel: ReadonlyMap<string, number>;
+  /** billable tokens (input incl. cache + output) attributed to the orchestrator. */
+  orchestratorTokens: number;
+  /** …and to every subagent session combined. */
+  subagentTokens: number;
+}
+
+/**
+ * Per-run accumulator. Lives on `ToolState` and is written by whichever harness
+ * is driving, so the counts survive across agent invocations (post-run resume,
+ * transient-provider retry) the same way `usageEntries` does.
+ */
+export class DispatchRecorder {
+  #dispatches = 0;
+  readonly #byLabel = new Map<string, number>();
+  #orchestratorTokens = 0;
+  #subagentTokens = 0;
+
+  /** Record one subagent dispatch. Call at the Task tool_use, not at completion:
+   *  a dispatch that errors out still cost the decision and usually the tokens. */
+  recordDispatch(label: string): void {
+    this.#dispatches++;
+    this.#byLabel.set(label, (this.#byLabel.get(label) ?? 0) + 1);
+  }
+
+  /**
+   * Attribute billable tokens to a session label. Anything that is not the
+   * orchestrator counts as subagent — including a session the labeler could not
+   * name, because an unnamed session is by definition not the orchestrator's.
+   */
+  recordTokens(label: string, billableTokens: number): void {
+    if (!Number.isFinite(billableTokens) || billableTokens <= 0) return;
+    if (label === ORCHESTRATOR_LABEL) this.#orchestratorTokens += billableTokens;
+    else this.#subagentTokens += billableTokens;
+  }
+
+  tally(): DispatchTally {
+    return {
+      dispatches: this.#dispatches,
+      byLabel: new Map(this.#byLabel),
+      orchestratorTokens: this.#orchestratorTokens,
+      subagentTokens: this.#subagentTokens,
+    };
+  }
+}
+
+/** subagent share of attributed tokens, 0–1. Null when nothing was attributed —
+ *  distinct from 0, which means specialists genuinely cost nothing. */
+export function subagentTokenShare(tally: DispatchTally): number | null {
+  const total = tally.orchestratorTokens + tally.subagentTokens;
+  if (total <= 0) return null;
+  return tally.subagentTokens / total;
+}
+
+const pct = (share: number): string => `${(share * 100).toFixed(1)}%`;
+const fmt = (n: number): string => n.toLocaleString("en-US");
+
+/** One stdout line. Empty when the run dispatched nothing AND attributed nothing —
+ *  a solo run has no routing to report and the line would be noise. */
+export function describeDispatchTally(tally: DispatchTally): string {
+  const share = subagentTokenShare(tally);
+  if (tally.dispatches === 0 && share === null) return "";
+  if (tally.dispatches === 0) return "» specialist dispatch: none this run";
+  const labels = [...tally.byLabel.entries()]
+    .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+    .map(([label, n]) => (n > 1 ? `${label}×${n}` : label))
+    .join(", ");
+  const cost =
+    share === null
+      ? "token split unavailable"
+      : `${pct(share)} of billable tokens (${fmt(tally.subagentTokens)} of ${fmt(
+          tally.orchestratorTokens + tally.subagentTokens,
+        )})`;
+  return `» specialist dispatch: ${tally.dispatches} (${labels}) — ${cost}`;
+}
+
+/**
+ * Markdown block for the GitHub job summary, rendered beside the usage table.
+ * Collapsed like the usage table so it costs nothing to ignore, and carries its
+ * own accuracy caveat: a reader comparing two runs needs to know the split is
+ * coarse before they draw a conclusion from it.
+ */
+export function formatDispatchSummary(tally: DispatchTally): string {
+  const share = subagentTokenShare(tally);
+  if (tally.dispatches === 0 && share === null) return "";
+
+  const lines: string[] = [
+    "<details>",
+    "<summary>Specialist dispatch</summary>",
+    "",
+    `- **Dispatches:** ${tally.dispatches}`,
+  ];
+
+  if (tally.dispatches > 0) {
+    const rows = [...tally.byLabel.entries()].sort(
+      (a, b) => b[1] - a[1] || a[0].localeCompare(b[0]),
+    );
+    for (const [label, n] of rows) lines.push(`  - \`${label}\` — ${n}`);
+  }
+
+  if (share === null) {
+    lines.push("- **Token split:** unavailable (no usage was attributed this run)");
+  } else {
+    lines.push(
+      `- **Orchestrator:** ${fmt(tally.orchestratorTokens)} billable tokens`,
+      `- **Subagents:** ${fmt(tally.subagentTokens)} billable tokens (${pct(share)})`,
+    );
+  }
+
+  lines.push(
+    "",
+    "> Dispatch counts are exact. The token split is orchestrator-vs-subagent only —",
+    "> per-lens attribution would rest on the session labeler's FIFO pairing, which is",
+    "> maintained for log readability and not relied on for correctness.",
+    "",
+    "</details>",
+  );
+  return lines.join("\n");
+}

package/src/agents/gateServer.ts

@@ -0,0 +1,178 @@
+/**
+ * gate server — localhost HTTP sidecar that returns Stop-hook decisions for
+ * the Claude harness. the managed Stop hook (see `action/agents/claude.ts`)
+ * curls this server on every stop and writes back the resulting
+ * `{decision: "block", reason}` to inject a follow-up turn inside the live
+ * `queryLoop`, replacing the pre-PR-#795 `--resume <sessionId>` subprocess.
+ *
+ * the server captures `ctx` by closure so every request reads the latest
+ * mutations from MCP tool callbacks (which run in the same process). the
+ * counters live here, not on `toolState`, because gate-retry budget and
+ * reflection one-shot are harness concerns the literal `toolState` design
+ * rule (see `action/toolState.ts`) explicitly excludes.
+ *
+ * decision policy mirrors the old `runPostRunRetryLoop`:
+ *   - gates dirty + budget remaining → block with combined gate prompt
+ *   - gates clean + reflection pending → block with reflection prompt
+ *   - otherwise → allow stop
+ * `summaryStale` is a one-shot nudge; once delivered the gate is suppressed
+ * so a deliberately-unchanged file doesn't burn the retry budget. when the
+ * budget is exhausted with hard-fail gates still failing, we allow the stop
+ * so `finalizeAgentResult` can render the terminal `AgentResult.success =
+ * false` — that state cannot be set from a stdout-only hook.
+ */
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import {
+  buildLearningsReflectionPrompt,
+  buildPostRunPrompt,
+  collectPostRunIssues,
+  shouldRunReflection,
+} from "#app/agents/postRun";
+import { type AgentRunContext, hasPostRunIssues, MAX_POST_RUN_RETRIES } from "#app/agents/shared";
+import { log } from "#app/utils/cli";
+
+export interface GateServerHandle {
+  url: string;
+  // bearer token the Stop hook must present. Passed to the agent process via a
+  // `_TOKEN`-suffixed env var so filterEnv() strips it from the agent's shell
+  // sandbox — only the real Stop hook (a child of the agent process, inheriting
+  // its full env) can read it. Without this, any loopback caller (incl. the
+  // agent) could poison the retry budget by hitting GET /gates.
+  token: string;
+  [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+export async function startGateServer(ctx: AgentRunContext): Promise<GateServerHandle> {
+  let blockCount = 0;
+  let reflectionDelivered = false;
+  let summaryStaleNudged = false;
+  // task output captured when the reflection nudge is delivered, restored on the
+  // next /gates call so a set_output during reflection can't clobber the result.
+  // a flag (not an undefined sentinel) because the snapshot value may itself be
+  // undefined and must still be restored over a reflection-set value.
+  let reflectionOutputPending = false;
+  let reflectionOutputSnapshot: string | undefined;
+  // set when a block decision was confirmed delivered; cleared when the Stop
+  // hook comes back for another decision. a run that ends with this still set
+  // means the hook received a block but claude never re-stopped — worth a log
+  // line, since it points at a lost injection rather than a served one.
+  let blockAwaitingRefetch = false;
+  const token = randomUUID();
+
+  const server = createServer((req, res) => {
+    void (async () => {
+      if (req.method !== "GET" || req.url !== "/gates") {
+        res.writeHead(404).end();
+        return;
+      }
+      // Authenticate before reading state or mutating counters — an unauthorized
+      // request must not consume the retry budget.
+      if (req.headers.authorization !== `Bearer ${token}`) {
+        res.writeHead(403).end();
+        return;
+      }
+      blockAwaitingRefetch = false;
+      // send a decision and run `commit` (the state mutation that decision
+      // implies — budget consumed, one-shots latched) only once the response
+      // has actually flushed to the hook. the Stop hook's curl has a 30s
+      // timeout and an `|| {"block":false}` fallback, so mutating BEFORE
+      // delivery meant one hiccup silently burned a retry or the reflection
+      // one-shot with no log of the mismatch. an undelivered decision now
+      // leaves the state untouched and is retried on the next stop.
+      const send = (body: string, commit?: () => void): void => {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.on("close", () => {
+          if (res.writableFinished) {
+            commit?.();
+          } else {
+            log.warning(
+              "» gate-server: decision response was not delivered (connection closed early) — state not mutated, will re-decide on the next stop",
+            );
+          }
+        });
+        res.end(body);
+      };
+      try {
+        const issues = await collectPostRunIssues(ctx, { skipSummaryStale: summaryStaleNudged });
+        if (hasPostRunIssues(issues)) {
+          if (blockCount >= MAX_POST_RUN_RETRIES) {
+            log.info("» gate-server: retry budget exhausted, allowing stop for terminal hard-fail");
+            send('{"block":false}');
+            return;
+          }
+          const reason = buildPostRunPrompt(issues);
+          const attempt = blockCount + 1;
+          log.info(`» gate-server: blocking (attempt ${attempt}/${MAX_POST_RUN_RETRIES})`);
+          send(JSON.stringify({ block: true, reason }), () => {
+            if (issues.summaryStale) summaryStaleNudged = true;
+            blockCount = attempt;
+            blockAwaitingRefetch = true;
+          });
+          return;
+        }
+        // the reflection turn just delivered (previous /gates call) may have
+        // clobbered the task output: some models re-trigger the "call set_output
+        // when done" instruction during reflection and overwrite the real result
+        // with "done". restore the snapshot taken when we delivered it — the
+        // same defense the opencode runPostRunRetryLoop applies. The prompt-level
+        // "do NOT call set_output" instruction is defense one; this is defense two.
+        if (reflectionOutputPending) {
+          ctx.toolState.output = reflectionOutputSnapshot;
+          reflectionOutputPending = false;
+        }
+        const learningsPath = ctx.toolState.learningsFilePath;
+        if (
+          !reflectionDelivered &&
+          learningsPath &&
+          shouldRunReflection(ctx.toolState.selectedMode)
+        ) {
+          const reason = buildLearningsReflectionPrompt(learningsPath);
+          log.info("» gate-server: delivering reflection nudge");
+          send(JSON.stringify({ block: true, reason }), () => {
+            reflectionDelivered = true;
+            reflectionOutputSnapshot = ctx.toolState.output;
+            reflectionOutputPending = true;
+            blockAwaitingRefetch = true;
+          });
+          return;
+        }
+        send('{"block":false}');
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        log.warning(`» gate-server handler error: ${msg}`);
+        // never block claude on a server-side fault — allow the stop and
+        // let the harness's terminal hard-fail path own the decision.
+        send('{"block":false}');
+      }
+    })();
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+  const addr = server.address();
+  if (!addr || typeof addr === "string") {
+    throw new Error("gate-server: failed to bind localhost port");
+  }
+  const url = `http://127.0.0.1:${addr.port}/gates`;
+  log.debug(`» gate-server listening at ${url}`);
+
+  return {
+    url,
+    token,
+    [Symbol.asyncDispose]: async () => {
+      if (blockAwaitingRefetch) {
+        // the hook confirmed receipt of a block decision but claude never
+        // stopped again — the injected turn was lost downstream (e.g. the
+        // hook script failed after the curl). budget was already consumed;
+        // surface the mismatch instead of losing it silently.
+        log.warning(
+          "» gate-server: a delivered block decision was never followed by another stop — the injected follow-up turn may have been lost",
+        );
+      }
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    },
+  };
+}

package/src/agents/index.ts

@@ -0,0 +1,10 @@
+import { claude } from "#app/agents/claude";
+// In-process OpenCode harness, adapted to opencode-ai >=1.14.x SDK-v2 /
+// Effect-ts CLI rewrite. (The legacy CLI-subprocess harness was removed; see
+// git history if a revert is ever needed.)
+import { opencode } from "#app/agents/opencode";
+import type { Agent } from "#app/agents/shared";
+
+export type { Agent, AgentUsage } from "#app/agents/shared";
+
+export const agents = { claude, opencode } satisfies Record<string, Agent>;