@namzu/cli 20.0.0 → 22.0.0

package/dist/integrations/subagents/runtime.js

@@ -3,17 +3,20 @@
  * DEFINE a specialist on the fly — pass a `role` (the persona / system prompt)
  * and namzu spins up a fresh sub-agent with that role at runtime, no
  * pre-registered definition needed. Omit `role` for a general-purpose one.
- * The call waits for a final result unless operator input releases the wait.
+ * 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
- * same query's inbox. Headless callers without an input waiter remain blocking.
+ * 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.
+ * CLI's on-disk `/resume` conversation store. A separate session-scoped
+ * receipt archive preserves observed outcomes without restoring 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, asTaskId, defineTool, filterReadOnlyTools, filterToolsNamed, generateSummaryId, isTerminalAgentTaskState, mcpJsonSchemaToZod, openTokenBudget, requireOpenProject, } from '@namzu/sdk';
+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 { NAMZU_WORKING_DOCTRINE } from '../../context/doctrine.js';
 import { MAX_AGENT_ACTIVITY_LABEL_CODE_UNITS, MAX_AGENT_PHASE_ORDER, SubagentActivityMonitor, } from './activity.js';
+import { DelegationHistory, HISTORY_GUIDANCE } from './history.js';
 import { CLI_INTERACTIVE_RUN_TIMEOUT_MS } from './policy.js';
 export const GENERAL_PURPOSE_SUBAGENT = 'general-purpose';
 /**
@@ -59,21 +62,32 @@ class ParentTaskScheduler extends LocalTaskScheduler {
     }
     async createTask(options) {
         await this.validateParent();
-        return super.createTask(options);
+        return super.createTask({
+            ...options,
+            beforeStart: async () => {
+                await options.beforeStart?.();
+                await this.validateParent();
+            },
+        });
     }
     owns(taskId) {
         return super.listTasks().some((task) => task.taskId === taskId);
     }
     getTask(taskId) {
-        return this.owns(taskId) ? super.getTask(taskId) : undefined;
+        // The parent ledger retains terminal results after the manager evicts
+        // its live record. Lookup and waiting must read the same owned history.
+        return super.listTasks().find((task) => task.taskId === taskId);
     }
     cancelTask(taskId, cause) {
         if (this.owns(taskId))
             super.cancelTask(taskId, cause);
     }
     async waitForTask(taskId) {
-        if (!this.owns(taskId))
+        const task = this.getTask(taskId);
+        if (!task)
             throw new Error(`Task ${taskId} does not belong to this parent run`);
+        if (isTerminalAgentTaskState(task.state))
+            return task;
         return super.waitForTask(taskId);
     }
     async continueTask(taskId, message) {
@@ -138,7 +152,7 @@ export async function createSubagentRuntime(opts) {
             currentActor: parentActor,
         }, tenantId);
         await store.updateSession({ ...session, status: 'active' }, tenantId);
-        const manager = new AgentManager(registry, { childTimeoutMs: CLI_INTERACTIVE_RUN_TIMEOUT_MS }, {
+        const manager = new AgentManager(registry, { childTimeoutMs: CLI_INTERACTIVE_RUN_TIMEOUT_MS, capacityBehavior: 'queue' }, {
             sessionStore: store,
             summaryMaterializer: new SessionSummaryMaterializer({
                 store,
@@ -210,7 +224,7 @@ export async function createSubagentRuntime(opts) {
                         sessionId: parent.sessionId,
                         runId,
                     },
-                    limit: opts.tokenBudget ?? 1_000_000,
+                    limit: opts.tokenBudget ?? 0,
                     pathBuilder: opts.pathBuilder,
                     workingDirectory: opts.cwd,
                 });
@@ -308,14 +322,15 @@ export async function createSubagentRuntime(opts) {
     const agentTool = defineTool({
         name: 'Agent',
         description: [
-            'Delegate a self-contained task to a sub-agent and wait for its result. If the operator sends a message while you wait, this call returns the running task ID so you can respond; the child keeps working and its result arrives later as a task notification.',
+            'Delegate a self-contained task to a sub-agent. Set run_in_background: true to receive its task ID immediately and continue independent work; completion arrives as a task notification. Otherwise wait for its result. Operator input can also release a blocking wait while the child keeps working. Use agent_task_list for current agent status (task_list is only the planning list), send_message to correct a running task, cancel_agent to stop only one owned task, and wait_for_task to retrieve its result; never launch duplicate work.',
+            'For a request to run multiple independent tasks in parallel, issue all Agent calls together in one response, or set run_in_background: true on each launch before waiting. A single blocking Agent call followed by another call runs them sequentially.',
             'Pick `subagent_type: "explore"` for anything that only needs to look — where is X defined, which files reference Y, how does Z work — it has reading and searching tools only and never asks for permission.',
             'Use the default "general-purpose" when the task must change files or run commands.',
             'Define a specialist inline with `role` — a system prompt describing who the sub-agent is and how to behave (e.g.',
             '"You are a security auditor; flag vulnerabilities and rate severity"); with `subagent_type: "explore"` the role keeps the read-only roster.',
             'Omit `role` for the plain sub-agent.',
             'The sub-agent runs in its own context with its own tools and cannot see this conversation — put everything it needs in `prompt`.',
-            'Call this multiple times in one response to run specialists in parallel.',
+            "Call this multiple times in one response to run specialists in parallel. Tasks beyond the project's live-agent capacity wait in a queue and start as slots become available. Queued tasks have not started execution; do not relaunch them.",
             'When coordinating several specialists, give them the same `workflow` label and an explicit `phase` plus `phase_order` so the operator can follow the work in the agent cockpit.',
             'These fields are display annotations only; they do not create dependencies, barriers, or serial execution.',
             fileAgentSummary.length > 0 ? `Project-defined types: ${fileAgentSummary}.` : '',
@@ -333,6 +348,10 @@ export async function createSubagentRuntime(opts) {
                     type: 'string',
                     description: 'Self-contained task with all the context the sub-agent needs.',
                 },
+                run_in_background: {
+                    type: 'boolean',
+                    description: 'Return after launch so the parent can continue independent work. Defaults to false.',
+                },
                 subagent_type: {
                     type: 'string',
                     enum: agentTypeIds,
@@ -340,6 +359,18 @@ export async function createSubagentRuntime(opts) {
                         ? ` This project also defines: ${fileAgentSummary}. Prefer a project-defined type when its description fits the task.`
                         : ''}`,
                 },
+                model: {
+                    type: 'string',
+                    description: 'Exact child model ID. Omit to inherit the session model. Use agent_models to discover available IDs; do not search repository files.',
+                },
+                provider: {
+                    type: 'string',
+                    description: 'Provider for this child only. Requires model; does not switch the parent conversation.',
+                },
+                effort: {
+                    type: 'string',
+                    description: 'Exact reasoning effort supported by the child model. Requires model. Omit for its provider default.',
+                },
                 role: {
                     type: 'string',
                     description: 'Optional persona / system prompt that defines this specialist sub-agent. Omit for general-purpose.',
@@ -370,12 +401,19 @@ export async function createSubagentRuntime(opts) {
         concurrencySafe: true,
         timeoutMs: CLI_INTERACTIVE_RUN_TIMEOUT_MS,
         async execute(input, context) {
-            const { description, prompt, subagent_type, role, workflow, phase, phase_order } = input;
+            const { description, prompt, subagent_type, role, workflow, phase, phase_order, run_in_background, model: requestedModel, provider: requestedProvider, effort: requestedEffort, } = input;
+            if (!requestedModel && (requestedProvider || requestedEffort))
+                throw new Error('Supply model when selecting a child provider or effort.');
+            if (requestedModel && !opts.resolveModel)
+                throw new Error('Child model selection is unavailable in this host.');
+            const selection = requestedModel
+                ? await opts.resolveModel?.({ model: requestedModel, provider: requestedProvider, effort: requestedEffort }, context.abortSignal)
+                : undefined;
             const explore = subagent_type === EXPLORE_SUBAGENT;
             const fileAgent = subagent_type !== undefined ? fileAgents.get(subagent_type) : undefined;
             let agentId = fileAgent?.name ?? (explore ? EXPLORE_SUBAGENT : GENERAL_PURPOSE_SUBAGENT);
             const persona = typeof role === 'string' ? role.trim() : '';
-            const dynamic = persona.length > 0;
+            const dynamic = persona.length > 0 || selection !== undefined;
             if (dynamic) {
                 // A role on top of a type keeps that type's roster and model: the
                 // persona says who the child is, the type says what it may touch,
@@ -383,11 +421,13 @@ export async function createSubagentRuntime(opts) {
                 // tool. Over a file-defined agent the role is appended to the
                 // file's prompt rather than replacing it.
                 agentId = `dyn-${++dynCounter}`;
-                registry.register(buildDefinition(agentId, `Dynamic specialist: ${agentId}`, fileAgent ? `${fileAgent.prompt}\n\n${persona}` : persona, opts, fileAgent
+                registry.register(buildDefinition(agentId, `Dynamic specialist: ${agentId}`, fileAgent
+                    ? `${fileAgent.prompt}\n\n${persona}`
+                    : persona || (explore ? EXPLORE_PROMPT : SUBAGENT_PROMPT), opts, fileAgent
                     ? fileAgentTools(fileAgent, opts)
                     : explore
                         ? () => filterReadOnlyTools(opts.buildTools())
-                        : opts.buildTools, fileAgent?.model ?? opts.model));
+                        : opts.buildTools, selection?.model ?? fileAgent?.model ?? opts.model, selection));
             }
             const tracker = activity.begin({
                 agentId,
@@ -408,6 +448,8 @@ export async function createSubagentRuntime(opts) {
             // longer be proved.
             const resumeHandler = opts.resolveResumeHandler?.(context.runId) ?? refuseUnownedChildReview;
             const configOverrides = {
+                tokenBudget: opts.tokenBudget ?? 0,
+                ...(selection ? { model: selection.model, effort: selection.effort } : {}),
                 ...(Object.keys(context.env ?? {}).length > 0 ? { env: context.env } : {}),
                 resumeHandler,
             };
@@ -418,15 +460,33 @@ export async function createSubagentRuntime(opts) {
             };
             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 outcome = await runBlockingAgentTask({
                     gateway: await gatewayForRun(context.runId),
                     signal: context.abortSignal,
                     waitForInbound: opts.resolveWaitForInbound?.(context.runId),
+                    background: run_in_background === true,
                     completionInbox,
-                    onCreated: () => {
+                    onCreated: (handle) => {
+                        save(handle, false);
                         taskOwnsCleanup = true;
                     },
-                    onSettled: (completed) => tracker.settle(completed),
+                    onSettled: (completed) => {
+                        save(completed, true);
+                        tracker.settle(completed);
+                    },
                     onFailed: (error) => tracker.fail(error),
                     onFinished: cleanupDefinition,
                     create: {
@@ -444,13 +504,14 @@ export async function createSubagentRuntime(opts) {
                     },
                 });
                 if (outcome.kind === 'yielded') {
+                    const progress = outcome.handle.state === 'pending' ? 'queued for an available slot' : 'still running';
                     return {
                         success: true,
-                        output: `Sub-agent ${agentId} is still running as task ${outcome.handle.taskId}; it has not completed. Waiting was released because the operator sent a message. Respond to that message while this task continues. Its actual result will arrive as a task notification; do not launch the same work again.`,
+                        output: `Sub-agent ${agentId} for task ${JSON.stringify(description)} is ${progress} as task ${outcome.handle.taskId}; it has not completed. ${run_in_background ? 'Continue independent work while this task runs in the background.' : 'Waiting was released because the operator sent a message. Answer their question or status request before making further tool calls; preserve existing work unless they ask to cancel or change it.'} Its actual result will arrive as a task notification; do not launch the same work again.`,
                         data: {
                             task_id: outcome.handle.taskId,
                             state: outcome.handle.state,
-                            wait_released: 'operator_input',
+                            wait_released: run_in_background ? 'background' : 'operator_input',
                         },
                     };
                 }
@@ -468,6 +529,57 @@ 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.',
+        inputSchema: mcpJsonSchemaToZod({
+            type: 'object',
+            properties: { history: { type: 'boolean' }, task_id: { type: 'string' } },
+            additionalProperties: false,
+        }),
+        category: 'custom',
+        permissions: [],
+        readOnly: true,
+        destructive: false,
+        concurrencySafe: true,
+        async execute(input, context) {
+            const request = input;
+            if (request.history || request.task_id) {
+                if (!opts.historyRoot)
+                    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);
+                return {
+                    success: true,
+                    output: JSON.stringify({ ...saved, tasks, guidance: HISTORY_GUIDANCE }),
+                };
+            }
+            const gateway = await gatewayForRun(context.runId);
+            const tasks = gateway.listTasks();
+            const labels = new Map(activity.getSnapshot().map((entry) => [entry.taskId, entry.description]));
+            const shown = tasks.slice(-40).map((task) => ({
+                description: labels.get(task.taskId) ?? task.agentId,
+                task_id: task.taskId,
+                agent: task.agentId,
+                state: task.state,
+                status: agentTaskOutcome(task),
+                ...(task.result?.stopReason ? { stop_reason: task.result.stopReason } : {}),
+            }));
+            return {
+                success: true,
+                output: JSON.stringify({
+                    tasks: shown,
+                    total: tasks.length,
+                    omitted: tasks.length - shown.length,
+                }),
+                data: { tasks: shown, total: tasks.length, omitted: tasks.length - shown.length },
+            };
+        },
+    });
     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.',
@@ -476,7 +588,7 @@ export async function createSubagentRuntime(opts) {
             properties: {
                 task_id: {
                     type: 'string',
-                    description: 'The task ID returned by Agent or a task notification.',
+                    description: 'The task_id from the Agent launch receipt or task notification metadata.',
                 },
             },
             required: ['task_id'],
@@ -520,13 +632,109 @@ export async function createSubagentRuntime(opts) {
             });
             if (outcome.kind === 'completed')
                 return completedAgentResult(outcome.handle);
+            const progress = outcome.handle.state === 'pending' ? 'queued for an available slot' : 'still running';
             return {
                 success: true,
-                output: `Task ${taskId} is still running; it has not completed. Waiting was released for an operator message. Its result will arrive as a task notification.`,
+                output: `Task ${taskId} is ${progress}; it has not completed. Waiting was released for an operator message. Its result will arrive as a task notification.`,
                 data: { task_id: taskId, state: outcome.handle.state, wait_released: 'operator_input' },
             };
         },
     });
+    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.',
+        inputSchema: mcpJsonSchemaToZod({
+            type: 'object',
+            properties: {
+                task_id: { type: 'string', description: 'Task UUID returned by Agent.' },
+                message: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: 16000,
+                    description: 'Correction or additional context for this task.',
+                },
+            },
+            required: ['task_id', 'message'],
+            additionalProperties: false,
+        }),
+        category: 'custom',
+        permissions: [],
+        readOnly: false,
+        destructive: false,
+        concurrencySafe: false,
+        async execute(input, context) {
+            context.abortSignal.throwIfAborted();
+            const { task_id, message } = input;
+            if (!message.trim())
+                return { success: false, output: '', error: 'Message must not be blank.' };
+            const taskId = asTaskId(task_id);
+            const gateway = await gatewayForRun(context.runId);
+            const task = gateway.getTask(taskId);
+            if (!task)
+                return {
+                    success: false,
+                    output: '',
+                    error: `Task ${taskId} does not belong to this parent run.`,
+                };
+            if (isTerminalAgentTaskState(task.state))
+                return {
+                    success: false,
+                    output: '',
+                    error: 'This task has finished; send_message cannot restart it.',
+                };
+            context.abortSignal.throwIfAborted();
+            await gateway.continueTask(taskId, message);
+            return {
+                success: true,
+                output: `Message queued for task ${taskId}; it will be available at the child's next request boundary.`,
+                data: { task_id: taskId, status: 'queued' },
+            };
+        },
+    });
+    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.',
+        inputSchema: mcpJsonSchemaToZod({
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'Exact task UUID returned by Agent or agent_task_list.',
+                },
+            },
+            required: ['task_id'],
+            additionalProperties: false,
+        }),
+        category: 'custom',
+        permissions: [],
+        readOnly: false,
+        destructive: false,
+        concurrencySafe: false,
+        async execute(input, context) {
+            context.abortSignal.throwIfAborted();
+            const taskId = asTaskId(input.task_id);
+            const gateway = await gatewayForRun(context.runId);
+            const task = gateway.getTask(taskId);
+            if (!task)
+                return {
+                    success: false,
+                    output: '',
+                    error: `Task ${taskId} does not belong to this parent run.`,
+                };
+            if (isTerminalAgentTaskState(task.state))
+                return {
+                    success: true,
+                    output: `Task ${taskId} already ended: ${agentTaskOutcome(task)}. No cancellation sent.`,
+                };
+            context.abortSignal.throwIfAborted();
+            gateway.cancelTask(taskId, 'user');
+            return {
+                success: true,
+                output: `Cancellation requested for task ${taskId}. Other tasks continue. Use agent_task_list or wait_for_task to confirm its terminal outcome.`,
+                data: { task_id: taskId, status: 'cancellation_requested' },
+            };
+        },
+    });
     let closePromise;
     const close = () => {
         if (closePromise)
@@ -535,12 +743,40 @@ export async function createSubagentRuntime(opts) {
         closePromise = Promise.all([...parents.keys()].map(releaseRun)).then(() => activity.close());
         return closePromise;
     };
+    const listModels = opts.listModels;
+    const modelCatalogueTool = listModels
+        ? defineTool({
+            name: 'agent_models',
+            description: 'Discover connected provider/model IDs and published capabilities for delegation. Search here before choosing a child model; capability metadata is not a quality ranking.',
+            inputSchema: mcpJsonSchemaToZod({
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Optional provider or model name filter.' },
+                },
+            }),
+            category: 'custom',
+            permissions: [],
+            readOnly: true,
+            destructive: false,
+            concurrencySafe: true,
+            async execute(input, context) {
+                return {
+                    success: true,
+                    output: await listModels(input.query ?? '', context.abortSignal),
+                };
+            },
+        })
+        : undefined;
     return {
+        cancelAgentTool,
+        modelCatalogueTool,
         gatewayForRun,
         completionInboxForRun,
         releaseRun,
         agentTool,
         waitForTaskTool,
+        agentTaskListTool,
+        sendMessageTool,
         allowedAgentIds: agentTypeIds,
         activity,
         close,
@@ -587,17 +823,32 @@ async function runBlockingAgentTask(input) {
             cancel(handle);
             signal.throwIfAborted();
         }
-        input.onCreated();
+        input.onCreated(handle);
         input.completionInbox.launched(handle.taskId);
         const completion = gateway.waitForTask(handle.taskId).then((completed) => {
-            input.onSettled(completed);
-            input.onFinished();
+            try {
+                input.onSettled(completed);
+            }
+            finally {
+                input.onFinished();
+            }
             return { kind: 'completed', handle: completed };
         }, (error) => {
-            input.onFailed(error);
-            input.onFinished();
+            try {
+                input.onFailed(error);
+            }
+            finally {
+                input.onFinished();
+            }
             throw error;
         });
+        if (input.background && !isTerminalAgentTaskState(handle.state)) {
+            // The observer retains activity/definition cleanup after this invocation
+            // returns. Parent release still owns cancellation and the tree budget.
+            completion.catch(() => { });
+            input.completionInbox.expect(handle.taskId);
+            return { kind: 'yielded', handle };
+        }
         const inbound = input
             .waitForInbound?.(wakeController.signal)
             .then(() => ({ kind: 'inbound' }));
@@ -610,7 +861,7 @@ async function runBlockingAgentTask(input) {
         // Only the wait has ended. Parent runtime ownership, token reservations and
         // the completion observer all outlive this tool invocation's local signal.
         input.completionInbox.expect(handle.taskId);
-        return { kind: 'yielded', handle };
+        return { kind: 'yielded', handle: current ?? handle };
     }
     catch (error) {
         if (handle)
@@ -625,10 +876,19 @@ async function runBlockingAgentTask(input) {
         wakeController.abort();
     }
 }
+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')
+        return 'incomplete';
+    return task.state;
+}
 /** Lifecycle completion is not proof the requested task finished successfully. */
 function completedAgentResult(completed) {
     const run = completed.result;
-    const succeeded = completed.state === 'completed' && (run?.status === undefined || run.status === 'completed');
+    const status = agentTaskOutcome(completed);
+    const succeeded = status === 'completed';
     const value = run?.structuredOutput ?? run?.result;
     let resultText = typeof value === 'string' ? value : value === undefined ? '' : JSON.stringify(value);
     if (!resultText && run?.stopReason && run.stopReason !== 'end_turn') {
@@ -645,19 +905,22 @@ function completedAgentResult(completed) {
     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 output = stopNote + (resultText || '(sub-agent returned no text)');
+    // ToolResult.data is host metadata, not necessarily model-visible content.
+    // Keep the handle and terminal status separate from arbitrary child output
+    // (which may itself contain UUIDs or text such as "Task 1").
+    const output = `task_id: ${completed.taskId}\nstatus: ${status}\n\nAgent result:\n${stopNote}${resultText || '(sub-agent returned no text)'}`;
     return {
         success: succeeded,
         output,
         ...(!succeeded
             ? {
-                error: `Sub-agent ${completed.agentId} ${completed.state}: ${run?.lastError ?? ''}\n${output}`,
+                error: `Sub-agent ${completed.agentId} ${status}: ${run?.lastError ?? ''}\n${output}`,
             }
             : {}),
         data: {
             task_id: completed.taskId,
             state: completed.state,
-            ...(run?.status ? { status: run.status } : {}),
+            status,
             ...(run?.stopReason ? { stop_reason: run.stopReason } : {}),
         },
     };
@@ -671,7 +934,7 @@ function buildDefinition(id, description, systemPrompt, opts,
 /** This definition's own roster; absent means the parent's working set. */
 tools = opts.buildTools, 
 /** This definition's model; absent means the session's. */
-model = opts.model) {
+model = opts.model, selection) {
     const agent = new ReactiveAgent({
         id,
         name: id,
@@ -691,7 +954,7 @@ model = opts.model) {
             category: 'general',
             description,
             tools: [],
-            defaults: { model, tokenBudget: 200_000 },
+            defaults: { model, tokenBudget: opts.tokenBudget ?? 0 },
         },
         // ReactiveAgent is Agent<ReactiveAgentConfig,…>; the registry stores the
         // erased Agent<BaseAgentConfig,…>. configBuilder supplies the richer config.
@@ -702,12 +965,19 @@ model = opts.model) {
             // 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
+            // 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))
+                : undefined;
             return {
                 model: options.model ?? model,
-                tokenBudget: options.tokenBudget ?? 200_000,
+                tokenBudget: options.tokenBudget ?? opts.tokenBudget ?? 0,
                 timeoutMs: options.timeoutMs ?? CLI_INTERACTIVE_RUN_TIMEOUT_MS,
                 maxIterations: 40,
-                provider: opts.buildProvider(),
+                provider: await opts.buildProvider(parent?.sessionId, selection),
+                ...(selection?.effort ? { effort: selection.effort } : {}),
                 tools: tools(),
                 systemPrompt: environment ? `${base}\n\n${environment}` : base,
                 ...(opts.projectInstructionContext