Add read_agent_trace fleet verb for orchestrator tiers

Lets an orchestrator or nested orchestrator read a worker's on-disk
turns.jsonl directly, so a cancelled or interrupted worker's completed
work is no longer invisible once its in-memory session record is gone.
Every response is bounded (turn window, entry count, per-entry chars),
tolerates partially written/malformed lines, and reports a clean error
for an unknown target. Fixes a latest-symlink double-count in directory
enumeration by resolving symlinks and de-duping by real path.

progress_note for leaf workers is a separate follow-up, not included
here.

Author: TheGreatAxios

CHANGELOG.md

@@ -39,6 +39,22 @@ parallel copies under `docs/` or `scripts/notes/`. At cut time: rename
   own), so the two layers no longer multiply. Attempt counts are now logged
   on each recovery so retry storms are visible in traces.
 
+- **`read_agent_trace` lets an orchestrator inspect a worker's on-disk trace
+  directly**, so a cancelled or interrupted worker's completed work is no
+  longer invisible just because its in-memory session record is gone. Reads
+  turns, tool calls, and tool errors straight from the worker's
+  `turns.jsonl`, tolerating a partially written or malformed line without
+  failing. Every response is bounded on four independent axes — turn window,
+  entry count, per-entry characters, and total output characters (the first
+  three multiply, so a total-output ceiling caps them together) — each with
+  a hard maximum the caller cannot exceed, and a truncated response says
+  exactly what was left out and how to page for the rest. A Tier 2 nested
+  orchestrator can only read its own descendants' traces, enforced by
+  reusing `SubAgentSessionStore`'s existing parentSessionId chain
+  (`assertCanTargetAgent`'s first live call site); leaf directors never see
+  the tool at all. `progress_note` for leaf workers is a separate,
+  not-yet-implemented follow-up.
+
 ### Fixed
 
 - **Interrupting a turn no longer risks a startup crash.** If an interrupt hit

src/agent/tools.ts

@@ -46,6 +46,7 @@ import { createWebSearchTool, disposeWebSearchClients } from "../tools/web-searc
 import { createUseSkillTool } from "./use-skill.js";
 import { createToolIndex, createToolSearchTool } from "./tool-search.js";
 import { createSearchAgentsTool } from "./agent-search.js";
+import { createReadAgentTraceTool } from "../subagent/trace-tool.js";
 import {
   createCodexToolProxies,
   type CodexRunManageTasks,
@@ -309,6 +310,9 @@ export async function createAgentToolset(args: AgentToolsetArgs): Promise<AgentT
                 }),
               ]
             : []),
