@namzu/sdk 12.0.1 → 12.2.0

package/dist/types/hitl/index.d.ts

@@ -122,6 +122,22 @@ export interface PlanApprovalData {
         id: string;
         description: string;
         toolName?: string;
+        /**
+         * Which agent the step is to be delegated to, when it is delegated.
+         *
+         * `PlanStep` gained this so an approver could see WHICH agent a step
+         * goes to rather than only THAT it delegates — approving "delegate
+         * this" is not approving "delegate this to the agent with shell
+         * access". It reached `PlanApprovalRequest`, which is the shape a host
+         * sees when it installs its own handler on `PlanManager`.
+         *
+         * It did not reach here, and this is the ordinary path: every host
+         * using `resumeHandler` is served by this type, and both mappers that
+         * build it copy field by field. So the fix landed on one of the two
+         * approval surfaces and the busier one kept showing
+         * `toolName: 'create_task'` and nothing else.
+         */
+        agentId?: string;
         dependsOn: string[];
         order: number;
     }>;

package/dist/types/hitl/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AACpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AAC1E,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAClE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,YAAY,EAAE,YAAY,EAAE,CAAA;AAE5B,MAAM,MAAM,kBAAkB,GAC3B;IAAE,MAAM,EAAE,UAAU,CAAA;CAAE,GACtB;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC3C;IACA,MAAM,EAAE,eAAe,CAAA;IACvB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAC3B,GACD;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,aAAa,EAAE,gBAAgB,EAAE,CAAA;CAAE,GAC7D;IAAE,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC5C;IACA,MAAM,EAAE,iBAAiB,CAAA;IACzB,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CAClB,GACD;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEtC,MAAM,MAAM,mBAAmB,GAC5B;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,YAAY,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC3F;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,YAAY,EAAE,YAAY,CAAC;IAAC,SAAS,EAAE,eAAe,EAAE,CAAA;CAAE,GAC/F;IACA,IAAI,EAAE,sBAAsB,CAAA;IAC5B,KAAK,EAAE,KAAK,CAAA;IACZ,YAAY,EAAE,YAAY,CAAA;IAC1B,OAAO,EAAE,iBAAiB,CAAA;CACzB,GACD;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;IAAC,YAAY,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,gBAAgB,CAAA;CAAE,CAAA;AAElG,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;AAEzF,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,OAAO,CAAA;IACd,aAAa,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAA;IACrC,aAAa,CAAC,EAAE,OAAO,CAAA;CACvB;AAED,MAAM,WAAW,kBAAkB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,kBAAkB,EAAE,CAAA;IAC7B,WAAW,EAAE,OAAO,CAAA;IACpB,aAAa,EAAE,OAAO,CAAA;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAA;QACV,WAAW,EAAE,MAAM,CAAA;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;QACjB,SAAS,EAAE,MAAM,EAAE,CAAA;QACnB,KAAK,EAAE,MAAM,CAAA;KACb,CAAC,CAAA;IACF,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,iBAAiB;IACjC,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,QAAQ,CAAA;IAClB,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAA;IACrC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;CACtC;AAED,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,YAAY,CAAA;IAChB,KAAK,EAAE,KAAK,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,OAAO,EAAE,CAAA;IACnB,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,QAAQ,CAAA;IAClB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,UAAU,CAAA;IAEvB;;;OAGG;IACH,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB,UAAU,EAAE;QACX,cAAc,EAAE,MAAM,CAAA;QACtB,SAAS,EAAE,MAAM,CAAA;KACjB,CAAA;IACD,SAAS,EAAE,MAAM,CAAA;IAEjB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAEzC;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAA;IAEnC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAA;CACpC;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAwB5F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"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"}

