jeopi-cli 16.2.23 → 16.2.25

package/src/task/critic-gate.ts

@@ -22,6 +22,15 @@
  * input, even re-submitting to `critic` is refused — the agent must stop and
  * report the surviving gaps instead of burning tokens on convergence-free
  * re-planning.
+ *
+ * `okay` clearing the gate is not the whole story: nothing previously stopped
+ * the plan file from being edited *after* the critic approved it and *before*
+ * a non-read-only agent executes it (a TOCTOU window — jeo-code closes the
+ * same gap with a `sha256(planContent) === consensus_hash` pin in
+ * `team.ts`/`approve.ts`). {@link ApprovedPlanHash} / {@link hashPlanContent} /
+ * {@link planIntegrityMismatchMessage} port that pin: the caller records the
+ * approved plan's hash when a verdict resolves `okay`, and re-checks it
+ * immediately before spawning a non-read-only agent.
  */
 
 /** Agent name whose structured verdicts drive the gate. */
@@ -146,3 +155,40 @@ export function criticGateWriteMessage(state: CriticGateState): string {
 		`(or the user sends a new message). Write plans and notes to local:// files instead.${formatRequiredFixes(state)}`
 	);
 }
+
+/** Canonical `local://` path for the plan the `/jeo` workflow gates on (see `prompts/agents/jeo.md`). */
+export const GATED_PLAN_LOCAL_URL = "local://jeo-plan.md";
+
+/** Hash of the plan content a critic verdict of `okay` approved, so a later
+ *  spawn gate can detect the plan changing out from under an already-`okay`
+ *  verdict. Held by the parent session alongside (but independent of)
+ *  {@link CriticGateState} — it survives the gate clearing on `okay`, which is
+ *  exactly when it starts mattering. */
+export interface ApprovedPlanHash {
+	/** sha256 hex digest of the plan content at the moment of the `okay` verdict. */
+	hash: string;
+	/** Agent id of the critic run that approved this content. */
+	agentId: string;
+	/** Epoch ms when the verdict was recorded. */
+	at: number;
+}
+
+/** Stable hash of plan content for {@link ApprovedPlanHash} pinning. Not a
+ *  cryptographic integrity boundary (the model can read its own hash target) —
+ *  it exists to catch accidental or incidental drift between critic approval
+ *  and execution, the same threat model as jeo-code's `consensus_hash`. */
+export function hashPlanContent(content: string): string {
+	return new Bun.CryptoHasher("sha256").update(content).digest("hex");
+}
+
+/**
+ * Error text for a non-read-only spawn attempted when the plan content no
+ * longer matches what the critic approved (edited after `okay`, or deleted).
+ */
+export function planIntegrityMismatchMessage(approved: ApprovedPlanHash): string {
+	return (
+		`Critic gate: \`${GATED_PLAN_LOCAL_URL}\` no longer matches the content \`${approved.agentId}\` reviewed and approved. ` +
+		`The plan changed (or was removed) after the \`okay\` verdict — spawning a non-read-only agent is blocked by the runtime. ` +
+		"Re-submit the current plan to a fresh `critic` and execute only after a new `okay` verdict."
+	);
+}

package/src/task/index.ts

