@arhen/pi-core-subagent 1.3.62 → 1.3.64

package/README.md

@@ -317,6 +317,21 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 
 > **Ask urgency:** `ask_parent` takes `urgent` (default `false`). Both variants steer into the leader's current turn so the question is never deferred to the end of a long turn. `[URGENT]` tells the leader to answer before its next step; `[not urgent]` tells it that the child keeps waiting, so it may finish its current step first. Failures steer for the same reason; completions and aborts queue as follow-ups.
 
+## Tool exposure and opt-in codemode
+
+Default: **legacy direct calls**, even when the codemode tool is active. Active helpers remain
+model-visible and retain native script-call compatibility. Explicit global `codemode.mode: "only"`
+still applies Pi\'s global script-only policy; this extension does not override it.
+
+- `/subagents mode` — show preference and effective profile.
+- `/subagents mode auto` — opt in to script-based routing while codemode is active; direct otherwise.
+- `/subagents mode codemode` — explicitly select script-based routing (direct fallback when unavailable).
+- `/subagents mode direct` — return to legacy direct behavior.
+
+Choice is stored per session branch. New sessions/branches without a preference start direct;
+existing explicit choices remain intact. Published 1.3.63 defaulted to `auto`: this compatibility
+correction requires the corrected source/package, not a retroactive change to that npm release.
+
 ## Commands
 
 - `/subagents` — list runs; `/subagents peek` (or `ctrl+shift+a`) — browsable pane

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.62",
+	"version": "1.3.64",
 	"type": "module",
 	"description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
 	"license": "MIT",

package/src/format.ts

