@namzu/cli 26.3.0 → 27.0.0

package/dist/integrations/subagents/runtime.js

@@ -5,20 +5,24 @@
  * pre-registered definition needed. Omit `role` for a general-purpose one.
  * The call waits for a final result unless background execution is requested
  * or operator input releases the wait.
- * The child then stays owned by the parent run, and its completion reaches the
+ * The child then stays owned by the parent turn, and its completion reaches the
  * same query's inbox. Headless callers also support explicit background work.
  *
  * The runtime is fully self-contained: a dedicated in-memory session/thread
  * store backs the AgentManager, so sub-agent bookkeeping never touches the
- * CLI's on-disk `/resume` conversation store. A separate session-scoped
- * receipt archive preserves observed outcomes without restoring execution authority.
+ * CLI's `/resume` conversation store. Each child is a child session whose log
+ * the SDK writes under the parent's `<session-id>/subagents/`, and the parent's
+ * log records its spawn and its ending; the saved-agents reader
+ * (`saved-agents.ts`) reads those records back as evidence, never as execution
+ * authority.
  */
-import { AgentManager, AgentRegistry, CompletionInbox, DefaultCapacityValidator, EXPLORE_AGENT_DESCRIPTION, EXPLORE_AGENT_ID, EXPLORE_AGENT_PROMPT, InMemorySessionStore, InMemoryTopicStore, LocalTaskScheduler, ReactiveAgent, RunCancelled, SessionSummaryMaterializer, TopicArchivedError, TopicManager, WorkspaceBackendRegistry, asRunId, asTaskId, defineTool, filterReadOnlyTools, filterToolsNamed, generateSummaryId, isTerminalAgentTaskState, mcpJsonSchemaToZod, openTokenBudget, requireOpenProject, } from '@namzu/sdk';
-import { resolveRunGuards } from '../../config/run-limits.js';
+import { AgentManager, AgentRegistry, CompletionInbox, DefaultCapacityValidator, DiskSessionTokenBudgetStore, EXPLORE_AGENT_DESCRIPTION, EXPLORE_AGENT_ID, EXPLORE_AGENT_PROMPT, InMemorySessionStore, InMemorySessionTokenBudgetStore, InMemoryTopicStore, LocalTaskScheduler, ReactiveAgent, SessionSummaryMaterializer, TopicArchivedError, TopicManager, TurnCancelled, WorkspaceBackendRegistry, asTaskId, asTurnId, defineTool, filterReadOnlyTools, filterToolsNamed, generateSummaryId, isTerminalAgentTaskState, mcpJsonSchemaToZod, openSessionTokenBudget, requireOpenProject, } from '@namzu/sdk';
+import { resolveTurnGuards } from '../../config/run-limits.js';
 import { NAMZU_WORKING_DOCTRINE } from '../../context/doctrine.js';
+import { CLI_CHECKPOINT_RETENTION } from '../state/retention.js';
 import { MAX_AGENT_ACTIVITY_LABEL_CODE_UNITS, MAX_AGENT_PHASE_ORDER, MAX_NARRATION_CODE_UNITS, MAX_RETAINED_NARRATION, SubagentActivityMonitor, } from './activity.js';