@@ -45,10 +45,18 @@ import {
 // Import review tools for side effects (registers subagent tool handlers)
 import "../tools/review";
 import type { AsyncJobManager } from "../async";
-import type { LocalProtocolOptions } from "../internal-urls";
+import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
 import { loadOverallPlanReference } from "../plan-mode/plan-handoff";
 import { AgentRegistry, MAIN_AGENT_ID } from "../registry/agent-registry";
-import { CRITIC_AGENT_NAME, evaluateCriticGateSpawn, parseCriticVerdict, updateCriticGateState } from "./critic-gate";
+import {
+	CRITIC_AGENT_NAME,
+	evaluateCriticGateSpawn,
+	GATED_PLAN_LOCAL_URL,
+	hashPlanContent,
+	parseCriticVerdict,
+	planIntegrityMismatchMessage,
+	updateCriticGateState,
+} from "./critic-gate";
 import { type DiscoveryResult, discoverAgents, getAgent } from "./discovery";
 import { runSubprocess } from "./executor";
 import {
@@ -547,6 +555,30 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		return this.session.settings.get("task.batch");
 	}
 
+	/** Local protocol options for resolving `local://` paths outside a specific
+	 *  subagent spawn (e.g. the critic-gate plan-integrity check below). */
+	#sessionLocalProtocolOptions(): LocalProtocolOptions {
+		return (
+			this.session.localProtocolOptions ?? {
+				getArtifactsDir: this.session.getArtifactsDir ?? (() => null),
+				getSessionId: this.session.getSessionId ?? (() => null),
+			}
+		);
+	}
+
+	/** Read + hash `local://jeo-plan.md` for the critic-gate plan-integrity pin.
+	 *  Returns `null` when the file does not exist or can't be read — callers
+	 *  treat that as "no current plan to compare against". */
+	async #hashGatedPlanContent(): Promise<string | null> {
+		try {
+			const absolutePath = resolveLocalUrlToPath(GATED_PLAN_LOCAL_URL, this.#sessionLocalProtocolOptions());
+			const content = await fs.readFile(absolutePath, "utf8");
+			return hashPlanContent(content);
+		} catch {
+			return null;
+		}
+	}
+
 	#getSpawnSemaphore(): Semaphore {
 		const max = this.session.settings.get("task.maxConcurrency");
 		if (this.#spawnSemaphore) {
@@ -1134,6 +1166,21 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			};
 		}
 
+		// Plan-integrity pin: even with the gate clear (latest verdict `okay`), a
+		// non-read-only spawn is refused if `local://jeo-plan.md` no longer matches
+		// the content that verdict approved — closes the TOCTOU window between
+		// critic approval and execution (see task/critic-gate.ts).
+		const approvedPlanHash = this.session.getApprovedPlanHash?.();
+		if (approvedPlanHash && !isReadOnlyAgent(agent)) {
+			const currentHash = await this.#hashGatedPlanContent();
+			if (currentHash !== approvedPlanHash.hash) {
+				return {
+					content: [{ type: "text", text: planIntegrityMismatchMessage(approvedPlanHash) }],
+					details: { projectAgentsDir, results: [], totalDurationMs: 0 },
+				};
+			}
+		}
+
 		const planModeState = this.session.getPlanModeState?.();
 		const planModeBaseTools = ["read", "grep", "glob", "lsp", "web_search"];
 		const planModeTools = [
@@ -1418,6 +1465,20 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					this.session.setCriticGateState(
 						updateCriticGateState(this.session.getCriticGateState?.(), parsed, result.id),
 					);
+					// Plan-integrity pin: an `okay` verdict records the current plan
+					// content's hash so a later spawn can detect the plan changing out
+					// from under this exact approval (see the check above and
+					// task/critic-gate.ts). A non-okay verdict clears any prior pin —
+					// the stronger critic-gate write/spawn lock takes over until the
+					// next `okay`, so a stale pin has no protective value to keep.
+					if (this.session.setApprovedPlanHash) {
+						if (parsed.verdict === "okay") {
+							const hash = await this.#hashGatedPlanContent();
+							this.session.setApprovedPlanHash(hash ? { hash, agentId: result.id, at: Date.now() } : undefined);
+						} else {
+							this.session.setApprovedPlanHash(undefined);
+						}
+					}
 				}
 			}
 

package/src/tools/builtin-names.ts

