@namzu/cli 18.1.0 → 19.0.0

package/dist/integrations/subagents/runtime.d.ts

@@ -11,25 +11,27 @@
  * store backs the AgentManager, so sub-agent bookkeeping never touches the
  * CLI's on-disk `/resume` conversation store.
  */
-import { type AuthorizationGateConfig, type LLMProvider, type PathBuilder, type ProjectInstructionContext, type ResumeHandler, type RunEvent, type SandboxProvider, type TaskScheduler, type ToolContext, type ToolDefinition, type ToolRegistryContract } from '@namzu/sdk';
+import { type AgentFileDefinition, type AuthorizationGateConfig, type LLMProvider, type PathBuilder, type Project, type ProjectInstructionContext, type ResumeHandler, type RunEvent, type RunId, type SandboxProvider, type SessionId, type TaskScheduler, type ToolContext, type ToolDefinition, type ToolRegistryContract, type Topic } from '@namzu/sdk';
 import { type SubagentActivitySource } from './activity.js';
 export declare 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 declare const EXPLORE_SUBAGENT = "explore";
+export interface SubagentParent {
+    readonly project: Project;
+    readonly topic: Topic;
+    readonly sessionId: SessionId;
+}
 export interface SubagentRuntimeOptions {
+    /** Resolve the actual invoking run; reject calls whose parent no longer exists. */
+    readonly resolveParent: (runId: RunId) => Promise<SubagentParent>;
     readonly cwd: string;
     readonly model: string;
+    /** Aggregate parent-and-descendant limit; defaults to the CLI's one million tokens. */
+    readonly tokenBudget?: number;
     /** Durable layout for child runs; omitted preserves the SDK default. */
     readonly pathBuilder?: PathBuilder;
     /** Root every child allocation at the session workspace or a fresh temp tree. */
@@ -62,9 +64,18 @@ export interface SubagentRuntimeOptions {
     readonly readEnvironment?: () => Promise<string>;
     /** Receives the child's RunEvents (lineage-stamped) — for the tree view. */
     readonly onEvent?: (event: RunEvent) => void;
+    /**
+     * Agents a project or user defined in `.namzu/agents/<name>.md`. Each
+     * becomes a type the `Agent` tool offers beside the built-in two, with
+     * its own prompt, roster and model. See `definitions.ts`.
+     */
+    readonly definitions?: readonly AgentFileDefinition[];
 }
 export interface SubagentRuntime {
-    readonly gateway: TaskScheduler;
+    /** One immutable scheduler context per actual parent run. */
+    gatewayForRun(runId: RunId): Promise<TaskScheduler>;
+    /** Release a settled parent's bookkeeping and cancel children it still owns. */
+    releaseRun(runId: RunId): Promise<void>;
     readonly agentTool: ToolDefinition;
     readonly allowedAgentIds: readonly string[];
     /** Live, bounded observation of children created by this CLI session. */
@@ -74,7 +85,7 @@ export interface SubagentRuntime {
 }
 /**
  * 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 declare function createSubagentRuntime(opts: SubagentRuntimeOptions): Promise<SubagentRuntime>;
 //# sourceMappingURL=runtime.d.ts.map

package/dist/integrations/subagents/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/integrations/subagents/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAMN,KAAK,uBAAuB,EAQ5B,KAAK,WAAW,EAEhB,KAAK,WAAW,EAChB,KAAK,yBAAyB,EAG9B,KAAK,aAAa,EAElB,KAAK,QAAQ,EACb,KAAK,eAAe,EAGpB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,cAAc,EAEnB,KAAK,oBAAoB,EASzB,MAAM,YAAY,CAAA;AAGnB,OAAO,EAIN,KAAK,sBAAsB,EAC3B,MAAM,eAAe,CAAA;AAGtB,eAAO,MAAM,wBAAwB,oBAAoB,CAAA;AACzD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,YAAY,CAAA;AA6CzC,MAAM,WAAW,sBAAsB;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,wEAAwE;IACxE,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAA;IAClC,iFAAiF;IACjF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,mBAAmB,GAAG,WAAW,CAAA;IAC7D,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,MAAM,WAAW,CAAA;IACzC,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,oBAAoB,CAAA;IAC/C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,uBAAuB,CAAA;IACpD;;;OAGG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,aAAa,GAAG,SAAS,CAAA;IAC1F,kEAAkE;IAClE,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAA;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,wBAAwB,CAAC,EAAE,MAAM,CAAA;IAC1C,2EAA2E;IAC3E,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,yBAAyB,CAAA;IACpE;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;IAChD,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAA;CAC5C;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAA;IACzC,uEAAuE;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACtB;AAQD;;;GAGG;AACH,wBAAsB,qBAAqB,CAC1C,IAAI,EAAE,sBAAsB,GAC1B,OAAO,CAAC,eAAe,CAAC,CA2R1B"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/integrations/subagents/runtime.ts"],"names":[],"mappings":"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"}

package/dist/integrations/subagents/runtime.js

@@ -11,48 +11,28 @@
  * 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, DefaultCapacityValidator, EXPLORE_AGENT_DESCRIPTION, EXPLORE_AGENT_ID, EXPLORE_AGENT_PROMPT, InMemorySessionStore, InMemoryTopicStore, LocalTaskScheduler, ReactiveAgent, RunCancelled, SessionSummaryMaterializer, TopicArchivedError, TopicManager, WorkspaceBackendRegistry, defineTool, filterReadOnlyTools, filterToolsNamed, generateSummaryId, 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,204 @@ 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 runtime = {
+                    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();
+                    }),
+                    close() {
+                        if (released)
+                            return;
+                        released = true;
+                        parentAbortController.abort(new RunCancelled('parent'));
+                        manager.cancelAll(runId, 'parent');
+                        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 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 +295,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 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.',
+            fileAgentSummary.length > 0 ? `Project-defined types: ${fileAgentSummary}.` : '',
+        ]
+            .filter((part) => part.length > 0)
+            .join(' '),
         inputSchema: mcpJsonSchemaToZod({
             type: 'object',
             properties: {
@@ -167,8 +323,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 +360,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,
@@ -236,7 +401,7 @@ export async function createSubagentRuntime(opts) {
             };
             try {
                 const completed = await runBlockingAgentTask({
-                    gateway,
+                    gateway: await gatewayForRun(context.runId),
                     signal: context.abortSignal,
                     create: {
                         agentId,
@@ -289,22 +454,15 @@ export async function createSubagentRuntime(opts) {
     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,
+        releaseRun,
         agentTool,
-        allowedAgentIds: [GENERAL_PURPOSE_SUBAGENT, EXPLORE_SUBAGENT],
+        allowedAgentIds: agentTypeIds,
         activity,
         close,
     };
@@ -371,7 +529,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 +551,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 +563,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,