terramend 0.2.0

package/dist/agents/opencodePlugin.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Source for the opencode plugin we drop into the per-run tmpdir at
+ * `<XDG_CONFIG_HOME>/opencode/plugin/terramend-events.ts`. The harness already
+ * redirects `XDG_CONFIG_HOME` to `ctx.tmpdir/.config` (see `opencode.ts`
+ * `homeEnv`), so opencode's auto-discovery scans the tmpdir, never the user's
+ * working tree. opencode's `Global.Path.config` resolves to
+ * `path.join(xdgConfig, "opencode")` and the config layer auto-discovers
+ * plugins from every directory in its scan list — including
+ * `Global.Path.config` — by globbing `{plugin,plugins}/*.{ts,js}` via
+ * `ConfigPlugin.load(dir)`.
+ *
+ * We MUST NOT write into the user's repo working tree. The repo is a checkout
+ * the agent operates on; only the agent's own tools (gated by
+ * `OPENCODE_PERMISSION`) may modify it. The whole reason we redirect HOME and
+ * XDG_CONFIG_HOME is so harness-side files (config, plugins, scratch state)
+ * land in the tmpdir.
+ *
+ * Why the events plugin exists: opencode's `task` tool runs subagents
+ * in-process and the CLI's `cli/cmd/run.ts` event loop filters
+ * `part.sessionID !== sessionID`, so subagent-internal `message.part.updated`
+ * events are silently discarded before reaching our parent NDJSON stream.
+ * plugins, by contrast, receive EVERY bus event via `bus.subscribeAll()`
+ * regardless of session.
+ *
+ * The events plugin re-emits every relevant bus event onto opencode's stdout
+ * as a single JSON line wrapped in a sentinel envelope. our `runOpenCode`
+ * parser recognises the envelope, unpacks it, and routes the inner part
+ * through the existing handlers with a per-session label from `SessionLabeler`
+ * so each subagent's tool calls / text appear inline alongside the
+ * orchestrator's.
+ *
+ * The subagent gate (the `tool.execute.before` hook that hard-blocks
+ * state-mutating MCP tool calls from a subagent session) lives in a SEPARATE
+ * plugin — `TERRAMEND_OPENCODE_GATE_PLUGIN_SOURCE` below — because it's the
+ * load-bearing security fence and must ship into the opencode harness,
+ * whereas this events re-emitter was only needed by the legacy CLI-parsing
+ * path (the active `opencode.ts` reads subagent events directly off the SDK
+ * event stream, so it installs ONLY the gate plugin). Deny-list source of
+ * truth: `src/agents/subagentToolGates.ts`.
+ *
+ * Dumb plugin / smart parent split: the events plugin emits every part for
+ * every session. the parent dedupes against the orchestrator's own session id
+ * (which it already knows from the `init` event). this keeps the plugin trivial
+ * and keeps the per-session attribution logic on the parent side where the
+ * SessionLabeler already lives.
+ *
+ * Event-name prefixing: the wrapped event-type sentinel is
+ * `terramend_bus_event` — picked to be unmistakably ours so a future opencode
+ * release that introduces a coincidentally-named event type won't collide.
+ */
+export declare const TERRAMEND_BUS_EVENT_TYPE: "terramend_bus_event";
+export declare const TERRAMEND_OPENCODE_PLUGIN_FILENAME: "terramend-events.ts";
+export declare const TERRAMEND_OPENCODE_GATE_PLUGIN_FILENAME: "terramend-subagent-gate.ts";
+/**
+ * Source written verbatim to `<XDG_CONFIG_HOME>/opencode/plugin/terramend-events.ts`.
+ *
+ * - Structural typing only (no runtime import of `@opencode-ai/plugin`):
+ *   opencode installs that dep into the directory containing the plugin
+ *   alongside discovery, but a) the dep isn't required for the structural
+ *   shape we use, and b) keeping zero imports avoids any module-resolution
+ *   coupling to opencode's plugin-loader internals across versions.
+ * - default export is the plugin factory (opencode's plugin loader accepts
+ *   default exports as the server entrypoint).
+ * - we only forward `message.part.updated`. that's where the user-visible
+ *   subagent activity (tool calls, text, step transitions) lives. add more
+ *   event types here if the parent needs them.
+ * - JSON.stringify+single write keeps the line atomic up to PIPE_BUF (4KB on
+ *   Linux). longer parts may interleave with concurrent stdout writers; the
+ *   parser tolerates non-JSON lines (logs them at debug) so a torn line is a
+ *   missed event, not a crash.
+ */
+export declare const TERRAMEND_OPENCODE_PLUGIN_SOURCE: string;
+/**
+ * Standalone subagent gate plugin written to
+ * `<XDG_CONFIG_HOME>/opencode/plugin/terramend-subagent-gate.ts`. Installed by
+ * the in-process `opencode.ts` harness — the gate is the load-bearing security
+ * fence, so it ships independently of the events re-emitter above (which the
+ * in-process harness doesn't need).
+ *
+ * Hard-blocks state-mutating MCP tool calls originating from a subagent
+ * session via `tool.execute.before`, complementing the runtime backstops from
+ * PR #796 (action/mcp/checkout.ts, action/mcp/git.ts). Deny-list source of
+ * truth: `action/agents/subagentToolGates.ts`.
+ */
+export declare const TERRAMEND_OPENCODE_GATE_PLUGIN_SOURCE: string;

