@namzu/cli 18.1.0 → 20.0.0

package/dist/integrations/subagents/runtime.js

@@ -3,56 +3,36 @@
  * 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 blocks until the child finishes and its final text returns as the
- * tool result, so a delegation surfaces in the transcript as a normal
- * `⏺ Agent(...)` call.
+ * The call waits for a final result unless 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.
  *
  * 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.
  */
-import { AgentManager, AgentRegistry, DefaultCapacityValidator, InMemorySessionStore, InMemoryTopicStore, LocalTaskScheduler, ReactiveAgent, RunCancelled, SessionSummaryMaterializer, ToolRegistry, TopicManager, WorkspaceBackendRegistry, asRunId, asSummaryId, asTenantId, asUserId, defineTool, mcpJsonSchemaToZod, } 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, 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 { CLI_INTERACTIVE_RUN_TIMEOUT_MS } from './policy.js';
 export const GENERAL_PURPOSE_SUBAGENT = 'general-purpose';
 /**
- * A sub-agent that can only look.
- *
- * "Find where X is defined", "which files reference Y", "how does Z work" are
- * the delegations a parent makes most, and every one of them ran with
- * `write`, `edit` and `bash` in the child's roster — so a lookup needed the
- * same approvals as a change, and an operator in `accept-edits` mode was
- * still asked about a child's shell command that only wanted to `cat`. This
- * definition's registry is the parent's working set filtered to tools that
- * declare themselves read-only, so a child that cannot change anything is
- * never asked whether it may.
+ * The kernel's read-only delegate, with this application's doctrine under
+ * its prompt. Roster and prompt come from `@namzu/sdk`; what is added here is
+ * the same working rules every namzu child gets.
  */
-export const EXPLORE_SUBAGENT = 'explore';
-const EXPLORE_PROMPT = [
-    'You are a read-only sub-agent dispatched by namzu to find things out: where something is defined, which files reference it, how a piece of code works, what a directory contains.',
-    'You cannot see the parent conversation — work only from the prompt you were given.',
-    'You have reading and searching tools only. You cannot edit, write or run commands, and you must not describe a change as made.',
-    'Search broadly first, then read what matters. Report file paths with line numbers, quote the relevant lines, and say plainly what you did not find.',
-    'End with a concise answer the parent can act on; do not ask the parent questions.',
-    '',
-    NAMZU_WORKING_DOCTRINE,
-].join('\n');
+export const EXPLORE_SUBAGENT = EXPLORE_AGENT_ID;
+const EXPLORE_PROMPT = [EXPLORE_AGENT_PROMPT, '', NAMZU_WORKING_DOCTRINE].join('\n');
 /**
- * The parent's roster, minus everything that can change state.
- *
- * Decided by each tool's own `isReadOnly` with no input — the declaration
- * `defineTool` records — rather than by a name list here, so a new read-only
- * builtin joins the explore roster without this file learning its name and
- * a tool that stops being read-only leaves it the same way.
+ * A file-defined agent's roster: the parent's working set, kept to the
+ * file's `tools` allowlist when there is one, and to read-only tools when
+ * the file says `readOnly: true`. Intersection, never union.
  */