package/dist/types/hitl/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"AA0OA,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC9D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,eAAe;YACnB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;QACnD,KAAK,aAAa;YACjB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;QACpD,KAAK,sBAAsB;YAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAA;QAC/C,KAAK,eAAe;YACnB,2DAA2D;YAC3D,yDAAyD;YACzD,6DAA6D;YAC7D,uCAAuC;YACvC,OAAO,OAAO,CAAC,OAAO,CAAC;gBACtB,MAAM,EAAE,iBAAiB;gBACzB,iBAAiB,EAAE,EAAE;gBACrB,QAAQ,EAAE,mEAAmE;gBAC7E,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,UAAU;aACvC,CAAC,CAAA;QACH,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,OAAO,CAAA;YAClC,MAAM,IAAI,KAAK,CAAC,gCAAiC,WAAmC,CAAC,IAAI,EAAE,CAAC,CAAA;QAC7F,CAAC;IACF,CAAC;AACF,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/hitl/index.ts"],"names":[],"mappings":"AA4PA,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC9D,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,eAAe;YACnB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAA;QACnD,KAAK,aAAa;YACjB,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAA;QACpD,KAAK,sBAAsB;YAC1B,OAAO,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAA;QAC/C,KAAK,eAAe;YACnB,2DAA2D;YAC3D,yDAAyD;YACzD,6DAA6D;YAC7D,uCAAuC;YACvC,OAAO,OAAO,CAAC,OAAO,CAAC;gBACtB,MAAM,EAAE,iBAAiB;gBACzB,iBAAiB,EAAE,EAAE;gBACrB,QAAQ,EAAE,mEAAmE;gBAC7E,UAAU,EAAE,OAAO,CAAC,QAAQ,CAAC,UAAU;aACvC,CAAC,CAAA;QACH,OAAO,CAAC,CAAC,CAAC;YACT,MAAM,WAAW,GAAU,OAAO,CAAA;YAClC,MAAM,IAAI,KAAK,CAAC,gCAAiC,WAAmC,CAAC,IAAI,EAAE,CAAC,CAAA;QAC7F,CAAC;IACF,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "12.0.1",
+  "version": "12.2.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/agents/AbstractAgent.ts

@@ -55,6 +55,41 @@ export abstract class AbstractAgent<
 
 	abstract run(input: AgentInput, config: TConfig, listener?: RunEventListener): Promise<TResult>
 
