terramend 0.2.0

package/src/agents/shared.ts

@@ -0,0 +1,292 @@
+import { execFileSync } from "node:child_process";
+import type { AgentId } from "#app/external";
+import type { ToolState } from "#app/toolState";
+import { log } from "#app/utils/cli";
+import type { ResolvedInstructions } from "#app/utils/instructions";
+import type { ResolvedPayload } from "#app/utils/payload";
+import type { TodoTracker } from "#app/utils/todoTracking";
+
+// maximum number of stderr lines to keep in the rolling buffer during agent execution
+export const MAX_STDERR_LINES = 20;
+
+// ── post-run retry loop ────────────────────────────────────────────────────────
+
+/**
+ * how many times the post-run loop may resume the agent to fix a dirty tree
+ * or a failing stop hook before giving up.
+ */
+export const MAX_POST_RUN_RETRIES = 3;
+
+export function getGitStatus(): string {
+  try {
+    return execFileSync("git", ["status", "--porcelain"], {
+      encoding: "utf-8",
+      timeout: 10_000,
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
+export function buildCommitPrompt(status: string): string {
+  return [
+    `UNCOMMITTED CHANGES — the working tree is dirty. push all changes to a pull request (new or existing). \`git status\` must be clean before you finish.`,
+    "",
+    "```",
+    status,
+    "```",
+  ].join("\n");
+}
+
+export interface StopHookFailure {
+  exitCode: number;
+  output: string;
+}
+
+export interface SummaryStale {
+  /** absolute path to the seeded snapshot file the agent was meant to edit. */
+  filePath: string;
+}
+
+export interface PostRunIssues {
+  stopHook?: StopHookFailure;
+  dirtyTree?: string;
+  /** populated when the rolling PR summary file is byte-identical to its
+   * seed, i.e. the agent never touched it. soft gate — nudges once via a
+   * resume turn but never fails the run, parallel to dirtyTree semantics. */
+  summaryStale?: SummaryStale;
+  /**
+   * populated when the agent selected a review mode but the post-run check
+   * over toolState shows neither a `create_pull_request_review` submission
+   * nor a final `report_progress` write happened. derived inline from
+   * `toolState.selectedMode` + `toolState.review` + `toolState.finalSummaryWritten`
+   * via {@link getUnsubmittedReview} — no parallel toolState flag is stored.
+   * carries the mode name so the resume prompt can reference it. handled like
+   * `stopHook`: nudge via resume, hard-fail if still unsatisfied after
+   * `MAX_POST_RUN_RETRIES`.
+   */
+  unsubmittedReview?: "Review" | "IncrementalReview";
+}
+
+export function hasPostRunIssues(issues: PostRunIssues): boolean {
+  return (
+    issues.stopHook !== undefined ||
+    issues.dirtyTree !== undefined ||
+    issues.summaryStale !== undefined ||
+    issues.unsubmittedReview !== undefined
+  );
+}
+
+/**
+ * token/cost usage data from a single agent run.
+ *
+ * NOTE on semantics: `inputTokens` here is the *total* billable input for the
+ * run — non-cached input + cache read + cache write — matching the per-agent
+ * SDK conventions. This is what gets persisted to `WorkflowRun.inputTokens`.
+ *
+ * The stdout token table and markdown step summary display a different "Input"
+ * column that shows only the non-cached portion (derivable as
+ * `inputTokens - cacheReadTokens - cacheWriteTokens`) so humans can see the
+ * cache hit ratio at a glance. Dashboards that query `WorkflowRun.inputTokens`
+ * directly are seeing the full total, not the log column.
+ */
+export interface AgentUsage {
+  agent: string;
+  /** full billable input: non-cached + cache read + cache write */
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number | undefined;
+  cacheWriteTokens?: number | undefined;
+  costUsd?: number | undefined;
+}
+
+export interface AgentToolUseEvent {
+  toolName: string;
+  input: unknown;
+}
+
+/**
+ * Result returned by agent execution
+ */
+export interface AgentResult {
+  success: boolean;
+  output?: string | undefined;
+  error?: string | undefined;
+  metadata?: Record<string, unknown>;
+  usage?: AgentUsage | undefined;
+}
+
+/**
+ * Env var that carries the per-run MCP bearer token to BOTH agent harnesses,
+ * which reference it from their MCP client config so the on-disk/in-config form
+ * holds only a placeholder, never the raw token:
+ *   - Claude Code expands `${TERRAMEND_MCP_TOKEN}` in .mcp.json headers.
+ *   - opencode expands `{env:TERRAMEND_MCP_TOKEN}` in remote-MCP headers.
+ * The `_TOKEN` suffix also makes filterEnv() strip it from the MCP shell
+ * sandbox. Set only on the agent/server spawn env (never process.env), so a
+ * co-located dependency-install subprocess never inherits it. See
+ * ToolContext.mcpServerToken and gateServer.ts for the same pattern.
+ */
+export const MCP_SERVER_TOKEN_ENV = "TERRAMEND_MCP_TOKEN";
+
+/**
+ * Context passed to agent.run() and threaded through the post-run loop.
+ *
+ * design rule: this is the single object that flows through the harness and
+ * downstream utilities by reference. derived predicates (e.g.
+ * `getUnsubmittedReview`), tmpfile paths, and seed bytes live on
+ * `toolState` — read them at the call site, do not duplicate them onto this
+ * interface. utilities that need run state should accept `ctx` whole, not
+ * destructure a narrow subset.
+ */
+export interface AgentRunContext {
+  payload: ResolvedPayload;
+  resolvedModel?: string | undefined;
+  mcpServerUrl: string;
+  /** per-run bearer token the agent's MCP client presents to mcpServerUrl. See
+   * ToolContext.mcpServerToken — delivered to the client config out-of-band so
+   * it never lands in a readable file. */
+  mcpServerToken: string;
+  tmpdir: string;
+  /** harness-owned secret paths that agent filesystem tools must never read. */
+  secretDenyPaths?: string[] | undefined;
+  instructions: ResolvedInstructions;
+  todoTracker?: TodoTracker | undefined;
+  /**
+   * user-configured stop hook script. runs after the agent finishes each
+   * attempt; non-zero exit resumes the agent with the hook output as
+   * guidance. null when the repo has no stop hook configured.
+   */
+  stopScript?: string | null | undefined;
+  /**
+   * mutable per-run state shared with the MCP server (by reference). post-run
+   * gates read fresh values from it after each agent attempt — `summaryFilePath`,
+   * `summarySeed`, `selectedMode`, `review`, `finalSummaryWritten`,
+   * `hadProgressComment` are all consulted by `collectPostRunIssues`. see
+   * `action/toolState.ts` for the literal-state design rule.
+   */
+  toolState: ToolState;
+  /**
+   * called synchronously when the agent subprocess is killed for inner
+   * activity timeout. lets main.ts tear down shared resources (MCP HTTP
+   * server) so lingering SSE reconnects don't keep the outer timer alive.
+   */
+  onActivityTimeout?: (() => void) | undefined;
+  onToolUse?: ((event: AgentToolUseEvent) => void) | undefined;
+  /**
+   * Terramend API JWT scoped to this run. agents only need this when they
+   * have to write state back to Terramend mid-run (today: opencode.ts uses
+   * it to seed the post-hook's writeback envelope for Codex auth refresh).
+   * empty string when the run wasn't context-resolved (e.g. local dry-runs).
+   */
+  apiToken: string;
+}
+
+export interface Agent {
+  name: AgentId;
+  install: (token?: string) => Promise<string>;
+  run: (ctx: AgentRunContext) => Promise<AgentResult>;
+}
+
+export const agent = (input: Agent): Agent => {
+  return {
+    ...input,
+    run: async (ctx: AgentRunContext): Promise<AgentResult> => {
+      log.debug(`» payload: ${JSON.stringify(ctx.payload, null, 2)}`);
+      return input.run(ctx);
+    },
+  };
+};
+
+/** format a USD cost to 4 decimal places, always showing the leading zero */
+export function formatCostUsd(costUsd: number): string {
+  return costUsd.toFixed(4);
+}
+
+/**
+ * merge two AgentUsage snapshots into one running total.
+ *
+ * both agent harnesses invoke their runner multiple times per `run()` when the
+ * post-run retry loop kicks in (MAX_POST_RUN_RETRIES). each invocation
+ * produces its own AgentUsage; we sum them so downstream callers (usage
+ * summary, WorkflowRun persistence) see the whole session — not just the
+ * final retry's slice.
+ *
+ * returns `undefined` when both sides are empty so callers can short-circuit
+ * without a special case. zero-valued cache / cost fields are dropped to
+ * `undefined` for symmetry with each harness's `buildUsage`.
+ */
+export function mergeAgentUsage(
+  a: AgentUsage | undefined,
+  b: AgentUsage | undefined,
+): AgentUsage | undefined {
+  // always return a fresh object — callers treat AgentUsage as immutable, and
+  // returning `a` / `b` directly would leak that invariant to future callers
+  if (!a && !b) return undefined;
+  if (!a) return { ...(b as AgentUsage) };
+  if (!b) return { ...a };
+  const cacheRead = (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0);
+  const cacheWrite = (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0);
+  const cost = (a.costUsd ?? 0) + (b.costUsd ?? 0);
+  return {
+    agent: a.agent,
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    cacheReadTokens: cacheRead > 0 ? cacheRead : undefined,
+    cacheWriteTokens: cacheWrite > 0 ? cacheWrite : undefined,
+    costUsd: cost > 0 ? cost : undefined,
+  };
+}
+
+/**
+ * unified per-run token table used by every agent harness.
+ *
+ * columns are kept stable across agents and models so downstream log parsers
+ * (scripts/token-usage.ts, cost dashboards) only have to understand one format:
+ *
+ *   Input       non-cached input tokens sent this run
+ *   Cache Read  input tokens served from prompt cache (Anthropic, etc.)
+ *   Cache Write input tokens written to prompt cache this run
+ *   Output      assistant output tokens
+ *   Total       sum of the four columns — the real billable quantity
+ *   Cost ($)    USD cost reported by the provider (only rendered when known)
+ *
+ * models that don't report prompt caching leave Cache Read / Write at 0.
+ * OpenCode emits per-step `part.cost` sourced from models.dev (works across
+ * Anthropic, OpenAI, Google, xAI, DeepSeek, Moonshot, OpenRouter, etc.);
+ * Claude CLI emits `total_cost_usd` on its final `result` event. pass the
+ * accumulated value via `costUsd` to render the Cost column.
+ */
+export function logTokenTable(t: {
+  input: number;
+  cacheRead: number;
+  cacheWrite: number;
+  output: number;
+  costUsd?: number | undefined;
+}): void {
+  const total = t.input + t.cacheRead + t.cacheWrite + t.output;
+  // narrow costUsd to a concrete number so the render path doesn't need a cast
+  const costUsd = typeof t.costUsd === "number" && t.costUsd > 0 ? t.costUsd : undefined;
+
+  const headerRow: Array<{ data: string; header: true }> = [
+    { data: "Input", header: true },
+    { data: "Cache Read", header: true },
+    { data: "Cache Write", header: true },
+    { data: "Output", header: true },
+    { data: "Total", header: true },
+  ];
+  const dataRow: string[] = [
+    String(t.input),
+    String(t.cacheRead),
+    String(t.cacheWrite),
+    String(t.output),
+    String(total),
+  ];
+
+  if (costUsd !== undefined) {
+    headerRow.push({ data: "Cost ($)", header: true });
+    dataRow.push(formatCostUsd(costUsd));
+  }
+
+  log.table([headerRow, dataRow]);
+}

package/src/agents/subagentModels.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import { deriveSubagentModels } from "#app/agents/subagentModels";
+
+describe("deriveSubagentModels", () => {
+  it("returns no override when orchestrator is undefined", () => {
+    expect(deriveSubagentModels(undefined)).toEqual({ reviewer: undefined });
+  });
+
+  it("returns no override when orchestrator slug isn't registered", () => {
+    expect(deriveSubagentModels("nonexistent/model")).toEqual({ reviewer: undefined });
+  });
+
+  describe("anthropic family — opus → sonnet", () => {
+    it("direct anthropic opus", () => {
+      expect(deriveSubagentModels("anthropic/claude-opus-4-8")).toEqual({
+        reviewer: "anthropic/claude-sonnet-4-6",
+      });
+    });
+    it("opencode-vendored opus stays on opencode prefix", () => {
+      expect(deriveSubagentModels("opencode/claude-opus-4-8")).toEqual({
+        reviewer: "opencode/claude-sonnet-4-6",
+      });
+    });
+    it("openrouter-anthropic-opus-via-anthropic-direct hits anthropic alias's openRouterResolve", () => {
+      // both the anthropic alias and the opencode alias have the same
+      // openRouterResolve. first-match-wins by alias declaration order
+      // (anthropic declared first in providers).
+      expect(deriveSubagentModels("openrouter/anthropic/claude-opus-4.8")).toEqual({
+        reviewer: "openrouter/anthropic/claude-sonnet-4.6",
+      });
+    });
+    it("sonnet has no further downshift", () => {
+      expect(deriveSubagentModels("anthropic/claude-sonnet-4-6")).toEqual({ reviewer: undefined });
+      expect(deriveSubagentModels("opencode/claude-sonnet-4-6")).toEqual({ reviewer: undefined });
+    });
+    it("haiku has no downshift", () => {
+      expect(deriveSubagentModels("anthropic/claude-haiku-4-5")).toEqual({ reviewer: undefined });
+    });
+  });
+
+  describe("openai family", () => {
+    it("gpt-pro → gpt (direct)", () => {
+      expect(deriveSubagentModels("openai/gpt-5.5-pro")).toEqual({ reviewer: "openai/gpt-5.5" });
+    });
+    it("gpt → gpt-5.4 (direct)", () => {
+      expect(deriveSubagentModels("openai/gpt-5.5")).toEqual({ reviewer: "openai/gpt-5.4" });
+    });
+    it("gpt → gpt-5.4 (opencode-vendored)", () => {
+      expect(deriveSubagentModels("opencode/gpt-5.5")).toEqual({ reviewer: "opencode/gpt-5.4" });
+    });
+    it("gpt-pro → gpt (openrouter)", () => {
+      expect(deriveSubagentModels("openrouter/openai/gpt-5.5-pro")).toEqual({
+        reviewer: "openrouter/openai/gpt-5.5",
+      });
+    });
+    it("gpt → gpt-5.4 (openrouter)", () => {
+      expect(deriveSubagentModels("openrouter/openai/gpt-5.5")).toEqual({
+        reviewer: "openrouter/openai/gpt-5.4",
+      });
+    });
+    it("gpt-5.4 itself (the hidden subagent target) has no further downshift", () => {
+      expect(deriveSubagentModels("openai/gpt-5.4")).toEqual({ reviewer: undefined });
+    });
+    it("gpt-mini has no downshift", () => {
+      expect(deriveSubagentModels("openai/gpt-5.4-mini")).toEqual({ reviewer: undefined });
+    });
+  });
+
+  describe("google (gemini) — inherit (Pro for both orchestrator and lenses)", () => {
+    // pro → flash was a meaningful capability cliff (Flash missed catastrophic
+    // cross-file bugs the v4 e2e test surfaced); Pro is cost-effective enough
+    // to keep on for lenses too. Google has no in-between tier.
+    it("direct google pro inherits", () => {
+      expect(deriveSubagentModels("google/gemini-3.1-pro-preview")).toEqual({
+        reviewer: undefined,
+      });
+    });
+    it("opencode-vendored gemini-pro inherits", () => {
+      expect(deriveSubagentModels("opencode/gemini-3.1-pro")).toEqual({
+        reviewer: undefined,
+      });
+    });
+    it("openrouter gemini-pro inherits", () => {
+      expect(deriveSubagentModels("openrouter/google/gemini-3.1-pro-preview")).toEqual({
+        reviewer: undefined,
+      });
+    });
+    it("flash has no downshift", () => {
+      expect(deriveSubagentModels("google/gemini-3-flash-preview")).toEqual({
+        reviewer: undefined,
+      });
+    });
+  });
+
+  describe("providers / models without a subagentModel — inherit", () => {
+    it("xai grok (already cheap flagship)", () => {
+      expect(deriveSubagentModels("xai/grok-4.3")).toEqual({ reviewer: undefined });
+    });
+    it("deepseek", () => {
+      expect(deriveSubagentModels("deepseek/deepseek-v4-pro")).toEqual({ reviewer: undefined });
+    });
+    it("moonshot kimi", () => {
+      expect(deriveSubagentModels("moonshotai/kimi-k2.6")).toEqual({ reviewer: undefined });
+    });
+    it("opencode big-pickle", () => {
+      expect(deriveSubagentModels("opencode/big-pickle")).toEqual({ reviewer: undefined });
+    });
+    it("legacy fallback aliases (gpt-codex, deepseek-reasoner)", () => {
+      expect(deriveSubagentModels("openai/gpt-5.3-codex")).toEqual({ reviewer: undefined });
+      expect(deriveSubagentModels("deepseek/deepseek-reasoner")).toEqual({ reviewer: undefined });
+    });
+  });
+});

package/src/agents/subagentModels.ts

@@ -0,0 +1,40 @@
+import { modelAliases } from "#app/models";
+
+/**
+ * Derive a cheaper subagent model override from the orchestrator's resolved
+ * model spec.
+ *
+ * This is a pure registry lookup: every alias in `action/models.ts` declares
+ * its own `subagentModel` (alias key in the same provider). At runtime we
+ * reverse-lookup the orchestrator's resolved slug to find the alias that
+ * produced it, follow the `subagentModel` pointer, and return the target
+ * alias's resolve / openRouterResolve depending on which route the
+ * orchestrator was using.
+ *
+ * Returns `{ reviewer: undefined }` when the orchestrator's alias has no
+ * `subagentModel` (e.g. it's already at a sufficiently cheap tier, or its
+ * provider doesn't have a clean cheaper-but-capable sibling). See models.ts
+ * for the wiring + per-provider rationale.
+ */
+export function deriveSubagentModels(orchestratorSpec: string | undefined): {
+  reviewer: string | undefined;
+} {
+  if (!orchestratorSpec) return { reviewer: undefined };
+
+  // Reverse-lookup. The same resolve string appears in only one alias
+  // (within its provider), so first match wins. We track which field
+  // matched (resolve vs openRouterResolve) so we can pick the same field
+  // off the subagent target — keeping the orchestrator's route consistent.
+  for (const source of modelAliases) {
+    const matchedDirect = source.resolve === orchestratorSpec;
+    const matchedOR = source.openRouterResolve === orchestratorSpec;
+    if (!matchedDirect && !matchedOR) continue;
+    if (!source.subagentModel) return { reviewer: undefined };
+    const target = modelAliases.find((a) => a.slug === source.subagentModel);
+    if (!target) return { reviewer: undefined };
+    const reviewer = matchedOR ? target.openRouterResolve : target.resolve;
+    return { reviewer };
+  }
+
+  return { reviewer: undefined };
+}

package/src/agents/subagentRegistration.test.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+
+const claudeSource = readFileSync(join(__dirname, "claude.ts"), "utf-8");
+const opencodeSharedSource = readFileSync(join(__dirname, "opencodeShared.ts"), "utf-8");
+const opencodeSource = readFileSync(join(__dirname, "opencode.ts"), "utf-8");
+
+/**
+ * The Claude Code `--agents` JSON and OpenCode `agent` config block are the
+ * only places where per-subagent model overrides take effect. They're built
+ * by string-only helpers we don't export, so this test reads the source and
+ * asserts the literal model strings + agent names are wired in. A regression
+ * here means the next review run silently runs lenses on Opus instead of
+ * Sonnet.
+ */
+describe("subagent registration source asserts", () => {
+  describe("claude.ts buildAgentsJson", () => {
+    it("registers review with sonnet model", () => {
+      expect(claudeSource).toMatch(
+        /\[REVIEWER_AGENT_NAME\]:\s*\{[^}]*model:\s*"claude-sonnet-4-6"/s,
+      );
+    });
+    it("imports the reviewer name constant", () => {
+      expect(claudeSource).toMatch(/REVIEWER_AGENT_NAME/);
+    });
+  });
+
+  describe("opencodeShared.ts buildReviewerAgentConfig", () => {
+    it("registers review with mode: subagent", () => {
+      expect(opencodeSharedSource).toMatch(/\[REVIEWER_AGENT_NAME\]:[^}]*mode:\s*"subagent"/s);
+    });
+    it("uses deriveSubagentModels for the reviewer model override", () => {
+      expect(opencodeSharedSource).toMatch(/deriveSubagentModels\(/);
+      expect(opencodeSharedSource).toMatch(/overrides\.reviewer/);
+    });
+    it("v2 runner passes orchestrator model to buildReviewerAgentConfig", () => {
+      expect(opencodeSource).toMatch(/buildReviewerAgentConfig\(model\)/);
+    });
+  });
+});

package/src/agents/subagentToolGates.ts

@@ -0,0 +1,114 @@
+/**
+ * Single source of truth for MCP tools subagents are forbidden from calling.
+ *
+ * Subagents share the orchestrator's in-process git working tree, `toolState`,
+ * progress comment, and run-scoped pr/branch context. A subagent that calls
+ * `checkout_pr` switches the orchestrator's HEAD; one that calls `push_branch`
+ * pushes whatever the orchestrator happens to have committed. The 2026-05-18
+ * `zed-industries/cloud` incident hit exactly this: a `reviewfrog` lens
+ * dispatched `checkout_pr({2582})` mid-review, the orchestrator's next push
+ * clobbered an unrelated engineer's branch. PR #796 added runtime backstops
+ * inside `checkout_pr`/`push_branch`; this list is the upstream gate that
+ * stops the call from ever reaching MCP when it originates from a subagent.
+ *
+ * The gate is enforced at two pre-tool hooks:
+ *   - opencode: `tool.execute.before` (action/agents/opencodePlugin.ts)
+ *   - claude:   `PreToolUse` settings hook (action/agents/claudePretoolGate.ts)
+ *
+ * Names are stored in their canonical bare form (the FastMCP tool `name`
+ * field). Each runtime presents them with a different prefix:
+ *   - claude:   `mcp__terramend__<name>`
+ *   - opencode: `terramend_<name>`
+ * The hooks strip those prefixes before comparing.
+ *
+ * Read-only MCP tools (`get_*`, `list_*`, `git_fetch`, `get_check_suite_logs`,
+ * `await_dependency_installation`, etc.) and the `git`/`shell` tools stay off
+ * this list — denying them would make review work impossible. The reviewer system prompt
+ * (`action/agents/reviewer.ts`) already forbids state-changing shell/git
+ * subcommands as a prose constraint; this list is the belt-and-suspenders
+ * machine fence for the high-stakes mutations we can identify by name alone.
+ *
+ * When adding a state-changing MCP tool to `action/mcp/server.ts`, add its
+ * canonical name here too. Inclusions justified inline.
+ */
+export const SUBAGENT_DENIED_TOOLS = [
+  // working-tree mutation: switches HEAD onto pr-N and registers a push remote
+  "checkout_pr",
+
+  // remote mutation: pushes commits / branches / tags / deletes a branch
+  "push_branch",
+  "push_tags",
+  "delete_branch",
+
+  // GitHub PR state mutation
+  "create_pull_request",
+  "update_pull_request_body",
+  // §27 — closes a (remediation) PR; a state-changing PR mutation.
+  "close_pull_request",
+
+  // GitHub comment / issue mutation
+  "create_issue",
+  "create_issue_comment",
+  "edit_issue_comment",
+  "reply_to_review_comment",
+
+  // GitHub review state mutation
+  "create_pull_request_review",
+  "resolve_review_thread",
+
+  // GitHub label mutation
+  "add_labels",
+
+  // run-state mutation: workflow output, progress comment, run mode select
+  "set_output",
+  "report_progress",
+  "select_mode",
+
+  // process / filesystem mutation outside the agent's intended scope
+  "start_dependency_installation",
+  "kill_background",
+  "upload_file",
+] as const;
+
+export type SubagentDeniedTool = (typeof SUBAGENT_DENIED_TOOLS)[number];
+
+/**
+ * Strip the runtime-specific MCP prefix from a tool name and return the
+ * canonical bare name (matching FastMCP's `name:` field). Returns the input
+ * unchanged if it doesn't carry a known prefix — keeping comparison simple
+ * for native (non-MCP) tools, which never appear on the deny list anyway.
+ */
+export function stripMcpPrefix(toolName: string): string {
+  // claude: `mcp__terramend__checkout_pr` → `checkout_pr`
+  if (toolName.startsWith("mcp__terramend__")) return toolName.slice("mcp__terramend__".length);
+  // opencode: `terramend_checkout_pr` → `checkout_pr`
+  if (toolName.startsWith("terramend_")) return toolName.slice("terramend_".length);
+  return toolName;
+}
+
+/**
+ * Whether `toolName` (in any runtime's prefix style) names a tool that
+ * subagents must not call.
+ */
+export function isSubagentDeniedTool(toolName: string): boolean {
+  const bare = stripMcpPrefix(toolName);
+  return (SUBAGENT_DENIED_TOOLS as readonly string[]).includes(bare);
+}
+
+/**
+ * Human-readable refusal surfaced to the model when a denied tool is gated.
+ * Phrased so a halfway-attentive subagent realises (a) the tool is denied to
+ * it specifically, (b) why (shared in-process state with the orchestrator),
+ * and (c) what to do instead (report findings; the orchestrator can call the
+ * tool directly).
+ */
+export function buildSubagentDenyMessage(toolName: string): string {
+  const bare = stripMcpPrefix(toolName);
+  return (
+    `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.`
+  );
+}