+          // Tier 1: the primary session is always an orchestrator, so this is
+          // unconditional wherever task/search_agents are mounted.
+          createReadAgentTraceTool(args.subAgent.getWorkdirBase),
         ]
       : []),
     stringTool({

src/subagent/authority.ts

@@ -5,9 +5,10 @@
  * in a prompt. This module owns two checks:
  *
  *  - assertTierMayMountFleetVerb: a Tier 3 leaf may never mount a fleet verb
- *    (today: task, search_agents; the spawn_agent/wait_agents/list_agents/
- *    send_input/interrupt_agent/close_agent/resume_agent/read_agent_trace
- *    verbs land in later child issues against this same gate).
+ *    (today: task, search_agents, read_agent_trace; the spawn_agent/
+ *    wait_agents/list_agents/send_input/interrupt_agent/close_agent/
+ *    resume_agent/followup_task verbs land in later child issues against
+ *    this same gate).
  *  - assertCanTargetAgent: a Tier 2 nested orchestrator may act only on its
  *    own descendants, never a sibling or anything above it in the tree.
  *    Tier 1 (the primary orchestrator) may target anyone. Callers pass the

src/subagent/run.ts

@@ -105,6 +105,7 @@ import {
 } from "./stop-policy.js";
 import { SubAgentDirector } from "./nudge-director.js";
 import { assertTierMayMountFleetVerb } from "./authority.js";
+import { createReadAgentTraceTool } from "./trace-tool.js";
 import {
   abortError,
   createSubAgentSpawnRegistryPlugin,
@@ -435,7 +436,7 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<string> {
       // AgentProfile with orchestrator: true from mounting task/search_agents
       // just because it is outside the closed director set.
       const tier = params.orchestratorTier ?? "leaf";
-      for (const verb of ["task", "search_agents"]) {
+      for (const verb of ["task", "search_agents", "read_agent_trace"]) {
         assertTierMayMountFleetVerb(tier, verb);
       }
       if (params.nestedDispatch === undefined) {
@@ -481,6 +482,11 @@ export async function runSubAgent(params: RunSubAgentParams): Promise<string> {
               }),
             ]
           : []),
+        // Every worker at every nesting depth is created under the same root
+        // workdirBase (nestedDispatch.getWorkdirBase is threaded through
+        // unchanged, never rebound to this worker's own dir), so the trace
+        // reader's search root is that same function.
+        createReadAgentTraceTool(nd.getWorkdirBase),
       ];
     }
 

src/subagent/trace-reader.test.ts

@@ -0,0 +1,228 @@
+import { describe, test, expect } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  AgentTraceNotFoundError,
+  findAgentTraceDir,
+  listUniqueSubdirs,
+  readAgentTrace,
+  MAX_TRACE_ENTRY_LIMIT,
+  MAX_TRACE_TURN_WINDOW,
+} from "./trace-reader.js";
+
+function tempDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "trace-reader-"));
+}
+
+function writeTurns(dir: string, turns: unknown[]): void {
+  fs.mkdirSync(dir, { recursive: true });
+  const text = turns.map((t) => JSON.stringify(t)).join("\n") + (turns.length > 0 ? "\n" : "");
+  fs.writeFileSync(path.join(dir, "turns.jsonl"), text);
+}
+
+describe("listUniqueSubdirs", () => {
+  test("a directory containing latest plus its target enumerates the session exactly once", async () => {
+    const root = tempDir();
+    const real = path.join(root, "01234567-89ab-7def-8123-456789abcdef");
+    fs.mkdirSync(real);
+    fs.symlinkSync(path.basename(real), path.join(root, "latest"));
+
+    const entries = await listUniqueSubdirs(root);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]!.path).toBe(fs.realpathSync(real));
+  });
+
+  test("two distinct real directories are both listed", async () => {
+    const root = tempDir();
+    fs.mkdirSync(path.join(root, "a"));
+    fs.mkdirSync(path.join(root, "b"));
+    const entries = await listUniqueSubdirs(root);
+    expect(entries).toHaveLength(2);
+  });
+
+  test("a broken symlink is skipped, not thrown", async () => {
+    const root = tempDir();
+    fs.symlinkSync(path.join(root, "does-not-exist"), path.join(root, "dangling"));
+    const entries = await listUniqueSubdirs(root);
+    expect(entries).toHaveLength(0);
+  });
+
+  test("missing directory returns empty rather than throwing", async () => {
+    const entries = await listUniqueSubdirs(path.join(tempDir(), "nope"));
+    expect(entries).toHaveLength(0);
+  });
+});
+
+describe("findAgentTraceDir", () => {
+  test("finds a direct child under root/subagents", async () => {
+    const root = tempDir();
+    const childDir = path.join(root, "subagents", "child-1");
+    writeTurns(childDir, []);
+    const found = await findAgentTraceDir(root, "child-1");
+    expect(found).toBe(fs.realpathSync(childDir));
+  });
+
+  test("finds a nested descendant several levels deep", async () => {
+    const root = tempDir();
+    const grandchildDir = path.join(root, "subagents", "child-1", "subagents", "grandchild-1");
+    writeTurns(grandchildDir, []);
+    const found = await findAgentTraceDir(root, "grandchild-1");
+    expect(found).toBe(fs.realpathSync(grandchildDir));
+  });
+
+  test("returns null for an unknown id", async () => {
+    const root = tempDir();
+    writeTurns(path.join(root, "subagents", "child-1"), []);
+    const found = await findAgentTraceDir(root, "does-not-exist");
+    expect(found).toBeNull();
+  });
+
+  test("is not confused by a latest symlink alongside the real worker dir", async () => {
+    const root = tempDir();
+    const childDir = path.join(root, "subagents", "child-1");
+    writeTurns(childDir, []);
+    fs.symlinkSync("child-1", path.join(root, "subagents", "latest"));
+    const found = await findAgentTraceDir(root, "child-1");
+    expect(found).toBe(fs.realpathSync(childDir));
+  });
+});
+
+describe("readAgentTrace", () => {
+  test("throws a clean error for a missing target", async () => {
+    const root = tempDir();
+    await expect(readAgentTrace(root, "ghost")).rejects.toBeInstanceOf(AgentTraceNotFoundError);
+  });
+
+  test("reads turns, tool calls, and tool errors", async () => {
+    const root = tempDir();
+    const childDir = path.join(root, "subagents", "worker-1");
+    writeTurns(childDir, [
+      { role: "user", content: [{ type: "text", text: "do the thing" }] },
+      {
+        role: "assistant",
+        content: [{ type: "tool_call", id: "call-1", name: "run_shell", arguments: { cmd: "ls" } }],
+      },
+      {
+        role: "user",
+        content: [
+          {
+            type: "tool_result",
+            callId: "call-1",
+            content: [{ type: "text", text: "boom" }],
+            isError: true,
+          },
+        ],
+      },
+    ]);
+
+    const result = await readAgentTrace(root, "worker-1");
+    expect(result.totalTurns).toBe(3);
+    expect(result.entries.map((e) => e.kind)).toEqual(["text", "tool_call", "error"]);
+    expect(result.entries[2]!.isError).toBe(true);
+    expect(result.omitted).toBeNull();
+  });
+
+  test("skips a malformed trailing line instead of throwing", async () => {
+    const root = tempDir();
+    const childDir = path.join(root, "subagents", "worker-1");
+    fs.mkdirSync(childDir, { recursive: true });
+    const good = JSON.stringify({ role: "user", content: [{ type: "text", text: "hi" }] });
+    fs.writeFileSync(path.join(childDir, "turns.jsonl"), `${good}\n{"role":"assistant","cont`);
+
+    const result = await readAgentTrace(root, "worker-1");
+    expect(result.totalTurns).toBe(1);
+    expect(result.parseWarnings).toBe(1);
+    expect(result.entries).toHaveLength(1);
+  });
+
+  test("bounds the entry count to the requested limit and reports omission", async () => {
+    const root = tempDir();
+    const childDir = path.join(root, "subagents", "worker-1");
+    const turns = Array.from({ length: 5 }, (_, i) => ({
+      role: "assistant",
+      content: [{ type: "text", text: `turn ${i}` }],
+    }));
+    writeTurns(childDir, turns);
+
+    const result = await readAgentTrace(root, "worker-1", { limit: 2 });
+    expect(result.entries).toHaveLength(2);
+    expect(result.entriesTruncated).toBe(true);
+    expect(result.omitted).not.toBeNull();
+    expect(result.omitted!.hint.length).toBeGreaterThan(0);
+  });
+
+  test("never exceeds the hard entry-limit cap regardless of requested limit", async () => {
+    const root = tempDir();
+    const childDir = path.join(root, "subagents", "worker-1");
+    const turns = Array.from({ length: 10 }, (_, i) => ({
+      role: "assistant",
+      content: [{ type: "text", text: `turn ${i}` }],
+    }));
+    writeTurns(childDir, turns);
+
+    const result = await readAgentTrace(root, "worker-1", { limit: 1_000_000 });
+    expect(result.entries.length).toBeLessThanOrEqual(MAX_TRACE_ENTRY_LIMIT);
+  });
+
+  test("never exceeds the hard turn-window cap regardless of requested range", async () => {
+    const root = tempDir();
+    const childDir = path.join(root, "subagents", "worker-1");
+    const turns = Array.from({ length: 500 }, (_, i) => ({
+      role: "assistant",
+      content: [{ type: "text", text: `turn ${i}` }],
+    }));
+    writeTurns(childDir, turns);
+
+    const result = await readAgentTrace(root, "worker-1", {
+      fromTurn: 0,
+      toTurn: 500,
+      limit: MAX_TRACE_ENTRY_LIMIT,
+    });
+    expect(result.toTurn - result.fromTurn).toBeLessThanOrEqual(MAX_TRACE_TURN_WINDOW);
+  });
+
+  test("filters entries by kind", async () => {
+    const root = tempDir();
+    const childDir = path.join(root, "subagents", "worker-1");
+    writeTurns(childDir, [
+      {
+        role: "assistant",
+        content: [
+          { type: "thinking", thinking: "hmm" },
+          { type: "text", text: "hello" },
+        ],
+      },
+    ]);
+
+    const result = await readAgentTrace(root, "worker-1", { kinds: ["text"] });
+    expect(result.entries.map((e) => e.kind)).toEqual(["text"]);
+  });
+
+  test("truncates an oversized entry body and marks it truncated", async () => {
+    const root = tempDir();
+    const childDir = path.join(root, "subagents", "worker-1");
+    writeTurns(childDir, [
+      { role: "assistant", content: [{ type: "text", text: "x".repeat(10_000) }] },
+    ]);
+
+    const result = await readAgentTrace(root, "worker-1");
+    expect(result.entries[0]!.truncated).toBe(true);
+    expect(result.entries[0]!.content.length).toBeLessThan(10_000);
+  });
+
+  test("a partially written trace (worker still running) reads what exists so far", async () => {
+    const root = tempDir();
+    const childDir = path.join(root, "subagents", "worker-1");
+    fs.mkdirSync(childDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(childDir, "turns.jsonl"),
+      `${JSON.stringify({ role: "user", content: [{ type: "text", text: "go" }] })}\n`,
+    );
+
+    const result = await readAgentTrace(root, "worker-1");
+    expect(result.totalTurns).toBe(1);
+    expect(result.entries).toHaveLength(1);
+  });
+});