-import { DelegationHistory, HISTORY_GUIDANCE } from './history.js';
-import { CLI_INTERACTIVE_RUN_TIMEOUT_MS } from './policy.js';
+import { CLI_INTERACTIVE_TURN_TIMEOUT_MS } from './policy.js';
+import { SAVED_AGENTS_GUIDANCE } from './saved-agents.js';
 /**
  * The parent's narration tool, named once.
  *
@@ -69,12 +73,12 @@ const SUBAGENT_PROMPT = [
     '- If you need to research and have no web tool available, say so plainly and answer from your own knowledge with that caveat — do not invent sources, data, or URLs.',
     '- Do not invent command output or results. If you cannot complete the task, say what blocked you.',
     '',
-    // The same working rules the parent runs under. A delegated task edits the
+    // The same working rules the parent sessions under. A delegated task edits the
     // same repository, and a child that reads a file before editing it while
     // the parent does not is the same defect in the other direction.
     NAMZU_WORKING_DOCTRINE,
 ].join('\n');
-/** Recheck the invoking run before admitting work through a retained gateway. */
+/** Recheck the invoking turn before admitting work through a retained gateway. */
 class ParentTaskScheduler extends LocalTaskScheduler {
     validateParent;
     constructor(manager, context, onEvent, validateParent) {
@@ -106,22 +110,22 @@ class ParentTaskScheduler extends LocalTaskScheduler {
     async waitForTask(taskId) {
         const task = this.getTask(taskId);
         if (!task)
-            throw new Error(`Task ${taskId} does not belong to this parent run`);
+            throw new Error(`Task ${taskId} does not belong to this parent turn`);
         if (isTerminalAgentTaskState(task.state))
             return task;
         return super.waitForTask(taskId);
     }
     async continueTask(taskId, message) {
         if (!this.owns(taskId))
-            throw new Error(`Task ${taskId} does not belong to this parent run`);
+            throw new Error(`Task ${taskId} does not belong to this parent turn`);
         await this.validateParent();
         await super.continueTask(taskId, message);
     }
 }
-/** A delegated run may never inherit the SDK's headless auto-approval fallback. */
+/** A delegated child may never inherit the SDK's headless auto-approval fallback. */
 const refuseUnownedChildReview = async () => ({
     action: 'abort',
-    reason: 'The parent run no longer owns an interactive review channel for this sub-agent.',
+    reason: 'The parent turn no longer owns an interactive review channel for this sub-agent.',
 });
 /**
  * Stand up the AgentManager + gateway + `Agent` tool. Returns the tool to
@@ -147,10 +151,18 @@ export async function createSubagentRuntime(opts) {
         .join('; ');
     const parents = new Map();
     const sessions = new Map();
+    // A ledger this runtime keeps for itself, when neither a shared store nor a
+    // project layout was given. Process-local: it bounds the children of one
+    // root turn, and the parent's own spend is counted wherever the parent
+    // keeps its ledger.
+    const tokenBudgetStore = opts.tokenBudgetStore ??
+        (opts.paths
+            ? new DiskSessionTokenBudgetStore({ paths: opts.paths })
+            : new InMemorySessionTokenBudgetStore());
     let closed = false;
     const sessionKey = ({ project, sessionId }) => JSON.stringify([project.tenantId, project.id, sessionId]);
-    const resolveParent = async (runId) => {
-        const parent = structuredClone(await opts.resolveParent(runId));
+    const resolveParent = async (turnId) => {
+        const parent = structuredClone(await opts.resolveParent(turnId));
         const { project, topic } = parent;
         if (topic.projectId !== project.id || topic.tenantId !== project.tenantId) {
             throw new Error('Delegation parent topic does not belong to its project and tenant');
@@ -174,7 +186,7 @@ export async function createSubagentRuntime(opts) {
         }, tenantId);
         await store.updateSession({ ...session, status: 'active' }, tenantId);
         const manager = new AgentManager(registry, {
-            childTimeoutMs: opts.timeoutMs ?? CLI_INTERACTIVE_RUN_TIMEOUT_MS,
+            childTimeoutMs: opts.timeoutMs ?? CLI_INTERACTIVE_TURN_TIMEOUT_MS,
             capacityBehavior: 'queue',
         }, {
             sessionStore: store,
@@ -195,7 +207,7 @@ export async function createSubagentRuntime(opts) {
     };
     const refreshLimits = async (shared, parent) => {
         if (shared.topicId !== parent.topic.id)
-            throw new Error('Delegation parent changed its topic while runs are active');
+            throw new Error('Delegation parent changed its topic while turns are active');
         // A slow metadata read must not overwrite a newer project snapshot.
         const updatedAt = parent.project.updatedAt.getTime();
         if (updatedAt < shared.projectUpdatedAt)
@@ -234,24 +246,23 @@ export async function createSubagentRuntime(opts) {
             throw error;
         }
     };
-    const gatewayForRun = async (runId) => {
+    const gatewayForTurn = async (turnId) => {
         if (closed)
             throw new Error('Sub-agent runtime is closed');
-        let pending = parents.get(runId);
+        let pending = parents.get(turnId);
         if (!pending) {
             pending = (async () => {
-                const parent = await resolveParent(runId);
-                const budget = await openTokenBudget({
-                    scope: {
-                        tenantId: parent.project.tenantId,
-                        projectId: parent.project.id,
-                        sessionId: parent.sessionId,
-                        runId,
-                    },
-                    limit: resolveRunGuards(opts, opts.resolveLimits?.(runId)).tokenBudget,
-                    pathBuilder: opts.pathBuilder,
-                    workingDirectory: opts.cwd,
+                const parent = await resolveParent(turnId);
+                // The invoking turn is the root of this delegation tree, so its
+                // ledger is keyed `(parent session, invoking turn)` — the ledger the
+                // parent's own `query()` opened for this turn when it shares the
+                // store. Every child spends from an account reserved under it.
+                const budget = await openSessionTokenBudget({
+                    store: tokenBudgetStore,
+                    scope: { rootSessionId: parent.sessionId, rootTurnId: turnId },
+                    limit: resolveTurnGuards(opts, opts.resolveLimits?.(turnId)).tokenBudget,
                 });
+                budget.bindTurn(parent.sessionId, turnId);
                 const lease = await acquireSession(parent);
                 const { manager } = lease.shared;
                 const parentAbortController = new AbortController();
@@ -260,12 +271,13 @@ export async function createSubagentRuntime(opts) {
                     if (closed ||
                         released ||
                         parentAbortController.signal.aborted ||
-                        parents.get(runId) !== pending) {
-                        throw new Error(`Parent run ${runId} was released`);
+                        parents.get(turnId) !== pending) {
+                        throw new Error(`Parent turn ${turnId} was released`);
                     }
                 };
                 const taskContext = {
-                    parentRunId: runId,
+                    parentSessionId: parent.sessionId,
+                    parentTurnId: turnId,
                     parentAgentId: 'namzu',
                     parentAbortController,
                     depth: 0,
@@ -282,10 +294,10 @@ export async function createSubagentRuntime(opts) {
                 };
                 const gateway = new ParentTaskScheduler(manager, taskContext, opts.onEvent, async () => {
                     assertOwned();
-                    const current = await resolveParent(runId);
+                    const current = await resolveParent(turnId);
                     assertOwned();
                     if (sessionKey(current) !== sessionKey(parent))
-                        throw new Error('Delegation run changed its parent scope');
+                        throw new Error('Delegation turn changed its parent scope');
                     await refreshLimits(lease.shared, current);
                     assertOwned();
                 });
@@ -298,8 +310,13 @@ export async function createSubagentRuntime(opts) {
                         if (released)
                             return;
                         released = true;
-                        parentAbortController.abort(new RunCancelled('parent'));
-                        manager.cancelAll(runId, 'parent');
+                        parentAbortController.abort(new TurnCancelled('parent'));
+                        // Only this turn's children. The manager is shared by every
+                        // turn of the session, and `cancelAll` would reach them all.
+                        for (const task of manager.listByParent(parent.sessionId)) {
+                            if (task.context.parentTurnId === turnId)
+                                manager.cancel(task.taskId, 'parent');
+                        }
                         completionInbox.close();
                         lease.release();
                     },
@@ -310,32 +327,32 @@ export async function createSubagentRuntime(opts) {
                 }
                 return runtime;
             })();
-            parents.set(runId, pending);
+            parents.set(turnId, pending);
         }
         try {
             const runtime = await pending;
-            if (closed || parents.get(runId) !== pending)
-                throw new Error(`Parent run ${runId} was released`);
+            if (closed || parents.get(turnId) !== pending)
+                throw new Error(`Parent turn ${turnId} was released`);
             return runtime.gateway;
         }
         catch (error) {
-            if (parents.get(runId) === pending)
-                parents.delete(runId);
+            if (parents.get(turnId) === pending)
+                parents.delete(turnId);
             throw error;
         }
     };
-    const releaseRun = async (runId) => {
-        const pending = parents.get(runId);
+    const releaseTurn = async (turnId) => {
+        const pending = parents.get(turnId);
         if (!pending)
             return;
-        parents.delete(runId);
+        parents.delete(turnId);
         await pending.then((runtime) => runtime.close(), () => undefined);
     };
-    const completionInboxForRun = async (runId) => {
-        await gatewayForRun(runId);
-        const pending = parents.get(runId);
+    const completionInboxForTurn = async (turnId) => {
+        await gatewayForTurn(turnId);
+        const pending = parents.get(turnId);
         if (!pending)
-            throw new Error(`Parent run ${runId} was released`);
+            throw new Error(`Parent turn ${turnId} was released`);
         return (await pending).completionInbox;
     };
     const activity = new SubagentActivityMonitor();
@@ -428,7 +445,7 @@ export async function createSubagentRuntime(opts) {
         readOnly: false,
         destructive: false,
         concurrencySafe: true,
-        timeoutMs: opts.resolveLimits ? 0 : (opts.timeoutMs ?? CLI_INTERACTIVE_RUN_TIMEOUT_MS),
+        timeoutMs: opts.resolveLimits ? 0 : (opts.timeoutMs ?? CLI_INTERACTIVE_TURN_TIMEOUT_MS),
         async execute(input, context) {
             const { description, prompt, subagent_type, role, workflow, phase, phase_order, phase_detail, run_in_background, model: requestedModel, provider: requestedProvider, effort: requestedEffort, } = input;
             if (!requestedModel && (requestedProvider || requestedEffort))
@@ -469,25 +486,25 @@ export async function createSubagentRuntime(opts) {
                 prompt,
                 batchId: context.toolBatchId,
                 toolUseId: context.toolUseId,
-                workflowId: String(context.runId),
+                workflowId: String(context.turnId),
                 workflow,
                 phase,
                 phaseOrder: phase_order,
                 phaseDetail: phase_detail,
             });
-            // The child is a separate run, but its human authority belongs to the
+            // The child is a separate session, but its human authority belongs to the
             // parent turn that invoked Agent. `drainQuery` deliberately auto-approves
             // when a handler is omitted for headless SDK callers; omission here would
             // therefore turn a missing/stale parent mapping into permission to mutate
             // the real project. Always install a handler, and abort if ownership can no
             // longer be proved.
-            const resumeHandler = opts.resolveResumeHandler?.(context.runId) ?? refuseUnownedChildReview;
+            const resumeHandler = opts.resolveResumeHandler?.(context.turnId) ?? refuseUnownedChildReview;
             const configOverrides = {
-                ...resolveRunGuards(opts, opts.resolveLimits?.(context.runId)),
+                ...resolveTurnGuards(opts, opts.resolveLimits?.(context.turnId)),
                 ...(selection ? { model: selection.model, effort: selection.effort } : {}),
                 ...(Object.keys(context.env ?? {}).length > 0 ? { env: context.env } : {}),
-                // The parent run's tool-result screens, so a sub-agent judges a
-                // connected answer the way the run that asked for the work
+                // The parent turn's tool-result screens, so a sub-agent judges a
+                // connected answer the way the turn that asked for the work
                 // does. Without it the child's executor installs the shipped
                 // default, and `toolResultScreens: []` — the operator's off
                 // switch — would hold for the parent and not for anything it
@@ -507,32 +524,19 @@ export async function createSubagentRuntime(opts) {
                     registry.unregister(agentId);
             };
             try {
-                const completionInbox = await completionInboxForRun(context.runId);
-                const parent = await resolveParent(context.runId);
-                const history = opts.historyRoot
-                    ? new DelegationHistory(opts.historyRoot, parent.sessionId)
-                    : undefined;
-                const save = (handle, terminal) => {
-                    history?.write({
-                        taskId: handle.taskId,
-                        parentRunId: context.runId,
-                        description,
-                        status: terminal ? agentTaskOutcome(handle) : 'unresolved',
-                        ...(terminal ? { output: String(completedAgentResult(handle).output ?? '') } : {}),
-                    });
-                };
+                const completionInbox = await completionInboxForTurn(context.turnId);
+                // Nothing is saved here: the SDK records the child's spawn and its
+                // ending in the parent's log, and the child's own log beside it.
                 const outcome = await runBlockingAgentTask({
-                    gateway: await gatewayForRun(context.runId),
+                    gateway: await gatewayForTurn(context.turnId),
                     signal: context.abortSignal,
-                    waitForInbound: opts.resolveWaitForInbound?.(context.runId),
+                    waitForInbound: opts.resolveWaitForInbound?.(context.turnId),
                     background: run_in_background === true,
                     completionInbox,
-                    onCreated: (handle) => {
-                        save(handle, false);
+                    onCreated: () => {
                         taskOwnsCleanup = true;
                     },
                     onSettled: (completed) => {
-                        save(completed, true);
                         tracker.settle(completed);
                     },
                     onFailed: (error) => tracker.fail(error),
@@ -551,7 +555,7 @@ export async function createSubagentRuntime(opts) {
                         ...(phase ? { phase } : {}),
                         ...(phase_detail ? { phaseDetail: phase_detail } : {}),
                         ...(phase_order !== undefined ? { phaseOrder: phase_order } : {}),
-                        // Hang the child run off THIS tool's span, so the delegation
+                        // Hang the child session off THIS tool's span, so the delegation
                         // shows up inside the turn that asked for it. Without it a
                         // sub-agent opens its OWN root trace, and the one structure
                         // a delegation trace exists to record — who dispatched whom
@@ -589,10 +593,10 @@ export async function createSubagentRuntime(opts) {
     });
     const agentTaskListTool = defineTool({
         name: 'agent_task_list',
-        description: 'List the agent invocations launched by this run and their current status, without waiting or starting work. Use this for agent progress questions. task_list contains planning items, not agent invocations. Use wait_for_task with a live ID for its result. Set history: true to inspect saved receipts from this conversation, optionally task_id for one saved result; archives do not prove liveness.',
+        description: 'List the agent invocations launched by this turn and their current status, without waiting or starting work. Use this for agent progress questions. task_list contains planning items, not agent invocations. Use wait_for_task with a live ID for its result. Set history: true to inspect agents saved from earlier turns of this conversation, optionally session_id for one saved result; saved agents are not live.',
         inputSchema: mcpJsonSchemaToZod({
             type: 'object',
-            properties: { history: { type: 'boolean' }, task_id: { type: 'string' } },
+            properties: { history: { type: 'boolean' }, session_id: { type: 'string' } },
             additionalProperties: false,
         }),
         category: 'custom',
@@ -602,28 +606,27 @@ export async function createSubagentRuntime(opts) {
         concurrencySafe: true,
         async execute(input, context) {
             const request = input;
-            if (request.history || request.task_id) {
-                if (!opts.historyRoot)
+            if (request.history || request.session_id) {
+                if (!opts.savedAgents)
                     return {
                         success: false,
                         output: 'Saved delegation history is unavailable in this host.',
                     };
-                const parent = await resolveParent(context.runId);
-                const history = new DelegationHistory(opts.historyRoot, parent.sessionId);
-                const saved = request.task_id
-                    ? { tasks: [history.read(request.task_id)], omitted: 0 }
-                    : history.list();
-                const tasks = saved.tasks.map(({ output, ...row }) => request.task_id ? { ...row, output } : row);
+                const parent = await resolveParent(context.turnId);
+                const history = opts.savedAgents(parent.sessionId);
+                const saved = request.session_id
+                    ? { agents: [await history.read(request.session_id)], omitted: 0 }
+                    : await history.list();
                 return {
                     success: true,
                     output: JSON.stringify({
-                        ...saved,
-                        tasks,
-                        guidance: HISTORY_GUIDANCE,
+                        agents: saved.agents,
+                        omitted: saved.omitted,
+                        guidance: SAVED_AGENTS_GUIDANCE,
                     }),
                 };
             }
-            const gateway = await gatewayForRun(context.runId);
+            const gateway = await gatewayForTurn(context.turnId);
             const tasks = gateway.listTasks();
             const labels = new Map(activity.getSnapshot().map((entry) => [entry.taskId, entry.description]));
             const shown = tasks.slice(-40).map((task) => ({
@@ -651,7 +654,7 @@ export async function createSubagentRuntime(opts) {
     });
     const waitForTaskTool = defineTool({
         name: 'wait_for_task',
-        description: 'Wait for a task this run already launched, or retrieve its complete result after a task notification. This does not start new work. Operator input releases the wait while the task continues.',
+        description: 'Wait for a task this turn already launched, or retrieve its complete result after a task notification. This does not start new work. Operator input releases the wait while the task continues.',
         inputSchema: mcpJsonSchemaToZod({
             type: 'object',
             properties: {
@@ -667,9 +670,9 @@ export async function createSubagentRuntime(opts) {
         readOnly: true,
         destructive: false,
         concurrencySafe: true,
-        timeoutMs: opts.resolveLimits ? 0 : (opts.timeoutMs ?? CLI_INTERACTIVE_RUN_TIMEOUT_MS),
+        timeoutMs: opts.resolveLimits ? 0 : (opts.timeoutMs ?? CLI_INTERACTIVE_TURN_TIMEOUT_MS),
         async execute(input, context) {
-            const gateway = await gatewayForRun(context.runId);
+            const gateway = await gatewayForTurn(context.turnId);
             let taskId;
             try {
                 taskId = asTaskId(input.task_id);
@@ -686,14 +689,14 @@ export async function createSubagentRuntime(opts) {
                 return {
                     success: false,
                     output: '',
-                    error: `Task ${taskId} does not belong to this parent run.`,
+                    error: `Task ${taskId} does not belong to this parent turn.`,
                 };
             const outcome = await runBlockingAgentTask({
                 gateway,
                 task,
                 signal: context.abortSignal,
-                completionInbox: await completionInboxForRun(context.runId),
-                waitForInbound: opts.resolveWaitForInbound?.(context.runId),
+                completionInbox: await completionInboxForTurn(context.turnId),
+                waitForInbound: opts.resolveWaitForInbound?.(context.turnId),
                 onCreated: () => { },
                 onSettled: () => { },
                 onFailed: () => { },
@@ -715,7 +718,7 @@ export async function createSubagentRuntime(opts) {
     });
     const sendMessageTool = defineTool({
         name: 'send_message',
-        description: 'Queue a correction or additional context for a running or queued sub-agent task owned by this run. The child receives it at its next request boundary; acceptance is not delivery. This does not start new work or restart finished tasks.',
+        description: 'Queue a correction or additional context for a running or queued sub-agent task owned by this turn. The child receives it at its next request boundary; acceptance is not delivery. This does not start new work or restart finished tasks.',
         inputSchema: mcpJsonSchemaToZod({
             type: 'object',
             properties: {
@@ -748,13 +751,13 @@ export async function createSubagentRuntime(opts) {
                     error: 'Message must not be blank.',
                 };
             const taskId = asTaskId(task_id);
-            const gateway = await gatewayForRun(context.runId);
+            const gateway = await gatewayForTurn(context.turnId);
             const task = gateway.getTask(taskId);
             if (!task)
                 return {
                     success: false,
                     output: '',
-                    error: `Task ${taskId} does not belong to this parent run.`,
+                    error: `Task ${taskId} does not belong to this parent turn.`,
                 };
             if (isTerminalAgentTaskState(task.state))
                 return {
@@ -777,7 +780,7 @@ export async function createSubagentRuntime(opts) {
     });
     const cancelAgentTool = defineTool({
         name: 'cancel_agent',
-        description: 'Request cancellation of one running or queued agent task owned by this run. Other agents and the parent continue. Acceptance is not proof of termination; check agent_task_list or wait_for_task for the terminal outcome. Does not restart finished tasks.',
+        description: 'Request cancellation of one running or queued agent task owned by this turn. Other agents and the parent continue. Acceptance is not proof of termination; check agent_task_list or wait_for_task for the terminal outcome. Does not restart finished tasks.',
         inputSchema: mcpJsonSchemaToZod({
             type: 'object',
             properties: {
@@ -797,13 +800,13 @@ export async function createSubagentRuntime(opts) {
         async execute(input, context) {
             context.abortSignal.throwIfAborted();
             const taskId = asTaskId(input.task_id);
-            const gateway = await gatewayForRun(context.runId);
+            const gateway = await gatewayForTurn(context.turnId);
             const task = gateway.getTask(taskId);
             if (!task)
                 return {
                     success: false,
                     output: '',
-                    error: `Task ${taskId} does not belong to this parent run.`,
+                    error: `Task ${taskId} does not belong to this parent turn.`,
                 };
             if (isTerminalAgentTaskState(task.state))
                 return {
@@ -855,7 +858,7 @@ export async function createSubagentRuntime(opts) {
         // for the operator who would otherwise be asked to approve being shown
         // it — a consent dialog per line of commentary is a tool nobody would
         // call. This is not a claim that the line is ephemeral: the kernel
-        // records THIS call in the run's transcript and checkpoints exactly as
+        // records THIS call in the session log and checkpoints exactly as
         // it records every other, so the text comes back into the model's own
         // history on a resume even though the band it was shown in does not.
         // Narration's parent-only boundary does not rest on this flag either:
@@ -901,7 +904,7 @@ export async function createSubagentRuntime(opts) {
         if (closePromise)
             return closePromise;
         closed = true;
-        closePromise = Promise.all([...parents.keys()].map(releaseRun)).then(() => activity.close());
+        closePromise = Promise.all([...parents.keys()].map(releaseTurn)).then(() => activity.close());
         return closePromise;
     };
     const listModels = opts.listModels;
@@ -934,9 +937,9 @@ export async function createSubagentRuntime(opts) {
     return {
         cancelAgentTool,
         modelCatalogueTool,
-        gatewayForRun,
-        completionInboxForRun,
-        releaseRun,
+        gatewayForTurn,
+        completionInboxForTurn,
+        releaseTurn,
         agentTool,
         waitForTaskTool,
         agentTaskListTool,
@@ -1042,24 +1045,24 @@ async function runBlockingAgentTask(input) {
     }
 }
 function agentTaskOutcome(task) {
-    const run = task.result;
-    if (run?.status && run.status !== 'completed')
-        return run.status;
-    if (task.state === 'completed' && run?.stopReason && run.stopReason !== 'end_turn')
+    const result = task.result;
+    if (result?.status && result.status !== 'completed')
+        return result.status;
+    if (task.state === 'completed' && result?.stopReason && result.stopReason !== 'end_turn')
         return 'incomplete';
     return task.state;
 }
 /** Lifecycle completion is not proof the requested task finished successfully. */
 function completedAgentResult(completed) {
-    const run = completed.result;
+    const turn = completed.result;
     const status = agentTaskOutcome(completed);
     const succeeded = status === 'completed';
-    const value = run?.structuredOutput ?? run?.result;
+    const value = turn?.structuredOutput ?? turn?.result;
     let resultText = typeof value === 'string' ? value : value === undefined ? '' : JSON.stringify(value);
-    if (!resultText && run?.stopReason && run.stopReason !== 'end_turn') {
-        // A hard limit can stop between tool rounds without setting Run.result.
+    if (!resultText && turn?.stopReason && turn.stopReason !== 'end_turn') {
+        // A hard limit can stop between tool rounds without setting Turn.result.
         // Keep the child's last visible statement, never its reasoning or tool data.
-        const partial = [...run.messages]
+        const partial = [...turn.messages]
             .reverse()
             .find((message) => message.role === 'assistant' &&
             typeof message.content === 'string' &&
@@ -1067,8 +1070,8 @@ function completedAgentResult(completed) {
         if (typeof partial === 'string')
             resultText = partial;
     }
-    const stopNote = run?.stopReason && run.stopReason !== 'end_turn'
-        ? `Sub-agent run ended with stop reason "${run.stopReason}". Output may be partial; this does not establish task completion.\n\n`
+    const stopNote = turn?.stopReason && turn.stopReason !== 'end_turn'
+        ? `Sub-agent turn ended with stop reason "${turn.stopReason}". Output may be partial; this does not establish task completion.\n\n`
         : '';
     // ToolResult.data is host metadata, not necessarily model-visible content.
     // Keep the handle and terminal status separate from arbitrary child output
@@ -1079,14 +1082,14 @@ function completedAgentResult(completed) {
         output,
         ...(!succeeded
             ? {
-                error: `Sub-agent ${completed.agentId} ${status}: ${run?.lastError ?? ''}\n${output}`,
+                error: `Sub-agent ${completed.agentId} ${status}: ${turn?.lastError ?? ''}\n${output}`,
             }
             : {}),
         data: {
             task_id: completed.taskId,
             state: completed.state,
             status,
-            ...(run?.stopReason ? { stop_reason: run.stopReason } : {}),
+            ...(turn?.stopReason ? { stop_reason: turn.stopReason } : {}),
         },
     };
 }
@@ -1125,17 +1128,17 @@ model = opts.model, selection) {
         // erased Agent<BaseAgentConfig,…>. configBuilder supplies the richer config.
         typedAgent: agent,
         configBuilder: async (options) => {
-            const limits = resolveRunGuards(opts, options.parentRunId ? opts.resolveLimits?.(asRunId(options.parentRunId)) : undefined);
+            const limits = resolveTurnGuards(opts, options.parentTurnId ? opts.resolveLimits?.(asTurnId(options.parentTurnId)) : undefined);
             // Resolved HERE, per child, rather than captured once for the session:
             // what day it is and which branch is checked out can both have changed
             // since the parent started, and a sub-agent asserting the stale answer
             // is worse than one that was never told.
             const environment = opts.readEnvironment ? await opts.readEnvironment() : null;
-            // AgentManager supplies the actual parent run before it stamps the child's
+            // AgentManager supplies the actual parent turn before it stamps the child's
             // own Session ID. All delegated work shares that invoking conversation's
             // upstream billing session, even after the TUI moves to another one.
-            const parent = options.parentRunId
-                ? await opts.resolveParent(asRunId(options.parentRunId))
+            const parent = options.parentTurnId
+                ? await opts.resolveParent(asTurnId(options.parentTurnId))
                 : undefined;
             const provider = await opts.buildProvider(parent?.sessionId, selection);
             const registry = tools();
@@ -1143,8 +1146,9 @@ model = opts.model, selection) {
             return {
                 model: options.model ?? model,
                 tokenBudget: options.tokenBudget ?? opts.tokenBudget ?? 0,
-                timeoutMs: options.timeoutMs ?? opts.timeoutMs ?? CLI_INTERACTIVE_RUN_TIMEOUT_MS,
+                timeoutMs: options.timeoutMs ?? opts.timeoutMs ?? CLI_INTERACTIVE_TURN_TIMEOUT_MS,
                 maxIterations: limits.maxIterations,
+                pruneKeepLast: CLI_CHECKPOINT_RETENTION,
                 provider,
                 ...(webSearch ? { webSearch } : {}),
                 ...(selection?.effort ? { effort: selection.effort } : {}),
@@ -1169,7 +1173,9 @@ model = opts.model, selection) {
                 ...(opts.sandboxTeardownTimeoutMs !== undefined
                     ? { sandboxTeardownTimeoutMs: opts.sandboxTeardownTimeoutMs }
                     : {}),
-                ...(opts.pathBuilder ? { pathBuilder: opts.pathBuilder } : {}),
+                ...(opts.outsideRootAccess ? { outsideRootAccess: opts.outsideRootAccess } : {}),
+                ...(opts.sandboxEscape ? { sandboxEscape: opts.sandboxEscape } : {}),
+                ...(opts.paths ? { paths: opts.paths } : {}),
             };
         },
     };