@cat-factory/executor-harness 1.90.0 → 1.92.2

package/dist/agent-runner.d.ts

@@ -1,5 +1,5 @@
 import type { Logger } from './logger.js';
-import { type HarnessCallMetric, type PiRunOutcome, type TodoProgress } from './pi.js';
+import { type HarnessCallMetric, type PiRunOutcome, type TodoProgress, type ToolSpan } from './pi.js';
 import { type McpServerSpec, type SkillSpec } from './agent-capabilities.js';
 import { type ProgressGuardLimits } from './progress-guard.js';
 import { type SliceReview } from './subagents.js';
@@ -72,6 +72,13 @@ export interface SubscriptionRunOptions {
     onActivity?: () => void;
     /** Called with the latest subtask counts each time the CLI updates its todo/plan list. */
     onProgress?: (progress: TodoProgress) => void;
+    /**
+     * Called once per completed tool call with a {@link ToolSpan}: the run's TRAJECTORY. The CLI's
+     * tool loop is internal to the CLI and never touches our proxy, so its own event stream is the
+     * only place these exist — without this hook a subscription-harness run's account of what it
+     * DID dies with the container.
+     */
+    onSpan?: (span: ToolSpan) => void;
     /**
      * Called with the FULL set of per-slice reviews each time one lands, so the backend can persist
      * a parallel review's completed work as it happens instead of only from the terminal result.

package/dist/agent-runner.js

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { claudeAssistantContent, isObject, numberOf, redactBody } from './claude-stream.js';
 import { createClaudeRunTelemetry, subagentDispatchId } from './claude-call-aggregator.js';
+import { ToolCallTracker, recordClaudeToolResults, } from './tool-trajectory.js';
 import { createCallMetricPublisher, publishCallMetric, } from './pi.js';
 import { claudeAllowedToolPatterns, codexMcpConfigToml, mcpServerSecretValues, writeClaudeMcpConfig, } from './agent-capabilities.js';
 import { ProgressGuard } from './progress-guard.js';
@@ -372,6 +373,27 @@ function createClaudeProgressGuard(opts) {
         reason: () => guardReason,
     };
 }
+/**
+ * The run's TRAJECTORY, on the claude-code stream: each `tool_use` block paired with the
+ * `tool_result` that answers it on the following user turn, numbered and captured (scrubbed +
+ * capped). The CLI's stream is the only place this loop is visible at all — its tool calls never
+ * touch our proxy — so without this a subscription-harness run's account of what it DID dies with
+ * the container.
+ *
+ * Both halves are no-ops when the caller wants no spans, so a driver that only needs the run's
+ * output never pays to serialise a body nothing will read. Split out of {@link runClaudeCode} for
+ * the per-function line budget, like {@link createClaudeProgressGuard}.
+ */
+function createClaudeToolTrajectory(opts, secrets) {
+    if (!opts.onSpan)
+        return { onToolUse: () => { }, onToolResults: () => { } };
+    const onSpan = opts.onSpan;
+    const tracker = new ToolCallTracker(secrets);
+    return {
+        onToolUse: (id, name, input) => tracker.started(id, name, input),
+        onToolResults: (content) => recordClaudeToolResults(tracker, content, (call) => onSpan({ ...call, bodies: 'stored' })),
+    };
+}
 export async function runClaudeCode(opts) {
     const stats = { toolCalls: 0, assistantChars: 0 };
     let summary = '';
@@ -459,6 +481,7 @@ export async function runClaudeCode(opts) {
     // diagnostic. Disabled when the caller supplies no limits (only the external watchdog bounds it).
     const progressGuard = createClaudeProgressGuard(opts);
     const { rememberTool, feedGuard, guardAbort } = progressGuard;
+    const trajectory = createClaudeToolTrajectory(opts, secrets);
     const onEvent = (event, meta) => {
         const type = event.type;
         // A subagent's turns ride the parent's stdout tagged with the dispatch that spawned them;
@@ -481,6 +504,7 @@ export async function runClaudeCode(opts) {
                 // `is_error` its `tool_result` carries on the next `user` turn.
                 if (typeof block.id === 'string' && typeof block.name === 'string') {
                     rememberTool(block.id, block.name);
+                    trajectory.onToolUse(block.id, block.name, block.input);
                 }
                 if (block.name === 'TodoWrite') {
                     const progress = todosToProgress(block.input?.todos);
@@ -506,6 +530,9 @@ export async function runClaudeCode(opts) {
                 // would kill nothing and only convert a clean exit into a spurious failure.
                 if (!meta?.final)
                     feedGuard(content);
+                // The trajectory's other half — fed on the FINAL flush too, unlike the guard, since a
+                // CLI that has exited is exactly when the last calls' results matter.
+                trajectory.onToolResults(content);
                 telemetry.onToolResult(dispatchId, content);
             }
         }

package/dist/pi-workspace.js

@@ -182,6 +182,9 @@ export async function runAgentInWorkspace(spec, opts = {}) {
             expectsEdits: spec.expectsEdits ?? true,
             onActivity: opts.onActivity,
             onProgress: opts.onProgress,
+            // The run's tool-call trajectory, the same hook the Pi path feeds — so a subscription run
+            // and a proxied one produce the same evidence rather than one of them producing none.
+            onSpan: opts.onSpan,
             // Per-slice review capture, so a parallel review's finished slices are persisted as they
             // land rather than only in the terminal output. Only the subscription runners fan work out
             // across subagents, so this is the only path that can produce it.

package/dist/pi.d.ts

@@ -187,18 +187,39 @@ export interface TodoProgress {
     items?: TodoItem[];
 }
 /**
- * One tool invocation in Pi's loop, captured for the run's observability trace.
- * Metadata only (name + timing + ok) — never the tool's args or result — so the
- * harness buffer stays tiny. The backend drains these on its existing job poll and
- * emits them as child spans under the run trace.
+ * One tool invocation in an agent's loop, captured for the run's TRAJECTORY: the ordered
+ * account of what the agent did, drained by the backend on its existing job poll and
+ * both persisted and emitted as a child span under the run trace.
+ *
+ * It carries the call's arguments and result (scrubbed and capped at capture — see
+ * `tool-trajectory.ts`), because the question asked of a finished run is which command
+ * ran against what, not how long a tool named `bash` took. Whether those bodies are
+ * RETAINED is the backend's decision, taken against the deployment switch and the
+ * workspace's opt-out; the harness's job is to capture them bounded and scrubbed.
  */
 export interface ToolSpan {
     tool: string;
-    /** Epoch ms the tool call started (approximated as the previous tool's end). */
+    /**
+     * The call's 0-based ordinal within this job. Two calls routinely land in the same
+     * millisecond, so this is the only thing that orders the trajectory — and it is what
+     * makes the backend's stored row id deterministic, so a replayed poll re-records
+     * instead of duplicating.
+     */
+    seq: number;
+    /** Epoch ms the tool call started (the previous call's end when no start was seen). */
     startedAt: number;
     /** Epoch ms the tool call ended (when its `tool_execution_end` event arrived). */
     endedAt: number;
     ok: boolean;
+    /** Whether the bodies below were captured at all — always `'stored'` from this harness. */
+    bodies: 'stored' | 'withheld';
+    /** The call's arguments, serialised, scrubbed and capped. `''` when it took none. */
+    args: string;
+    /** What the tool returned, scrubbed and capped. `''` when it returned nothing. */
+    result: string;
+    /** Characters the cap dropped from {@link args} / {@link result}; 0 when nothing was cut. */
+    argsDropped: number;
+    resultDropped: number;
 }
 /**
  * What the agent actually did this run, independent of any file changes. Used to

package/dist/pi.js

@@ -4,10 +4,11 @@ import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { killChildProcess, spawnDetached } from './process.js';
 import { pathExists } from './fs-utils.js';
-import { redactSecrets } from './redact.js';
+import { redactSecrets, secretsToRedact } from './redact.js';
 import { HarnessFailure } from './failure.js';
 import { log } from './logger.js';
 import { ProgressGuard, progressGuardLimitsFromEnv, toolCallSignal, } from './progress-guard.js';
+import { ToolCallTracker, readToolCallId, toolCallResult, toolCallStart, } from './tool-trajectory.js';
 // Drives the Pi coding-agent CLI. Pi is pointed at the Worker's OpenAI-compatible
 // proxy via a custom provider in ~/.pi/agent/models.json, authenticated with the
 // per-job session token (interpolated from $PI_PROXY_TOKEN) — so no provider key
@@ -606,10 +607,17 @@ export function runPi(opts) {
         let malformedLines = 0;
         let observerErrors = 0;
         const guard = new ProgressGuard(opts.guardLimits ?? progressGuardLimitsFromEnv(), opts.expectsEdits ?? true);
-        // Start boundary for the next tool span: each tool's slice runs from the previous
-        // tool's end (or the run start) to its own `tool_execution_end`. Approximate but
-        // contiguous — enough for the trace tree, and metadata-only.
-        let toolBoundary = Date.now();
+        // Pairs each tool call's start with its result, numbers the pairs and captures the two
+        // bodies (scrubbed + capped). A call whose start Pi never emitted still gets an entry,
+        // timed from the previous call's end — see `ToolCallTracker`.
+        //
+        // The known-secret list is DERIVED from the token this function itself hands the child
+        // (`PI_PROXY_TOKEN` / `SEARXNG_API_KEY`) rather than taken as a parameter: the bodies
+        // travel to a store and to external trace sinks, and a caller that forgets to pass the
+        // list produces bodies scrubbed of credential SHAPES only, with no signal that the
+        // narrower rule ever ran. Deriving it here means the one place that knows the child's
+        // credentials is the place that scrubs them.
+        const tools = new ToolCallTracker(secretsToRedact(opts.sessionToken));
         // SIGTERM first, then SIGKILL if Pi ignores it. Shared by the watchdog abort
         // and the no-progress guard; the `close` handler turns it into a rejection.
         const killChild = () => killChildProcess(child);
@@ -648,22 +656,19 @@ export function runPi(opts) {
                     opts.onProgress(progress);
             }
             if (opts.onSpan) {
+                const start = toolCallStart(event);
+                if (start)
+                    tools.started(start.id, start.name, start.args);
                 const signal = toolCallSignal(event);
                 if (signal && signal.name) {
-                    const endedAt = Date.now();
+                    const call = tools.finished(readToolCallId(event), signal.name, toolCallResult(event), signal.isError);
                     try {
-                        opts.onSpan({
-                            tool: signal.name,
-                            startedAt: toolBoundary,
-                            endedAt,
-                            ok: !signal.isError,
-                        });
+                        opts.onSpan({ ...call, bodies: 'stored' });
                     }
                     catch {
                         // A faulty observer must never break the run.
                         observerErrors++;
                     }
-                    toolBoundary = endedAt;
                 }
             }
             if (runGuard && !guardReason && !aborted) {

package/dist/tool-trajectory.d.ts

@@ -0,0 +1,78 @@
+/** Cap on a captured argument blob. Generous for a command line, far below a file body. */
+export declare const MAX_TOOL_ARGS_CHARS: number;
+/** Cap on a captured result. Larger than the args cap: a result is where the bytes actually are. */
+export declare const MAX_TOOL_RESULT_CHARS: number;
+/** A captured body plus what the cap dropped from it. */
+export interface CapturedToolBody {
+    text: string;
+    dropped: number;
+}
+/**
+ * Serialise, scrub and cap one tool body.
+ *
+ * A non-string value is JSON-serialised, and a value that cannot be (a cycle, a `BigInt`, a
+ * throwing getter) is NAMED as unserialisable rather than dropped to `''`: an empty body means
+ * "the call carried none", and a capture failure is a different fact.
+ */
+export declare function captureToolBody(value: unknown, max: number, secrets: readonly string[]): CapturedToolBody;
+/** What {@link ToolCallTracker} emits per completed call — the fields a `ToolSpan` needs. */
+export interface TrackedToolCall {
+    tool: string;
+    seq: number;
+    startedAt: number;
+    endedAt: number;
+    ok: boolean;
+    args: string;
+    result: string;
+    argsDropped: number;
+    resultDropped: number;
+}
+/**
+ * Pairs each tool call's START with its RESULT and numbers the pairs, so the two agent CLIs feed
+ * one trajectory shape from two very different streams (Pi's flat `tool_execution_*` events, the
+ * claude-code stream's `tool_use` / `tool_result` content blocks).
+ *
+ * Correlation is BY ID where the stream supplies one, and by tool name otherwise, because that is
+ * the difference between the two producers: claude-code's blocks always carry a `tool_use_id`, and
+ * a parallel batch of calls is routine there, while Pi's stream is sequential. A result the tracker
+ * cannot pair with a start is still EMITTED (with no args and the previous call's end as its
+ * start): losing a step of the trajectory to a schema tweak would be worse than an entry that says
+ * less than its neighbours, and the `seq` it takes keeps every later entry's ordinal honest.
+ */
+export declare class ToolCallTracker {
+    private readonly secrets;
+    private seq;
+    private readonly byId;
+    private readonly byTool;
+    /**
+     * Start boundary for a call whose own start was never seen: the previous call's end, or the run
+     * start. Approximate but contiguous, which is the property the trace tree needs.
+     */
+    private boundary;
+    constructor(secrets?: readonly string[], now?: number);
+    /** Record that a call began, with the arguments the agent supplied. */
+    started(id: string | undefined, tool: string, args: unknown, at?: number): void;
+    /** Record that a call finished, and return the completed entry. */
+    finished(id: string | undefined, tool: string, result: unknown, isError: boolean, at?: number): TrackedToolCall;
+    private take;
+}
+/** Read a tool-call id off a stream event, whatever the producer calls it. */
+export declare function readToolCallId(event: Record<string, unknown>): string | undefined;
+/** A tool call BEGINNING, read off a Pi `--mode json` event, or undefined if it isn't one. */
+export declare function toolCallStart(event: Record<string, unknown>): {
+    id?: string;
+    name: string;
+    args: unknown;
+} | undefined;
+/** The RESULT payload of a Pi `tool_execution_end` event, unwrapped from its envelope. */
+export declare function toolCallResult(event: Record<string, unknown>): unknown;
+/**
+ * Feed one claude-code `user` turn's content blocks to the tracker, emitting an entry per
+ * `tool_result`.
+ *
+ * The CLI answers each `tool_use` with a `tool_result` carrying the same `tool_use_id`, so the
+ * pairing is exact even when the model fired a batch of calls in parallel — which it routinely
+ * does, and which is why the trajectory here is ordered by the ordinal the tracker stamps rather
+ * than by the turn the results arrived on.
+ */
+export declare function recordClaudeToolResults(tracker: ToolCallTracker, content: readonly unknown[], emit: (call: TrackedToolCall) => void): void;

package/dist/tool-trajectory.js

@@ -0,0 +1,194 @@
+import { redact } from './redact.js';
+// The TRAJECTORY capture: what the agent DID, one entry per tool call, in the order it made them.
+//
+// The harness has always buffered a compact span per tool call (name + timing + ok) for the run's
+// trace. That is enough to draw a tree and not enough to answer the question anyone actually asks
+// of a finished run — WHICH command, against WHAT, and what came back. The evidence standard for a
+// merged PR is "how, not just the diff", and a span saying `bash` ran for 300ms is not evidence of
+// anything. So each entry now carries the call's arguments and result, captured here because this
+// is the only process that ever sees them: an agent CLI's tool loop is internal to the CLI, and
+// the container is gone the moment the job settles.
+//
+// Two properties keep that affordable and safe:
+//
+//  - **Bounded at capture.** Each body is capped (a build log is routinely megabytes) and the entry
+//    STATES what the cap dropped, so a reader can tell a short command from the head of a long one.
+//    The caps are what keep the drain buffer and the poll response small.
+//  - **Scrubbed at capture.** A tool's arguments and output routinely echo an env var, a clone URL
+//    or the leased subscription token, and these travel to a store and to external trace sinks.
+//
+// The RETENTION decision is the backend's, not this module's: entries carry `bodies: 'stored'` and
+// the backend's double gate (`LLM_RECORD_PROMPTS` + the workspace's `storeAgentContext`) decides
+// whether to keep them, exactly as it already does for the prompt bodies the call-metric
+// reconstruction assembles here. Deciding it twice would mean the container had to be told the
+// workspace's settings, and an image one release behind its backend would then be deciding it with
+// stale ones.
+/** Cap on a captured argument blob. Generous for a command line, far below a file body. */
+export const MAX_TOOL_ARGS_CHARS = 2 * 1024;
+/** Cap on a captured result. Larger than the args cap: a result is where the bytes actually are. */
+export const MAX_TOOL_RESULT_CHARS = 4 * 1024;
+const EMPTY = { text: '', dropped: 0 };
+/**
+ * Serialise, scrub and cap one tool body.
+ *
+ * A non-string value is JSON-serialised, and a value that cannot be (a cycle, a `BigInt`, a
+ * throwing getter) is NAMED as unserialisable rather than dropped to `''`: an empty body means
+ * "the call carried none", and a capture failure is a different fact.
+ */
+export function captureToolBody(value, max, secrets) {
+    if (value === undefined || value === null)
+        return EMPTY;
+    let text;
+    if (typeof value === 'string') {
+        text = value;
+    }
+    else {
+        try {
+            text = JSON.stringify(value) ?? '';
+        }
+        catch {
+            return { text: '[unserialisable]', dropped: 0 };
+        }
+    }
+    if (text === '')
+        return EMPTY;
+    const scrubbed = redact(text, secrets);
+    if (scrubbed.length <= max)
+        return { text: scrubbed, dropped: 0 };
+    return { text: scrubbed.slice(0, max), dropped: scrubbed.length - max };
+}
+/**
+ * Pairs each tool call's START with its RESULT and numbers the pairs, so the two agent CLIs feed
+ * one trajectory shape from two very different streams (Pi's flat `tool_execution_*` events, the
+ * claude-code stream's `tool_use` / `tool_result` content blocks).
+ *
+ * Correlation is BY ID where the stream supplies one, and by tool name otherwise, because that is
+ * the difference between the two producers: claude-code's blocks always carry a `tool_use_id`, and
+ * a parallel batch of calls is routine there, while Pi's stream is sequential. A result the tracker
+ * cannot pair with a start is still EMITTED (with no args and the previous call's end as its
+ * start): losing a step of the trajectory to a schema tweak would be worse than an entry that says
+ * less than its neighbours, and the `seq` it takes keeps every later entry's ordinal honest.
+ */
+export class ToolCallTracker {
+    secrets;
+    seq = 0;
+    byId = new Map();
+    byTool = new Map();
+    /**
+     * Start boundary for a call whose own start was never seen: the previous call's end, or the run
+     * start. Approximate but contiguous, which is the property the trace tree needs.
+     */
+    boundary;
+    constructor(secrets = [], now = Date.now()) {
+        this.secrets = secrets;
+        this.boundary = now;
+    }
+    /** Record that a call began, with the arguments the agent supplied. */
+    started(id, tool, args, at = Date.now()) {
+        const pending = {
+            tool,
+            startedAt: at,
+            args: captureToolBody(args, MAX_TOOL_ARGS_CHARS, this.secrets),
+        };
+        if (id) {
+            this.byId.set(id, pending);
+            return;
+        }
+        const queue = this.byTool.get(tool) ?? [];
+        queue.push(pending);
+        this.byTool.set(tool, queue);
+    }
+    /** Record that a call finished, and return the completed entry. */
+    finished(id, tool, result, isError, at = Date.now()) {
+        const pending = this.take(id, tool);
+        const captured = captureToolBody(result, MAX_TOOL_RESULT_CHARS, this.secrets);
+        const call = {
+            tool: pending?.tool ?? tool,
+            seq: this.seq++,
+            startedAt: pending?.startedAt ?? this.boundary,
+            endedAt: at,
+            ok: !isError,
+            args: pending?.args.text ?? '',
+            argsDropped: pending?.args.dropped ?? 0,
+            result: captured.text,
+            resultDropped: captured.dropped,
+        };
+        this.boundary = at;
+        return call;
+    }
+    take(id, tool) {
+        if (id) {
+            const byId = this.byId.get(id);
+            if (byId) {
+                this.byId.delete(id);
+                return byId;
+            }
+        }
+        const queue = this.byTool.get(tool);
+        // FIFO, so a sequential stream pairs each result with the call that opened first. A stream
+        // that interleaves un-idded calls of one tool would mis-pair here; none of the two producers
+        // does, and the alternative (refusing to pair at all) loses the args on every ordinary run.
+        const pending = queue?.shift();
+        if (queue && queue.length === 0)
+            this.byTool.delete(tool);
+        return pending;
+    }
+}
+/** Read a tool-call id off a stream event, whatever the producer calls it. */
+export function readToolCallId(event) {
+    for (const key of ['toolCallId', 'tool_call_id', 'callId', 'id']) {
+        const value = event[key];
+        if (typeof value === 'string' && value !== '')
+            return value;
+    }
+    return undefined;
+}
+/** A tool call BEGINNING, read off a Pi `--mode json` event, or undefined if it isn't one. */
+export function toolCallStart(event) {
+    if (event.type !== 'tool_execution_start' && event.type !== 'tool_call')
+        return undefined;
+    const name = typeof event.toolName === 'string' ? event.toolName : '';
+    if (!name)
+        return undefined;
+    // Read every spelling the stream might use rather than pinning one: Pi's event schema has been
+    // renamed under us before (see `todoResultDetails`, which reads three shapes of one result), and
+    // a rename here costs the ARGUMENTS of every call, silently.
+    const args = event.args ?? event.arguments ?? event.input ?? event.parameters;
+    const id = readToolCallId(event);
+    return { name, args, ...(id ? { id } : {}) };
+}
+/** The RESULT payload of a Pi `tool_execution_end` event, unwrapped from its envelope. */
+export function toolCallResult(event) {
+    const result = event.result;
+    if (result && typeof result === 'object') {
+        const inner = result;
+        // `details` is the structured payload Pi's own extensions return (the todo tool's shape), and
+        // `content`/`output` the free-text ones. Falling back to the whole envelope keeps a shape none
+        // of these match readable rather than empty.
+        return inner.details ?? inner.content ?? inner.output ?? result;
+    }
+    return result ?? event.output ?? event.content;
+}
+/**
+ * Feed one claude-code `user` turn's content blocks to the tracker, emitting an entry per
+ * `tool_result`.
+ *
+ * The CLI answers each `tool_use` with a `tool_result` carrying the same `tool_use_id`, so the
+ * pairing is exact even when the model fired a batch of calls in parallel — which it routinely
+ * does, and which is why the trajectory here is ordered by the ordinal the tracker stamps rather
+ * than by the turn the results arrived on.
+ */
+export function recordClaudeToolResults(tracker, content, emit) {
+    for (const block of content) {
+        if (!block || typeof block !== 'object')
+            continue;
+        const record = block;
+        if (record.type !== 'tool_result')
+            continue;
+        const id = typeof record.tool_use_id === 'string' ? record.tool_use_id : undefined;
+        // The block carries no tool NAME (only the id the assistant turn named), so an unpaired
+        // result falls back to a stated placeholder rather than an empty string that would render
+        // as a nameless step.
+        emit(tracker.finished(id, 'unknown', record.content, record.is_error === true));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/executor-harness",
-  "version": "1.90.0",
+  "version": "1.92.2",
   "description": "Container payload: a thin TypeScript wrapper that runs the Pi coding agent against a cloned repo and opens a PR. Runs in the Cloudflare Container (and, in local native mode, as a host process); carries no secrets.",
   "repository": {
     "type": "git",
@@ -25,14 +25,14 @@
     "access": "public"
   },
   "devDependencies": {
-    "@hono/node-server": "^2.0.12",
+    "@hono/node-server": "^2.1.0",
     "@types/node": "^26.1.2",
-    "hono": "^4.12.33",
+    "hono": "^4.13.0",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@cat-factory/kernel": "0.232.0",
-    "@cat-factory/server": "0.210.0",
-    "@cat-factory/spend": "0.14.7"
+    "@cat-factory/kernel": "0.242.0",
+    "@cat-factory/server": "0.222.0",
+    "@cat-factory/spend": "0.15.6"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/agent-runner.ts

@@ -4,6 +4,11 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { claudeAssistantContent, isObject, numberOf, redactBody } from './claude-stream.js'
 import { createClaudeRunTelemetry, subagentDispatchId } from './claude-call-aggregator.js'
+import {
+  ToolCallTracker,
+  type TrackedToolCall,
+  recordClaudeToolResults,
+} from './tool-trajectory.js'
 import type { Logger } from './logger.js'
 import {
   createCallMetricPublisher,
@@ -13,6 +18,7 @@ import {
   type PiRunOutcome,
   type PiRunStats,
   type TodoProgress,
+  type ToolSpan,
 } from './pi.js'
 import {
   claudeAllowedToolPatterns,
@@ -123,6 +129,13 @@ export interface SubscriptionRunOptions {
   onActivity?: () => void
   /** Called with the latest subtask counts each time the CLI updates its todo/plan list. */
   onProgress?: (progress: TodoProgress) => void
+  /**
+   * Called once per completed tool call with a {@link ToolSpan}: the run's TRAJECTORY. The CLI's
+   * tool loop is internal to the CLI and never touches our proxy, so its own event stream is the
+   * only place these exist — without this hook a subscription-harness run's account of what it
+   * DID dies with the container.
+   */
+  onSpan?: (span: ToolSpan) => void
   /**
    * Called with the FULL set of per-slice reviews each time one lands, so the backend can persist
    * a parallel review's completed work as it happens instead of only from the terminal result.
@@ -538,6 +551,36 @@ function createClaudeProgressGuard(opts: SubscriptionRunOptions): {
   }
 }
 
+/**
+ * The run's TRAJECTORY, on the claude-code stream: each `tool_use` block paired with the
+ * `tool_result` that answers it on the following user turn, numbered and captured (scrubbed +
+ * capped). The CLI's stream is the only place this loop is visible at all — its tool calls never
+ * touch our proxy — so without this a subscription-harness run's account of what it DID dies with
+ * the container.
+ *
+ * Both halves are no-ops when the caller wants no spans, so a driver that only needs the run's
+ * output never pays to serialise a body nothing will read. Split out of {@link runClaudeCode} for
+ * the per-function line budget, like {@link createClaudeProgressGuard}.
+ */
+function createClaudeToolTrajectory(
+  opts: SubscriptionRunOptions,
+  secrets: readonly string[],
+): {
+  onToolUse: (id: string, name: string, input: unknown) => void
+  onToolResults: (content: unknown[]) => void
+} {
+  if (!opts.onSpan) return { onToolUse: () => {}, onToolResults: () => {} }
+  const onSpan = opts.onSpan
+  const tracker = new ToolCallTracker(secrets)
+  return {
+    onToolUse: (id, name, input) => tracker.started(id, name, input),
+    onToolResults: (content) =>
+      recordClaudeToolResults(tracker, content, (call: TrackedToolCall) =>
+        onSpan({ ...call, bodies: 'stored' }),
+      ),
+  }
+}
+
 export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
@@ -628,6 +671,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   // diagnostic. Disabled when the caller supplies no limits (only the external watchdog bounds it).
   const progressGuard = createClaudeProgressGuard(opts)
   const { rememberTool, feedGuard, guardAbort } = progressGuard
+  const trajectory = createClaudeToolTrajectory(opts, secrets)
 
   const onEvent = (event: Record<string, unknown>, meta?: { final?: boolean }): void => {
     const type = event.type
@@ -650,6 +694,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         // `is_error` its `tool_result` carries on the next `user` turn.
         if (typeof block.id === 'string' && typeof block.name === 'string') {
           rememberTool(block.id, block.name)
+          trajectory.onToolUse(block.id, block.name, block.input)
         }
         if (block.name === 'TodoWrite') {
           const progress = todosToProgress((block.input as Record<string, unknown>)?.todos)
@@ -672,6 +717,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
         // Not on the at-close flush: the CLI has already exited, so tripping the guard there
         // would kill nothing and only convert a clean exit into a spurious failure.
         if (!meta?.final) feedGuard(content)
+        // The trajectory's other half — fed on the FINAL flush too, unlike the guard, since a
+        // CLI that has exited is exactly when the last calls' results matter.
+        trajectory.onToolResults(content)
         telemetry.onToolResult(dispatchId, content)
       }
     } else if (type === 'result') {

package/src/coding-agent.ts

@@ -1101,40 +1101,36 @@ export async function runMultiRepoCoding(
       baseSha: '',
       resumed: false,
     },
-    ...peers.map(
-      (peer): RepoLeg => ({
-        repo: peer.repo,
-        dirName: claimDir(peer.repo),
-        dir: '',
-        cloneBranch: peer.repo.baseBranch,
-        // Coding peers always carry `newBranch` (the backend sets the shared work branch);
-        // fall back to the primary's for the type (read-only peers never reach this path).
-        workBranch: peer.newBranch ?? primaryWorkBranch,
-        ghToken: peer.ghToken ?? job.ghToken,
-        ...(peer.pr ? { pr: peer.pr } : {}),
-        ...(peer.frameId ? { frameId: peer.frameId } : {}),
-        primary: false,
-        baseSha: '',
-        resumed: false,
-      }),
-    ),
+    ...peers.map((peer): RepoLeg => ({
+      repo: peer.repo,
+      dirName: claimDir(peer.repo),
+      dir: '',
+      cloneBranch: peer.repo.baseBranch,
+      // Coding peers always carry `newBranch` (the backend sets the shared work branch);
+      // fall back to the primary's for the type (read-only peers never reach this path).
+      workBranch: peer.newBranch ?? primaryWorkBranch,
+      ghToken: peer.ghToken ?? job.ghToken,
+      ...(peer.pr ? { pr: peer.pr } : {}),
+      ...(peer.frameId ? { frameId: peer.frameId } : {}),
+      primary: false,
+      baseSha: '',
+      resumed: false,
+    })),
     // Read-only reference repos (doc-writer): cloned as siblings the agent reads but never writes.
     // `workBranch` is set to the base only to satisfy the type — a read-only leg never branches or
     // pushes (guarded by `readOnly` in both the clone and push phases below).
-    ...references.map(
-      (reference): RepoLeg => ({
-        repo: reference.repo,
-        dirName: claimDir(reference.repo),
-        dir: '',
-        cloneBranch: reference.repo.baseBranch,
-        workBranch: reference.repo.baseBranch,
-        ghToken: reference.ghToken ?? job.ghToken,
-        primary: false,
-        readOnly: true,
-        baseSha: '',
-        resumed: false,
-      }),
-    ),
+    ...references.map((reference): RepoLeg => ({
+      repo: reference.repo,
+      dirName: claimDir(reference.repo),
+      dir: '',
+      cloneBranch: reference.repo.baseBranch,
+      workBranch: reference.repo.baseBranch,
+      ghToken: reference.ghToken ?? job.ghToken,
+      primary: false,
+      readOnly: true,
+      baseSha: '',
+      resumed: false,
+    })),
   ]
 
   return withWorkspace('multi', async (root) => {

package/src/pi-workspace.ts

@@ -325,6 +325,9 @@ export async function runAgentInWorkspace(
       expectsEdits: spec.expectsEdits ?? true,
       onActivity: opts.onActivity,
       onProgress: opts.onProgress,
+      // The run's tool-call trajectory, the same hook the Pi path feeds — so a subscription run
+      // and a proxied one produce the same evidence rather than one of them producing none.
+      onSpan: opts.onSpan,
       // Per-slice review capture, so a parallel review's finished slices are persisted as they
       // land rather than only in the terminal output. Only the subscription runners fan work out
       // across subagents, so this is the only path that can produce it.

package/src/pi.ts

@@ -4,7 +4,7 @@ import { homedir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { killChildProcess, spawnDetached } from './process.js'
 import { pathExists } from './fs-utils.js'
-import { redactSecrets } from './redact.js'
+import { redactSecrets, secretsToRedact } from './redact.js'
 import { HarnessFailure } from './failure.js'
 import { log } from './logger.js'
 import type { EffortReport } from './effort.js'
@@ -14,6 +14,12 @@ import {
   toolCallSignal,
   type ProgressGuardLimits,
 } from './progress-guard.js'
+import {
+  ToolCallTracker,
+  readToolCallId,
+  toolCallResult,
+  toolCallStart,
+} from './tool-trajectory.js'
 
 // Drives the Pi coding-agent CLI. Pi is pointed at the Worker's OpenAI-compatible
 // proxy via a custom provider in ~/.pi/agent/models.json, authenticated with the
@@ -501,18 +507,39 @@ export interface TodoProgress {
 }
 
 /**
- * One tool invocation in Pi's loop, captured for the run's observability trace.
- * Metadata only (name + timing + ok) — never the tool's args or result — so the
- * harness buffer stays tiny. The backend drains these on its existing job poll and
- * emits them as child spans under the run trace.
+ * One tool invocation in an agent's loop, captured for the run's TRAJECTORY: the ordered
+ * account of what the agent did, drained by the backend on its existing job poll and
+ * both persisted and emitted as a child span under the run trace.
+ *
+ * It carries the call's arguments and result (scrubbed and capped at capture — see
+ * `tool-trajectory.ts`), because the question asked of a finished run is which command
+ * ran against what, not how long a tool named `bash` took. Whether those bodies are
+ * RETAINED is the backend's decision, taken against the deployment switch and the
+ * workspace's opt-out; the harness's job is to capture them bounded and scrubbed.
  */
 export interface ToolSpan {
   tool: string
-  /** Epoch ms the tool call started (approximated as the previous tool's end). */
+  /**
+   * The call's 0-based ordinal within this job. Two calls routinely land in the same
+   * millisecond, so this is the only thing that orders the trajectory — and it is what
+   * makes the backend's stored row id deterministic, so a replayed poll re-records
+   * instead of duplicating.
+   */
+  seq: number
+  /** Epoch ms the tool call started (the previous call's end when no start was seen). */
   startedAt: number
   /** Epoch ms the tool call ended (when its `tool_execution_end` event arrived). */
   endedAt: number
   ok: boolean
+  /** Whether the bodies below were captured at all — always `'stored'` from this harness. */
+  bodies: 'stored' | 'withheld'
+  /** The call's arguments, serialised, scrubbed and capped. `''` when it took none. */
+  args: string
+  /** What the tool returned, scrubbed and capped. `''` when it returned nothing. */
+  result: string
+  /** Characters the cap dropped from {@link args} / {@link result}; 0 when nothing was cut. */
+  argsDropped: number
+  resultDropped: number
 }
 
 function isObject(value: unknown): value is Record<string, unknown> {
@@ -918,10 +945,17 @@ export function runPi(opts: {
       opts.guardLimits ?? progressGuardLimitsFromEnv(),
       opts.expectsEdits ?? true,
     )
-    // Start boundary for the next tool span: each tool's slice runs from the previous
-    // tool's end (or the run start) to its own `tool_execution_end`. Approximate but
-    // contiguous — enough for the trace tree, and metadata-only.
-    let toolBoundary = Date.now()
+    // Pairs each tool call's start with its result, numbers the pairs and captures the two
+    // bodies (scrubbed + capped). A call whose start Pi never emitted still gets an entry,
+    // timed from the previous call's end — see `ToolCallTracker`.
+    //
+    // The known-secret list is DERIVED from the token this function itself hands the child
+    // (`PI_PROXY_TOKEN` / `SEARXNG_API_KEY`) rather than taken as a parameter: the bodies
+    // travel to a store and to external trace sinks, and a caller that forgets to pass the
+    // list produces bodies scrubbed of credential SHAPES only, with no signal that the
+    // narrower rule ever ran. Deriving it here means the one place that knows the child's
+    // credentials is the place that scrubs them.
+    const tools = new ToolCallTracker(secretsToRedact(opts.sessionToken))
 
     // SIGTERM first, then SIGKILL if Pi ignores it. Shared by the watchdog abort
     // and the no-progress guard; the `close` handler turns it into a rejection.
@@ -958,21 +992,22 @@ export function runPi(opts: {
         if (progress) opts.onProgress(progress)
       }
       if (opts.onSpan) {
+        const start = toolCallStart(event)
+        if (start) tools.started(start.id, start.name, start.args)
         const signal = toolCallSignal(event)
         if (signal && signal.name) {
-          const endedAt = Date.now()
+          const call = tools.finished(
+            readToolCallId(event),
+            signal.name,
+            toolCallResult(event),
+            signal.isError,
+          )
           try {
-            opts.onSpan({
-              tool: signal.name,
-              startedAt: toolBoundary,
-              endedAt,
-              ok: !signal.isError,
-            })
+            opts.onSpan({ ...call, bodies: 'stored' })
           } catch {
             // A faulty observer must never break the run.
             observerErrors++
           }
-          toolBoundary = endedAt
         }
       }
       if (runGuard && !guardReason && !aborted) {

package/src/tool-trajectory.ts

@@ -0,0 +1,239 @@
+import { redact } from './redact.js'
+
+// The TRAJECTORY capture: what the agent DID, one entry per tool call, in the order it made them.
+//
+// The harness has always buffered a compact span per tool call (name + timing + ok) for the run's
+// trace. That is enough to draw a tree and not enough to answer the question anyone actually asks
+// of a finished run — WHICH command, against WHAT, and what came back. The evidence standard for a
+// merged PR is "how, not just the diff", and a span saying `bash` ran for 300ms is not evidence of
+// anything. So each entry now carries the call's arguments and result, captured here because this
+// is the only process that ever sees them: an agent CLI's tool loop is internal to the CLI, and
+// the container is gone the moment the job settles.
+//
+// Two properties keep that affordable and safe:
+//
+//  - **Bounded at capture.** Each body is capped (a build log is routinely megabytes) and the entry
+//    STATES what the cap dropped, so a reader can tell a short command from the head of a long one.
+//    The caps are what keep the drain buffer and the poll response small.
+//  - **Scrubbed at capture.** A tool's arguments and output routinely echo an env var, a clone URL
+//    or the leased subscription token, and these travel to a store and to external trace sinks.
+//
+// The RETENTION decision is the backend's, not this module's: entries carry `bodies: 'stored'` and
+// the backend's double gate (`LLM_RECORD_PROMPTS` + the workspace's `storeAgentContext`) decides
+// whether to keep them, exactly as it already does for the prompt bodies the call-metric
+// reconstruction assembles here. Deciding it twice would mean the container had to be told the
+// workspace's settings, and an image one release behind its backend would then be deciding it with
+// stale ones.
+
+/** Cap on a captured argument blob. Generous for a command line, far below a file body. */
+export const MAX_TOOL_ARGS_CHARS = 2 * 1024
+/** Cap on a captured result. Larger than the args cap: a result is where the bytes actually are. */
+export const MAX_TOOL_RESULT_CHARS = 4 * 1024
+
+/** A captured body plus what the cap dropped from it. */
+export interface CapturedToolBody {
+  text: string
+  dropped: number
+}
+
+const EMPTY: CapturedToolBody = { text: '', dropped: 0 }
+
+/**
+ * Serialise, scrub and cap one tool body.
+ *
+ * A non-string value is JSON-serialised, and a value that cannot be (a cycle, a `BigInt`, a
+ * throwing getter) is NAMED as unserialisable rather than dropped to `''`: an empty body means
+ * "the call carried none", and a capture failure is a different fact.
+ */
+export function captureToolBody(
+  value: unknown,
+  max: number,
+  secrets: readonly string[],
+): CapturedToolBody {
+  if (value === undefined || value === null) return EMPTY
+  let text: string
+  if (typeof value === 'string') {
+    text = value
+  } else {
+    try {
+      text = JSON.stringify(value) ?? ''
+    } catch {
+      return { text: '[unserialisable]', dropped: 0 }
+    }
+  }
+  if (text === '') return EMPTY
+  const scrubbed = redact(text, secrets)
+  if (scrubbed.length <= max) return { text: scrubbed, dropped: 0 }
+  return { text: scrubbed.slice(0, max), dropped: scrubbed.length - max }
+}
+
+/** One tool call the tracker is holding open, between its start and its result. */
+interface PendingCall {
+  tool: string
+  startedAt: number
+  args: CapturedToolBody
+}
+
+/** What {@link ToolCallTracker} emits per completed call — the fields a `ToolSpan` needs. */
+export interface TrackedToolCall {
+  tool: string
+  seq: number
+  startedAt: number
+  endedAt: number
+  ok: boolean
+  args: string
+  result: string
+  argsDropped: number
+  resultDropped: number
+}
+
+/**
+ * Pairs each tool call's START with its RESULT and numbers the pairs, so the two agent CLIs feed
+ * one trajectory shape from two very different streams (Pi's flat `tool_execution_*` events, the
+ * claude-code stream's `tool_use` / `tool_result` content blocks).
+ *
+ * Correlation is BY ID where the stream supplies one, and by tool name otherwise, because that is
+ * the difference between the two producers: claude-code's blocks always carry a `tool_use_id`, and
+ * a parallel batch of calls is routine there, while Pi's stream is sequential. A result the tracker
+ * cannot pair with a start is still EMITTED (with no args and the previous call's end as its
+ * start): losing a step of the trajectory to a schema tweak would be worse than an entry that says
+ * less than its neighbours, and the `seq` it takes keeps every later entry's ordinal honest.
+ */
+export class ToolCallTracker {
+  private seq = 0
+  private readonly byId = new Map<string, PendingCall>()
+  private readonly byTool = new Map<string, PendingCall[]>()
+  /**
+   * Start boundary for a call whose own start was never seen: the previous call's end, or the run
+   * start. Approximate but contiguous, which is the property the trace tree needs.
+   */
+  private boundary: number
+
+  constructor(
+    private readonly secrets: readonly string[] = [],
+    now: number = Date.now(),
+  ) {
+    this.boundary = now
+  }
+
+  /** Record that a call began, with the arguments the agent supplied. */
+  started(id: string | undefined, tool: string, args: unknown, at: number = Date.now()): void {
+    const pending: PendingCall = {
+      tool,
+      startedAt: at,
+      args: captureToolBody(args, MAX_TOOL_ARGS_CHARS, this.secrets),
+    }
+    if (id) {
+      this.byId.set(id, pending)
+      return
+    }
+    const queue = this.byTool.get(tool) ?? []
+    queue.push(pending)
+    this.byTool.set(tool, queue)
+  }
+
+  /** Record that a call finished, and return the completed entry. */
+  finished(
+    id: string | undefined,
+    tool: string,
+    result: unknown,
+    isError: boolean,
+    at: number = Date.now(),
+  ): TrackedToolCall {
+    const pending = this.take(id, tool)
+    const captured = captureToolBody(result, MAX_TOOL_RESULT_CHARS, this.secrets)
+    const call: TrackedToolCall = {
+      tool: pending?.tool ?? tool,
+      seq: this.seq++,
+      startedAt: pending?.startedAt ?? this.boundary,
+      endedAt: at,
+      ok: !isError,
+      args: pending?.args.text ?? '',
+      argsDropped: pending?.args.dropped ?? 0,
+      result: captured.text,
+      resultDropped: captured.dropped,
+    }
+    this.boundary = at
+    return call
+  }
+
+  private take(id: string | undefined, tool: string): PendingCall | undefined {
+    if (id) {
+      const byId = this.byId.get(id)
+      if (byId) {
+        this.byId.delete(id)
+        return byId
+      }
+    }
+    const queue = this.byTool.get(tool)
+    // FIFO, so a sequential stream pairs each result with the call that opened first. A stream
+    // that interleaves un-idded calls of one tool would mis-pair here; none of the two producers
+    // does, and the alternative (refusing to pair at all) loses the args on every ordinary run.
+    const pending = queue?.shift()
+    if (queue && queue.length === 0) this.byTool.delete(tool)
+    return pending
+  }
+}
+
+/** Read a tool-call id off a stream event, whatever the producer calls it. */
+export function readToolCallId(event: Record<string, unknown>): string | undefined {
+  for (const key of ['toolCallId', 'tool_call_id', 'callId', 'id']) {
+    const value = event[key]
+    if (typeof value === 'string' && value !== '') return value
+  }
+  return undefined
+}
+
+/** A tool call BEGINNING, read off a Pi `--mode json` event, or undefined if it isn't one. */
+export function toolCallStart(
+  event: Record<string, unknown>,
+): { id?: string; name: string; args: unknown } | undefined {
+  if (event.type !== 'tool_execution_start' && event.type !== 'tool_call') return undefined
+  const name = typeof event.toolName === 'string' ? event.toolName : ''
+  if (!name) return undefined
+  // Read every spelling the stream might use rather than pinning one: Pi's event schema has been
+  // renamed under us before (see `todoResultDetails`, which reads three shapes of one result), and
+  // a rename here costs the ARGUMENTS of every call, silently.
+  const args = event.args ?? event.arguments ?? event.input ?? event.parameters
+  const id = readToolCallId(event)
+  return { name, args, ...(id ? { id } : {}) }
+}
+
+/** The RESULT payload of a Pi `tool_execution_end` event, unwrapped from its envelope. */
+export function toolCallResult(event: Record<string, unknown>): unknown {
+  const result = event.result
+  if (result && typeof result === 'object') {
+    const inner = result as Record<string, unknown>
+    // `details` is the structured payload Pi's own extensions return (the todo tool's shape), and
+    // `content`/`output` the free-text ones. Falling back to the whole envelope keeps a shape none
+    // of these match readable rather than empty.
+    return inner.details ?? inner.content ?? inner.output ?? result
+  }
+  return result ?? event.output ?? event.content
+}
+
+/**
+ * Feed one claude-code `user` turn's content blocks to the tracker, emitting an entry per
+ * `tool_result`.
+ *
+ * The CLI answers each `tool_use` with a `tool_result` carrying the same `tool_use_id`, so the
+ * pairing is exact even when the model fired a batch of calls in parallel — which it routinely
+ * does, and which is why the trajectory here is ordered by the ordinal the tracker stamps rather
+ * than by the turn the results arrived on.
+ */
+export function recordClaudeToolResults(
+  tracker: ToolCallTracker,
+  content: readonly unknown[],
+  emit: (call: TrackedToolCall) => void,
+): void {
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue
+    const record = block as Record<string, unknown>
+    if (record.type !== 'tool_result') continue
+    const id = typeof record.tool_use_id === 'string' ? record.tool_use_id : undefined
+    // The block carries no tool NAME (only the id the assistant turn named), so an unpaired
+    // result falls back to a stated placeholder rather than an empty string that would render
+    // as a nameless step.
+    emit(tracker.finished(id, 'unknown', record.content, record.is_error === true))
+  }
+}