+	/**
+	 * A fresh shell of this agent, for a run that must not share one.
+	 *
+	 * See {@link Agent.forRun}. An agent is a shell around metadata — every
+	 * per-run decision arrives in `config` and `input` — so a second instance
+	 * costs one object and gives the run its own abort controller and run id,
+	 * which is precisely what the invocation lock is protecting.
+	 *
+	 * Rebuilt from `this.constructor` and `this.metadata`, which covers every
+	 * agent in this package: they all take metadata and nothing else. A
+	 * subclass with a different constructor signature will throw here, and the
+	 * answer to that is `this` — the caller then shares the shell and gets the
+	 * existing refusal on a concurrent run, which is the behaviour before this
+	 * existed. Losing parallelism is a worse outcome than not having it; losing
+	 * the run is not on the table.
+	 *
+	 * A host whose agent needs real construction arguments supplies
+	 * `AgentDefinition.createAgent` instead, which wins over this.
+	 */
+	forRun(): this {
+		try {
+			const Ctor = this.constructor as unknown as new (metadata: AgentMetadata) => this
+			return new Ctor(this.metadata)
+		} catch (err) {
+			this.log.warn(
+				'Could not build a per-run shell; concurrent runs of this agent will still be refused',
+				{
+					agentId: this.metadata.id,
+					error: err instanceof Error ? err.message : String(err),
+				},
+			)
+			return this
+		}
+	}
+
 	/**
 	 * Acquire the invocation lock to prevent concurrent execution.
 	 * Returns a Disposable that must be disposed to release the lock.

package/src/agents/lock.ts

@@ -11,7 +11,16 @@ export class ConcurrentInvocationError extends Error {
 	readonly agentId: string
 
 	constructor(agentId: string) {
-		super(`Agent ${agentId} is already processing. Concurrent invocations are not allowed.`)
+		// Names the remedy, because the refusal alone sent readers looking for a
+		// concurrency bug in their own code. An agent instance holds per-run
+		// state — an abort controller and the run id — so two overlapping runs
+		// on one shell would cancel each other; the answer is a second shell,
+		// not a second attempt. Delegated spawns get one automatically via
+		// `Agent.forRun`, so reaching this from a fan-out means the agent
+		// could not be rebuilt and wants `AgentDefinition.createAgent`.
+		super(
+			`Agent ${agentId} is already processing. Concurrent invocations of one instance are not allowed, because its abort controller and run id are instance state and two runs would cancel each other. Run a second instance instead — or, for a delegated spawn, give its AgentDefinition a \`createAgent\` factory so each child gets its own.`,
+		)
 		this.name = 'ConcurrentInvocationError'
 		this.agentId = agentId
 	}

package/src/manager/agent/__tests__/a-fan-out-to-one-agent-id.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from 'vitest'
+
+import { ReactiveAgent } from '../../../agents/ReactiveAgent.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import type { AgentDefinition } from '../../../types/agent/factory.js'
+
+/**
+ * A fan-out naming the same agent four times ran one child and lost three.
+ *
+ * `AgentRegistry` hands out ONE `typedAgent` per registered id, and an instance
+ * refuses a second concurrent `run` — correctly, because its abort controller
+ * and run id are instance state and two overlapping runs would cancel each
+ * other. So four `create_task` calls at one specialist produced one result and
+ * three `ConcurrentInvocationError`s.
+ *
+ * The prescribed remedy already existed in the docs — "a host that wants
+ * parallelism constructs a second instance" — and was unreachable from
+ * delegation, where the definition owns the instance and the caller has only an
+ * id. Observed live on published 12.0.1: four launches, three lost.
+ *
+ * These cover the shell itself. That the manager USES it per spawn is covered
+ * where the manager is driven; what has to hold here is that asking for a
+ * per-run shell gives you a genuinely separate one.
+ */
+
+const metadata = {
+	id: 'worker',
+	name: 'worker',
+	version: '1.0.0',
+	category: 'general',
+	description: 'a worker',
+}
+
+describe('an agent can hand out a shell a single run has to itself', () => {
+	it('returns a different instance', () => {
+		const agent = new ReactiveAgent(metadata)
+
+		expect(agent.forRun()).not.toBe(agent)
+	})
+
+	it('keeps the identity, because it is the same agent', () => {
+		const agent = new ReactiveAgent(metadata)
+		const shell = agent.forRun()
+
+		expect(shell.metadata.id).toBe('worker')
+		expect(shell.type).toBe(agent.type)
+		expect(shell.getCapabilities()).toEqual(agent.getCapabilities())
+	})
+
+	it('gives each shell its own invocation lock, which is the whole point', async () => {
+		// Locking one must not lock the other. Asserted through the public
+		// surface: a run that never settles holds the lock, and a second run on
+		// a SEPARATE shell must still be admitted.
+		// ONE registered agent, two shells — the registry's shape, and the
+		// shape the fan-out actually hits.
+		const registered = new ReactiveAgent(metadata)
+		const first = registered.forRun()
+		const second = registered.forRun()
+
+		// A provider that starts and never finishes, so each run holds its
+		// shell's lock for the duration of the assertion.
+		const provider = {
+			// biome-ignore lint/correctness/useYield: it never produces anything, on purpose
+			async *chatStream() {
+				await new Promise<never>(() => {})
+			},
+		}
+		const config = {
+			model: 'mock',
+			tokenBudget: 10_000,
+			timeoutMs: 10_000,
+			maxIterations: 2,
+			provider,
+			tools: new ToolRegistry(),
+			systemPrompt: 'hold',
+			sessionId: 'ses_fan' as never,
+			threadId: 'thd_fan' as never,
+			projectId: 'prj_fan' as never,
+			tenantId: 'tnt_fan' as never,
+		}
+
+		// Start one run on each shell; neither resolves, and neither should
+		// refuse. A shared shell would reject the second synchronously.
+		const a = first.run({ messages: [], workingDirectory: '/tmp' } as never, config as never)
+		const b = second.run({ messages: [], workingDirectory: '/tmp' } as never, config as never)
+
+		await expect(
+			Promise.race([
+				Promise.all([a, b]).then(() => 'settled'),
+				new Promise((r) => setTimeout(() => r('still running'), 50)),
+			]),
+		).resolves.toBe('still running')
+
+		void a.catch(() => {})
+		void b.catch(() => {})
+	})
+
+	it('a definition may override the shell with its own factory', () => {
+		// The escape hatch for an agent that needs real construction
+		// arguments, which `forRun`'s metadata-only rebuild cannot supply.
+		let built = 0
+		const definition: AgentDefinition = {
+			info: { ...metadata, tools: [], defaults: {} } as never,
+			typedAgent: new ReactiveAgent(metadata) as never,
+			createAgent: () => {
+				built += 1
+				return new ReactiveAgent(metadata) as never
+			},
+		}
+
+		const one = definition.createAgent?.()
+		const two = definition.createAgent?.()
+
+		expect(built).toBe(2)
+		expect(one).not.toBe(two)
+		expect(one).not.toBe(definition.typedAgent)
+	})
+})

package/src/manager/agent/lifecycle.ts