package/dist/agents/opencodeShared.d.ts

@@ -0,0 +1,40 @@
+export type OpenCodeConfig = {
+    mcp?: Record<string, unknown>;
+    permission?: Record<string, unknown>;
+    provider?: Record<string, unknown>;
+    agent?: Record<string, unknown>;
+    experimental?: Record<string, unknown>;
+    model?: string;
+    enabled_providers?: string[];
+    [key: string]: unknown;
+};
+/**
+ * Build the `provider.google.models[id].options` map that pins every direct-Google
+ * Gemini alias to `thinkingLevel: "high"`. Sourced from the model registry so
+ * adding/renaming a Google alias in `action/models.ts` flows through automatically.
+ */
+export declare function geminiHighThinkingOverrides(): Record<string, {
+    options: object;
+}>;
+/**
+ * Read-only `reviewfrog` subagent for lens-based review. Non-mutative +
+ * non-recursive — enforced by the system prompt in reviewer.ts.
+ *
+ * Per-subagent `model:` override is driven by the registry in
+ * `action/models.ts` via each alias's `subagentModel` field. Currently wired:
+ * Anthropic opus → sonnet, OpenAI gpt-pro → gpt and gpt → gpt-5.4, Google
+ * gemini-pro → gemini-flash. Other providers inherit (no override).
+ */
+export declare function buildReviewerAgentConfig(orchestratorModel: string | undefined): Record<string, unknown>;
+/**
+ * Install the opencode-ai npm tarball and return the path to the executable.
+ *
+ * The bin path differs by version: v1.4.x and earlier shipped `bin/opencode`;
+ * v1.14+ renames the platform-specific binary to `bin/opencode.exe` for every
+ * OS via the postinstall script. Callers pass the binPath that matches their
+ * pinned version so a v1↔v2 swap can't silently install the wrong file.
+ */
+export declare function installOpencodeCli(params: {
+    binPath: string;
+}): Promise<string>;
+export declare function autoSelectModel(): string | undefined;

package/dist/agents/postRun.d.ts