@@ -248,8 +248,8 @@ export function makeTaskNotice(run: RunSnapshot, task: TaskSnapshot, kind: strin
 		isStartupFailure(task, kind)
 			? "Never started — stop and diagnose before spawning anything else: a config-level error (model, plan, auth, agent file) fails identically on every respawn."
 			: kind === "completed"
-				? `Use subagent_result(runId: "${run.id}", taskId: "${task.id}") for full output.`
-				: `Session file kept — resume_subagent(runId: "${run.id}", taskId: "${task.id}", model?: ...) revives it with full context. subagent_result for what it produced so far.`,
+				? `Use subagent_result({ runId: "${run.id}", taskId: "${task.id}" }) for full output.`
+				: `Session file kept — resume_subagent({ runId: "${run.id}", taskId: "${task.id}", model?: ... }) revives it with full context. subagent_result for what it produced so far.`,
 	].join("\n");
 }
 export function makeAskNotice(
@@ -257,7 +257,7 @@ export function makeAskNotice(
 	extra: { taskId?: string; agent?: string; question?: string; urgent?: boolean },
 ): string {
 	const who = extra.agent ? `${extra.agent} (${extra.taskId ?? "task"})` : (extra.taskId ?? "a subagent");
-	const reply = `reply_subagent(runId: "${run.id}", taskId: "${extra.taskId ?? ""}", message: ...)`;
+	const reply = `reply_subagent({ runId: "${run.id}", taskId: "${extra.taskId ?? ""}", message: ... })`;
 	return extra.urgent
 		? `[URGENT] Subagent ${who} is blocked and cannot continue until you answer: ${extra.question ?? ""}\nAnswer now, before your next step, with ${reply}.`
 		: `[not urgent] Subagent ${who} asks: ${extra.question ?? ""}\nIt waits while you keep working — finish your current step first if you want, then answer with ${reply}.`;
@@ -270,7 +270,7 @@ export function makeNotice(run: RunSnapshot, kind: string): string {
 	for (const task of run.tasks) {
 		lines.push(`- ${task.agent}: ${task.status}${task.error ? ` — ${truncateText(task.error, 200)}` : ""}`);
 	}
-	lines.push(`Use subagent_result(runId: "${run.id}") for full output.`);
+	lines.push(`Use subagent_result({ runId: "${run.id}" }) for full output.`);
 	return lines.join("\n");
 }
 

package/src/index.ts

@@ -1,5 +1,6 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
+import type { TSchema } from "typebox";
 import {
 	compactLines,
 	formatUsage,
@@ -13,6 +14,7 @@ import { waveNotation } from "./graph.ts";
 import { cloneRun, type ParkedMsg, SubagentManager } from "./manager.ts";
 import { listSelectableModels } from "./models.ts";
 import { createPeekPane, type PeekTask } from "./peek.ts";
+import { type AnyToolDefinition, createPresentation, isSubagentMode } from "./presentation.ts";
 import {
 	AwaitParam,
 	ModelsParam,
@@ -29,6 +31,13 @@ import { cleanupMerged, ownerAlive, reapDeadWorktrees, repoRoot, sweepStale } fr
 
 export default function (pi: ExtensionAPI) {
 	const manager = new SubagentManager(pi);
+	const definitions: AnyToolDefinition[] = [];
+	const presentation = createPresentation(pi, definitions);
+	const defineTool = <TParams extends TSchema, TDetails = unknown, TState = any>(
+		definition: ToolDefinition<TParams, TDetails, TState>,
+	): void => {
+		definitions.push(definition as AnyToolDefinition);
+	};
 
 	const openPeek = async (ctx: ExtensionContext) => {
 		if (!ctx.hasUI) return;
@@ -65,11 +74,30 @@ export default function (pi: ExtensionAPI) {
 	};
 	pi.registerCommand("subagents", {
 		description:
-			"List subagent runs. `/subagents peek` opens the browsable pane; `/subagents auto-limit on|off` toggles the 1 h default runtime ceiling (default off = 6 h).",
+			"List subagent runs. `/subagents peek` opens the browsable pane; `/subagents mode [auto|direct|codemode]` reports or switches the tool exposure profile; `/subagents auto-limit on|off` toggles the 1 h default runtime ceiling (default off = 6 h).",
 		handler: async (args, ctx) => {
 			const arg = String(args ?? "")
 				.trim()
 				.toLowerCase();
+			if (arg === "mode" || arg.startsWith("mode ")) {
+				const value = arg.split(/\s+/)[1];
+				if (value === undefined) {
+					ctx.ui.notify(presentation.describe(), "info");
+				} else if (isSubagentMode(value)) {
+					presentation.setPreference(value);
+					// A switch during a streaming turn or an executing script would rewrite the loadout under
+					// a live call; defer it to the next request boundary in that case.
+					const idle = typeof ctx.isIdle === "function" ? ctx.isIdle() : true;
+					if (idle) presentation.sync();
+					ctx.ui.notify(
+						`Subagent exposure mode set to ${value}${idle ? "." : " — applies at the next request boundary."} ${presentation.describe()}`,
+						"info",
+					);
+				} else {
+					ctx.ui.notify(`Unknown subagent mode "${value}". Use \`/subagents mode auto|direct|codemode\`.`, "warning");
+				}
+				return;
+			}
 			if (arg === "peek") return openPeek(ctx);
 			if (arg === "auto-limit" || arg.startsWith("auto-limit ")) {
 				const value = arg.split(/\s+/)[1];
@@ -103,8 +131,19 @@ export default function (pi: ExtensionAPI) {
 		manager.turnActivity = false;
 	});
 
+	pi.on("before_agent_start", () => {
+		presentation.sync();
+	});
+	// Successive model turns of the same run are safe boundaries too: a codemode availability or
+	// helper-selection change made between turns must reach the next request without a new prompt.
+	pi.on("turn_start", () => {
+		presentation.sync();
+	});
+
 	pi.on("session_start", async (_event, ctx) => {
 		await manager.restoreFromSidecar(ctx);
+		presentation.restore(ctx);
+		presentation.sync();
 
 		const roots = new Set<string>();
 		const cwdRoot = repoRoot(ctx.cwd);
@@ -125,6 +164,11 @@ export default function (pi: ExtensionAPI) {
 			} catch {}
 		}
 	});
+	pi.on("session_tree", (_event, ctx) => {
+		presentation.restore(ctx);
+		presentation.sync();
+	});
+
 	pi.on("session_shutdown", async (_event, ctx) => {
 		if (ctx?.hasUI) {
 			try {
@@ -134,11 +178,11 @@ export default function (pi: ExtensionAPI) {
 		manager.clearRuns();
 	});
 
-	pi.registerTool<typeof ModelsParam, ModelCatalog>({
+	defineTool<typeof ModelsParam, ModelCatalog>({
 		name: "subagent_models",
 		label: "Subagent Models",
 		description:
-			"List the models a subagent task may name, each with the exact `model` value to pass. The list is scoped to this session's enabled models when scoping is configured (the same set `/scoped-models` shows); when no scoping is configured, every model with usable credentials is listed and the output says so. Each entry includes its context window and pi catalog price per million tokens, and the thinking levels the runtime honors — a level shown here is not silently clamped. References shown here are safe to pass; ambiguous ones are called out. Naming a model is optional: omit `model` to inherit the session model, or call this when choosing one.",
+			"List the models a subagent task may name: the exact `model` value to pass, the thinking levels the runtime honors, the context window and catalog price. Scoped to this session's models when scoping is configured, else every usable model; ambiguous references are called out. Full reference: `describeNamespace('subagents')`.",
 		promptSnippet: "List the models a subagent task can name (reference, thinking levels, context, price).",
 		parameters: ModelsParam,
 		async execute(_id, _params, _signal, _onUpdate, ctx) {
@@ -146,26 +190,24 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof SubagentParams, RunDetails>({
+	defineTool<typeof SubagentParams, RunDetails>({
 		name: "subagent",
 		label: "Subagent",
 
 		description:
-			"Run isolated subagents (own context, own session) in the background: returns a runId immediately, completion notifies you. One call = one agent (`agent`+`task`) or many (`tasks`, or `chain` with `{previous}`). `needs` edges gate tasks and prepend upstream outputs to their prompts. A user agent file (`.agents/agents`, `.claude/agents`, `.pi/agents`; project dirs, then home) whose `description` matches the goal is authoritative: body = system prompt, frontmatter `model`/`tools` apply, but explicit per-call `tools`/`write` override the file's tools. Write agents get an isolated git worktree; the result reports the branch. Children always carry talk tools (ask/notify the leader, message siblings).",
+			"Run isolated subagents (own context/session) in the background; returns a runId and completion notifies you. One call = one agent (`agent`+`task`) or many (`tasks`, `chain`, or `needs` edges that gate tasks and prepend upstream output). Write tasks use an isolated git worktree and report a branch; a matching agent file is authoritative (matched by description, body/model win). Full reference: `describeNamespace('subagents')`.",
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
 			"`model` is optional: omit it to inherit your current session model, or name one (agent-file `model` frontmatter wins) to pin the run. Call subagent_models for the exact references, thinking levels, and prices this session may use.",
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
 			"Batch every sub-task in ONE call: subagent({ tasks: [...] }) — never multiple parallel subagent calls.",
 			"Declare ordering with `needs` edges on the tasks, never by splitting into separate calls; dependents receive upstream outputs automatically — do not restate them. Prefer flat `tasks` (plain parallel); add `needs` only when ordering genuinely matters.",
+			"Define each agent inline: invented name, focused system prompt, read-only by default (write:true to edit). Agent files are matched by description/goal, not name; a match is authoritative (body/model), and only per-call tools/write override its tools.",
+			"Write agents work in an isolated git worktree; review the branch diff and merge with `git merge --no-ff <branch>` when done.",
+			"After spawning, call subagent_status({ runId }) ONCE to confirm the tasks started; fix or respawn a task that died on spawn.",
 			"End each task with a runnable check, e.g. 'Verify: bun test'. A subagent's claim of success is not evidence.",
-			"Write agents work in an isolated git worktree; their changes land on a branch — review the diff, then merge with `git merge --no-ff <branch>`. Never leave a worktree branch unmerged at the end of the task.",
-			"Define each agent inline: invented name, focused system prompt, read-only by default (write:true to edit). A matched agent file takes over (see description); matching is by description, not name — name the agent whatever fits the goal.",
-			"Right after spawning, call subagent_status(runId) ONCE before any other work — a child that died on spawn (or never started) is invisible until far later otherwise. If it shows a task failed/never started, fix or respawn immediately.",
-			"Never block with nothing to do: if you have no work left after spawning, end your turn — completion notifies you and wakes a fresh turn with the results. await_subagent/autoAwait while idle only burns time and tokens.",
-			"A failed task interrupts you immediately as a steering message — handle it in the same turn (resume, swap model, re-dispatch) instead of finishing the plan on a broken intermediate result. Completes and aborts queue as follow-ups.",
-			"autoAwait:true only when this SAME turn must consume the result immediately. await_subagent is for syncing with your own parallel work — not the default follow-up to a spawn.",
-			"A task that failed mid-work (provider error, rate limit, timeout) keeps its session file and branch: resume_subagent(runId, taskId, model?) revives it with full context — prefer that over respawning. Respawn only when it never started (no session file).",
+			"When you have no work left, end your turn — completion notifies you. await_subagent/autoAwait only when this turn must consume the result immediately.",
+			"A failed task keeps its session file and branch: resume_subagent({ runId, taskId }) revives it; respawn only when it never started.",
 		],
 		parameters: SubagentParams,
 		executionMode: "parallel",
@@ -195,7 +237,7 @@ export default function (pi: ExtensionAPI) {
 						? `\n${asks.length} child(ren) waiting for your answer:\n${asks
 								.map(
 									(a) =>
-										`- ${a.agent} (${a.taskId}): ${a.text}\n  reply_subagent(runId: "${run.id}", taskId: "${a.taskId}", message: ...)`,
+										`- ${a.agent} (${a.taskId}): ${a.text}\n  reply_subagent({ runId: "${run.id}", taskId: "${a.taskId}", message: ... })`,
 								)
 								.join("\n")}\nAnswer each, then await_subagent again for the result.`
 						: "",
@@ -208,7 +250,7 @@ export default function (pi: ExtensionAPI) {
 				content: [
 					{
 						type: "text",
-						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nNext: call subagent_status("${details.run.id}") now to confirm the tasks actually started before doing anything else.\nAfter that, completion will notify you — if you have no other work, end your turn instead of waiting.\nOther tools: subagent_result / reply_subagent / steer_subagent / resume_subagent / subagent_cancel.`,
+						text: `Background run started: ${details.run.id} (${details.run.mode}, ${details.run.tasks.length} task${details.run.tasks.length > 1 ? "s" : ""}).\nNext: call subagent_status({ runId: "${details.run.id}" }) now to confirm the tasks actually started before doing anything else.\nAfter that, completion will notify you — if you have no other work, end your turn instead of waiting.\nOther tools: subagent_result / reply_subagent / steer_subagent / resume_subagent / subagent_cancel.`,
 					},
 				],
 				details,
@@ -282,11 +324,11 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof RunIdParam, { run?: RunSnapshot }>({
+	defineTool<typeof RunIdParam, { run?: RunSnapshot }>({
 		name: "subagent_status",
 		label: "Subagent Status",
 		description:
-			"Live per-task status of a subagent run (non-blocking), incl. each child's session file path (JSONL) to `tail -f` from outside. Call once right after spawning to verify children actually started.",
+			"Live per-task status of a subagent run (non-blocking), incl. each child's session file path to `tail -f`. Call once right after spawning to verify children actually started.",
 		promptSnippet: "Check progress of a subagent run; use right after spawn as a health check.",
 		parameters: RunIdParam,
 		async execute(_id, params) {
@@ -303,7 +345,7 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof ResultParam, { run?: RunSnapshot }>({
+	defineTool<typeof ResultParam, { run?: RunSnapshot }>({
 		name: "subagent_result",
 		label: "Subagent Result",
 		description: "Full result (finalText + usage) of a run or one task. Non-blocking.",
@@ -330,11 +372,11 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof AwaitParam, { run?: RunSnapshot }>({
+	defineTool<typeof AwaitParam, { run?: RunSnapshot }>({
 		name: "await_subagent",
 		label: "Await Subagent",
 		description:
-			"Block until a run finishes (or timeoutMs elapses). Only when you have your own work to sync — otherwise end your turn; completion notifies you. While parked, child→leader messages (asks, notifies, completions) wake the wait and arrive inside the result.",
+			"Block until a run finishes (or timeoutMs elapses). Only when you have your own work to sync; otherwise end your turn. Child messages that arrive while parked wake the wait and are returned.",
 		parameters: AwaitParam,
 		async execute(_id, params) {
 			const { runId, timeoutMs } = params as { runId: string; timeoutMs?: number };
@@ -352,7 +394,7 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof ReplyParam, { run?: RunSnapshot }>({
+	defineTool<typeof ReplyParam, { run?: RunSnapshot }>({
 		name: "reply_subagent",
 		label: "Reply Subagent",
 		description: "Answer a child's ask_parent question; resumes its run.",
@@ -373,7 +415,7 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof SteerParam, { steered?: string[] }>({
+	defineTool<typeof SteerParam, { steered?: string[] }>({
 		name: "steer_subagent",
 		label: "Steer Subagent",
 		description:
@@ -400,11 +442,11 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof ResumeParam, { run?: RunSnapshot }>({
+	defineTool<typeof ResumeParam, { run?: RunSnapshot }>({
 		name: "resume_subagent",
 		label: "Resume Subagent",
 		description:
-			"Revive a failed/aborted task in its original session (full context + worktree branch preserved). Optional `model` swaps provider (e.g. after a rate limit); optional `thinking` sets the effort — the stored level is clamped to what the target model accepts, so a resume never dies on an unsupported effort; optional `message` replaces the default 'recap and continue' prompt. Refuses tasks that never started — respawn those.",
+			"Revive a failed/aborted task in its original session (full context + worktree branch preserved). Optional `model` swaps provider after e.g. a rate limit; `thinking` is clamped to the target model; `message` replaces the default recap prompt. Refuses tasks that never started — respawn those.",
 		parameters: ResumeParam,
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const { runId, taskId, message, model, thinking } = params as {
@@ -421,7 +463,7 @@ export default function (pi: ExtensionAPI) {
 				content: [
 					{
 						type: "text",
-						text: `Resumed ${runId}/${taskId} (${res.task.agent})${model ? ` on ${model}` : ""} from ${res.task.sessionFile}${res.task.branch ? `, branch ${res.task.branch}` : ""}.${res.note ? ` Adjusted ${res.note}.` : ""}\nNext: subagent_status("${runId}") to confirm it is running; completion will notify you.`,
+						text: `Resumed ${runId}/${taskId} (${res.task.agent})${model ? ` on ${model}` : ""} from ${res.task.sessionFile}${res.task.branch ? `, branch ${res.task.branch}` : ""}.${res.note ? ` Adjusted ${res.note}.` : ""}\nNext: subagent_status({ runId: "${runId}" }) to confirm it is running; completion will notify you.`,
 					},
 				],
 				details: { run: run ? cloneRun(run) : undefined },
@@ -429,7 +471,7 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerTool<typeof RunIdParam, { aborted?: number }>({
+	defineTool<typeof RunIdParam, { aborted?: number }>({
 		name: "subagent_cancel",
 		label: "Subagent Cancel",
 		description: "Abort a running/queued subagent run. Children are killed; run becomes aborted.",
@@ -446,4 +488,6 @@ export default function (pi: ExtensionAPI) {
 			};
 		},
 	});
+
+	presentation.registerInitial();
 }

package/src/manager.ts

@@ -63,6 +63,9 @@ import {
 	type Worktree,
 } from "./worktree.ts";
 
+/** Legacy callers import the resolver from here; its owner is `models.ts`. */
+export { resolveChildModel };
+
 export const DEFAULT_CONCURRENCY = 3;
 export const MAX_CONCURRENCY = 8;
 const DEFAULT_RUNTIME_MS = 3_600_000;

package/src/presentation.ts

@@ -0,0 +1,209 @@
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolDefinition,
+	ToolExposure,
+	ToolLoadout,
+	ToolLoadoutChanges,
+	ToolNamespace,
+} from "@earendil-works/pi-coding-agent";
+
+/**
+ * Presentation preference for the subagent toolset.
+ * - auto: native codemode presentation when the codemode tool is active, direct otherwise.
+ * - direct (default): legacy native declarations and active-tool script callability.
+ * - codemode: subagent tools are callable from codemode scripts but not declared or listed.
+ */
+export type SubagentMode = "auto" | "direct" | "codemode";
+export type EffectiveMode = "direct" | "codemode";
+
+/** Branch-scoped custom entry holding the preference, so resume/tree keep it. */
+export const MODE_ENTRY_TYPE = "subagent-mode";
+export const CODEMODE_TOOL_NAME = "codemode";
+
+export const SUBAGENT_NAMESPACE: ToolNamespace = {
+	name: "subagents",
+	description: "Isolated background subagents with a dependency-graph scheduler, git-worktree isolation and intercom.",
+	instructions: `Isolated subagents with their own context, session and optional git worktree. Delegate independent review, testing, research or parallel analysis.
+
+## Modes
+- direct (default): legacy native tool declarations and active-tool script callability; activating codemode alone does not switch profiles.
+- auto (opt-in): codemode presentation while the \`codemode\` tool is active, direct otherwise.
+- codemode: active tools are callable from scripts but not declared; inactive tools stay model-only and are not callable at all.
+Switch with \`/subagents mode auto|direct|codemode\`. The preference is stored on the session branch and restored on reload, resume and tree navigation.
+
+## Operations
+Object arguments, exactly as validated when issued by the model:
+- \`subagent({ agent, task, prompt?, write?, tools?, model?, thinking?, cwd?, maxRuntimeMs?, autoAwait?, notifyPerTask? })\` runs one agent; \`tasks: [...]\`, \`chain: [...]\` with \`{previous}\` and \`needs\` edges gate tasks and prepend upstream output.
+- \`subagent_models()\` lists the models a task may name: the exact \`model\` value to pass, the thinking levels the runtime honors, the context window and pi catalog price per million tokens. The list follows this session's scoped models when scoping is configured, else every usable model; the output states which case applies, and references that would resolve to another model are called out as ambiguous.
+- \`subagent_status({ runId })\` returns live per-task status and session file paths; call once right after spawning.
+- \`subagent_result({ runId, taskId? })\` returns final text, usage and the worktree branch/diff summary.
+- \`await_subagent({ runId, timeoutMs? })\` blocks only when this turn must consume the result.
+- \`reply_subagent({ runId, taskId, message })\` answers a child \`ask_parent\` question and resumes it.
+- \`steer_subagent({ runId, taskId?, message })\` injects a message into running tasks.
+- \`resume_subagent({ runId, taskId, message?, model?, thinking? })\` revives a failed/aborted task with its context and branch.
+- \`subagent_cancel({ runId })\` aborts the run and kills its children.
+
+## Agents
+- Define each agent inline: invented name, focused system prompt. Agent files (\`.agents/agents\`, \`.claude/agents\`, \`.pi/agents\`; project dirs, then home) are matched by \`description\` against the goal, never by name. A match is authoritative: its body is the system prompt, its \`model\` frontmatter wins over the inline value, and its \`tools\` apply — only the per-call \`tools\` and \`write\` override them.
+- Agents are read-only by default; \`write: true\` gives an isolated git worktree branch. Review the diff and merge with \`git merge --no-ff <branch>\`.
+- \`model\` is optional: omit it to inherit the session model, or name one from \`subagent_models\` to pin the run.
+
+## Rules
+- Batch every sub-task in ONE call with \`tasks\`/\`needs\`; do not split parallel work into separate calls.
+- After spawning, call \`subagent_status({ runId })\` once to confirm the tasks started; fix or respawn a task that died on spawn.
+- A task that failed mid-work keeps its session file and branch: \`resume_subagent({ runId, taskId })\`, model swap included, revives it; respawn only a task that never started.
+- Completion and failures notify you: end the turn when you have no work left; use \`autoAwait\` only when the same turn must consume the result.
+- End each task with a runnable check, e.g. 'Verify: bun test'. A subagent's claim of success is not evidence.
+
+## Codemode
+When the codemode profile is explicitly selected (or selected by opt-in auto), these tools are not declared. Call an active operation as \`tools.<name>(args)\`; spawning uses \`await tools.subagent(args)\`. If its signature is unknown, inspect only \`text(await describeTool('subagent'))\` once and reuse it. For another operation, inspect only its exact name when needed. Broad search and tool-list dumps are unnecessary for these known names; this namespace is the optional full reference. Inactive tools remain unavailable. Arguments are validated exactly like model-issued calls.`,
+};
+
+/** Adds the script-call path to the upfront rules, but only in the codemode profile. */
+export const CODEMODE_DISCOVERY_GUIDELINE =
+	"Codemode subagents: call active tools as tools.<name>(args); spawn with await tools.subagent(args). If its signature is unknown, inspect only text(await describeTool('subagent')) once, then reuse it. Other helpers: describeTool(exactName) only when needed. No broad search or tool-list dump required; describeNamespace('subagents') is optional full reference.";
+
+/** The full-reference pointer only resolves while codemode scripts can reach `describeNamespace`. */
+const NAMESPACE_REFERENCE = / Full reference: `describeNamespace\('subagents'\)`\./;
+
+export function isSubagentMode(value: unknown): value is SubagentMode {
+	return value === "auto" || value === "direct" || value === "codemode";
+}
+
+export type AnyToolDefinition = ToolDefinition<any, any, any>;
+
+export interface Presentation {
+	readonly preference: SubagentMode;
+	/** The profile currently registered, or undefined before the first registration. */
+	readonly applied: EffectiveMode | undefined;
+	/** Effective mode for the given active set, defaulting to the session's live active tools. */
+	effective(active?: readonly string[]): EffectiveMode;
+	/** Report preference, effective mode and codemode availability. */
+	describe(): string;
+	setPreference(mode: SubagentMode): void;
+	/** Restore the latest preference stored on the session branch. */
+	restore(ctx: ExtensionContext): void;
+	/** Register the tools for the current effective mode; no-op when already applied. */
+	sync(): boolean;
+	/** Initial registration during extension load, before any session state exists. */
+	registerInitial(): void;
+}
+
+/**
+ * Owns the subagent exposure profile. Tools stay registered while only their exposure changes, so
+ * the active selection (and the running manager) is preserved across mode switches.
+ */
+export function createPresentation(pi: ExtensionAPI, definitions: readonly AnyToolDefinition[]): Presentation {
+	const ownNames = (): string[] => definitions.map((definition) => definition.name);
+	let preference: SubagentMode = "direct";
+	let applied: EffectiveMode | undefined;
+	let appliedOwn = new Set<string>();
+
+	const codemodeActive = (active: readonly string[]): boolean => active.includes(CODEMODE_TOOL_NAME);
+	const effectiveFrom = (active: readonly string[]): EffectiveMode =>
+		preference !== "direct" && codemodeActive(active) ? "codemode" : "direct";
+	const sameSet = (a: ReadonlySet<string>, b: ReadonlySet<string>): boolean =>
+		a.size === b.size && [...a].every((name) => b.has(name));
+
+	// Hides only the declarations of active subagent tools; other tools keep their loadout. Runs on
+	// every loadout recompute, so it follows the registered profile: a preference that is only
+	// pending (mid-stream) must not rewrite a live loadout.
+	const hideDeclarations = (loadout: ToolLoadout): ToolLoadoutChanges | undefined => {
+		if (applied !== "codemode") return undefined;
+		const active = new Set(loadout.declared.map((tool) => tool.name));
+		const hidden = definitions.map((definition) => definition.name).filter((name) => active.has(name));
+		return hidden.length > 0 ? { hiddenDeclarations: hidden } : undefined;
+	};
+
+	// Opted-in codemode defers only active own tools; inactive tools stay model-only. Legacy direct
+	// callability follows native activation. Re-registering
+	// must not reactivate a tool the user deactivated, so `defaultActive: false` replaces the native
+	// default once the initial registration has made the tools available by default.
+	const register = (mode: EffectiveMode, ownActive: ReadonlySet<string>, initial = false): void => {
+		const own = new Set(ownNames());
+		applied = mode;
+		for (const definition of definitions) {
+			const scriptCallable = mode === "codemode" && ownActive.has(definition.name);
+			const exposure: ToolExposure = scriptCallable ? "deferred" : mode === "direct" ? "direct" : "model-only";
+			const promptGuidelines = [...(definition.promptGuidelines ?? [])];
+			if (scriptCallable && !promptGuidelines.includes(CODEMODE_DISCOVERY_GUIDELINE))
+				promptGuidelines.push(CODEMODE_DISCOVERY_GUIDELINE);
+			// Legacy direct tools stay ungrouped; the namespace reference only belongs to the opted-in profile.
+			const description =
+				mode === "direct" ? definition.description.replace(NAMESPACE_REFERENCE, "") : definition.description;
+			pi.registerTool({
+				...definition,
+				description,
+				exposure,
+				namespace: mode === "codemode" ? SUBAGENT_NAMESPACE : undefined,
+				promptGuidelines,
+				prepareLoadout: hideDeclarations,
+				...(initial ? {} : { defaultActive: false }),
+			} as AnyToolDefinition);
+		}
+		// With an explicit --tools/defaultTools allowlist the SDK force-activates every registered
+		// declarable tool it names, ignoring `defaultActive`. Restore exactly the own-name membership
+		// that was asked for; every unrelated name, including a newly registered one, is preserved.
+		if (!initial) {
+			const active = pi.getActiveTools();
+			if (active.some((name) => own.has(name) && !ownActive.has(name)))
+				pi.setActiveTools(active.filter((name) => !own.has(name) || ownActive.has(name)));
+		}
+		appliedOwn = new Set(ownActive);
+	};
+
+	return {
+		get preference() {
+			return preference;
+		},
+		get applied() {
+			return applied;
+		},
+		effective: (active = pi.getActiveTools()) => effectiveFrom(active),
+		describe() {
+			const active = pi.getActiveTools();
+			const target = effectiveFrom(active);
+			const shown = applied ?? target;
+			const available = codemodeActive(active);
+			const availability = available ? "codemode is active" : "codemode is not active";
+			const fallback = !available && preference === "codemode" ? "; using direct fallback" : "";
+			const pending = target !== shown ? `; pending ${target} at the next request boundary` : "";
+			return `Subagent exposure: mode ${preference} → effective ${shown} (${availability}${fallback}${pending}). Use /subagents mode auto|direct|codemode.`;
+		},
+		setPreference(mode) {
+			preference = mode;
+			pi.appendEntry(MODE_ENTRY_TYPE, { mode });
+		},
+		restore(ctx) {
+			let restored: SubagentMode | undefined;
+			for (const entry of ctx.sessionManager.getBranch()) {
+				const candidate = entry as { type?: string; customType?: string; data?: { mode?: unknown } };
+				if (
+					candidate.type === "custom" &&
+					candidate.customType === MODE_ENTRY_TYPE &&
+					isSubagentMode(candidate.data?.mode)
+				)
+					restored = candidate.data.mode;
+			}
+			// Branch-sensitive state: a branch without an entry uses the package default again.
+			preference = restored ?? "direct";
+		},
+		sync() {
+			const own = new Set(ownNames());
+			const active = pi.getActiveTools();
+			const next = effectiveFrom(active);
+			const ownActive = new Set(active.filter((name) => own.has(name)));
+			// Members inside a profile are part of the registration: a helper activated or deactivated
+			// natively must change its exposure (deferred vs model-only) at the next boundary.
+			if (next === applied && sameSet(ownActive, appliedOwn)) return false;
+			register(next, ownActive);
+			return true;
+		},
+		registerInitial() {
+			// Before the session runtime exists `pi.getActiveTools()` is not bound; the optimistic
+			// all-active set is corrected by `sync()` once the session starts.
+			register("direct", new Set(ownNames()), true);
+		},
+	};
+}

package/src/schemas.ts

@@ -19,7 +19,8 @@ const TaskItem = Type.Object({
 	prompt: Type.Optional(Type.String({ description: "System prompt defining this agent's behavior" })),
 	write: Type.Optional(
 		Type.Boolean({
-			description: "true = write toolset (adds bash, edit, write); default false = read-only (read, grep, find, ls)",
+			description:
+				"true = write toolset (adds bash, edit, write); default false = read-only (read, grep, find, ls, codemode)",
 		}),
 	),
 	model: Type.Optional(