@@ -123,7 +123,27 @@ export class AgentManager {
 			)
 		}
 
-		const agent = this.registry.resolve(options.agentId)
+		// A shell this task has to itself, not the registry's shared instance.
+		//
+		// `resolve` returns one `typedAgent` per registered id, and an instance
+		// refuses a second concurrent `run` because it holds per-run state. So
+		// a fan-out naming the same `agent_id` four times drove four runs at one
+		// shell: one worked and three died with `ConcurrentInvocationError` —
+		// while `create_task`'s own description tells the model that this
+		// fan-out is the thing to do. Observed live on 12.0.1, four launches,
+		// three lost.
+		//
+		// The remedy was already written down — "a host that wants parallelism
+		// constructs a second instance" — and was unreachable here, because the
+		// definition owns the instance and this path only has an id.
+		//
+		// Nothing else about the child is shared: its abort signal is the task's
+		// own (`input.signal` below), its config is rebuilt per spawn by
+		// `configBuilder`, and the manager cancels through the task rather than
+		// the agent. The shell was the only shared thing left.
+		const definitionForSpawn = this.registry.getOrThrow(options.agentId)
+		const sharedAgent = definitionForSpawn.typedAgent
+		const agent = definitionForSpawn.createAgent?.() ?? sharedAgent.forRun?.() ?? sharedAgent
 
 		const childAbortController = createChildAbortController(context.parentAbortController)
 

package/src/runtime/query/__tests__/the-other-approval-surface-names-the-agent.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+
+import type { PlanManager } from '../../../manager/plan/lifecycle.js'
+import { MockLLMProvider, registerMock } from '../../../provider/index.js'
+import { ToolRegistry } from '../../../registry/index.js'
+import type { HITLResumeDecision, PlanApprovalData } from '../../../types/hitl/index.js'
+import {
+	generateProjectId,
+	generateSessionId,
+	generateTenantId,
+	generateThreadId,
+} from '../../../utils/id.js'
+import { drainQuery } from '../index.js'
+
+/**
+ * There are TWO approval surfaces, and the fix landed on one of them.
+ *
+ * `PlanStep.agentId` was added so an approver could see WHICH agent a step goes
+ * to rather than only THAT it delegates. It reached `PlanApprovalRequest` — the
+ * shape a host sees when it installs its own handler on `PlanManager` — and the
+ * test written at the time asserted on exactly that, by constructing a
+ * `PlanManager` directly.
+ *
+ * It did not reach `PlanApprovalData`, which is what every `resumeHandler` host
+ * receives, because that type declared its own step shape and both mappers copy
+ * field by field. So the busier surface kept showing `toolName: 'create_task'`
+ * and nothing else — the precise behaviour the change was supposed to end.
+ *
+ * A live run did not catch it either: the run observes `plan_ready`, which
+ * carries whole `PlanStep`s and therefore always had `agentId`. Watching the
+ * event stream confirmed the field existed somewhere, which is not the same
+ * question as whether the approver gets it.
+ */
+
+registerMock()
+
+async function agentIdSeenByResumeHandler(): Promise<PlanApprovalData['steps']> {
+	let seen: PlanApprovalData['steps'] | undefined
+
+	await drainQuery({
+		provider: new MockLLMProvider({ responses: [{ content: 'done' }] } as never),
+		tools: new ToolRegistry(),
+		agentId: 'a',
+		agentName: 'A',
+		messages: [{ role: 'user', content: 'go' }],
+		workingDirectory: process.cwd(),
+		runConfig: { model: 'mock', tokenBudget: 100_000, timeoutMs: 30_000, maxIterations: 4 },
+		projectId: generateProjectId(),
+		sessionId: generateSessionId(),
+		threadId: generateThreadId(),
+		tenantId: generateTenantId(),
+		// The ordinary host path: a resumeHandler, not a hand-installed
+		// PlanManager handler.
+		resumeHandler: async (request: { type: string; plan?: PlanApprovalData }) => {
+			if (request.type === 'plan_approval' && request.plan) seen = request.plan.steps
+			return { action: 'approve_plan' } as HITLResumeDecision
+		},
+		onContextCreated: ({ planManager }: { planManager: PlanManager }) => {
+			planManager.startGenerating('the work')
+			planManager.addStep({
+				id: 'step_1',
+				description: 'delegated work',
+				agentId: 'shell-runner',
+				toolName: 'create_task',
+				dependsOn: [],
+				order: 1,
+			})
+			planManager.addStep({ id: 'step_2', description: 'my own work', dependsOn: [], order: 2 })
+			planManager.markReady()
+			void planManager.requestApproval()
+		},
+	} as never)
+
+	if (!seen) throw new Error('the resume handler never received a plan approval')
+	return seen
+}
+
+describe('the resumeHandler approval surface names the agent too', () => {
+	it('carries agentId through to the host', async () => {
+		const steps = await agentIdSeenByResumeHandler()
+
+		expect(steps.map((s) => s.agentId)).toEqual(['shell-runner', undefined])
+	})
+
+	it('still distinguishes the two steps by more than toolName', async () => {
+		// The defect in the shape that matters: without agentId both delegated
+		// steps reach the approver identical, and an orchestrator-owned step is
+		// told apart only by an absent toolName.
+		const steps = await agentIdSeenByResumeHandler()
+		const delegated = steps.find((s) => s.id === 'step_1')
+
+		expect(delegated?.toolName).toBe('create_task')
+		expect(delegated?.agentId).toBe('shell-runner')
+	})
+})