@@ -0,0 +1,132 @@
+import { type AgentResult, type AgentRunContext, type AgentUsage, type PostRunIssues, type StopHookFailure } from "#app/agents/shared";
+import type { ToolState } from "#app/toolState";
+/**
+ * derive "agent picked a review mode but never produced visible output" from
+ * the literal facts on `toolState`. returns the selected mode when the gate
+ * should fire, `null` otherwise — pure read, no side effects, safe to invoke
+ * after every agent attempt.
+ *
+ * the gate is anchored to `hadProgressComment` so silent runs (non-issue
+ * events, dispatcher skipped seeding) don't fire a nudge there's no UI for.
+ *
+ * `Review` and `IncrementalReview` have different valid exits:
+ *   - Review: only `create_pull_request_review` counts. `report_progress` is
+ *     not a substitute — a Review run that exits with just a summary comment
+ *     has produced nothing reviewable on the PR. matches the hard-fail
+ *     message at `expected = "create_pull_request_review"` below.
+ *   - IncrementalReview: `report_progress` is a legitimate "no review
+ *     warranted" exit, so either toolState flag short-circuits.
+ * splitting per mode also closes the bypass where a subagent (e.g. a
+ * `task`-dispatched `reviewfrog` lens) calls `report_progress` and silences
+ * the gate even though the orchestrator never submitted a review.
+ */
+export declare function getUnsubmittedReview(toolState: ToolState): "Review" | "IncrementalReview" | null;
+/**
+ * run the user-configured stop hook.
+ *
+ * parallel to `executeLifecycleHook` (which soft-fails with a warning), but
+ * returns structured output so agent harnesses can feed the failure back into
+ * the session as a resume prompt.
+ *
+ * - non-zero exit → `StopHookFailure`, actionable: the output is fed to the
+ *   agent so it can fix the underlying issue.
+ * - timeout / spawn error → null, treated as passed: we can't usefully ask the
+ *   agent to fix an infrastructure problem, and retrying would risk infinite
+ *   loops.
+ */
+export declare function executeStopHook(script: string): Promise<StopHookFailure | null>;
+export declare function buildStopHookPrompt(failure: StopHookFailure): string;
+export declare function buildSummaryStalePrompt(filePath: string): string;
+export declare function buildUnsubmittedReviewPrompt(mode: "Review" | "IncrementalReview"): string;
+/**
+ * check the post-run gates: did the stop hook pass, is the working tree
+ * clean, and (when applicable) did the agent touch the rolling PR summary
+ * snapshot or produce review output? returns everything that still needs
+ * nudging so the caller can render a single combined resume prompt.
+ *
+ * reads run state directly off `ctx.toolState` so each invocation sees the
+ * latest mutations from MCP tool calls. `skipSummaryStale` lets the loop
+ * suppress the summary-stale check after the one-shot nudge has been
+ * delivered (re-firing it would burn the retry budget on a soft gate the
+ * agent has already decided not to act on).
+ */
+export declare function collectPostRunIssues(ctx: AgentRunContext, options?: {
+    skipSummaryStale?: boolean;
+}): Promise<PostRunIssues>;
+export declare function buildPostRunPrompt(issues: PostRunIssues): string;
+/**
+ * terminal-only post-run finalize: re-checks the hard-fail gates after the
+ * agent has exited and converts a successful result to a hard-fail when
+ * `stopHook` or `unsubmittedReview` is still failing. used by harnesses
+ * that inject follow-up turns via a mechanism other than the resume
+ * callback (e.g. the Claude managed Stop hook + gate server). soft gates
+ * (`dirtyTree`, `summaryStale`) are intentionally not re-checked here —
+ * they never flip a successful run to failed.
+ */
+export declare function finalizeAgentResult<R extends AgentResult>(params: {
+    ctx: AgentRunContext;
+    result: R;
+}): Promise<R>;
+export declare function shouldRunReflection(mode: string | undefined): boolean;
+/**
+ * prompt for a dedicated post-run reflection turn nudging the agent to edit
+ * the rolling learnings file if it discovered anything worth persisting.
+ *
+ * this exists because passive "if you learned something, write it down"
+ * instructions baked into mode checklists are frequently ignored — the agent
+ * stays focused on the task and the meta-ask falls through. delivering it
+ * as its own resume turn, with nothing competing for attention, raises the
+ * fire rate substantially.
+ *
+ * the file is the single source of truth — there is no separate MCP tool
+ * call. the server reads the file at end-of-run and persists any edits to
+ * `Repo.learnings`.
+ *
+ * the prompt copy is shaped by repo-wide audits of the actual content the
+ * agent has been writing (issue #619 in terramend/app). recurring failure
+ * modes the framing pushes back on:
+ *  - massive multi-paragraph "bullets" that are really mini-articles
+ *  - facts anchored to moving repo state (PR / review / commit / branch
+ *    refs, dates, version pins, line numbers) that decay within weeks
+ *  - sections growing into giant flat lists with no internal structure,
+ *    forcing future runs to read kilobytes to find one fact
+ *
+ * single litmus delivered in the prompt: "would a future run on this repo
+ * do its work better because this bullet exists?". tool-quirk workarounds
+ * are explicitly allowed when the agent burned calls discovering the
+ * quirk this run — recording the workaround prevents next run from
+ * repeating the waste. tradeoff: the same quirk gets duplicated across
+ * repos, so when a quirk is fixed upstream in tool descriptions the
+ * per-repo bullets go stale and we have no batch-invalidation path.
+ */
+export declare function buildLearningsReflectionPrompt(filePath: string): string;
+/**
+ * shared post-run retry loop used by every agent harness.
+ *
+ * checks the post-run gates (stop hook + dirty tree), and if either is
+ * failing, invokes `resume` to let the agent fix and push in the same turn.
+ * bails at `MAX_POST_RUN_RETRIES` attempts. the `canResume` predicate is
+ * consulted before each retry — harnesses that can't re-enter the session
+ * (e.g. claude without a sessionId) return false here.
+ *
+ * an optional `reflectionPrompt` fires exactly once, after the gates first
+ * observe a clean state. it's a one-shot nudge (e.g. "update learnings if
+ * relevant"), not a gate, so it does not consume the gate-retry budget. if
+ * the reflection turn dirties the tree, the loop picks that up on the next
+ * iteration via the normal dirty-tree gate.
+ *
+ * stop hook must pass for the run to succeed; persistent hook failures are
+ * surfaced as `AgentResult.error`. dirty-tree-only failures preserve prior
+ * behavior: they're logged but don't fail the run.
+ */
+export declare function runPostRunRetryLoop<R extends AgentResult>(params: {
+    ctx: AgentRunContext;
+    initialResult: R;
+    initialUsage: AgentUsage | undefined;
+    resume: (context: {
+        prompt: string;
+        previousResult: R;
+    }) => Promise<R>;
+    canResume?: ((result: R) => boolean) | undefined;
+    reflectionPrompt?: string | undefined;
+}): Promise<AgentResult>;