@@ -19,6 +19,7 @@ export const BUILTIN_TOOL_NAMES = [
 	"task",
 	"job",
 	"irc",
+	"subagent",
 	"todo",
 	"web_search",
 	"search_tool_bm25",

package/src/tools/index.ts

@@ -27,7 +27,7 @@ import type { CustomMessage } from "../session/messages";
 import type { UsageStatistics } from "../session/session-entries";
 import type { ToolChoiceQueue } from "../session/tool-choice-queue";
 import { TaskTool } from "../task";
-import type { CriticGateState } from "../task/critic-gate";
+import type { ApprovedPlanHash, CriticGateState } from "../task/critic-gate";
 import type { AgentOutputManager } from "../task/output-manager";
 import { canSpawnAtDepth } from "../task/types";
 import { countToolsForAutoDiscovery, resolveEffectiveToolDiscoveryMode } from "../tool-discovery/mode";
@@ -64,6 +64,7 @@ import { ResolveTool } from "./resolve";
 import { reportFindingTool } from "./review";
 import { SearchToolBm25Tool } from "./search-tool-bm25";
 import { loadSshTool } from "./ssh";
+import { isSubagentToolEnabled, SubagentTool } from "./subagent";
 import { type TodoPhase, TodoTool } from "./todo";
 import { WriteTool } from "./write";
 import { YieldTool } from "./yield";
@@ -102,6 +103,7 @@ export * from "./resolve";
 export * from "./review";
 export * from "./search-tool-bm25";
 export * from "./ssh";
+export * from "./subagent";
 export * from "./todo";
 export * from "./tts";
 export * from "./write";
@@ -278,6 +280,10 @@ export interface ToolSession {
 	getCriticGateState?: () => CriticGateState | undefined;
 	/** Replace the critic gate state (undefined clears the gate). */
 	setCriticGateState?: (state: CriticGateState | undefined) => void;
+	/** Plan content hash a critic verdict of `okay` approved (see `task/critic-gate.ts`); survives the gate clearing on `okay` so a later spawn can detect post-approval plan drift. */
+	getApprovedPlanHash?: () => ApprovedPlanHash | undefined;
+	/** Replace the approved-plan hash (undefined clears it). */
+	setApprovedPlanHash?: (hash: ApprovedPlanHash | undefined) => void;
 	/** Goal mode state (if active or paused) */
 	getGoalModeState?: () => GoalModeState | undefined;
 	/** Goal runtime for the active agent session. */
@@ -466,6 +472,7 @@ export const BUILTIN_TOOLS: Record<BuiltinToolName, ToolFactory> = {
 	task: s => TaskTool.create(s),
 	job: s => new JobTool(s),
 	irc: IrcTool.createIf,
+	subagent: SubagentTool.createIf,
 	todo: s => new TodoTool(s),
 	web_search: s => new WebSearchTool(s),
 	search_tool_bm25: SearchToolBm25Tool.createIf,
@@ -620,6 +627,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "browser") return session.settings.get("browser.enabled");
 		if (name === "checkpoint" || name === "rewind") return session.settings.get("checkpoint.enabled");
 		if (name === "irc") return isIrcEnabled(session.settings, session.taskDepth ?? 0);
+		if (name === "subagent") return isSubagentToolEnabled(session.settings, session.taskDepth ?? 0);
 		if (name === "retain" || name === "recall" || name === "reflect") {
 			return ["hindsight", "mnemopi"].includes(session.settings.get("memory.backend") ?? "");
 		}

package/src/tools/subagent.test.ts

@@ -0,0 +1,305 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { AsyncJobManager } from "../async";
+import { Settings } from "../config/settings";
+import { IrcBus } from "../irc/bus";
+import { AgentRegistry } from "../registry/agent-registry";
+import type { AgentSession } from "../session/agent-session";
+import type { ToolSession } from "./index";
+import { SubagentTool } from "./subagent";
+import { ToolError } from "./tool-errors";
+
+function makeSession(opts: { agentId: string; registry: AgentRegistry; manager?: AsyncJobManager }): ToolSession {
+	return {
+		cwd: process.cwd(),
+		hasUI: false,
+		settings: Settings.isolated(),
+		getSessionFile: () => null,
+		getSessionSpawns: () => "*",
+		agentRegistry: opts.registry,
+		asyncJobManager: opts.manager,
+		getAgentId: () => opts.agentId,
+	};
+}
+
+function textOf(result: { content: Array<{ type: string; text?: string }> }): string {
+	return result.content.find(part => part.type === "text")?.text ?? "";
+}
+
+/** Registers a `task` job whose `run` never resolves until the test resolves it. */
+function registerPendingTaskJob(manager: AsyncJobManager, ownerId: string, id: string) {
+	const { promise, resolve } = Promise.withResolvers<string>();
+	manager.register(
+		"task",
+		id,
+		async ({ markRunning }) => {
+			markRunning();
+			return promise;
+		},
+		{ id, ownerId },
+	);
+	return { resolve };
+}
+
+describe("SubagentTool", () => {
+	let registry: AgentRegistry;
+	let manager: AsyncJobManager;
+
+	beforeEach(() => {
+		// `IrcBus.global()` (used internally by steer/resume/pause) always routes
+		// through `AgentRegistry.global()`, so the fake session must live there
+		// too for delivery to resolve the same refs `list`/`inspect` see.
+		AgentRegistry.resetGlobalForTests();
+		registry = AgentRegistry.global();
+		manager = new AsyncJobManager({ onJobComplete: () => {} });
+		IrcBus.resetGlobalForTests();
+	});
+
+	afterEach(() => {
+		manager.cancelAll();
+	});
+
+	it("scopes `list` to the calling agent's own spawns", async () => {
+		registerPendingTaskJob(manager, "Main", "Sub1");
+		registerPendingTaskJob(manager, "Other", "Sub2");
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const result = await tool.execute("call-1", { action: "list" });
+
+		expect(result.details?.subagents.map(s => s.id)).toEqual(["Sub1"]);
+	});
+
+	it('reports a spawn as "queued" until its runner calls markRunning', async () => {
+		const { promise, resolve } = Promise.withResolvers<string>();
+		manager.register("task", "Sub1", async () => promise, { id: "Sub1", ownerId: "Main", queued: true });
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const result = await tool.execute("call-1", { action: "list" });
+
+		expect(result.details?.subagents[0]).toMatchObject({ id: "Sub1", status: "queued" });
+		resolve("cleanup");
+	});
+
+	it("rejects cancel without a target id", async () => {
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		await expect(tool.execute("call-1", { action: "cancel" })).rejects.toThrow(ToolError);
+	});
+
+	it("classifies cancel outcomes: cancelled, not_found, already_completed", async () => {
+		const { resolve } = registerPendingTaskJob(manager, "Main", "Running1");
+		manager.register("task", "Done1", async () => "done", { id: "Done1", ownerId: "Main" });
+		// Let Done1 settle before cancelling it.
+		await manager.getJob("Done1")?.promise;
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const result = await tool.execute("call-1", { action: "cancel", ids: ["Running1", "Done1", "Ghost"] });
+
+		expect(result.details?.cancelled).toEqual(
+			expect.arrayContaining([
+				{ id: "Running1", status: "cancelled" },
+				{ id: "Done1", status: "already_completed" },
+				{ id: "Ghost", status: "not_found" },
+			]),
+		);
+		resolve("cleanup");
+	});
+
+	it("cannot cancel a job owned by a different agent", async () => {
+		const { resolve } = registerPendingTaskJob(manager, "Other", "Sub1");
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const result = await tool.execute("call-1", { action: "cancel", ids: ["Sub1"] });
+
+		expect(result.details?.cancelled).toEqual([{ id: "Sub1", status: "not_found" }]);
+		expect(manager.getJob("Sub1")?.status).toBe("running");
+		resolve("cleanup");
+	});
+
+	it("rejects steer/resume/pause targeting the caller itself", async () => {
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		await expect(tool.execute("c1", { action: "steer", id: "Main", message: "hi" })).rejects.toThrow(ToolError);
+		await expect(tool.execute("c2", { action: "resume", id: "Main", message: "hi" })).rejects.toThrow(ToolError);
+		await expect(tool.execute("c3", { action: "pause", id: "Main" })).rejects.toThrow(ToolError);
+	});
+
+	it("resume is a no-op on a still-running subagent and does not require a message", async () => {
+		const { resolve } = registerPendingTaskJob(manager, "Main", "Sub1");
+		registry.register({ id: "Sub1", displayName: "Sub1", kind: "sub", session: null, status: "running" });
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const result = await tool.execute("call-1", { action: "resume", id: "Sub1" });
+
+		expect(result.isError).toBeFalsy();
+		expect(textOf(result)).toContain("already running");
+		resolve("cleanup");
+	});
+
+	it("resume requires a message once the subagent has finished", async () => {
+		manager.register("task", "Sub1", async () => "done", { id: "Sub1", ownerId: "Main" });
+		await manager.getJob("Sub1")?.promise;
+		registry.register({ id: "Sub1", displayName: "Sub1", kind: "sub", session: null, status: "idle" });
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		await expect(tool.execute("call-1", { action: "resume", id: "Sub1" })).rejects.toThrow(ToolError);
+	});
+
+	it("marks a finished-but-resident subagent as resumable in its snapshot", async () => {
+		manager.register("task", "Sub1", async () => "done", { id: "Sub1", ownerId: "Main" });
+		await manager.getJob("Sub1")?.promise;
+		registry.register({ id: "Sub1", displayName: "Sub1", kind: "sub", session: null, status: "idle" });
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const result = await tool.execute("call-1", { action: "list" });
+
+		expect(result.details?.subagents[0]).toMatchObject({ id: "Sub1", status: "completed", resumable: true });
+	});
+
+	it("pause is a no-op once the subagent already finished", async () => {
+		manager.register("task", "Sub1", async () => "done", { id: "Sub1", ownerId: "Main" });
+		await manager.getJob("Sub1")?.promise;
+		registry.register({ id: "Sub1", displayName: "Sub1", kind: "sub", session: null, status: "idle" });
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const result = await tool.execute("call-1", { action: "pause", id: "Sub1" });
+
+		expect(textOf(result)).toContain("not running");
+	});
+	it('pause marks a still-running subagent "paused"; a later resume clears it', async () => {
+		const { resolve } = registerPendingTaskJob(manager, "Main", "Sub1");
+		const fakeSession = { deliverIrcMessage: async () => "injected" as const } as unknown as AgentSession;
+		registry.register({ id: "Sub1", displayName: "Sub1", kind: "sub", session: fakeSession, status: "running" });
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const pauseResult = await tool.execute("c1", { action: "pause", id: "Sub1" });
+		expect(pauseResult.isError).toBeFalsy();
+
+		// Simulate the subagent actually reaching a safe boundary and stopping in
+		// response to the pause request (a real run would flip both together).
+		resolve("stopped early");
+		await manager.getJob("Sub1")?.promise;
+		registry.setStatus("Sub1", "idle");
+
+		const paused = await tool.execute("c2", { action: "list" });
+		expect(paused.details?.subagents[0]).toMatchObject({ id: "Sub1", status: "paused", resumable: true });
+
+		const resumeResult = await tool.execute("c3", { action: "resume", id: "Sub1", message: "continue" });
+		expect(resumeResult.isError).toBeFalsy();
+
+		const afterResume = await tool.execute("c4", { action: "list" });
+		expect(afterResume.details?.subagents[0].status).not.toBe("paused");
+	});
+	it("resume without a message succeeds on a paused subagent (GJC parity) but still requires one once terminal", async () => {
+		const { resolve } = registerPendingTaskJob(manager, "Main", "Sub1");
+		const fakeSession = { deliverIrcMessage: async () => "injected" as const } as unknown as AgentSession;
+		registry.register({ id: "Sub1", displayName: "Sub1", kind: "sub", session: fakeSession, status: "running" });
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+
+		await tool.execute("c1", { action: "pause", id: "Sub1" });
+		resolve("stopped early");
+		await manager.getJob("Sub1")?.promise;
+		registry.setStatus("Sub1", "idle");
+
+		// No `message` — a paused subagent has known intent (we asked it to stop),
+		// so resume proceeds with a default continuation body instead of throwing.
+		const resumed = await tool.execute("c2", { action: "resume", id: "Sub1" });
+		expect(resumed.isError).toBeFalsy();
+		expect(resumed.details?.receipt?.outcome).toBe("injected");
+
+		// Once genuinely terminal again (no outstanding pause), resume still needs a message.
+		await expect(tool.execute("c3", { action: "resume", id: "Sub1" })).rejects.toThrow(ToolError);
+	});
+
+	it("a subagent that goes idle while running is never mistaken for paused", async () => {
+		const { resolve } = registerPendingTaskJob(manager, "Main", "Sub1");
+		registry.register({ id: "Sub1", displayName: "Sub1", kind: "sub", session: null, status: "running" });
+		resolve("finished on its own");
+		await manager.getJob("Sub1")?.promise;
+		registry.setStatus("Sub1", "idle");
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const result = await tool.execute("call-1", { action: "list" });
+
+		expect(result.details?.subagents[0]).toMatchObject({ id: "Sub1", status: "completed", resumable: true });
+	});
+
+	it("cancel aborts a live resumed session even without an active async job", async () => {
+		const abortReasons: (string | undefined)[] = [];
+		const fakeSession = {
+			abort: async (opts?: { reason?: string }) => {
+				abortReasons.push(opts?.reason);
+			},
+		} as unknown as AgentSession;
+		manager.register("task", "Sub1", async () => "done", { id: "Sub1", ownerId: "Main" });
+		await manager.getJob("Sub1")?.promise;
+		registry.register({ id: "Sub1", displayName: "Sub1", kind: "sub", session: fakeSession, status: "running" });
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const result = await tool.execute("call-1", { action: "cancel", id: "Sub1" });
+
+		expect(result.details?.cancelled).toEqual([{ id: "Sub1", status: "cancelled" }]);
+		expect(abortReasons).toEqual(["Cancelled via subagent tool"]);
+	});
+
+	it("applies `limit` to `list` and reports how many were hidden", async () => {
+		registerPendingTaskJob(manager, "Main", "Sub1");
+		registerPendingTaskJob(manager, "Main", "Sub2");
+		registerPendingTaskJob(manager, "Main", "Sub3");
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		const result = await tool.execute("call-1", { action: "list", limit: 2 });
+
+		expect(result.details?.subagents).toHaveLength(2);
+		expect(result.details?.truncated).toBe(1);
+	});
+
+	it("verbosity widths match GJC: receipt<=280, preview<=2000, full<=12000 chars", async () => {
+		const longOutput = "x".repeat(15_000);
+		manager.register("task", "Sub1", async () => longOutput, { id: "Sub1", ownerId: "Main" });
+		await manager.getJob("Sub1")?.promise;
+
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+
+		// `verbosity` defaults to "receipt" per GJC (not "preview").
+		const defaulted = await tool.execute("c0", { action: "inspect", ids: ["Sub1"] });
+		expect(defaulted.details?.subagents[0].resultText).toHaveLength(280);
+
+		const receipt = await tool.execute("c1", { action: "inspect", ids: ["Sub1"], verbosity: "receipt" });
+		expect(receipt.details?.subagents[0].resultText).toHaveLength(280);
+
+		const preview = await tool.execute("c2", { action: "inspect", ids: ["Sub1"], verbosity: "preview" });
+		expect(preview.details?.subagents[0].resultText).toHaveLength(2_000);
+
+		const full = await tool.execute("c3", { action: "inspect", ids: ["Sub1"], verbosity: "full" });
+		expect(full.details?.subagents[0].resultText).toHaveLength(12_000);
+	});
+
+	it('rejects verbosity="full" on `list`, and on any action without explicit ids', async () => {
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+		await expect(tool.execute("c1", { action: "list", verbosity: "full" })).rejects.toThrow(ToolError);
+		await expect(tool.execute("c2", { action: "inspect", verbosity: "full" })).rejects.toThrow(ToolError);
+		// Explicit ids makes `full` valid for a non-list action.
+		const result = await tool.execute("c3", { action: "inspect", ids: ["Ghost"], verbosity: "full" });
+		expect(result.isError).toBe(true);
+	});
+
+	it("`list` defaults to 10 results and clamps `limit` to a max of 50", async () => {
+		for (let i = 0; i < 12; i++) {
+			registerPendingTaskJob(manager, "Main", `Sub${i}`);
+		}
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+
+		const defaulted = await tool.execute("c1", { action: "list" });
+		expect(defaulted.details?.subagents).toHaveLength(10);
+		expect(defaulted.details?.truncated).toBe(2);
+
+		const overshoot = await tool.execute("c2", { action: "list", limit: 1_000 });
+		expect(overshoot.details?.subagents).toHaveLength(12);
+		expect(overshoot.details?.truncated).toBeUndefined();
+	});
+
+	it("accepts `timeout_ms` (snake_case, matching GJC) for `await`", async () => {
+		registerPendingTaskJob(manager, "Main", "Sub1");
+		const tool = new SubagentTool(makeSession({ agentId: "Main", registry, manager }));
+
+		const result = await tool.execute("c1", { action: "await", ids: ["Sub1"], timeout_ms: 5 });
+		expect(result.details?.subagents[0]).toMatchObject({ id: "Sub1", status: "running" });
+	});
+});