package/src/runtime/query/index.ts

@@ -527,6 +527,7 @@ export async function* query(params: QueryParams): AsyncGenerator<RunEvent, Run>
 					id: s.id,
 					description: s.description,
 					toolName: s.toolName,
+					agentId: s.agentId,
 					dependsOn: s.dependsOn,
 					order: s.order ?? i + 1,
 				})),

package/src/runtime/query/iteration/phases/plan.ts

@@ -29,6 +29,7 @@ export async function* runPlanGate(ctx: IterationContext): AsyncGenerator<RunEve
 				id: s.id,
 				description: s.description,
 				toolName: s.toolName,
+				agentId: s.agentId,
 				dependsOn: s.dependsOn,
 				order: s.order,
 			})),

package/src/tools/coordinator/__tests__/an-approver-is-never-shown-an-impossible-step.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest'
+
+import { PlanManager } from '../../../manager/plan/lifecycle.js'
+import type { TaskGateway } from '../../../types/agent/gateway.js'
+import type { RunId } from '../../../types/ids/index.js'
+import type { PlanApprovalRequest } from '../../../types/plan/index.js'
+import type { ToolContext } from '../../../types/tool/index.js'
+import { buildCoordinatorTools } from '../index.js'
+
+/**
+ * A plan could name an agent the launch would then refuse.
+ *
+ * `create_task` constrains `agent_id` with a closed enum; `approve_plan` typed
+ * the same field as a bare string. So a model could propose, and a human could
+ * approve, "delegate to X" for an X that `create_task` rejects at schema-parse
+ * time — the run then burns a turn on a step a human had already blessed.
+ *
+ * The check lives in `execute`, not in the schema, and that is deliberate.
+ * `approve_plan` is mounted even with an EMPTY roster, because planning with no
+ * delegates and a human channel is a supported configuration — and `z.enum([])`
+ * renders as `{"not":{}}`, the shape `delegateSchema` already refuses because a
+ * strict tool-schema validator rejects the whole request over it rather than
+ * the one tool. `create_task` escapes that by being withheld entirely; this
+ * tool cannot be. Enforcing in `execute` as well is the precedent the canonical
+ * `Agent` tool set for complete mediation.
+ *
+ * It runs BEFORE `startGenerating`, so the refusal costs no half-built plan and
+ * the human is never shown the bad step at all.
+ */
+
+const RUN = 'run_roster' as RunId
+
+function unusedGateway(): TaskGateway {
+	return {
+		async createTask() {
+			throw new Error('this test never launches')
+		},
+		async waitForTask() {
+			throw new Error('this test never waits')
+		},
+		async continueTask() {},
+		cancelTask() {},
+		getTask() {
+			return undefined
+		},
+		listTasks() {
+			return []
+		},
+		onTaskCompleted() {
+			return () => {}
+		},
+	}
+}
+
+function ctx(): ToolContext {
+	return {
+		runId: RUN,
+		workingDirectory: '/tmp/test',
+		abortSignal: new AbortController().signal,
+		env: {},
+		log: () => {},
+	}
+}
+
+/** Run `approve_plan`, reporting both its result and what the approver saw. */
+async function approve(
+	roster: string[],
+	steps: Array<{ description: string; agent_id?: string }>,
+): Promise<{ result: Awaited<ReturnType<ReturnType<typeof build>>>; seen?: PlanApprovalRequest }> {
+	let seen: PlanApprovalRequest | undefined
+	const pm = new PlanManager(RUN, async (request) => {
+		seen = request
+		return { approved: true }
+	})
+	const run = build(roster, pm)
+	const result = await run(steps)
+	return { result, ...(seen ? { seen } : {}) }
+}
+
+function build(roster: string[], pm: PlanManager) {
+	const tools = buildCoordinatorTools({
+		gateway: unusedGateway(),
+		workingDirectory: '/tmp/test',
+		allowedAgentIds: roster,
+		getPlanManager: () => pm,
+	})
+	const approvePlan = tools.find((t) => t.name === 'approve_plan')
+	if (!approvePlan) throw new Error('approve_plan missing from coordinator builder')
+	return (steps: Array<{ description: string; agent_id?: string }>) =>
+		approvePlan.execute({ title: 'do it', summary: 'a plan', steps }, ctx())
+}
+
+describe('a plan may only name an agent the run can actually launch', () => {
+	it('refuses a step naming an agent outside the roster', async () => {
+		const { result } = await approve(
+			['researcher', 'writer'],
+			[{ description: 'audit the deps', agent_id: 'security-auditor' }],
+		)
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('security-auditor')
+	})
+
+	it('names the roster, so the model can correct itself in one turn', async () => {
+		const { result } = await approve(
+			['researcher', 'writer'],
+			[{ description: 'audit', agent_id: 'nobody' }],
+		)
+
+		expect(result.error).toContain('researcher')
+		expect(result.error).toContain('writer')
+	})
+
+	it('never shows the approver the step it refused', async () => {
+		// The whole point of checking before `startGenerating`: a human must
+		// not be asked to approve work that cannot run.
+		const { seen } = await approve(
+			['researcher'],
+			[{ description: 'audit', agent_id: 'security-auditor' }],
+		)
+
+		expect(seen).toBeUndefined()
+	})
+
+	it('leaves no half-built plan behind', async () => {
+		const pm = new PlanManager(RUN, async () => ({ approved: true }))
+		const run = build(['researcher'], pm)
+
+		await run([{ description: 'audit', agent_id: 'ghost' }])
+
+		expect(pm.active).toBeNull()
+	})
+
+	it('says something different when the run has no delegates at all', async () => {
+		// `approve_plan` is mounted on an empty roster on purpose — planning
+		// without delegation is supported — so the message has to explain that
+		// rather than list an empty set.
+		const { result } = await approve([], [{ description: 'audit', agent_id: 'anyone' }])
+
+		expect(result.success).toBe(false)
+		expect(result.error).toContain('no delegates')
+	})
+
+	it('still admits a plan that delegates only within the roster', async () => {
+		const { result, seen } = await approve(
+			['researcher', 'writer'],
+			[{ description: 'gather', agent_id: 'researcher' }, { description: 'summarize' }],
+		)
+
+		expect(result.success).toBe(true)
+		expect(seen?.steps.map((s) => s.agentId)).toEqual(['researcher', undefined])
+	})
+})

