@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/test/unit/tool-activation-stale-peer.test.ts

@@ -0,0 +1,32 @@
+import assert from "node:assert/strict";
+import { registerHooks } from "node:module";
+import { test } from "node:test";
+
+test("activates against the running Pi when a package-local pi-ai lacks transcript helpers", async () => {
+	// Simulate an older pi-ai installed beside this package, not the running host.
+	const hook = registerHooks({
+		resolve(specifier, context, nextResolve) {
+			if (specifier === "@earendil-works/pi-ai" && context.parentURL &&
+				new URL(context.parentURL).pathname.endsWith("/src/extension/tool-activation.ts")) {
+				return { url: "data:text/javascript,export const legacy = true", shortCircuit: true };
+			}
+			return nextResolve(specifier, context);
+		},
+	});
+	try {
+		const { registerSubagentToolActivation } = await import("../../src/extension/tool-activation.ts");
+		const tools = new Set(["read", "subagent"]);
+		const pi = {
+			getAllTools: () => [...tools].map((name) => ({ name })),
+			getActiveTools: () => ["read", "subagent"],
+			setActiveTools() {},
+			registerTool: (tool: { name: string }) => { tools.add(tool.name); },
+			on: () => () => {},
+		};
+		// SAFETY: activation calls only the five Pi methods supplied by this fixture.
+		registerSubagentToolActivation(pi as never, { advertisedPrompt: () => undefined });
+		assert.ok(tools.has("subagents_enable"), "host API should enable the self-service loader");
+	} finally {
+		hook.deregister();
+	}
+});

package/dist/extensions/pi-subagents/test/unit/tool-activation.test.ts

