@selesai/code 0.13.40 → 0.14.3

package/dist/extensions/pi-subagents/src/extension/tool-activation.ts

@@ -0,0 +1,146 @@
+import type { ExtensionAPI, ExtensionContext, ToolDefinition } from "@selesai/code";
+import { Type } from "typebox";
+import { MODEL_ONLY_TOOL } from "../shared/extension-context.ts";
+import type { ToolActivationMode } from "../shared/types.ts";
+
+interface ActivationDetails {
+	enabled?: string[];
+	missing?: string[];
+	unavailable?: string[];
+}
+
+const LOADER_NAME = "subagents_enable";
+const SUBAGENT_NAME = "subagent";
+let warnedUnsupportedHost = false;
+
+type ToolSelectionMessage = {
+	role: string;
+	toolsAdded?: readonly { name: string }[];
+	toolsRemoved?: readonly { name: string }[];
+};
+
+function hasNativeToolSelection(messages: readonly ToolSelectionMessage[]): boolean {
+	return messages.some((message) => message.role === "system"
+		&& (Object.hasOwn(message, "toolsAdded") || Object.hasOwn(message, "toolsRemoved")));
+}
+
+function setSelection(pi: ExtensionAPI, includeSubagent: boolean, includeLoader: boolean): void {
+	const next = pi.getActiveTools().filter((name) => (includeSubagent || name !== SUBAGENT_NAME) && (includeLoader || name !== LOADER_NAME));
+	if (includeSubagent) next.push(SUBAGENT_NAME);
+	if (includeLoader) next.push(LOADER_NAME);
+	pi.setActiveTools([...new Set(next)]);
+}
+
+// Mirrors pi-ai's per-API transcript handling: without these flags, a mid-conversation tool change
+// makes Pi resend the conversation under a new leading system message, missing the prompt cache.
+function addsToolsWithoutCheckpoint(model: ExtensionContext["model"]): boolean {
+	const compat = model?.compat as {
+		supportsMidConvoSystemMessages?: boolean;
+		supportsMidConvoToolChanges?: boolean;
+		supportsMidConvoToolAdditions?: boolean;
+		supportsAdditionalTools?: boolean;
+		supportsToolSearch?: boolean;
+	} | undefined;
+	if (!model || compat?.supportsMidConvoSystemMessages !== true) return false;
+	switch (model.api) {
+		case "anthropic-messages": return compat.supportsMidConvoToolChanges === true;
+		case "openai-completions": return compat.supportsMidConvoToolAdditions === true;
+		case "openai-responses":
+		case "openai-codex-responses":
+		case "azure-openai-responses": return compat.supportsAdditionalTools === true || compat.supportsToolSearch === true;
+		default: return false;
+	}
+}
+
+// Returns whether the loader is selected for this session.
+function applyRecordedSelection(pi: ExtensionAPI, ctx: ExtensionContext, mode: "auto" | "dynamic"): boolean {
+	const available = pi.getAllTools();
+	if (!Array.isArray(available) || !Array.isArray(pi.getActiveTools())) return true;
+	if (!available.some((tool) => tool.name === LOADER_NAME)) return true;
+	// SAFETY: The running Pi session manager exposes buildSessionContext, but its read-only extension type omits it.
+	const messages = (ctx.sessionManager as typeof ctx.sessionManager & { buildSessionContext(): { messages: ToolSelectionMessage[] } }).buildSessionContext().messages;
+	if (hasNativeToolSelection(messages)) {
+		// Replayed here because a package-local pi-ai may be older than the running Pi.
+		const recorded = new Set<string>();
+		for (const message of messages) {
+			if (message.role !== "system") continue;
+			for (const tool of message.toolsRemoved ?? []) recorded.delete(tool.name);
+			for (const tool of message.toolsAdded ?? []) recorded.add(tool.name);
+		}
+		// "auto" never adds the loader to a transcript that did not declare it: that is itself a tool change.
+		const loaderSelected = mode === "dynamic" || recorded.has(LOADER_NAME);
+		setSelection(pi, recorded.has(SUBAGENT_NAME), loaderSelected);
+		return loaderSelected;
+	}
+	// "auto" goes eager only for an empty session; any history keeps the tools it already sent.
+	const eager = mode === "auto" && messages.length === 0 && !addsToolsWithoutCheckpoint(ctx.model);
+	setSelection(pi, eager || (messages.length > 0 && pi.getActiveTools().includes(SUBAGENT_NAME)), !eager);
+	return !eager;
+}
+
+export function registerSubagentToolActivation(
+	pi: ExtensionAPI,
+	options: { advertisedPrompt: () => string | undefined | Promise<string | undefined>; mode?: ToolActivationMode },
+): void {
+	const mode = options.mode ?? "auto";
+	// Same as --exclude-tools subagents_enable: without the loader, subagent stays active.
+	if (mode === "eager") return;
+	if (typeof pi.getAllTools !== "function" || typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") {
+		if (!warnedUnsupportedHost) {
+			warnedUnsupportedHost = true;
+			console.warn("[pi-subagents] Dynamic tool activation requires Pi 0.86.1 or newer; keeping subagent eagerly available.");
+		}
+		return;
+	}
+
+	// Takes no arguments, but a stray one (DeepSeek sends `{ action: "enable" }`) must not fail validation.
+	const parameters = Type.Object({});
+	const loader: ToolDefinition<typeof parameters, ActivationDetails> = {
+		name: LOADER_NAME,
+		...MODEL_ONLY_TOOL,
+		label: "Enable Subagents",
+		description: "Enable pi-subagents delegation and management tools without launching work. Call when delegation is authorized by the current request or applicable user/project instructions, or when managing existing runs. Direct execution is the default; complexity alone never authorizes delegation. Full tools are available on the next model request.",
+		promptSnippet: "pi-subagents is installed. For authorized specialist, independent-review, or parallel work, call subagents_enable, then subagent. Authorization must come from the current request or applicable instructions; complexity alone is not authorization.",
+		parameters,
+		async execute() {
+			if (!pi.getAllTools().some((tool) => tool.name === SUBAGENT_NAME)) return {
+				isError: true,
+				content: [{ type: "text", text: "Cannot enable unavailable tools: subagent." }],
+				details: { unavailable: [SUBAGENT_NAME] },
+			};
+			try {
+				setSelection(pi, true, true);
+			} catch (error) {
+				return {
+					isError: true,
+					content: [{ type: "text", text: `Activation failed: ${error instanceof Error ? error.message : String(error)}` }],
+					details: { missing: [SUBAGENT_NAME] },
+				};
+			}
+			if (!pi.getActiveTools().includes(SUBAGENT_NAME)) return {
+				isError: true,
+				content: [{ type: "text", text: "Activation failed: subagent." }],
+				details: { missing: [SUBAGENT_NAME] },
+			};
+			const advertised = await options.advertisedPrompt();
+			return {
+				content: [{ type: "text", text: `Enabled: subagent. If your tool list includes subagent (possibly prefixed), call subagent({action:\"list\",capabilities:true}). Otherwise, wait for the next user prompt; do not retry now. Start Pi with --exclude-tools subagents_enable to keep subagent always available.${advertised ? `\n\n${advertised}` : ""}` }],
+				details: { enabled: [SUBAGENT_NAME] },
+			};
+		},
+	};
+	pi.registerTool(loader);
+
+	// Decided at session start and tree navigation only; switching models keeps the session's tools.
+	let loaderSelected = true;
+	pi.on("session_start", (_event, ctx) => { loaderSelected = applyRecordedSelection(pi, ctx, mode); });
+	pi.on("session_tree", (_event, ctx) => { loaderSelected = applyRecordedSelection(pi, ctx, mode); });
+	pi.on("before_agent_start", (event) => {
+		if (!loaderSelected) return;
+		const available = pi.getAllTools();
+		if (!Array.isArray(available) || !available.some((tool) => tool.name === LOADER_NAME)) return;
+		const selectedTools = event.systemPromptOptions.selectedTools ??= [...pi.getActiveTools()];
+		if (!selectedTools.includes(LOADER_NAME)) selectedTools.push(LOADER_NAME);
+		if (!pi.getActiveTools().includes(LOADER_NAME)) pi.setActiveTools([...pi.getActiveTools(), LOADER_NAME]);
+	});
+}