package/dist/agents/reviewer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Definition of the `reviewfrog` named subagent — the constrained
+ * read-only worker dispatched by Build mode self-review and the in-Terramend
+ * /anneal multi-lens review.
+ *
+ * The contract: non-mutative + non-recursive.
+ *   allow: file reads, grep/glob, web search/fetch, read-only MCP queries
+ *   deny:  state-changing MCP tools, file writes, shell, nested subagent dispatch
+ *
+ * Enforcement is now belt-and-suspenders:
+ *   1. Machine-enforced PreToolUse gates intercept every state-mutating MCP
+ *      tool call originating from a subagent session and refuse it before
+ *      MCP runs. See action/agents/subagentToolGates.ts (the deny list),
+ *      action/agents/claudePretoolGate.ts (Claude Code's PreToolUse hook),
+ *      and action/agents/opencodePlugin.ts (opencode's tool.execute.before
+ *      hook). Followed PR #796 which added runtime backstops inside
+ *      checkout_pr / push_branch after a subagent-originated tool call
+ *      clobbered an unrelated PR branch in zed-industries/cloud.
+ *   2. The prose system prompt below as a backup against (a) tools added
+ *      to the MCP server without a corresponding deny-list update, and
+ *      (b) shell/git read-vs-write distinctions the static gate can't see.
+ *      It states the rule as a no-op-if-reverted invariant the model can
+ *      apply to any tool, including ones added after this comment was
+ *      written.
+ *
+ * Historical note: per-agent `disallowedTools` in claude-code is upstream-
+ * broken for subagent-spawned tool calls (anthropics/claude-agent-sdk-
+ * typescript#172, open as of Mar 2026), which is why the gate runs at
+ * PreToolUse rather than tool-registration time.
+ */
+export declare const REVIEWER_AGENT_NAME = "reviewfrog";
+/**
+ * System prompt baked into the named reviewer subagent. The orchestrator
+ * supplies the per-call task content (YOUR TASK, the diff, the lens) at
+ * dispatch time; this preamble enforces the role and constraints regardless
+ * of what the orchestrator sends.
+ */
+export declare const REVIEWER_SYSTEM_PROMPT: string;

package/dist/agents/sessionLabeler.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Track per-session labels so log lines from parallel subagents can be
+ * differentiated. The orchestrator dispatches lens subagents
+ * via the Task tool; each subagent runs in its own opencode/claude Session
+ * with its own `sessionID` (or `session_id`) tag on the NDJSON event stream.
+ *
+ * Without per-session prefixing, parallel subagent tool_use / tool_result /
+ * text events appear as a single interleaved stream tagged with `[Terramend]`,
+ * making it impossible for a human reading the logs to attribute work to a
+ * specific lens.
+ *
+ * The labeler is deliberately runtime-agnostic — both opencode.ts and
+ * claude.ts feed it the same shape. The contract is FIFO: when the orchestrator
+ * dispatches N task tool_use blocks in a single assistant turn (the parallel
+ * fan-out the multi-lens prompt requires), the i-th new sessionID is assumed
+ * to belong to the i-th task dispatch. This is correct as long as parallel
+ * dispatches are emitted in source-order and the runtimes respect that order
+ * when assigning child sessions; we do not depend on it for correctness of
+ * the read-only contract — only for log readability.
+ */
+export interface TaskDispatchInput {
+    description?: string | undefined;
+    subagent_type?: string | undefined;
+    prompt?: string | undefined;
+}
+export declare const ORCHESTRATOR_LABEL = "orchestrator";
+/**
+ * Extract a human-readable label from a Task tool's input. Tries (in order):
+ *   1. explicit `lens: <name>` marker on a line in the prompt — preferred,
+ *      lets the orchestrator name the lens deterministically
+ *   2. the Task tool's `description` field — short, written by orchestrator
+ *      per call, usually enough
+ *   3. the `subagent_type` — falls back to the named
+ *      subagent identity when description is missing
+ *   4. generic "subagent" — last resort
+ */
+export declare function deriveLabelFromTaskInput(input: TaskDispatchInput): string;
+/**
+ * Stateful tracker mapping subagent activity back to human-readable labels.
+ *
+ * Two attribution channels are supported because the runtimes differ:
+ *
+ *   - **OpenCode** spawns each subagent as its own opencode `Session` with
+ *     a distinct `sessionID`. The harness records each Task dispatch into a
+ *     pending FIFO queue; the next previously-unseen sessionID consumes the
+ *     head of the queue and binds it to that label.
+ *
+ *   - **Claude Code** runs subagents inside the orchestrator's session — they
+ *     all share `session_id` — and instead stamps every subagent message with
+ *     `parent_tool_use_id` pointing at the Agent tool_use id that spawned them.
+ *     The harness binds each Agent tool_use id to its dispatched label up
+ *     front, then `labelFor` looks the label up directly when an event arrives
+ *     carrying that `parent_tool_use_id`.
+ *
+ * `labelFor(sessionID, parentToolUseId?)` accepts both: when
+ * `parentToolUseId` is set and known it short-circuits to the direct mapping;
+ * otherwise it falls through to the FIFO/sessionID path.
+ */
+export declare class SessionLabeler {
+    private readonly labels;
+    private readonly labelsByToolUseId;
+    private readonly pendingLabels;
+    private fallbackCounter;
+    /**
+     * Record a Task/Agent tool dispatch.
+     *
+     * @param input  Task tool input — used to derive the lens label.
+     * @param toolUseId  Optional Agent tool_use id. When provided, future events
+     *                   carrying `parent_tool_use_id === toolUseId` resolve
+     *                   directly to this label without consuming the FIFO queue
+     *                   (Claude path). Always also pushed to the FIFO queue so
+     *                   the OpenCode path still works when toolUseId is absent.
+     */
+    recordTaskDispatch(input: TaskDispatchInput, toolUseId?: string | null): string;
+    /**
+     * Return a label for the given event.
+     *
+     * @param sessionID         Session id from the event (OpenCode: per-session;
+     *                          Claude: shared across orchestrator + subagents).
+     * @param parentToolUseId   Claude's `parent_tool_use_id` — non-null on
+     *                          subagent messages. When set and known, takes
+     *                          priority over the FIFO/sessionID path.
+     */
+    labelFor(sessionID: string | undefined | null, parentToolUseId?: string | null): string;
+    /** number of distinct sessions seen so far (for diagnostics) */
+    size(): number;
+    /** all (sessionID, label) pairs, oldest first */
+    entries(): Array<[string, string]>;
+    /** how many pending labels are queued waiting to bind to a new session */
+    pendingDispatchCount(): number;
+}
+/**
+ * Format a log message with a session label prefix in magenta. Mirrors the
+ * style of utils/log.ts:prefixLines() so per-session prefixes look the same
+ * as the dormant withLogPrefix-based ones.
+ */
+export declare function formatWithLabel(label: string, message: string): string;

package/dist/agents/shared.d.ts

@@ -0,0 +1,189 @@
+import type { AgentId } from "#app/external";
+import type { ToolState } from "#app/toolState";
+import type { ResolvedInstructions } from "#app/utils/instructions";
+import type { ResolvedPayload } from "#app/utils/payload";
+import type { TodoTracker } from "#app/utils/todoTracking";
+export declare const MAX_STDERR_LINES = 20;
+/**
+ * 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 declare const MAX_POST_RUN_RETRIES = 3;
+export declare function getGitStatus(): string;
+export declare function buildCommitPrompt(status: string): string;
+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 declare function hasPostRunIssues(issues: PostRunIssues): boolean;
+/**
+ * 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 declare 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 declare const agent: (input: Agent) => Agent;
+/** format a USD cost to 4 decimal places, always showing the leading zero */
+export declare function formatCostUsd(costUsd: number): string;
+/**
+ * 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 declare function mergeAgentUsage(a: AgentUsage | undefined, b: AgentUsage | undefined): AgentUsage | 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 declare function logTokenTable(t: {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+    costUsd?: number | undefined;
+}): void;

package/dist/agents/subagentModels.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare function deriveSubagentModels(orchestratorSpec: string | undefined): {
+    reviewer: string | undefined;
+};

package/dist/agents/subagentToolGates.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 declare const SUBAGENT_DENIED_TOOLS: readonly ["checkout_pr", "push_branch", "push_tags", "delete_branch", "create_pull_request", "update_pull_request_body", "close_pull_request", "create_issue", "create_issue_comment", "edit_issue_comment", "reply_to_review_comment", "create_pull_request_review", "resolve_review_thread", "add_labels", "set_output", "report_progress", "select_mode", "start_dependency_installation", "kill_background", "upload_file"];
+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 declare function stripMcpPrefix(toolName: string): string;
+/**
+ * Whether `toolName` (in any runtime's prefix style) names a tool that
+ * subagents must not call.
+ */
+export declare function isSubagentDeniedTool(toolName: string): boolean;
+/**
+ * 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 declare function buildSubagentDenyMessage(toolName: string): string;