@@ -0,0 +1,313 @@
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterEach, describe, it } from "node:test";
+import { validateToolArguments } from "@earendil-works/pi-ai";
+import registerSubagentExtension from "../../src/extension/index.ts";
+import { SELESAI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../src/shared/utils.ts";
+import { resolvePiPackageRoot } from "../../src/runs/shared/pi-spawn.ts";
+
+type Handler = (event: any, context: any) => any;
+type Tool = { name: string; description?: string; promptSnippet?: string; parameters?: unknown; execute?: (...args: any[]) => any };
+
+const runtimes: Array<{ handlers: Map<string, Handler[]>; context: any }> = [];
+
+type RuntimeOptions = { config?: Record<string, unknown>; model?: unknown };
+const DYNAMIC: RuntimeOptions = { config: { toolActivation: "dynamic" } };
+
+function createRuntime(messages: any[] = [], excluded: string[] = [], missingApis: string[] = [], options: RuntimeOptions = {}) {
+	const handlers = new Map<string, Handler[]>();
+	const tools = new Map<string, Tool>();
+	let activeNames = ["read"];
+	const excludedNames = new Set(excluded);
+	const missingApiNames = new Set(missingApis);
+	const pi = new Proxy({
+		events: { on() { return () => {}; }, emit() {} },
+		on(name: string, handler: Handler) {
+			const registered = handlers.get(name) ?? [];
+			registered.push(handler);
+			handlers.set(name, registered);
+		},
+		registerTool(tool: Tool) {
+			tools.set(tool.name, tool);
+			if (!excludedNames.has(tool.name)) activeNames = [...new Set([...activeNames, tool.name])];
+		},
+		getAllTools() {
+			return [...tools.values()].filter((tool) => !excludedNames.has(tool.name));
+		},
+		getActiveTools() { return [...activeNames]; },
+		setActiveTools(names: string[]) {
+			const available = new Set([...tools.keys(), "read"].filter((name) => !excludedNames.has(name)));
+			activeNames = [...new Set(names.filter((name) => available.has(name)))];
+		},
+		registerCommand() {}, registerShortcut() {}, registerMessageRenderer() {}, sendMessage() {}, getSessionName() {},
+	}, { get(target, property) {
+		if (missingApiNames.has(String(property))) return undefined;
+		return property in target ? target[property as keyof typeof target] : () => undefined;
+	} });
+	const context = {
+		cwd: process.cwd(), isIdle() { return false; }, hasUI: false, model: options.model as any,
+		ui: { setWidget() {}, theme: { fg(_name: string, text: string) { return text; }, bg(_name: string, text: string) { return text; }, bold(text: string) { return text; } } },
+		sessionManager: {
+			getSessionId() { return "activation-session"; }, getSessionFile() { return null; }, getEntries() { return []; },
+			buildSessionContext() { return { messages }; },
+		},
+		modelRegistry: { getAvailable() { return []; } },
+	};
+	const childEnv = process.env.SELESAI_SUBAGENT_CHILD;
+	const priorAgentDir = process.env.SELESAI_CODING_AGENT_DIR;
+	const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "tool-activation-agent-"));
+	if (options.config) {
+		fs.mkdirSync(path.join(agentDir, "extensions", "subagent"), { recursive: true });
+		fs.writeFileSync(path.join(agentDir, "extensions", "subagent", "config.json"), JSON.stringify(options.config));
+	}
+	process.env.SELESAI_CODING_AGENT_DIR = agentDir;
+	delete process.env.SELESAI_SUBAGENT_CHILD;
+	try {
+		registerSubagentExtension(pi as any);
+	} finally {
+		if (childEnv === undefined) delete process.env.SELESAI_SUBAGENT_CHILD;
+		else process.env.SELESAI_SUBAGENT_CHILD = childEnv;
+		if (priorAgentDir === undefined) delete process.env.SELESAI_CODING_AGENT_DIR;
+		else process.env.SELESAI_CODING_AGENT_DIR = priorAgentDir;
+	}
+	runtimes.push({ handlers, context });
+	return {
+		handlers, tools, context,
+		active: () => [...activeNames],
+		select: (names: string[]) => { activeNames = [...names]; },
+		async emit(name: string, event: any) {
+			for (const handler of handlers.get(name) ?? []) await handler(event, context);
+		},
+	};
+}
+
+afterEach(async () => {
+	for (const runtime of runtimes.splice(0)) {
+		for (const handler of runtime.handlers.get("session_shutdown") ?? []) await handler({ type: "session_shutdown", reason: "quit" }, runtime.context);
+	}
+});
+
+describe("subagent tool activation", () => {
+	it("keeps subagent eager unless the host provides the complete dynamic-tool API", async () => {
+		for (const missing of ["getAllTools", "getActiveTools", "setActiveTools"]) {
+			const runtime = createRuntime([], [], [missing], DYNAMIC);
+			await runtime.emit("session_start", { type: "session_start", reason: "startup" });
+			assert.ok(runtime.active().includes("subagent"), `${missing} must fail closed to eager subagent`);
+			assert.equal(runtime.tools.has("subagents_enable"), false);
+		}
+	});
+
+	it("starts fresh parents with a compact self-service loader and keeps support tools active", async () => {
+		const runtime = createRuntime([], [], [], DYNAMIC);
+		await runtime.emit("session_start", { type: "session_start", reason: "startup" });
+
+		assert.equal(runtime.active().includes("subagent"), false);
+		assert.ok(runtime.active().includes("subagents_enable"));
+		assert.ok(runtime.active().includes("bg_wait"));
+		assert.ok(runtime.active().includes("subagent_supervisor"));
+		const loader = runtime.tools.get("subagents_enable");
+		assert.ok(loader);
+		assert.match(loader.description ?? "", /current request|applicable .*instructions/i);
+		assert.deepEqual(validateToolArguments(loader as never, { type: "toolCall", id: "call-1", name: "subagents_enable", arguments: { action: "enable" } }), { action: "enable" });
+
+		const result = await loader.execute?.("enable", {}, new AbortController().signal, undefined, runtime.context);
+		assert.notEqual(result?.isError, true);
+		assert.ok(runtime.active().includes("subagent"));
+		assert.ok(runtime.active().includes("read"));
+		const enabled = runtime.active();
+		await loader.execute?.("enable-again", {}, new AbortController().signal, undefined, runtime.context);
+		assert.deepEqual(runtime.active(), enabled);
+	});
+
+	it("restores native cold and warm transcript selections across start, reload, and tree navigation", async () => {
+		const tool = { name: "subagent", description: "historical", parameters: { type: "object" } };
+		const history = [{ role: "system", content: "", toolsAdded: [], timestamp: 1 }];
+		const cold = createRuntime(history, [], [], DYNAMIC);
+		await cold.emit("session_start", { type: "session_start", reason: "reload" });
+		assert.equal(cold.active().includes("subagent"), false);
+		await cold.emit("session_tree", { type: "session_tree", newLeafId: null, oldLeafId: null });
+		assert.equal(cold.active().includes("subagent"), false);
+		history.push({ role: "system", content: "", toolsAdded: [tool], timestamp: 2 });
+		await cold.emit("session_tree", { type: "session_tree", newLeafId: null, oldLeafId: null });
+		assert.ok(cold.active().includes("subagent"));
+
+		const warm = createRuntime([{ role: "system", content: "", toolsAdded: [tool], timestamp: 1 }], [], [], DYNAMIC);
+		await warm.emit("session_start", { type: "session_start", reason: "resume" });
+		assert.ok(warm.active().includes("subagent"));
+		assert.ok(warm.active().includes("subagents_enable"));
+	});
+
+	it("keeps eager compatibility for legacy history and when the loader is restricted", async () => {
+		const legacy = createRuntime([{ role: "user", content: "continue", timestamp: 1 }], [], [], DYNAMIC);
+		await legacy.emit("session_start", { type: "session_start", reason: "startup" });
+		assert.ok(legacy.active().includes("subagent"));
+		assert.ok(legacy.active().includes("subagents_enable"));
+
+		const restricted = createRuntime([], ["subagents_enable"], [], DYNAMIC);
+		await restricted.emit("session_start", { type: "session_start", reason: "startup" });
+		assert.ok(restricted.active().includes("subagent"));
+		assert.equal(restricted.active().includes("subagents_enable"), false);
+	});
+
+	it("does not activate delegation from prompt keywords and reports an unavailable target", async () => {
+		const runtime = createRuntime([], [], [], DYNAMIC);
+		await runtime.emit("session_start", { type: "session_start", reason: "startup" });
+		runtime.select(["read"]);
+		const selectedTools = runtime.active();
+		await runtime.emit("before_agent_start", {
+			type: "before_agent_start", prompt: "delegate this complex task", systemPrompt: "base",
+			systemPromptOptions: { selectedTools, sections: {}, promptGuidelines: [] },
+		});
+		assert.equal(runtime.active().includes("subagent"), false);
+		assert.ok(runtime.active().includes("subagents_enable"));
+		assert.ok(selectedTools.includes("subagents_enable"));
+		const defaultSelectionEvent = {
+			type: "before_agent_start", prompt: "continue", systemPrompt: "base",
+			systemPromptOptions: { selectedTools: runtime.active(), sections: {}, promptGuidelines: [] },
+		};
+		await runtime.emit("before_agent_start", defaultSelectionEvent);
+		assert.ok(defaultSelectionEvent.systemPromptOptions.selectedTools?.includes("read"));
+		assert.ok(defaultSelectionEvent.systemPromptOptions.selectedTools?.includes("subagents_enable"));
+
+		(runtime.tools as Map<string, Tool>).delete("subagent");
+		const loader = runtime.tools.get("subagents_enable");
+		const result = await loader?.execute?.("missing", {}, new AbortController().signal, undefined, runtime.context);
+		assert.equal(result?.isError, true);
+		assert.match(result?.content?.[0]?.text ?? "", /unavailable.*subagent/i);
+	});
+});
+
+describe("host dynamic tool support detection", () => {
+	it("activates the loader on an in-process host with no Pi package root evidence", async () => {
+		const prior = process.env[SELESAI_CODING_AGENT_PACKAGE_ROOT_ENV];
+		const priorPiPackageDir = process.env.PI_PACKAGE_DIR;
+		delete process.env[SELESAI_CODING_AGENT_PACKAGE_ROOT_ENV];
+		delete process.env.PI_PACKAGE_DIR;
+		const priorArgv1 = process.argv[1];
+		// Selesai vendors this package inside the host repo; use a neutral entry point.
+		process.argv[1] = path.join(os.tmpdir(), "tool-activation-entry.mjs");
+		try {
+			assert.equal(resolvePiPackageRoot(), undefined, "the test process must not look like a running host package");
+			const runtime = createRuntime([], [], [], DYNAMIC);
+			await runtime.emit("session_start", { type: "session_start", reason: "startup" });
+			assert.ok(runtime.tools.has("subagents_enable"));
+			assert.equal(runtime.active().includes("subagent"), false);
+		} finally {
+			if (prior !== undefined) process.env[SELESAI_CODING_AGENT_PACKAGE_ROOT_ENV] = prior;
+			if (priorPiPackageDir !== undefined) process.env.PI_PACKAGE_DIR = priorPiPackageDir;
+			process.argv[1] = priorArgv1;
+		}
+	});
+});
+
+const tool = (name: string) => ({ name, description: name, parameters: { type: "object" } });
+const declared = (added: string[], removed: string[] = []) => ({
+	role: "system", content: "", toolsAdded: added.map(tool), ...(removed.length ? { toolsRemoved: removed.map((name) => ({ name })) } : {}), timestamp: 1,
+});
+const model = (api: string, compat?: Record<string, boolean>) => ({ id: "m", provider: "p", api, compat });
+const system = { supportsMidConvoSystemMessages: true };
+const COMPATIBLE = model("anthropic-messages", { ...system, supportsMidConvoToolChanges: true });
+const INCOMPATIBLE = model("openai-completions", { supportsMidConvoToolAdditions: true });
+
+async function startAgent(runtime: ReturnType<typeof createRuntime>): Promise<string[]> {
+	const event = {
+		type: "before_agent_start", prompt: "continue", systemPrompt: "base",
+		systemPromptOptions: { selectedTools: runtime.active(), sections: {}, promptGuidelines: [] },
+	};
+	await runtime.emit("before_agent_start", event);
+	return event.systemPromptOptions.selectedTools;
+}
+
+describe("toolActivation modes", () => {
+	it("defaults to auto, which starts a new session with subagent and no loader when the model cannot add tools", async () => {
+		for (const options of [{}, { config: { toolActivation: "auto" }, model: INCOMPATIBLE }]) {
+			const runtime = createRuntime([], [], [], options);
+			await runtime.emit("session_start", { type: "session_start", reason: "startup" });
+			const first = await startAgent(runtime);
+			assert.ok(first.includes("subagent") && first.includes("read"));
+			assert.equal(first.includes("subagents_enable"), false);
+			// Switching to a capable model mid-session changes nothing.
+			runtime.context.model = COMPATIBLE;
+			assert.deepEqual(await startAgent(runtime), first);
+		}
+	});
+
+	it("offers the loader in auto only when the model's API can add tools mid-conversation", async () => {
+		const cases: Array<[unknown, boolean]> = [
+			[undefined, false],
+			[model("anthropic-messages"), false],
+			[model("anthropic-messages", { ...system, supportsMidConvoToolChanges: true }), true],
+			[model("anthropic-messages", { supportsMidConvoSystemMessages: false, supportsMidConvoToolChanges: true }), false],
+			[model("anthropic-messages", { supportsMidConvoToolChanges: true }), false],
+			[model("anthropic-messages", system), false],
+			[model("openai-completions", { ...system, supportsMidConvoToolAdditions: true }), true],
+			[model("openai-completions", { ...system, supportsMidConvoToolChanges: true }), false],
+			[model("openai-responses", { ...system, supportsAdditionalTools: true }), true],
+			[model("openai-responses", { ...system, supportsToolSearch: true }), true],
+			[model("openai-responses", system), false],
+			[model("openai-codex-responses", { ...system, supportsToolSearch: true }), true],
+			[model("azure-openai-responses", { ...system, supportsAdditionalTools: true }), true],
+			[model("google-generative-ai", { ...system, supportsMidConvoToolChanges: true, supportsMidConvoToolAdditions: true, supportsAdditionalTools: true }), false],
+		];
+		for (const [caseModel, compatible] of cases) {
+			const runtime = createRuntime([], [], [], { model: caseModel });
+			await runtime.emit("session_start", { type: "session_start", reason: "startup" });
+			const selectedTools = await startAgent(runtime);
+			assert.equal(selectedTools.includes("subagents_enable"), compatible, JSON.stringify(caseModel));
+			assert.equal(selectedTools.includes("subagent"), !compatible, JSON.stringify(caseModel));
+		}
+	});
+
+	it("always offers the loader in dynamic, even to a recorded session without it", async () => {
+		for (const messages of [[], [declared(["read", "subagent"])]]) {
+			const runtime = createRuntime(messages, [], [], { ...DYNAMIC, model: INCOMPATIBLE });
+			await runtime.emit("session_start", { type: "session_start", reason: "resume" });
+			assert.ok((await startAgent(runtime)).includes("subagents_enable"));
+			assert.equal(runtime.active().includes("subagent"), messages.length > 0);
+		}
+	});
+
+	it("registers no loader in eager, even with a capable model or recorded loader history", async () => {
+		for (const messages of [[], [declared(["read", "subagents_enable"])]]) {
+			const runtime = createRuntime(messages, [], [], { config: { toolActivation: "eager" }, model: COMPATIBLE });
+			await runtime.emit("session_start", { type: "session_start", reason: "resume" });
+			assert.equal(runtime.tools.has("subagents_enable"), false);
+			const selectedTools = await startAgent(runtime);
+			assert.ok(selectedTools.includes("subagent"));
+			assert.equal(selectedTools.includes("subagents_enable"), false);
+		}
+	});
+
+	it("replays recorded sessions in auto without adding or removing tools, whatever the model", async () => {
+		const cases: Array<[string, any[], string[]]> = [
+			["cold", [declared(["read", "subagents_enable"])], ["subagents_enable"]],
+			["warm", [declared(["read", "subagents_enable"]), declared(["subagent"])], ["subagents_enable", "subagent"]],
+			["eager", [declared(["read", "subagent"])], ["subagent"]],
+			["loader removed", [declared(["read", "subagents_enable", "subagent"]), declared([], ["subagents_enable"])], ["subagent"]],
+			["legacy", [{ role: "user", content: "continue", timestamp: 1 }], ["subagents_enable", "subagent"]],
+		];
+		for (const caseModel of [COMPATIBLE, INCOMPATIBLE]) {
+			for (const [label, messages, expected] of cases) {
+				const runtime = createRuntime(messages, [], [], { model: caseModel });
+				for (const event of [
+					{ type: "session_start", reason: "resume" },
+					{ type: "session_start", reason: "reload" },
+					{ type: "session_tree", newLeafId: null, oldLeafId: null },
+				]) {
+					await runtime.emit(event.type, event);
+					const selectedTools = await startAgent(runtime);
+					for (const name of ["subagents_enable", "subagent"]) {
+						assert.equal(selectedTools.includes(name), expected.includes(name), `${label}, ${caseModel.api}, ${event.type}: ${name}`);
+						assert.equal(runtime.active().includes(name), expected.includes(name), `${label}, ${caseModel.api}, ${event.type}: active ${name}`);
+					}
+				}
+			}
+		}
+	});
+
+	it("rejects an unknown toolActivation value instead of falling back", () => {
+		assert.throws(() => createRuntime([], [], [], { config: { toolActivation: "lazy" } }), /config\.toolActivation must be "auto", "dynamic", or "eager"/);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/tool-budget.test.ts

@@ -3,6 +3,7 @@ import { describe, it } from "node:test";
 import {
 	DEFAULT_TOOL_BUDGET_BLOCK,
 	initialToolBudgetState,
+	isToolBudgetBlockedMessage,
 	shouldBlockToolForBudget,
 	toolBudgetBlockedMessage,
 	toolBudgetSoftNudge,
@@ -49,6 +50,19 @@ describe("tool-budget module", () => {
 		assert.equal(shouldBlockToolForBudget({ hard: 0, block: "*" }, "read", 1), true);
 	});
 
+	it("recognizes only the exact runtime block message for this budget and tool", () => {
+		const budget = { hard: 0, block: "*" };
+		const exact = toolBudgetBlockedMessage(budget, "bash", 1);
+		assert.equal(isToolBudgetBlockedMessage(budget, exact, "bash"), true);
+		assert.equal(isToolBudgetBlockedMessage({ hard: 2, block: "*" }, toolBudgetBlockedMessage({ hard: 2, block: "*" }, "bash", 3), "bash"), true, "plural count past the hard limit");
+		assert.equal(isToolBudgetBlockedMessage(budget, toolBudgetBlockedMessage({ hard: 3, block: "*" }, "bash", 4), "bash"), false, "different hard limit");
+		assert.equal(isToolBudgetBlockedMessage(budget, toolBudgetBlockedMessage(budget, "read", 1), "bash"), false, "different tool name");
+		assert.equal(isToolBudgetBlockedMessage(budget, `src/log.md:12:${exact}`, "bash"), false, "phrase embedded in ordinary tool output");
+		assert.equal(isToolBudgetBlockedMessage(budget, `${exact}\nnext line`, "bash"), false, "trailing output lines");
+		assert.equal(isToolBudgetBlockedMessage(budget, exact, undefined), false, "missing resolved tool name fails closed");
+		assert.equal(isToolBudgetBlockedMessage(budget, exact.replace("after 1 tool call", "after 0 tool call"), "bash"), false, "blocked count must exceed the hard limit");
+	});
+
 	it("formats user-facing budget messages", () => {
 		const budget = { soft: 2, hard: 3, block: ["read"] };
 		assert.match(toolBudgetSoftNudge(budget, 2), /soft limit reached after 2 tool calls/);

package/dist/extensions/pi-subagents/test/unit/tool-description.test.ts

@@ -9,6 +9,7 @@ import {
 	buildSubagentToolDescription,
 	buildSubagentToolPromptMetadata,
 	COMPACT_SUBAGENT_TOOL_DESCRIPTION,
+	DEFAULT_SUBAGENT_TOOL_DESCRIPTION,
 	FULL_SUBAGENT_TOOL_DESCRIPTION,
 	SUBAGENT_SAFETY_GUIDANCE,
 } from "../../src/extension/tool-description.ts";
@@ -28,95 +29,86 @@ function parentToolEnv(agentDir?: string): NodeJS.ProcessEnv {
 }
 
 describe("registered subagent tool description", () => {
-	it("uses the full description by default", () => {
-		const description = buildSubagentToolDescription();
-		const metadata = buildSubagentToolPromptMetadata();
-		assert.equal(description, FULL_SUBAGENT_TOOL_DESCRIPTION);
-		assert.match(description, /^Run one child with \{ agent, task\? \}; use \{ workflowScript \} for inline orchestration/i);
-		assert.match(description, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
-		assert.equal(metadata.promptSnippet, undefined);
-		assert.equal(metadata.promptGuidelines, undefined);
+	it("keeps the operator authority gate visible in every description mode", () => {
+		const authorityGate = "Direct parent execution is the default. Invoke subagents only when delegation is authorized by the operator's current request or applicable user/project instructions; task size, complexity, risk, tool-call count, or recipe fit do not independently authorize delegation.";
+		const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-authority-"));
+		const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-agent-"));
+		fs.mkdirSync(path.join(cwd, ".selesai"), { recursive: true });
+		fs.writeFileSync(path.join(cwd, ".selesai", "subagent-tool-description.md"), "Operator-owned custom guidance.", "utf-8");
+
+		for (const description of [
+			buildSubagentToolDescription(),
+			buildSubagentToolDescription({ toolDescriptionMode: "full" }),
+			buildSubagentToolDescription({ toolDescriptionMode: "compact" }),
+			buildSubagentToolDescription({ toolDescriptionMode: "custom" }, { cwd, agentDir }),
+		]) {
+			assert.ok(description.includes(authorityGate));
+		}
+
+		const fallbackCwd = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-authority-fallback-"));
+		assert.ok(buildSubagentToolDescription({ toolDescriptionMode: "custom" }, { cwd: fallbackCwd, agentDir, warn() {} }).includes(authorityGate));
+		assert.match(buildSubagentToolDescription({ toolDescriptionMode: "custom" }, { cwd, agentDir }), /Operator-owned custom guidance/);
 	});
 
-	it("explains managed worktree baseRef restrictions in every built-in description", () => {
-		for (const description of [FULL_SUBAGENT_TOOL_DESCRIPTION, COMPACT_SUBAGENT_TOOL_DESCRIPTION]) {
-			assert.match(description, /baseRef.*HEAD.*named ref.*40\/64-character commit IDs.*revision expressions.*unsupported/);
-			assert.match(description, /Omitted baseRef defaults to HEAD resolved at worktree allocation/);
+	it("uses the full description and no split metadata by default (Selesai)", () => {
+		assert.equal(buildSubagentToolDescription(), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.deepEqual(buildSubagentToolPromptMetadata(), {});
+		for (const toolDescriptionMode of ["full", "compact", "custom"] as const) {
+			assert.deepEqual(buildSubagentToolPromptMetadata({ toolDescriptionMode }), {});
 		}
 	});
 
-	it("keeps the full description when configured", () => {
-		const description = buildSubagentToolDescription({ toolDescriptionMode: "full" });
-		assert.equal(buildSubagentToolPromptMetadata({ toolDescriptionMode: "full" }).promptSnippet, undefined);
-		assert.match(description, /^Run one child with \{ agent, task\? \}; use \{ workflowScript \} for inline orchestration or \{ workflowScriptPath \}/i);
-		assert.match(description, /workflowScriptPath:"workflows\/review\.js".*host reads the file.*sandbox/i);
-		assert.match(description, /SINGLE CHILD:.*starts exactly one direct child/i);
-		assert.match(description, /lane\.status.*lane\.recordMerge.*lane\.recordSupersession/i);
-		assert.match(description, /Do not combine agent\/task with action, workflowScript, or workflowScriptPath/i);
-		assert.match(description, /runs\.run for one child and await runs\.all.*ordinary parallel children/i);
-		assert.match(description, /runs\.lanes\(\[\{key,stages:.*later stages sequence per lane/i);
-		assert.match(description, /do not read \.output from unawaited runs\.run launches/i);
-		assert.match(description, /runs\.steer\(key, message, \{mode\?, index\?, ackTimeoutMs\?\}\).*prior keyed child.*without exposing its run id/i);
-		assert.match(description, /receipts are queued, delivered, missed, or failed/i);
-		assert.match(description, /repository mutation lanes.*worktree:true.*runs\.run\/runs\.all.*managed isolation/i);
-		assert.match(description, /ordinary JavaScript statement body.*explicit return/i);
-		assert.match(description, /Sequential example/i);
-		assert.match(description, /Parallel example/i);
-		assert.match(description, /defaultSubagentContext wins over agent defaultContext/i);
-		assert.doesNotMatch(description, /Compatibility tasks\[\]|CHAIN EXAMPLES|PARALLEL \(compatibility\)/i);
-		assert.doesNotMatch(description, /append-step|approve-checkpoint|reject-checkpoint/);
-		assert.match(description, /cannot access filesystem, shell, arbitrary Pi tools, or host globals/i);
-		assert.match(description, /exactly one non-empty title or summary/i);
-		assert.match(description, /goal may only be true and requires budget:\{tokens\}/i);
-		assert.match(description, /SAFETY-CRITICAL SUBAGENT GUIDANCE/);
-		assert.match(description, /continue independent work only until its next dependency barrier; consume the result before work that depends on it/i);
-		assert.match(description, /children\.list.*resumable\/not-resumable reasons/i);
-		assert.match(description, /Resume only rows reported resumable/i);
-		assert.match(description, /Each workflow key identifies one result lane.*new stable workflow key.*retained resume pass/i);
-		assert.match(description, /output.*not an output declaration.*outputReference.*outputPathMapping.*artifactPaths/i);
-		assert.match(description, /implementation challenge.*\{action:\"resume\", id:\"run-id\", message:\"\.\.\.\"\}/i);
-		assert.match(description, /Resume keeps the stored agent\/model\/tool contract/i);
-		assert.match(description, /Oracle\/advisor consultations should use supervisor dialogue for material unknowns when available/i);
-		assert.match(description, /same-role fallback challenge and label it as fallback/i);
-		assert.match(description, /status\.json/);
-		assert.match(description, /no per-step cwd.*workflow cwd.*outer subagent request.*cd \/path\/to\/worktree/i);
-		assert.match(description, /suffix on the model string.*off\/minimal\/low\/medium\/high\/xhigh\/max/i);
-		assert.match(description, /suffix wins over the agent's thinking default/i);
-		assert.match(description, /watchdog\.configure' and is ignored on dispatch/i);
-		assert.match(description, /lane infrastructure blocker.*explicit owner approval/i);
+	it("keeps execution, authority, evidence and recovery contracts in every built-in mode", () => {
+		for (const description of [DEFAULT_SUBAGENT_TOOL_DESCRIPTION, FULL_SUBAGENT_TOOL_DESCRIPTION, COMPACT_SUBAGENT_TOOL_DESCRIPTION]) {
+			for (const contract of [
+				/one child with \{agent,task\?\}/,
+				/Workflow script: write it as one ```js workflow block in this reply, then call subagent\(\{workflow:true,\.\.\.\}\)/,
+				/workflow:'\.\/path\.js' \(any value with '\/'\) loads a file from request cwd; other strings name a resource/,
+				/agent\/task exclude workflow; task excludes action.*agent may target management actions/,
+				/Raw-script sandboxes add deeply frozen args/,
+				/raw-script args persist as evidence, so never include secrets/,
+				/action is management\/control; validate accepts workflow:true or a path without launching/,
+				/action:"list",capabilities:true.*executable, non-disabled.*runner.available === true/,
+				/Passive PATH\/PATHEXT\/X_OK.*not authentication\/version\/launch proof/,
+				/exactly one top-level subagent workflow call with async:true/,
+				/explicit return, top-level await.*nested async function\/arrow\/method helpers are rejected/,
+				/Await runs.run.*before .output.*ordered array, not a key map/,
+				/every stored run promise with direct await, Promise.race or Promise.all/,
+				/Await\/return runs.steer\(key,message,options\?\) for a prior key, never raw run ids/,
+				/Consume results at dependency barriers/,
+				/Native async completion wakes this session.*return control.*bg_wait merely for a wake/,
+				/not for final reviews\/gates/,
+				/one writer per cwd\/worktree.*fresh-context read-only reviewers/i,
+				/output on runs.run\/runs.all, not task filename prose.*outputReference.*outputPathMapping.*artifactPaths/,
+				/children.list is workflow-only, not an exhaustive list of direct native children.*exact run id.*action:"status",id.*status identifies the candidate.*action:"resume",id,message.*authoritatively checks eligibility, may reject it.*labeled same-role fallback only when no known candidate exists or resume rejects eligibility/,
+				/latest returned runId.*distinct resume pass needs a new stable key.*identical launch parameters/,
+				/Oracle\/advisor.*supervisor dialogue/,
+				/raw scripts \(workflow:true or a path\) cannot use runs.host/,
+				/Granted commands\/relative outputs use workflow cwd, never per-step cwd/,
+				/worktree:true requires clean source.*baseRef defaults to HEAD at allocation.*named ref, never full 40\/64-character commit IDs or revision expressions/,
+				/External CLI agents support native options only when their runner declares them.*tool budget, fast, fork context/,
+				/child launch, prompt runtime, extension load or child tooling failure is a lane infrastructure blocker/,
+				/exact failure.*run\/status.*repo\/cwd\/worktree\/branch\/ref.*clean worktree.*partial diff.*same-protocol retry/,
+				/interactive_shell, pi -ne, Codex\/Claude\/Cursor CLI.*explicit owner approval/,
+				/fallback requires explicit owner approval, not Pi core's generic pi -ne hint/,
+				/Ordinary child subagents are not orchestrators.*depth\/session limits/,
+				/Before advanced orchestration.*action:"guide",topic:"workflows".*pi-subagents skill/,
+				/action:"guide",topic:"tool-reference".*controls\/evidence gates/,
+			]) assert.match(description, contract);
+		}
 	});
 
-	it("offers a compact mode that keeps the two-tier contract and safety guidance", () => {
-		const description = buildSubagentToolDescription({ toolDescriptionMode: "compact" });
-		assert.equal(description, COMPACT_SUBAGENT_TOOL_DESCRIPTION);
-		assert.match(description, /^Run one child with \{ agent, task\? \}; use \{ workflowScript \} for inline orchestration or \{ workflowScriptPath \}/i);
-		assert.match(description, /workflowScriptPath:"workflows\/review\.js".*request cwd.*sandbox/i);
-		assert.match(description, /SINGLE .*starts exactly one direct child/i);
-		assert.match(description, /runs\.run for one child and await runs\.all.*ordinary parallel work/i);
-		assert.match(description, /runs\.lanes\(\[\{key,stages:.*later stages sequence per lane/i);
-		assert.match(description, /do not read \.output from unawaited runs\.run launches/i);
-		assert.match(description, /runs\.steer\(key,message,options\?\).*prior keyed child/i);
-		assert.match(description, /never accepts a raw run id/i);
-		assert.match(description, /repository mutation lanes.*worktree:true.*runs\.run\/runs\.all.*managed isolation/i);
-		assert.doesNotMatch(description, /tasks\[\]|chain\[\]/i);
-		assert.match(description, /ordinary async subagents notify this session natively.*return control.*do not call bg_wait/i);
-		assert.match(description, /bg_wait only for provider, detached, or other background work without a native notification/i);
-		assert.match(description, /continue independent work only until its next dependency barrier; consume the result before work that depends on it/i);
-		assert.match(description, /children\.list.*resume only rows reported resumable/i);
-		assert.match(description, /Each workflow key identifies one result lane.*new stable workflow key.*retained resume pass/i);
-		assert.match(description, /output.*not an output declaration.*outputReference.*outputPathMapping.*artifactPaths/i);
-		assert.match(description, /\{action:\"resume\",id:\"run-id\",message:\"\.\.\.\"\} for a simple follow-up or challenge/i);
-		assert.match(description, /resume keeps the stored agent\/model\/tool contract/i);
-		assert.match(description, /Oracle\/advisor consultations use available supervisor dialogue/i);
-		assert.match(description, /same-role fallback challenge and label it as fallback/i);
-		assert.match(description, /exactly one non-empty title or summary/i);
-		assert.match(description, /goal may only be true and requires budget:\{tokens\}/i);
-		assert.match(description, /no per-step cwd.*workflow cwd.*outer subagent request.*cd \/path\/to\/worktree/i);
-		assert.match(description, /Per-run thinking is a suffix on the model string.*off\/minimal\/low\/medium\/high\/xhigh\/max/i);
-		assert.match(description, /suffix wins over the agent's thinking default/i);
-		assert.match(description, /watchdog\.configure' and is ignored on dispatch/i);
-		assert.match(description, /lane infrastructure blocker.*explicit owner approval/i);
-		assert.ok(description.length < FULL_SUBAGENT_TOOL_DESCRIPTION.length);
+	it("keeps full mode supplemental details and moves recipes to shipped guides", () => {
+		assert.equal(buildSubagentToolDescription({ toolDescriptionMode: "full" }), FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(buildSubagentToolDescription({ toolDescriptionMode: "compact" }), COMPACT_SUBAGENT_TOOL_DESCRIPTION);
+		assert.ok(COMPACT_SUBAGENT_TOOL_DESCRIPTION.length < FULL_SUBAGENT_TOOL_DESCRIPTION.length);
+		assert.match(FULL_SUBAGENT_TOOL_DESCRIPTION, /runs.lanes.*structuredOutput.verdict === 'blocked'.*never reviewer prose/);
+		assert.match(FULL_SUBAGENT_TOOL_DESCRIPTION, /mission:false.*state.get.*state.set/);
+		const workflows = fs.readFileSync(path.join(projectRoot, "docs/workflows.md"), "utf8");
+		const reference = fs.readFileSync(path.join(projectRoot, "docs/tool-reference.md"), "utf8");
+		for (const heading of ["Parallel sequential lanes", "Host command steps", "Advanced rolling child runs", "Worktree isolation"]) assert.ok(workflows.includes(heading));
+		for (const heading of ["Acceptance gates", "Retained children", "Management actions", "Workflow steering"]) assert.ok(reference.includes(heading));
+		assert.match(reference, /JSON-encoded object strings/);
 	});
 
 	it("renders a custom project description with placeholders and mandatory safety guidance", () => {
@@ -286,6 +278,8 @@ describe("registered subagent tool description", () => {
 		writeExtensionConfig(defaultAgentDir, {});
 		const defaultTool = readRegisteredTool(defaultAgentDir);
 		assert.equal(defaultTool.description, FULL_SUBAGENT_TOOL_DESCRIPTION);
+		assert.equal(defaultTool.properties.includes("step"), false);
+		assert.doesNotMatch(defaultTool.description, /append-step|approve-checkpoint|reject-checkpoint/);
 		assert.equal(defaultTool.promptSnippet, undefined);
 		assert.equal(defaultTool.promptGuidelines, undefined);
 
@@ -318,11 +312,4 @@ describe("registered subagent tool description", () => {
 		writeExtensionConfig(invalidAgentDir, { toolDescriptionMode: "tiny" });
 		assert.equal(readRegisteredTool(invalidAgentDir).description, FULL_SUBAGENT_TOOL_DESCRIPTION);
 	});
-
-	it("registers the trimmed schema and description by default", () => {
-		const agentDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagents-tool-desc-trimmed-"));
-		const tool = readRegisteredTool(agentDir);
-		assert.equal(tool.properties.includes("step"), false);
-		assert.doesNotMatch(tool.description, /append-step|approve-checkpoint|reject-checkpoint/);
-	});
 });