package/dist/extensions/pi-subagents/src/extension/tool-description.ts

@@ -2,98 +2,77 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { ExtensionConfig, ToolDescriptionMode } from "../shared/types.ts";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
+import { resolveDisabledFeatureSurface, type DisabledFeatureSurface, type SubagentSurfaceFeature } from "../shared/disabled-features.ts";
 
 const CUSTOM_TOOL_DESCRIPTION_FILE = "subagent-tool-description.md";
 const CUSTOM_TOOL_DESCRIPTION_MAX_BYTES = 50 * 1024;
-const EXTERNAL_CLI_RUNNER_GUIDANCE = "External CLI agents (custom external-cli runners; there are no bundled adapter agents) use their own runner contract and do not support native Pi child options such as model override, structured output, acceptance/agent contract, tool budget, fast mode, fork context, skills, or native Pi tools unless the runner explicitly implements them.";
-const SUBAGENT_FAILURE_RECOVERY_GUIDANCE = "If a subagent workflow, child launch, prompt runtime, extension load, or child tooling setup fails, treat it as a lane infrastructure blocker—not permission to change execution mode. Stop and report the exact failure, run/status, and repo/cwd/worktree/branch/ref state; verify the worktree is clean or capture a partial diff before retrying or asking the owner. Retry or fix the subagent path only through a clear same-protocol retry. Do not silently switch to interactive_shell, pi -ne, Codex/Claude/Cursor CLI, a foreground agent, or another external mode. For backlog lanes and other subagent-governed workflows, external/foreground/CLI fallback requires explicit owner approval. Pi core may print a generic pi -ne extension-load hint; that out-of-repo hint is not protocol-approved fallback. interactive_shell remains valid when the user explicitly requests foreground/CLI work or the task is outside the governed subagent protocol.";
-const AGENT_SELECTION_GUIDANCE = "Before execution, call { action: \"list\", capabilities: true } and run only executable, non-disabled agents; for external-cli rows, also require runner.available === true. This is a passive PATH/PATHEXT/X_OK lookup, not authentication, version, or launch proof; launch preflight remains authoritative.";
-const WORKFLOW_RESUME_KEY_GUIDANCE = "Each workflow key identifies one result lane: use a new stable workflow key for every distinct retained resume pass; same-key calls are reused only when launch parameters are identical, and incompatible parameters are rejected.";
-const WORKFLOW_OUTPUT_BINDING_GUIDANCE = "For durable workflow child files, set output on runs.run/runs.all; task filename prose is not an output declaration, and return the child's outputReference, outputPathMapping, or artifactPaths instead of inventing a literal path.";
-const WORKFLOW_LANES_GUIDANCE = "For bounded parallel sequential chains, use runs.lanes([{key,stages:[{key,agent,task},{key,resume:'previous',task},...]}]); first stages run together, later stages sequence per lane, and the bounded board reports lane-local failures. Only an explicit structuredOutput.verdict === 'blocked' blocks a successful stage; reviewer prose is not parsed.";
-const WORKTREE_BASE_REF_GUIDANCE = "baseRef must be HEAD or a supported named ref such as refs/heads/main; full 40/64-character commit IDs and revision expressions such as HEAD~1 are unsupported. Omitted baseRef defaults to HEAD resolved at worktree allocation. The source checkout must still be clean.";
-const WORKFLOW_SCRIPT_PORTABILITY_GUIDANCE = "workflowScript rejects nested async function, arrow, and method helpers; use top-level await, plain helper functions that return runs.run(...), or explicit Promise chains instead.";
-const WORKFLOW_RESOURCE_GUIDANCE = "For permission/policy-extension interoperability, use an extension-owned named resource such as {workflow:'review',args:{task:'...'}} or {workflow:'run-ci',args:{command:'npm test'}}. The host resolves the script and authority internally so policy can distinguish it from raw workflowScript/workflowScriptPath; args are bounded plain data, and do not combine workflow with agent, task, workflowScript, or workflowScriptPath.";
-const WORKFLOW_HOST_GUIDANCE = "For permission-sensitive host calls, use an extension-owned resource such as {workflow:'run-ci',args:{command:'npm test'}}; raw workflowScript/workflowScriptPath have unknown resource provenance and cannot use runs.host. In a resource that grants it, await runs.host(key,{kind:'command',command,timeoutMs,output?,role?,provider?}). runs.host has no per-step cwd: commands and relative output paths use the workflow cwd; set cwd on the outer subagent request instead (for example, {cwd:'/path/to/worktree',workflowScript:'...'}), or put a trusted directory change in the command (for example, 'cd /path/to/worktree && npm test'). runs.host supports only command steps; output is bounded and command failure fails the workflow.";
+const AGENT_SELECTION_GUIDANCE = 'First call {action:"list",capabilities:true}: executable, non-disabled agents only; external-cli requires runner.available === true. Passive PATH/PATHEXT/X_OK is not authentication/version/launch proof; preflight is authoritative.';
+const SUBAGENT_FAILURE_RECOVERY_GUIDANCE = "Workflow, child launch, prompt runtime, extension load or child tooling failure is a lane infrastructure blocker. Stop; report exact failure, run/status and repo/cwd/worktree/branch/ref; verify clean worktree or capture partial diff before same-protocol retry or asking the owner. Never silently switch to interactive_shell, pi -ne, Codex/Claude/Cursor CLI or foreground/external mode: governed-workflow fallback requires explicit owner approval, not Pi core's generic pi -ne hint. Explicit foreground/CLI requests and work outside that protocol remain valid.";
 