-function readOnlyToolsFrom(source) {
-    const filtered = new ToolRegistry();
-    for (const tool of source.getAll()) {
-        if (tool.isReadOnly?.(undefined) === true)
-            filtered.register(tool);
-    }
-    return filtered;
+function fileAgentTools(definition, opts) {
+    return () => {
+        const source = definition.readOnly ? filterReadOnlyTools(opts.buildTools()) : opts.buildTools();
+        return definition.tools ? filterToolsNamed(source, definition.tools) : source;
+    };
 }
 const SUBAGENT_PROMPT = [
     'You are a focused sub-agent dispatched by namzu to complete one self-contained task and report back.',
@@ -70,6 +50,39 @@ const SUBAGENT_PROMPT = [
     // 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. */
+class ParentTaskScheduler extends LocalTaskScheduler {
+    validateParent;
+    constructor(manager, context, onEvent, validateParent) {
+        super(manager, context, onEvent);
+        this.validateParent = validateParent;
+    }
+    async createTask(options) {
+        await this.validateParent();
+        return super.createTask(options);
+    }
+    owns(taskId) {
+        return super.listTasks().some((task) => task.taskId === taskId);
+    }
+    getTask(taskId) {
+        return this.owns(taskId) ? super.getTask(taskId) : undefined;
+    }
+    cancelTask(taskId, cause) {
+        if (this.owns(taskId))
+            super.cancelTask(taskId, cause);
+    }
+    async waitForTask(taskId) {
+        if (!this.owns(taskId))
+            throw new Error(`Task ${taskId} does not belong to this parent run`);
+        return super.waitForTask(taskId);
+    }
+    async continueTask(taskId, message) {
+        if (!this.owns(taskId))
+            throw new Error(`Task ${taskId} does not belong to this parent run`);
+        await this.validateParent();
+        await super.continueTask(taskId, message);
+    }
+}
 /** A delegated run may never inherit the SDK's headless auto-approval fallback. */
 const refuseUnownedChildReview = async () => ({
     action: 'abort',
@@ -77,63 +90,216 @@ const refuseUnownedChildReview = async () => ({
 });
 /**
  * Stand up the AgentManager + gateway + `Agent` tool. Returns the tool to
- * register on the parent and the gateway to pass to `query({ taskGateway })`.
+ * register on the parent and the gateway to pass to `query({ taskScheduler })`.
  */
 export async function createSubagentRuntime(opts) {
-    const tenantId = asTenantId('tnt_namzu-cli');
-    const store = new InMemorySessionStore();
-    const topicStore = new InMemoryTopicStore();
-    const userActor = {
-        kind: 'user',
-        userId: asUserId('usr_namzu'),
-        tenantId,
-    };
-    const project = await store.createProject({ tenantId, name: 'namzu-cli' }, tenantId);
-    const thread = await topicStore.createTopic({ projectId: project.id, title: 'namzu-cli' }, tenantId);
-    // No workspace gate here, and that is a finding rather than an omission.
-    //
-    // A direct `createSession` bypasses `requireOpenProject`, which is why the
-    // CLI's persistent conversation store now calls it explicitly. This site is
-    // the other shape: the store is a fresh `InMemorySessionStore` built four
-    // lines up, the project was created two lines up, and neither outlives this
-    // runtime — so the id can never be one an owner has closed. A gate on a path
-    // that always creates its own project checks a condition that cannot be
-    // false, and a check that cannot fail teaches the next reader nothing except
-    // that gates here are decoration.
-    //
-    // The trigger to add one is the day this store is replaced by a persistent
-    // one, or the project id starts arriving from a caller.
-    const parentSession = await store.createSession({ topicId: thread.id, projectId: project.id, currentActor: userActor }, tenantId);
-    await store.updateSession({ ...parentSession, status: 'active' }, tenantId);
-    let summaryCounter = 0;
-    const materializer = new SessionSummaryMaterializer({
-        store,
-        generateSummaryId: () => asSummaryId(`sum_namzu_${++summaryCounter}`),
-    });
     const registry = new AgentRegistry();
     registry.register(buildDefinition(GENERAL_PURPOSE_SUBAGENT, 'A general-purpose sub-agent.', SUBAGENT_PROMPT, opts));
-    registry.register(buildDefinition(EXPLORE_SUBAGENT, 'A read-only sub-agent for finding files, symbols and answers.', EXPLORE_PROMPT, opts, () => readOnlyToolsFrom(opts.buildTools())));
-    const topicManager = new TopicManager({ topicStore, sessionStore: store });
-    const manager = new AgentManager(registry, { childTimeoutMs: CLI_INTERACTIVE_RUN_TIMEOUT_MS }, {
-        sessionStore: store,
-        summaryMaterializer: materializer,
-        workspaceRegistry: new WorkspaceBackendRegistry(),
-        capacity: new DefaultCapacityValidator(store),
-        topicManager,
-    });
-    const taskContext = {
-        parentRunId: asRunId('run_namzu-cli'),
-        parentAgentId: 'namzu',
-        parentAbortController: new AbortController(),
-        depth: 0,
-        budgetTracker: { total: 1_000_000, remaining: 1_000_000 },
-        tenantId,
-        topicId: thread.id,
-        sessionId: parentSession.id,
-        projectId: project.id,
-        parentActor: userActor,
+    registry.register(buildDefinition(EXPLORE_SUBAGENT, EXPLORE_AGENT_DESCRIPTION, EXPLORE_PROMPT, opts, () => filterReadOnlyTools(opts.buildTools())));
+    // Agents a project or user defined in a file, each a type of its own.
+    // The roster is the file's allowlist intersected with the parent's set —
+    // a file cannot grant a tool the parent does not have — narrowed further
+    // to read-only when the file says so. The prompt is the file's body over
+    // the same sub-agent base every child gets.
+    const fileAgents = new Map();
+    for (const definition of opts.definitions ?? []) {
+        fileAgents.set(definition.name, definition);
+        registry.register(buildDefinition(definition.name, definition.description, definition.prompt, opts, fileAgentTools(definition, opts), definition.model ?? opts.model));
+    }
+    const agentTypeIds = [GENERAL_PURPOSE_SUBAGENT, EXPLORE_SUBAGENT, ...fileAgents.keys()];
+    const fileAgentSummary = [...fileAgents.values()]
+        .map((definition) => `"${definition.name}" — ${definition.description}`)
+        .join('; ');
+    const parents = new Map();
+    const sessions = new Map();
+    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 { 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');
+        }
+        await requireOpenProject({ getProject: async () => project }, project.id, project.tenantId, 'spawn');
+        if (topic.status === 'archived')
+            throw new TopicArchivedError({ topicId: topic.id, op: 'spawn' });
+        return parent;
+    };
+    const createSessionRuntime = async (parent) => {
+        const { project, topic, sessionId } = parent;
+        const tenantId = project.tenantId;
+        const store = new InMemorySessionStore([project]);
+        const topicStore = new InMemoryTopicStore([topic]);
+        const parentActor = { kind: 'agent', agentId: 'namzu', tenantId };
+        const session = await store.createSession({
+            id: sessionId,
+            topicId: topic.id,
+            projectId: project.id,
+            currentActor: parentActor,
+        }, tenantId);
+        await store.updateSession({ ...session, status: 'active' }, tenantId);
+        const manager = new AgentManager(registry, { childTimeoutMs: CLI_INTERACTIVE_RUN_TIMEOUT_MS }, {
+            sessionStore: store,
+            summaryMaterializer: new SessionSummaryMaterializer({
+                store,
+                generateSummaryId,
+            }),
+            workspaceRegistry: new WorkspaceBackendRegistry(),
+            capacity: new DefaultCapacityValidator(store),
+            topicManager: new TopicManager({ topicStore, sessionStore: store }),
+        });
+        return {
+            manager,
+            store,
+            topicId: topic.id,
+            projectUpdatedAt: project.updatedAt.getTime(),
+        };
+    };
+    const refreshLimits = async (shared, parent) => {
+        if (shared.topicId !== parent.topic.id)
+            throw new Error('Delegation parent changed its topic while runs are active');
+        // A slow metadata read must not overwrite a newer project snapshot.
+        const updatedAt = parent.project.updatedAt.getTime();
+        if (updatedAt < shared.projectUpdatedAt)
+            return;
+        shared.projectUpdatedAt = updatedAt;
+        await shared.store.updateProject(parent.project.id, parent.project.config, parent.project.tenantId);
+    };
+    const acquireSession = async (parent) => {
+        const key = sessionKey(parent);
+        let entry = sessions.get(key);
+        if (!entry) {
+            entry = { ready: createSessionRuntime(parent), owners: 0 };
+            sessions.set(key, entry);
+        }
+        entry.owners++;
+        const ownedEntry = entry;
+        let released = false;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            ownedEntry.owners--;
+            if (ownedEntry.owners !== 0)
+                return;
+            if (sessions.get(key) === ownedEntry)
+                sessions.delete(key);
+            void ownedEntry.ready.then((shared) => shared.manager.dispose(), () => undefined);
+        };
+        try {
+            const shared = await entry.ready;
+            await refreshLimits(shared, parent);
+            return { shared, release };
+        }
+        catch (error) {
+            release();
+            throw error;
+        }
+    };
+    const gatewayForRun = async (runId) => {
+        if (closed)
+            throw new Error('Sub-agent runtime is closed');
+        let pending = parents.get(runId);
+        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: opts.tokenBudget ?? 1_000_000,
+                    pathBuilder: opts.pathBuilder,
+                    workingDirectory: opts.cwd,
+                });
+                const lease = await acquireSession(parent);
+                const { manager } = lease.shared;
+                const parentAbortController = new AbortController();
+                let released = false;
+                const assertOwned = () => {
+                    if (closed ||
+                        released ||
+                        parentAbortController.signal.aborted ||
+                        parents.get(runId) !== pending) {
+                        throw new Error(`Parent run ${runId} was released`);
+                    }
+                };
+                const taskContext = {
+                    parentRunId: runId,
+                    parentAgentId: 'namzu',
+                    parentAbortController,
+                    depth: 0,
+                    budget,
+                    tenantId: parent.project.tenantId,
+                    topicId: parent.topic.id,
+                    sessionId: parent.sessionId,
+                    projectId: parent.project.id,
+                    parentActor: {
+                        kind: 'agent',
+                        agentId: 'namzu',
+                        tenantId: parent.project.tenantId,
+                    },
+                };
+                const gateway = new ParentTaskScheduler(manager, taskContext, opts.onEvent, async () => {
+                    assertOwned();
+                    const current = await resolveParent(runId);
+                    assertOwned();
+                    if (sessionKey(current) !== sessionKey(parent))
+                        throw new Error('Delegation run changed its parent scope');
+                    await refreshLimits(lease.shared, current);
+                    assertOwned();
+                });
+                const completionInbox = new CompletionInbox();
+                completionInbox.attach(gateway);
+                const runtime = {
+                    gateway,
+                    completionInbox,
+                    close() {
+                        if (released)
+                            return;
+                        released = true;
+                        parentAbortController.abort(new RunCancelled('parent'));
+                        manager.cancelAll(runId, 'parent');
+                        completionInbox.close();
+                        lease.release();
+                    },
+                };
+                if (closed) {
+                    runtime.close();
+                    throw new Error('Sub-agent runtime is closed');
+                }
+                return runtime;
+            })();
+            parents.set(runId, pending);
+        }
+        try {
+            const runtime = await pending;
+            if (closed || parents.get(runId) !== pending)
+                throw new Error(`Parent run ${runId} was released`);
+            return runtime.gateway;
+        }
+        catch (error) {
+            if (parents.get(runId) === pending)
+                parents.delete(runId);
+            throw error;
+        }
+    };
+    const releaseRun = async (runId) => {
+        const pending = parents.get(runId);
+        if (!pending)
+            return;
+        parents.delete(runId);
+        await pending.then((runtime) => runtime.close(), () => undefined);
+    };
+    const completionInboxForRun = async (runId) => {
+        await gatewayForRun(runId);
+        const pending = parents.get(runId);
+        if (!pending)
+            throw new Error(`Parent run ${runId} was released`);
+        return (await pending).completionInbox;
     };