package/src/tools/coordinator/index.ts

@@ -1015,6 +1015,46 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 					return { success: false, output: '', error: dependencies.error }
 				}
 
+				// The roster, checked here rather than in the schema, and BEFORE
+				// the plan is built — so a human is never shown a step naming an
+				// agent that cannot run it.
+				//
+				// `create_task` constrains the same field with a closed enum, so
+				// a plan could name an agent the launch would then refuse. The
+				// mismatch used to be invisible because the name was dropped on
+				// the way to the approver; now that a step carries it, an
+				// approver could read "delegate to X" for an X that does not
+				// exist.
+				//
+				// NOT closed in the schema, deliberately. `approve_plan` is
+				// mounted even with an empty roster — planning with no delegates
+				// and a human channel is a supported configuration — and
+				// `z.enum([])` renders as `{"not":{}}`, the shape `delegateSchema`
+				// already refuses because a strict tool-schema validator rejects
+				// the whole request over it rather than the one tool.
+				// `create_task` escapes that by being withheld entirely; this
+				// tool cannot be.
+				//
+				// Enforcing in `execute` as well as the schema is the precedent
+				// the canonical `Agent` tool set for complete mediation.
+				const unknownAgents = [
+					...new Set(
+						steps
+							.map((s) => s.agent_id)
+							.filter((id): id is string => Boolean(id) && !agentIds.includes(id as string)),
+					),
+				]
+				if (unknownAgents.length > 0) {
+					return {
+						success: false,
+						output: '',
+						error:
+							agentIds.length === 0
+								? `This plan delegates to ${unknownAgents.join(', ')}, but this run has no delegates. Plan the work as your own steps and omit agent_id.`
+								: `No such agent: ${unknownAgents.join(', ')}. Delegate only to ${agentIds.join(', ')}, or omit agent_id for a step you carry out yourself.`,
+					}
+				}
+
 				pm.startGenerating(title)
 				for (let i = 0; i < steps.length; i++) {
 					const step = steps[i]

package/src/types/agent/core.ts

@@ -17,6 +17,28 @@ export interface Agent<
 
 	run(input: AgentInput, config: TConfig, listener?: RunEventListener): Promise<TResult>
 
+	/**
+	 * A shell of this agent that one run may have to itself.
+	 *
+	 * An agent instance holds per-run state — an abort controller, the id of
+	 * the run in flight — and refuses a second concurrent `run` because of it.
+	 * That refusal is correct for a host calling `run` twice on purpose: two
+	 * overlapping runs would share one abort controller, so cancelling either
+	 * kills both.
+	 *
+	 * It is wrong for delegation, which is why this exists. `AgentRegistry`
+	 * hands out ONE instance per registered id, so a fan-out naming the same
+	 * `agent_id` four times drove four runs at one shell: one worked and three
+	 * died with `ConcurrentInvocationError`. The prescribed remedy — "construct
+	 * a second instance" — was unreachable from there, because the definition
+	 * owns the instance and the caller only has an id.
+	 *
+	 * OPTIONAL, and absence is safe: a manager that cannot get a fresh shell
+	 * falls back to the shared one and the refusal stands, which is loud rather
+	 * than wrong. `AbstractAgent` implements it for every agent built on it.
+	 */
+	forRun?(): Agent<TConfig, TResult>
+
 	cancel(): Promise<void>
 	getCapabilities(): AgentCapabilities
 }