-export const DEFAULT_SUBAGENT_TOOL_DESCRIPTION = `Delegate to configured subagents. For execution, omit action and use {agent, task?} for one child, workflowScript for inline orchestration, workflowScriptPath to load a script from the request cwd, or a named workflow resource for permission/policy-aware execution. ${WORKFLOW_RESOURCE_GUIDANCE} ${AGENT_SELECTION_GUIDANCE} The script inputs are mutually exclusive. Use action:'validate' with either script input to check it without launching children. For multi-step or parallel work, make exactly one top-level subagent call with async:true; launch children only inside that workflow and do not make another top-level call for them. Use runs.run('key',{agent,task}) for one child, await runs.all([{key:'a',agent:'reviewer',task:'...'},{key:'b',agent:'reviewer',task:'...'}]) for ordinary parallel children, and read its ordered array result with indexes, destructuring, or .map(...), not by key property. ${WORKFLOW_SCRIPT_PORTABILITY_GUIDANCE} ${WORKFLOW_LANES_GUIDANCE} ${WORKFLOW_HOST_GUIDANCE} ${WORKTREE_BASE_REF_GUIDANCE} ${EXTERNAL_CLI_RUNNER_GUIDANCE} ${SUBAGENT_FAILURE_RECOVERY_GUIDANCE} Use action only for management/control. Use guide or the pi-subagents skill for advanced workflow details.`;
+type FeatureText = (feature: SubagentSurfaceFeature, text: string, disabledText?: string) => string;
 
-export const SUBAGENT_TOOL_PROMPT_SNIPPET = "Delegate to subagents; orchestrate in one workflowScript call.";
-
-export const SUBAGENT_TOOL_PROMPT_GUIDELINES = [
-	`Use subagent only when delegation is needed. ${AGENT_SELECTION_GUIDANCE}`,
-	'Omit action for execution; use { agent, task? } for one child. For multi-step or parallel work, make exactly one top-level { workflowScript, async: true } call and launch children only inside it. Use action only for management/control.',
-	"workflowScript rejects nested async function, arrow, and method helpers; use top-level await, plain helper functions, or explicit Promise chains.",
-	"Inside workflowScript, use runs.run/runs.all and await their results. runs.all returns an ordered array, not a key map; stored runs.run promises must later be observed with direct await, Promise.race, or Promise.all.",
-	'Keep one writer per cwd/worktree; isolate concurrent writers. For durable files, set output on runs.run/runs.all and return the child\'s outputReference, outputPathMapping, or artifactPaths. For advanced workflows, read the bundled pi-subagents skill or call { action: "guide", topic: "workflows" }.',
-];
+function featureText(disabled: DisabledFeatureSurface): FeatureText {
+	return (feature, text, disabledText = "") => disabled.features.has(feature) ? disabledText : text;
+}
 