-    const gateway = new LocalTaskScheduler(manager, taskContext, opts.onEvent);
     const activity = new SubagentActivityMonitor();
     // Dynamic `Agent` tool: the model passes an optional `role` (the persona /
     // system prompt) and we register + spawn a fresh specialist for it at call
@@ -141,19 +307,21 @@ export async function createSubagentRuntime(opts) {
     let dynCounter = 0;
     const agentTool = defineTool({
         name: 'Agent',
-        description: 'Delegate a self-contained task to a sub-agent and get its result back (BLOCKING). ' +
-            '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. 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.',
+        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.',
+            '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.',
+            '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}.` : '',
+        ]
+            .filter((part) => part.length > 0)
+            .join(' '),
         inputSchema: mcpJsonSchemaToZod({
             type: 'object',
             properties: {
@@ -167,8 +335,10 @@ export async function createSubagentRuntime(opts) {
                 },
                 subagent_type: {
                     type: 'string',
-                    enum: [GENERAL_PURPOSE_SUBAGENT, EXPLORE_SUBAGENT],
-                    description: '"explore" for read-only lookups (find, search, explain); "general-purpose" (default) when the task changes files or runs commands.',
+                    enum: agentTypeIds,
+                    description: `"explore" for read-only lookups (find, search, explain); "general-purpose" (default) when the task changes files or runs commands.${fileAgentSummary.length > 0
+                        ? ` This project also defines: ${fileAgentSummary}. Prefer a project-defined type when its description fits the task.`
+                        : ''}`,
                 },
                 role: {
                     type: 'string',
@@ -202,15 +372,22 @@ export async function createSubagentRuntime(opts) {
         async execute(input, context) {
             const { description, prompt, subagent_type, role, workflow, phase, phase_order } = input;
             const explore = subagent_type === EXPLORE_SUBAGENT;
-            let agentId = explore ? EXPLORE_SUBAGENT : GENERAL_PURPOSE_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;
             if (dynamic) {
-                // A role on top of explore keeps explore's roster: the persona says
-                // who the child is, the type says what it may touch, and a role
-                // must not be a way to hand a read-only child a `write` tool.
+                // 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,
+                // and a role must not be a way to hand a read-only child a `write`
+                // 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}`, persona, opts, explore ? () => readOnlyToolsFrom(opts.buildTools()) : opts.buildTools));
+                registry.register(buildDefinition(agentId, `Dynamic specialist: ${agentId}`, fileAgent ? `${fileAgent.prompt}\n\n${persona}` : persona, opts, fileAgent
+                    ? fileAgentTools(fileAgent, opts)
+                    : explore
+                        ? () => filterReadOnlyTools(opts.buildTools())
+                        : opts.buildTools, fileAgent?.model ?? opts.model));
             }
             const tracker = activity.begin({
                 agentId,
@@ -234,10 +411,24 @@ export async function createSubagentRuntime(opts) {
                 ...(Object.keys(context.env ?? {}).length > 0 ? { env: context.env } : {}),
                 resumeHandler,
             };
+            let taskOwnsCleanup = false;
+            const cleanupDefinition = () => {
+                if (dynamic)
+                    registry.unregister(agentId);
+            };
             try {
-                const completed = await runBlockingAgentTask({
-                    gateway,
+                const completionInbox = await completionInboxForRun(context.runId);
+                const outcome = await runBlockingAgentTask({
+                    gateway: await gatewayForRun(context.runId),
                     signal: context.abortSignal,
+                    waitForInbound: opts.resolveWaitForInbound?.(context.runId),
+                    completionInbox,
+                    onCreated: () => {
+                        taskOwnsCleanup = true;
+                    },
+                    onSettled: (completed) => tracker.settle(completed),
+                    onFailed: (error) => tracker.fail(error),
+                    onFinished: cleanupDefinition,
                     create: {
                         agentId,
                         prompt,
@@ -252,59 +443,105 @@ export async function createSubagentRuntime(opts) {
                         onEvent: tracker.onEvent,
                     },
                 });
-                tracker.settle(completed);
-                const runStatus = completed.result?.status;
-                const succeeded = completed.state === 'completed' && (runStatus === undefined || runStatus === 'completed');
-                const resultText = typeof completed.result?.result === 'string'
-                    ? completed.result.result
-                    : completed.result?.result !== undefined
-                        ? JSON.stringify(completed.result.result)
-                        : '';
-                if (!succeeded) {
+                if (outcome.kind === 'yielded') {
                     return {
-                        success: false,
-                        output: '',
-                        error: `Sub-agent ${agentId} ${completed.state}: ${completed.result?.lastError ?? resultText ?? '(no detail)'}`,
+                        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.`,
+                        data: {
+                            task_id: outcome.handle.taskId,
+                            state: outcome.handle.state,
+                            wait_released: 'operator_input',
+                        },
                     };
                 }
-                return {
-                    success: true,
-                    output: resultText || '(sub-agent returned no text)',
-                };
+                return completedAgentResult(outcome.handle);
             }
             catch (error) {
                 tracker.fail(error);
                 throw error;
             }
             finally {
-                // A per-call dynamic specialist is single-use — drop its definition
-                // (and retained persona string) so long sessions don't leak `dyn-N`
-                // registrations whether the task succeeded, failed, or threw.
-                if (dynamic)
-                    registry.unregister(agentId);
+                // A yielded task retains its definition until its actual completion.
+                // Before creation succeeds, this invocation owns that cleanup.
+                if (!taskOwnsCleanup)
+                    cleanupDefinition();
             }
         },
     });
+    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.',
+        inputSchema: mcpJsonSchemaToZod({
+            type: 'object',
+            properties: {
+                task_id: {
+                    type: 'string',
+                    description: 'The task ID returned by Agent or a task notification.',
+                },
+            },
+            required: ['task_id'],
+        }),
+        category: 'custom',
+        permissions: [],
+        readOnly: true,
+        destructive: false,
+        concurrencySafe: true,
+        timeoutMs: CLI_INTERACTIVE_RUN_TIMEOUT_MS,
+        async execute(input, context) {
+            const gateway = await gatewayForRun(context.runId);
+            let taskId;
+            try {
+                taskId = asTaskId(input.task_id);
+            }
+            catch {
+                return {
+                    success: false,
+                    output: '',
+                    error: 'task_id must be a task UUID returned by Agent or a task notification.',
+                };
+            }
+            const task = gateway.getTask(taskId);
+            if (!task)
+                return {
+                    success: false,
+                    output: '',
+                    error: `Task ${taskId} does not belong to this parent run.`,
+                };
+            const outcome = await runBlockingAgentTask({
+                gateway,
+                task,
+                signal: context.abortSignal,
+                completionInbox: await completionInboxForRun(context.runId),
+                waitForInbound: opts.resolveWaitForInbound?.(context.runId),
+                onCreated: () => { },
+                onSettled: () => { },
+                onFailed: () => { },
+                onFinished: () => { },
+            });
+            if (outcome.kind === 'completed')
+                return completedAgentResult(outcome.handle);
+            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.`,
+                data: { task_id: taskId, state: outcome.handle.state, wait_released: 'operator_input' },
+            };
+        },
+    });
     let closePromise;
     const close = () => {
         if (closePromise)
             return closePromise;
-        closePromise = Promise.resolve().then(() => {
-            // This controller is the parent of every child the manager creates.
-            // Abort it before disposing bookkeeping so a live child keeps the
-            // structured reason even if its blocking tool wait already detached.
-            if (!taskContext.parentAbortController.signal.aborted) {
-                taskContext.parentAbortController.abort(new RunCancelled('parent'));
-            }
-            manager.dispose();
-            activity.close();
-        });
+        closed = true;
+        closePromise = Promise.all([...parents.keys()].map(releaseRun)).then(() => activity.close());
         return closePromise;
     };
     return {
-        gateway,
+        gatewayForRun,
+        completionInboxForRun,
+        releaseRun,
         agentTool,
-        allowedAgentIds: [GENERAL_PURPOSE_SUBAGENT, EXPLORE_SUBAGENT],
+        waitForTaskTool,
+        allowedAgentIds: agentTypeIds,
         activity,
         close,
     };
@@ -316,6 +553,7 @@ async function runBlockingAgentTask(input) {
     let handle;
     let cancellationRequested = false;
     let taskCancellationAttempted = false;
+    const wakeController = new AbortController();
     let rejectAbort = () => { };
     const aborted = new Promise((_resolve, reject) => {
         rejectAbort = reject;
@@ -341,7 +579,7 @@ async function runBlockingAgentTask(input) {
     signal.addEventListener('abort', onAbort, { once: true });
     if (signal.aborted)
         onAbort();
-    const creation = gateway.createTask(input.create);
+    const creation = input.create === undefined ? Promise.resolve(input.task) : gateway.createTask(input.create);
     creation.catch(() => { });
     try {
         handle = await Promise.race([creation, aborted]);
@@ -349,8 +587,30 @@ async function runBlockingAgentTask(input) {
             cancel(handle);
             signal.throwIfAborted();
         }
-        const completed = await Promise.race([gateway.waitForTask(handle.taskId), aborted]);
-        return completed;
+        input.onCreated();
+        input.completionInbox.launched(handle.taskId);
+        const completion = gateway.waitForTask(handle.taskId).then((completed) => {
+            input.onSettled(completed);
+            input.onFinished();
+            return { kind: 'completed', handle: completed };
+        }, (error) => {
+            input.onFailed(error);
+            input.onFinished();
+            throw error;
+        });
+        const inbound = input
+            .waitForInbound?.(wakeController.signal)
+            .then(() => ({ kind: 'inbound' }));
+        const outcome = await Promise.race(inbound ? [completion, aborted, inbound] : [completion, aborted]);
+        const current = gateway.getTask(handle.taskId);
+        if (outcome.kind === 'completed' || (current && isTerminalAgentTaskState(current.state))) {
+            input.completionInbox.claim(handle.taskId);
+            return outcome.kind === 'completed' ? outcome : await completion;
+        }
+        // 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 };
     }
     catch (error) {
         if (handle)
@@ -362,8 +622,46 @@ async function runBlockingAgentTask(input) {
             void creation.then(cancel, () => { });
         }
         signal.removeEventListener('abort', onAbort);
+        wakeController.abort();
     }
 }
+/** 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 value = run?.structuredOutput ?? run?.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.
+        // Keep the child's last visible statement, never its reasoning or tool data.
+        const partial = [...run.messages]
+            .reverse()
+            .find((message) => message.role === 'assistant' &&
+            typeof message.content === 'string' &&
+            message.content.trim().length > 0)?.content;
+        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 output = stopNote + (resultText || '(sub-agent returned no text)');
+    return {
+        success: succeeded,
+        output,
+        ...(!succeeded
+            ? {
+                error: `Sub-agent ${completed.agentId} ${completed.state}: ${run?.lastError ?? ''}\n${output}`,
+            }
+            : {}),
+        data: {
+            task_id: completed.taskId,
+            state: completed.state,
+            ...(run?.status ? { status: run.status } : {}),
+            ...(run?.stopReason ? { stop_reason: run.stopReason } : {}),
+        },
+    };
+}
 /**
  * Build an agent definition with the given id + persona (system prompt). Used
  * for the static `general-purpose` agent and for each dynamically-defined
@@ -371,7 +669,9 @@ async function runBlockingAgentTask(input) {
  */
 function buildDefinition(id, description, systemPrompt, opts, 
 /** This definition's own roster; absent means the parent's working set. */
-tools = opts.buildTools) {
+tools = opts.buildTools, 
+/** This definition's model; absent means the session's. */
+model = opts.model) {
     const agent = new ReactiveAgent({
         id,
         name: id,
@@ -391,7 +691,7 @@ tools = opts.buildTools) {
             category: 'general',
             description,
             tools: [],
-            defaults: { model: opts.model, tokenBudget: 200_000 },
+            defaults: { model, tokenBudget: 200_000 },
         },
         // ReactiveAgent is Agent<ReactiveAgentConfig,…>; the registry stores the
         // erased Agent<BaseAgentConfig,…>. configBuilder supplies the richer config.
@@ -403,7 +703,7 @@ tools = opts.buildTools) {
             // is worse than one that was never told.
             const environment = opts.readEnvironment ? await opts.readEnvironment() : null;
             return {
-                model: options.model ?? opts.model,
+                model: options.model ?? model,
                 tokenBudget: options.tokenBudget ?? 200_000,
                 timeoutMs: options.timeoutMs ?? CLI_INTERACTIVE_RUN_TIMEOUT_MS,
                 maxIterations: 40,