package/src/types/agent/factory.ts

@@ -8,6 +8,26 @@ export type { AgentContextLevel } from './base.js'
 export interface AgentDefinition {
 	info: AgentInfo
 	typedAgent: Agent<BaseAgentConfig, BaseAgentResult>
+
+	/**
+	 * Build a fresh agent for a single spawn.
+	 *
+	 * `typedAgent` is ONE instance, and an instance refuses a second
+	 * concurrent run because it holds per-run state. So a delegation fan-out
+	 * naming the same `agent_id` four times ran one child and lost three to
+	 * `ConcurrentInvocationError` — while `create_task`'s own description tells
+	 * a model that exactly this fan-out is the thing to do.
+	 *
+	 * The manager prefers this over `typedAgent` for every spawn. Supply it
+	 * when your agent needs real construction arguments; agents built on
+	 * `AbstractAgent` already get a working default from `Agent.forRun`, so
+	 * most hosts need nothing here.
+	 *
+	 * `configBuilder` is not a substitute: it produces a fresh CONFIG per
+	 * spawn, and the config was never the part being shared.
+	 */
+	createAgent?: () => Agent<BaseAgentConfig, BaseAgentResult>
+
 	configBuilder?: (options: AgentFactoryOptions) => BaseAgentConfig | Promise<BaseAgentConfig>
 
 	contextLevel?: AgentContextLevel

package/src/types/hitl/index.ts

@@ -109,6 +109,24 @@ export interface PlanApprovalData {
 		id: string
 		description: string
 		toolName?: string
+
+		/**
+		 * Which agent the step is to be delegated to, when it is delegated.
+		 *
+		 * `PlanStep` gained this so an approver could see WHICH agent a step
+		 * goes to rather than only THAT it delegates — approving "delegate
+		 * this" is not approving "delegate this to the agent with shell
+		 * access". It reached `PlanApprovalRequest`, which is the shape a host
+		 * sees when it installs its own handler on `PlanManager`.
+		 *
+		 * It did not reach here, and this is the ordinary path: every host
+		 * using `resumeHandler` is served by this type, and both mappers that
+		 * build it copy field by field. So the fix landed on one of the two
+		 * approval surfaces and the busier one kept showing
+		 * `toolName: 'create_task'` and nothing else.
+		 */
+		agentId?: string
+
 		dependsOn: string[]
 		order: number
 	}>