-export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
+const safetyGuidance = (on: FeatureText) => `SAFETY-CRITICAL SUBAGENT GUIDANCE:
+• 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.
 • ${AGENT_SELECTION_GUIDANCE}
 • ${SUBAGENT_FAILURE_RECOVERY_GUIDANCE}
-• Keep execution and management separate: omit action for structured single-child or workflowScript execution; use action only for management/control.
-• Async/background runs are the normal default unless config sets asyncByDefault:false; set async:true explicitly when async behavior matters. Use async:false only when the parent must block until completion. Async mode still shows progress. Final reviews and gate checks stay async; needing a result is not a blocking reason. After an async launch, continue independent work only until its next dependency barrier; consume the result before work that depends on it. Ordinary async subagents notify this session natively, so return control and do not call bg_wait merely to get a completion wake. Do not sleep or poll status just to wait; use bg_wait only for provider, detached, or other background work without a native notification when this turn must receive its result.
-• ${WORKFLOW_RESUME_KEY_GUIDANCE}
-• ${WORKFLOW_OUTPUT_BINDING_GUIDANCE}
-• ${WORKFLOW_HOST_GUIDANCE}
-• Ordinary child subagents are not orchestrators. Only explicitly configured fanout children may use the child-safe subagent tool, still bounded by depth/session limits.
-• Oracle/advisor consultations should use supervisor dialogue for material unknowns when available; request one-shot only when desired.
-• Keep one writer for the same cwd/worktree. Use fresh-context read-only reviewers for independent review, then have the parent synthesize and apply fixes.
-• Async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, status via { action: "status", id }, and lifecycle diagnostics via { action: "debug.run", id }. Include output paths and residual risks when reporting results.`;
-
-export const FULL_SUBAGENT_TOOL_DESCRIPTION = `Run one child with { agent, task? }; use { workflowScript } for inline orchestration or { workflowScriptPath } to load it from the request cwd. The script inputs are mutually exclusive. Omit action for execution. Use action only for management/control actions.
-
-${WORKFLOW_RESOURCE_GUIDANCE}
-
-EXECUTION:
-• ${EXTERNAL_CLI_RUNNER_GUIDANCE}
-• ${AGENT_SELECTION_GUIDANCE}
-• When passing an explicit model to a child (on the call or a runs.run/runs.all item), first call { action: "models" } and copy an exact provider/id; bare ids resolve only when unique in the registry, and agent names (e.g. gpt-pro, advisor) are not model ids. Set per-run thinking with a suffix on the model string (e.g. provider/id:high; off/minimal/low/medium/high/xhigh/max); the suffix wins over the agent's thinking default. The thinking field only applies to action='watchdog.configure' and is ignored on dispatch.
-• SINGLE CHILD: { agent:"worker", task:"..." }. This structured form starts exactly one direct child. Fields such as model, context, cwd, worktree, output, budgets, acceptance, and async apply to that child. Do not combine agent/task with action, workflowScript, or workflowScriptPath.
-• WORKFLOW SCRIPT: { workflowScript: "return runs.run('main', {agent:'worker', task:'...'})" }. Use stable-key runs.run for one child and await runs.all([{key,agent,task}, ...]) for ordinary parallel children. runs.all resolves to an ordered array, not a key map, so use results[0], array destructuring, or results.map((result) => result.output), not results.<key>. Do not read .output from unawaited runs.run launches. Stored runs.run promises are only for advanced rolling fanout and each must later be observed with direct await, Promise.race, or Promise.all. Ordinary JavaScript provides sequence, branching, filtering, retries, and aggregation. workflowScript is an ordinary JavaScript statement body, so use an explicit return for a useful result. Use top-level await, plain helper functions, or explicit Promise chains; nested async function, arrow, and method helpers are rejected. For task text with Markdown fences or shell blocks, build quoted lines instead of nesting raw template literals: \`const task=["Run:","\`\`\`bash","npm test","\`\`\`"].join("\\n")\`. Scripts normally start async unless config sets asyncByDefault:false; set async:true explicitly when async behavior matters. Pass async:false only when the parent must block until completion, never for final reviews or gates. Same-repo blocking workflows default to a live in-chat card; explicit live-card requires same-repository async:false, so async workflows should omit chatProgress or use auto/off. Workflow-level child controls default onto each runs.run launch, and explicit child fields override them. Use {action:"children.list"} to list recent retained workflow children with resumable/not-resumable reasons. Resume only rows reported resumable. For a simple follow-up or implementation challenge, use {action:"resume", id:"run-id", message:"..."}. Resume keeps the stored agent/model/tool contract. If no resumable child is listed, launch a same-role fallback challenge and label it as fallback. Inside workflowScript, continue one with runs.run(key, {resume:"run-id", task:"follow-up"}); workflow resumes wait for completed output, and loops must continue from each latest returned runId. Await runs.steer(key, message, {mode?, index?, ackTimeoutMs?}) to guide a prior keyed child without exposing its run id; receipts are queued, delivered, missed, or failed. Always await or return runs.steer. For repository mutation lanes, set worktree:true on the workflow or individual runs.run/runs.all item for managed isolation; each parallel child gets a separate worktree and handoff artifact. ${WORKTREE_BASE_REF_GUIDANCE} A workflow usageBudget is enforced once across the workflow. Available globals are runs.run, runs.all, runs.steer, runs.status, runs.ref/refs, emit, console, and standard JavaScript only. Workflows get async state.get(key) and state.set(key, JSONValue) through their automatic or explicit mission; mission:false workflows do not have a state global. Scripts cannot access filesystem, shell, arbitrary Pi tools, or host globals.
-• ${WORKFLOW_LANES_GUIDANCE}
-• FILE SCRIPT: { workflowScriptPath:"workflows/review.js" }. Relative paths resolve against the request cwd. The host reads the file before the filesystem-free workflow sandbox starts. Do not combine this field with workflowScript.
-• Sequential example: { workflowScript: "const a = await runs.run('analyze', {agent:'agent-a', task:'Analyze the request'}); return (await runs.run('plan', {agent:'agent-b', task:'Plan from: '+a.output})).output" }
-• Parallel example: { workflowScript: "const [a,b] = await runs.all([{key:'correctness',agent:'agent-a',task:'Review correctness'},{key:'tests',agent:'agent-b',task:'Review tests'}]); return {correctness:a.output,tests:b.output}" }
-• Optional context is "fresh", "fork", or "profile". profile requires the selected agent's declared defaultContext and ignores config defaultSubagentContext. Explicit fresh/fork wins. When omitted, config defaultSubagentContext wins over agent defaultContext. Config forkContext can summarize transcript overflow with stable recovery refs before spawn without adding another public context value. timeoutMs/maxRuntimeMs apply to foreground and async workflows; foreground workflows default to 30 minutes and async workflows have no default timeout. Omit acceptance for reviewer/read-only calls; evidence levels end at verified, and acceptance.review.required requests independent writer review.
-• Durable mission attachment is automatic by default. Use missionId to attach an existing mission, mission:{...} to override auto-create, or mission:false for ephemeral work. A mission object needs exactly one non-empty title or summary; objective and labels are optional. goal may only be true and requires budget:{tokens}.
-
-MANAGEMENT / CONTROL (use action; omit execution fields):
-• validate checks workflowScript or workflowScriptPath syntax and statically decidable structure without launching children. list, get, models, guide, children.list, create, update, delete, eject, disable, enable, reset, status, debug.run, doctor, grant-spawn-budget, worktree.discard, worktree.cleanup (plan-only), lane.status, lane.recordMerge, lane.recordSupersession, refine/refine.show/refine.rollback, mission.create/list/show/update/resolve-decision/attach-run/close, inspector.open/status/close, project.open/status/close, and watchdog actions remain available. Use {action:"guide", topic:"overview"} for packaged current-version help; topics are overview, workflows, agents, missions, observability, tool-reference, configuration, models, watchdog, and extension-api.
-• status, interrupt, stop, resume, and steer manage live or persisted runs. Use status view:"fleet" for an overview or view:"transcript" with id and optional index to tail output.
-• Create durable project schedules with { action:"schedule.create", id?, name?, sessionOnly?:true, at:"+10m" | ISO, baseRef?, workflowScript:"return runs.run('main', {agent:'worker', task:'...'})" }, or use workflowScriptPath instead. An optional baseRef uses the same managed-worktree ref policy and resolves at allocation; the source checkout must still be clean. With sessionOnly:true, the schedule records the creating session file and only that session can restore or execute it; omitted/false preserves project-wide behavior. Manage them with schedule.list/show/history/pause/resume/run/run-due/delete. This first slice supports fixed intervals; calendar schedules and schedule mission attachment are deferred.
-
-${SUBAGENT_SAFETY_GUIDANCE}`;
-
-export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `Run one child with { agent, task? }; use { workflowScript } for inline orchestration or { workflowScriptPath } to load it from the request cwd. The script inputs are mutually exclusive. Omit action for execution. Use action only for management/control actions.
-
-${WORKFLOW_RESOURCE_GUIDANCE}
+• Omit action for execution. For an authorized delegated multi-step/parallel workflow: exactly one top-level subagent ${on("workflow-scripts", "workflow call with async:true; children launch only inside it", "chain or tasks call with async:true")}.
+• Async follows asyncByDefault (normally true); async:false only to block the parent, not for final reviews/gates. Consume results at dependency barriers. Native async completion wakes this session: return control, no sleep/poll or bg_wait merely for a wake. bg_wait is for provider/detached work without native notification needing a same-turn result.
+• Ordinary child subagents are not orchestrators; only configured fanout within depth/session limits. For an authorized delegated workflow, keep one writer per cwd/worktree and isolate concurrent writers. Use fresh-context read-only reviewers when independent review was requested, then parent synthesis/fixes. Oracle/advisor unknowns use supervisor dialogue; one-shot only when requested.
+• Bind durable output ${on("workflow-scripts", "on runs.run/runs.all", "with output")}, not task filename prose; return actual outputReference/outputPathMapping/artifactPaths, evidence and residual risks.
+• children.list is workflow-only, not an exhaustive list of direct native children: resume only resumable rows. When an intended child's exact run id is known, inspect it with {action:"status",id}; if status identifies the candidate, attempt {action:"resume",id,message}. Resume authoritatively checks eligibility, may reject it, and otherwise detaches a follow-up/challenge with the stored agent/model/tool contract. Use a labeled same-role fallback only when no known candidate exists or resume rejects eligibility.${on("workflow-scripts", " Scripts await runs.run(newKey,{resume:runId,task}); continue from latest returned runId. Each distinct resume pass needs a new stable key; same-key reuse requires identical launch parameters.")}
+${on("workflow-scripts", "• Named resources own authority; raw scripts (workflow:true or a path) cannot use runs.host. Granted commands/relative outputs use workflow cwd, never per-step cwd.\n")}• Inspect asyncId/asyncDir (status.json, events.jsonl, logs) with status/debug.run; control with interrupt/stop/resume/steer. For local Pi children explicitly granted subagent_command, command.status/yield/cancel targets one exact toolCallId without interrupting the child. Read {action:"guide",topic:"tool-reference"} for controls/evidence gates.`;
+
+const scriptExecutionGuidance = (on: FeatureText) => `Delegate one child with {agent,task?}; otherwise set exactly one workflow source, with optional args.
+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. action is management/control; validate accepts workflow:true or a path without launching.
+Scripts: JavaScript statement bodies with explicit return, top-level await, plain helpers/Promise chains; nested async function/arrow/method helpers are rejected. Await runs.run('key',{agent,task}) before .output; await runs.all([{key,agent,task},...]) for an ordered array, not a key map. Observe 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; queued/delivered/missed/failed receipts are not compliance proof.
+Before advanced orchestration (runs.lanes, rolling fanout, mission state, handoffs), read {action:"guide",topic:"workflows"} or the pi-subagents skill. Raw-script sandboxes add deeply frozen args; all sandboxes provide runs, emit, console, JavaScript and enabled mission state, with no filesystem/shell/Pi tools/host globals. External CLI agents support native options only when their runner declares them; read guide tool-reference before passing model, structured output, acceptance/agentContract, ${on("tool-budgets", "tool budget, ")}fast, fork context or skills/tools.
+Model override: first call {action:"models"}; copy exact provider/id, not agent names. Thinking uses model suffix${on("watchdog", ", not watchdog-only thinking")}.
+Named resources: {workflow:'review',args:{task:'...'}} or {workflow:'run-ci',args:{command:'npm test'}}. Raw scripts also accept bounded plain-data args; raw-script args persist as evidence, so never include secrets. worktree:true requires clean source; baseRef defaults to HEAD at allocation or a supported named ref, never full 40/64-character commit IDs or revision expressions.`;
+
+const structuredExecutionGuidance = (on: FeatureText) => `Delegate one child with {agent,task?}. tasks:[{agent,task},...] runs children in parallel. chain:[{agent,task?,as?} or {parallel:[{agent,task},...]}] runs steps in order; a parallel step waits for all its children and a failed step stops the chain.
+Chain task placeholders: {task} is the top-level task (the original request); {previous} is the prior step's output (a parallel step's outputs in order), and the default when task is omitted; {outputs.name} is the output of an earlier step with as:'name'.
+agent, chain and tasks exclude each other and action. action is management/control; agent may target management actions.
+External CLI agents support native options only when their runner declares them; read guide tool-reference before passing model, structured output, acceptance/agentContract, ${on("tool-budgets", "tool budget, ")}fast, fork context or skills/tools.
+Model override: first call {action:"models"}; copy exact provider/id, not agent names. Thinking uses model suffix${on("watchdog", ", not watchdog-only thinking")}.
+worktree:true requires clean source; baseRef defaults to HEAD at allocation or a supported named ref, never full 40/64-character commit IDs or revision expressions.`;
+
+const defaultDescription = (on: FeatureText) => `${on("workflow-scripts", scriptExecutionGuidance(on), structuredExecutionGuidance(on))}\n\n${safetyGuidance(on)}`;
+
+const managementDiscovery = (on: FeatureText) => [
+	["list/get/models/guide"],
+	[on("agent-management", "create/update/delete/eject/disable/enable/reset/refine")],
+	[on("missions", "mission.*"), on("schedules", "schedule.*"), on("watchdog", "watchdog.*"), on("panes", "inspector.*, project.*"), on("lane-management", "lane.status/recordMerge/recordSupersession")],
+	[on("lane-management", "worktree.discard and reviewed worktree.cleanup")],
+	[`doctor${on("spawn-budget-grants", " and grant-spawn-budget")}`],
+].map((group) => group.filter(Boolean).join(", ")).filter(Boolean).join("; ");
+
+const fullDescription = (on: FeatureText) => `${defaultDescription(on)}
+
+WORKFLOW DETAILS:
+${on("workflow-scripts", "• runs.lanes([{key,stages:[{key,agent,task},{key,resume:'previous',task}]}]) runs first stages together, later stages sequentially per lane. Failures stay lane-local; only explicit structuredOutput.verdict === 'blocked' blocks a successful stage, never reviewer prose.\n")}• ${on("workflow-scripts", "Workflow child controls default onto runs.run/runs.all items; child fields override them.", "Top-level child controls apply to every chain/tasks child.")} worktree:true isolates each child and returns handoff artifacts.${on("usage-budgets", " usageBudget is shared across the workflow; already-running children are not stopped.")}
+• Missions auto-attach${on("missions", " unless mission:false")}; ${on("workflow-scripts", "await state.get(key)/state.set(key,JSONValue) requires a mission. ")}See guide topic missions. Omit acceptance for reviewer/read-only calls; acceptance.review.required requests independent writer review.
+• Management discovery: ${managementDiscovery(on)}. Use guide topics agents, ${on("missions", "missions, ")}observability, tool-reference, configuration, models${on("watchdog", ", watchdog")} or extension-api for exact action fields.${on("schedules", on("workflow-scripts", " Schedules take script inputs, not direct children; recipes live in the missions guide."))}`;
+
+const allEnabled = featureText(resolveDisabledFeatureSurface({}));
+
+export const SUBAGENT_SAFETY_GUIDANCE = safetyGuidance(allEnabled);
+
+export const DEFAULT_SUBAGENT_TOOL_DESCRIPTION = defaultDescription(allEnabled);
+
+export const SUBAGENT_TOOL_PROMPT_SNIPPET = "For operator-requested delegation, use subagents; compose multi-child work in one workflow call.";
+const STRUCTURED_SUBAGENT_TOOL_PROMPT_SNIPPET = "For operator-requested delegation, use subagents; compose multi-child work in one chain or tasks call.";
+export const SUBAGENT_TOOL_PROMPT_GUIDELINES = [
+	"Do not invoke subagents unless the operator requested delegation directly or through applicable instructions.",
+];
 
-EXECUTE:
-• ${EXTERNAL_CLI_RUNNER_GUIDANCE}
-• ${AGENT_SELECTION_GUIDANCE}
-• Passing an explicit model? Call {action:"models"} first and copy an exact provider/id; bare ids resolve only when unique in the registry; agent names (e.g. gpt-pro, advisor) are not model ids. Per-run thinking is a suffix on the model string (provider/id:high; off/minimal/low/medium/high/xhigh/max), and the suffix wins over the agent's thinking default; the thinking field only applies to action='watchdog.configure' and is ignored on dispatch.
-• SINGLE {agent:"worker",task:"..."} starts exactly one direct child. Fields apply to that child. Do not combine agent/task with action, workflowScript, or workflowScriptPath.
-• SCRIPT {workflowScript:"return runs.run('main', {agent:'worker', task:'...'})"}. Use stable-key runs.run for one child and await runs.all([{key,agent,task}, ...]) for ordinary parallel work. runs.all resolves to an ordered array, not a key map; use results[0], destructuring, or results.map(...), not results.<key>. Do not read .output from unawaited runs.run launches. Stored runs.run promises are only for advanced rolling fanout and each must later be observed with direct await, Promise.race, or Promise.all. Await runs.steer(key,message,options?) to guide a prior keyed child; it returns queued, delivered, missed, or failed and never accepts a raw run id. Always await or return steering calls. Use {action:"children.list"} for recent retained workflow children and resume only rows reported resumable. Use {action:"resume",id:"run-id",message:"..."} for a simple follow-up or challenge; resume keeps the stored agent/model/tool contract. If none is resumable, launch a same-role fallback challenge and label it as fallback. Inside workflowScript use runs.run(key,{resume:"run-id",task:"follow-up"}) when the script must wait for completion and continue from the latest returned runId. Workflows get async state.get/state.set through their automatic or explicit mission; mission:false does not. Scripts are ordinary JavaScript statement bodies; use explicit return for a useful result. Use top-level await, plain helper functions, or explicit Promise chains; nested async function, arrow, and method helpers are rejected. For task text with Markdown fences or shell blocks, build quoted lines instead of nesting raw template literals: \`const task=["Run:","\`\`\`bash","npm test","\`\`\`"].join("\\n")\`. Use JavaScript for sequence, branching, retries, and aggregation. For repository mutation lanes, use worktree:true on the workflow or runs.run/runs.all item for managed isolation. ${WORKTREE_BASE_REF_GUIDANCE} Scripts normally start async unless config sets asyncByDefault:false; set async:true explicitly when async behavior matters. async:false blocks the parent until completion and auto-enables a same-repo live chat card unless chatProgress is off; explicit live-card requires same-repository async:false, so async workflows should omit chatProgress or use auto/off.
-• ${WORKFLOW_LANES_GUIDANCE}
-• FILE SCRIPT {workflowScriptPath:"workflows/review.js"} loads the script on the host relative to the request cwd before sandbox execution. Do not combine it with workflowScript.
-• Example: {workflowScript:"const [a,b]=await runs.all([{key:'a',agent:'agent-a',task:'Implement A',worktree:true},{key:'b',agent:'agent-b',task:'Implement B',worktree:true}]); return [a.output,b.output]"}
-• context can be fresh, fork, or profile. profile requires the selected agent's declared defaultContext and ignores defaultSubagentContext. Explicit fresh/fork wins; omitted context follows defaultSubagentContext before agent defaultContext. Config forkContext can summarize transcript overflow with stable recovery refs before spawn without adding another public context value. timeoutMs/maxRuntimeMs apply to foreground and async workflows; foreground workflows default to 30 minutes and async workflows have no default timeout. Omit acceptance for reviewer/read-only calls.
-
-MANAGE / CONTROL:
-• Use action without execution fields for list/get/models/guide/authoring, refine/refine.show/refine.rollback, mission, watchdog, status, interrupt, stop, resume, steer, worktree.cleanup (mode:'plan' only), script-only scheduling, diagnostics, and other management actions. guide reads shipped current-version docs by topic.
-• A mission object needs exactly one non-empty title or summary; objective and labels are optional. goal may only be true and requires budget:{tokens}.
-
-ASYNC / SAFETY:
-• ${SUBAGENT_FAILURE_RECOVERY_GUIDANCE}
-• Omitted async follows asyncByDefault config; set async:true explicitly when async behavior matters. Continue independent work only until its next dependency barrier; consume the result before work that depends on it. Ordinary async subagents notify this session natively, so return control and do not call bg_wait merely to get a completion wake. Do not sleep or poll merely to wait; use bg_wait only for provider, detached, or other background work without a native notification when this turn must receive its result.
-• ${WORKFLOW_RESUME_KEY_GUIDANCE}
-• ${WORKFLOW_OUTPUT_BINDING_GUIDANCE}
-• ${WORKFLOW_HOST_GUIDANCE}
-• Ordinary children are not orchestrators. Keep one writer per cwd/worktree and use fresh read-only reviewers for independent checks.
-• Oracle/advisor consultations use available supervisor dialogue for material unknowns; request one-shot when desired.
-• Status and artifacts live under asyncId/asyncDir with status.json, events.jsonl, output logs, and {action:"status",id:"..."}.`;
+export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = DEFAULT_SUBAGENT_TOOL_DESCRIPTION;
 
+export const FULL_SUBAGENT_TOOL_DESCRIPTION = fullDescription(allEnabled);
 
 function isToolDescriptionMode(value: unknown): value is ToolDescriptionMode {
 	return value === "full" || value === "compact" || value === "custom";
@@ -107,6 +86,8 @@ export interface ToolDescriptionOptions {
 	cwd?: string;
 	agentDir?: string;
 	warn?: (message: string) => void;
+	/** Removes lines for disabled features from the default and full descriptions; custom descriptions are unchanged apart from the appended safety guidance. */
+	disabledFeatures?: DisabledFeatureSurface;
 }
 
 export interface SubagentToolPromptMetadata {
@@ -114,7 +95,10 @@ export interface SubagentToolPromptMetadata {
 	promptGuidelines?: string[];
 }
 
-export function buildSubagentToolPromptMetadata(config: Pick<ExtensionConfig, "toolDescriptionMode"> = {}): SubagentToolPromptMetadata {
+export function buildSubagentToolPromptMetadata(config: Pick<ExtensionConfig, "toolDescriptionMode"> = {}, disabledFeatures?: DisabledFeatureSurface): SubagentToolPromptMetadata {
+	// Selesai: the full description already carries this guidance; no separate prompt snippet/guidelines.
+	void config;
+	void disabledFeatures;
 	return {};
 }
 
@@ -194,29 +178,32 @@ function loadCustomToolDescription(options?: ToolDescriptionOptions): string | u
 	return undefined;
 }
 
-function withMandatorySafetyGuidance(description: string): string {
+function withMandatorySafetyGuidance(description: string, safety: string): string {
 	const customDescription = description
 		.split(SUBAGENT_SAFETY_GUIDANCE)
+		.flatMap((part) => part.split(safety))
 		.flatMap((part) => part.split(SUBAGENT_FAILURE_RECOVERY_GUIDANCE))
 		.map((part) => part.trim())
 		.filter(Boolean)
 		.join("\n\n");
 	return customDescription
-		? `${customDescription}\n\n${SUBAGENT_SAFETY_GUIDANCE}`
-		: SUBAGENT_SAFETY_GUIDANCE;
+		? `${customDescription}\n\n${safety}`
+		: safety;
 }
 
 export function buildSubagentToolDescription(config: Pick<ExtensionConfig, "toolDescriptionMode"> = {}, options?: ToolDescriptionOptions): string {
+	const on = options?.disabledFeatures ? featureText(options.disabledFeatures) : allEnabled;
+	// Selesai keeps the full description as the default (upstream defaults to the compact one).
 	const mode = resolveToolDescriptionMode(config, options);
 	let description: string;
-	if (mode === "compact") description = COMPACT_SUBAGENT_TOOL_DESCRIPTION;
+	if (mode === "compact") description = defaultDescription(on);
 	else if (mode === "custom") {
 		const custom = loadCustomToolDescription(options);
-		if (custom) description = withMandatorySafetyGuidance(custom);
+		if (custom) description = withMandatorySafetyGuidance(custom, safetyGuidance(on));
 		else {
 			warn(options, `${CUSTOM_TOOL_DESCRIPTION_FILE} was not found or valid for toolDescriptionMode "custom"; using full description.`);
-			description = FULL_SUBAGENT_TOOL_DESCRIPTION;
+			description = fullDescription(on);
 		}
-	} else description = FULL_SUBAGENT_TOOL_DESCRIPTION;
+	} else description = fullDescription(on);
 	return description;
 }

package/dist/extensions/pi-subagents/src/extension/upgrade-notice.ts

@@ -0,0 +1,40 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import packageJson from "../../package.json" with { type: "json" };
+import { writeAtomicJson } from "../shared/atomic-json.ts";
+import { getAgentDir } from "../shared/utils.ts";
+
+// major.minor.patch as one comparable number; undefined for anything else.
+const versionNumber = (version: unknown) => typeof version === "string" && /^\d+\.\d+\.\d+$/.test(version)
+	? version.split(".").reduce((total, part) => total * 1e6 + Number(part), 0)
+	: undefined;
+
+export async function showUpgradeNotice(
+	ctx: { hasUI: boolean; ui: { notify(message: string, type: "info"): void } },
+	stateDir = path.join(getAgentDir(), "pi-subagents"),
+	changelogPath = fileURLToPath(new URL("../../CHANGELOG.md", import.meta.url)),
+	version = packageJson.version,
+): Promise<void> {
+	if (!ctx.hasUI) return;
+	const statePath = path.join(stateDir, "last-seen-version.json");
+	const lastSeen = await fs.promises.readFile(statePath, "utf-8").then((raw) => JSON.parse(raw).version).catch(() => undefined);
+	const previous = versionNumber(lastSeen);
+	const current = versionNumber(version);
+	if (current === undefined || previous === current) return;
+	writeAtomicJson(statePath, { version });
+	if (previous === undefined || previous > current) return;
+
+	const bullets = (await fs.promises.readFile(changelogPath, "utf-8")).split(/^## /m).flatMap((section) => {
+		const released = versionNumber(/^\[([^\]]+)\]/.exec(section)?.[1]);
+		if (released === undefined || released <= previous || released > current) return [];
+		const highlights = section.split(/^### /m).find((part) => part.startsWith("Highlights")) ?? "";
+		return (highlights.match(/^- .*/gm) ?? []).map((bullet) => bullet.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").trim());
+	});
+	ctx.ui.notify([
+		`pi-subagents updated from ${lastSeen} to ${version}`,
+		...bullets.slice(0, 5),
+		...(bullets.length > 5 ? [`...and ${bullets.length - 5} more`] : []),
+		"Changelog: https://github.com/nicobailon/pi-subagents/blob/main/CHANGELOG.md",
+	].join("\n"), "info");
+}

package/dist/extensions/pi-subagents/src/inspectors/actions.ts

@@ -0,0 +1,148 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { readMissionBinding } from "../missions/lifecycle.ts";
+import { listMissions, missionRecordPath, resolveMissionStoreLocation } from "../missions/store.ts";
+import type { MissionStoreConfig } from "../missions/types.ts";
+import { resolveAuthorityDecision, type AuthorityPolicyConfig } from "../policy/authority.ts";
+import { DIRS, type Details, type SubagentState } from "../shared/types.ts";
+import { readStatus } from "../shared/utils.ts";
+import { resolveSubagentRunId } from "../runs/background/run-id-resolver.ts";
+import { resolveNodeExecutable } from "../shared/node-executable.ts";
+import { encodeSessionRoots } from "./session-roots-codec.ts";
+import { formatShellCommand } from "./shell-command.ts";
+import type { InspectorAction, InspectorContext, InspectorLaunch, InspectorParams, InspectorPlugin, InspectorTarget } from "./types.ts";
+
+export { INSPECTOR_ACTIONS } from "./types.ts";
+export type { InspectorAction, InspectorParams, InspectorPlugin } from "./types.ts";
+
+function result(text: string, isError = false): AgentToolResult<Details> {
+	const response: AgentToolResult<Details> = {
+		content: [{ type: "text", text }],
+		details: { mode: "management", results: [] },
+	};
+	if (isError) response.isError = true;
+	return response;
+}
+
+function pathWithin(base: string, candidate: string): boolean {
+	const resolvedBase = path.resolve(base);
+	const resolvedCandidate = path.resolve(candidate);
+	return resolvedCandidate === resolvedBase || resolvedCandidate.startsWith(`${resolvedBase}${path.sep}`);
+}
+function trustedDir(dir: string, deps: InspectorDispatcherDeps): boolean {
+	try {
+		if (fs.lstatSync(dir).isSymbolicLink() || !fs.statSync(dir).isDirectory()) return false;
+		const real = fs.realpathSync(dir);
+		if ([...(deps.state?.asyncJobs.values() ?? []), ...(deps.state?.fleetJobs?.values() ?? [])].some((job) => {
+			try {
+				return fs.realpathSync(job.asyncDir) === real;
+			} catch {
+				return false;
+			}
+		})) return true;
+		const root = deps.asyncDirRoot ?? DIRS.async;
+		return fs.existsSync(root) && pathWithin(root, dir) && pathWithin(fs.realpathSync(root), real);
+	} catch { return false; }
+}
+function resolveTarget(params: InspectorParams, deps: InspectorDispatcherDeps): InspectorTarget | { error: string } {
+	const requested = params.id ?? params.runId;
+	let runId: string;
+	let asyncDir: string;
+	if (params.dir) {
+		asyncDir = path.resolve(params.dir);
+		if (!trustedDir(asyncDir, deps)) return { error: `Async run directory '${asyncDir}' is outside trusted run roots.` };
+		const status = readStatus(asyncDir);
+		if (!status) return { error: `No async run status found in '${asyncDir}'.` };
+		if (requested && requested !== status.runId && !status.runId.startsWith(requested)) return { error: `Run '${requested}' does not match status run '${status.runId}'.` };
+		runId = status.runId;
+	} else {
+		if (!requested) return { error: "Inspector actions require id or dir." };
+		try {
+			const found = resolveSubagentRunId(requested, { state: deps.state, asyncDirRoot: deps.asyncDirRoot ?? DIRS.async, resultsDir: deps.resultsDir ?? DIRS.results });
+			if (!found) return { error: `No subagent run found for '${requested}'.` };
+			if (found.kind !== "async" || !found.location.asyncDir) return { error: `Run '${found.id}' is not an inspectable async run with lifecycle artifacts.` };
+			runId = found.id;
+			asyncDir = found.location.asyncDir;
+		} catch (cause) {
+			return { error: cause instanceof Error ? cause.message : String(cause) };
+		}
+	}
+	const status = readStatus(asyncDir);
+	if (!status) return { error: `No lifecycle status exists for async run '${runId}'.` };
+	if (params.index !== undefined && (params.index < 0 || params.index >= (status.steps?.length ?? 0))) return { error: `Async run '${runId}' has ${status.steps?.length ?? 0} children. Index ${params.index} is out of range.` };
+	const target: InspectorTarget = { runId, asyncDir, status: { cwd: status.cwd, state: status.state, steps: status.steps } };
+	if (params.index !== undefined) target.index = params.index;
+	return target;
+}
+function missionFor(target: InspectorTarget, deps: InspectorDispatcherDeps): { id: string; path: string } | undefined {
+	try {
+		const binding = readMissionBinding(target.asyncDir);
+		if (binding) return { id: binding.missionId, path: missionRecordPath(binding.location, binding.missionId) };
+		const location = resolveMissionStoreLocation(deps.missions ? { projectRoot: deps.cwd, config: deps.missions } : { projectRoot: deps.cwd });
+		const mission = listMissions(location).records.find((record) => record.runs.some((run) => run.runId === target.runId));
+		return mission ? { id: mission.id, path: missionRecordPath(location, mission.id) } : undefined;
+	} catch {
+		return undefined;
+	}
+}
+function launchFor(target: InspectorTarget, deps: InspectorDispatcherDeps): InspectorLaunch {
+	const mission = missionFor(target, deps);
+	const runnerPath = deps.runnerPath ?? fileURLToPath(new URL("../../inspector-runner.mjs", import.meta.url));
+	const job = deps.state?.asyncJobs.get(target.runId) ?? deps.state?.fleetJobs?.get(target.runId);
+	const sessionRoots = [...new Set([...(deps.sessionRoots ?? deps.state?.trustedSessionRoots ?? []), ...(job?.sessionRoot ? [job.sessionRoot] : [])])];
+	const allowSteer = resolveAuthorityDecision({ action: "steerRun", policy: deps.authorityPolicy }) === "auto";
+	const allowStop = resolveAuthorityDecision({ action: "stopRun", policy: deps.authorityPolicy }) === "auto";
+	const argv = [runnerPath, "--async-dir", target.asyncDir, "--run-id", target.runId, "--allow-steer", String(allowSteer), "--allow-stop", String(allowStop), "--session-roots", encodeSessionRoots(sessionRoots)];
+	if (target.index !== undefined) argv.push("--index", String(target.index));
+	if (mission) argv.push("--mission-path", mission.path);
+	const executable = resolveNodeExecutable();
+	const launch: InspectorLaunch = { executable, argv, displayCommand: formatShellCommand(executable, argv), allowSteer, allowStop, sessionRoots };
+	if (mission) launch.mission = mission;
+	return launch;
+}
+
+export interface InspectorDispatcherDeps {
+	state?: SubagentState;
+	asyncDirRoot?: string;
+	resultsDir?: string;
+	missions?: MissionStoreConfig;
+	authorityPolicy?: AuthorityPolicyConfig;
+	sessionRoots?: string[];
+	cwd: string;
+	signal?: AbortSignal;
+	now?: () => Date;
+	runnerPath?: string;
+	env?: NodeJS.ProcessEnv;
+	plugins?: readonly InspectorPlugin[];
+}
+export async function handleInspectorAction(action: InspectorAction, params: InspectorParams, deps: InspectorDispatcherDeps): Promise<AgentToolResult<Details>> {
+	const target = resolveTarget(params, deps);
+	if ("error" in target) return result(target.error, true);
+	const context: InspectorContext = {
+		cwd: deps.cwd,
+		signal: deps.signal,
+		env: deps.env ?? process.env,
+		target,
+	};
+	if (deps.now) context.now = deps.now;
+	if (action === "inspector.command") return result(launchFor(target, deps).displayCommand);
+	const plugins = deps.plugins ?? [];
+	if (action === "inspector.open") {
+		for (const plugin of plugins) {
+			if (await plugin.available(context)) return plugin.open(context, launchFor(target, deps), params);
+		}
+		return result("No inspector plugin is available. Start a supported inspector host, or use inspector.command for a standalone command.", true);
+	}
+	const owner = plugins.find((plugin) => plugin.owns(context));
+	if (!owner) return result(`No inspector plugin owns this binding for async run ${target.runId}.`);
+	if (action === "inspector.status") {
+		return owner.status
+			? owner.status(context)
+			: result(`Inspector plugin '${owner.name}' does not support status for async run ${target.runId}.`, true);
+	}
+	return owner.close
+		? owner.close(context)
+		: result(`Inspector plugin '${owner.name}' does not support close for async run ${target.runId}.`, true);
+}