@ferris1225/pi-subagents 2.3.1 → 4.0.0

package/src/dispatch.ts

@@ -1,11 +1,8 @@
 /**
- * The `subagent` tool: dispatches explore/worker/cleaner/reviewer agents as isolated pi
+ * The `subagent` tool: dispatches explorer/worker/cleaner/reviewer agents as isolated pi
  * child processes, single or parallel. Owns the public dispatch contract,
  * per-run status tracking, the auto-fix chain (REVIEW_FAIL → worker → re-review),
  * and completion delivery. Stable thread generations live in thread-lifecycle.ts.
- *
- * Vision: a task flagged `vision: true` uses the configured vision model, then
- * hands directly to the current main-window model on model/provider failure.
  */
 
 import { StringEnum } from "@earendil-works/pi-ai";
@@ -58,9 +55,6 @@ export { FORK_CONTINUATION_PROMPT, isWorktreeCapableAgent } from "./thread-lifec
 
 const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
 
-const VISION_DESCRIPTION =
-	"Set true when the task may require viewing images (screenshots, mockups, designs) — the configured vision model is used first, then model-level failures hand directly to the current main-window model. A task that names an image file or describes frontend/UI work (Vue/React, mockups, screenshots, page styling) is dispatched as vision automatically";
-
 const ISOLATION_DESCRIPTION =
 	"Filesystem isolation: shared uses the caller's working tree; worktree creates a detached temporary Git worktree (write-capable agents, including worker and cleaner, only)";
 
@@ -75,7 +69,6 @@ const TaskItem = Type.Object({
 		description: "Self-contained task to delegate (the agent has no memory of this conversation)",
 	}),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
-	vision: Type.Optional(Type.Boolean({ description: VISION_DESCRIPTION })),
 	isolation: IsolationSchema,
 });
 
@@ -86,7 +79,6 @@ const SubagentParams = Type.Object({
 	),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
-	vision: Type.Optional(Type.Boolean({ description: VISION_DESCRIPTION })),
 	isolation: IsolationSchema,
 });
 
@@ -95,27 +87,6 @@ export function defaultIsolationMode(mode: "single" | "parallel", agentName: str
 	return mode === "parallel" && agentName === "worker" ? "worktree" : "shared";
 }
 
-const IMAGE_FILE_PATTERN = /\.(?:png|jpe?g|webp|gif|bmp|tiff?|avif)\b/i;
-/** Frontend/UI work: the agent may screenshot and visually verify what it
- * builds, and the model cannot be swapped mid-run — vision must be on at
- * spawn. Only language-neutral signals: code terms and file names stay in
- * English even in non-English briefs; purely semantic wording is the LLM's
- * job via the vision flag, not a per-language keyword list. Word boundaries
- * keep ordinary words (build, guide, reactor) from matching. */
-const FRONTEND_PATTERN = /\b(?:vue|react|svelte|angular|nuxt|next\.?js|vite|tailwind|screenshots?|mockups?|wireframes?|UI)\b/i;
-const FRONTEND_FILE_PATTERN = /\.(?:vue|html?|css|svg)\b/i;
-
-/** Deterministic vision fallback: a brief that names an image file or describes
- * frontend/UI work is vision work even when the dispatcher forgot the flag —
- * prompting alone cannot guarantee `vision: true`, and a non-vision model can
- * neither see reference images nor visually verify what it builds. */
-export function taskImpliesVision(task: string): boolean {
-	return IMAGE_FILE_PATTERN.test(task) || FRONTEND_FILE_PATTERN.test(task) || FRONTEND_PATTERN.test(task);
-}
-
-const wantsVision = (flag: boolean | undefined, task: string): boolean =>
-	flag === true || taskImpliesVision(task);
-
 const autoFixRootTails = new Map<string, Promise<void>>();
 
 async function canonicalAutoFixRoot(cwd: string): Promise<string> {
@@ -163,34 +134,15 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 		name: "subagent",
 		label: "Subagent",
 		description: [
-			"Delegate a discrete, self-contained task to a specialized sub-agent running in an ISOLATED context window.",
-			"Built-in roles (only configured enabled agents can dispatch): explore (read-only codebase recon), worker (implement/fix/refactor/test, full tools), cleaner (explicit evidence-first cleanup, full/write tools), reviewer (adversarial pre-commit gate, read-only).",
-			"When cleaner is enabled, route explicit cleanup intent in any language (for example dead code, redundancy, simplification, or over-engineering), including a requested periodic cleanup pass. Audit/find/inspect/report is read-only evidence, while explicit remove/clean/simplify/refactor permits verified edits. Generic code review goes to reviewer. Never route cleaner by PR count or as the pre-commit gate; reviewer reviews its edits.",
-			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
-			"Isolation: single tasks default to shared; parallel worker tasks default to detached Git worktrees unless isolation: shared is explicit. Cleaner is write-capable and can opt into worktree isolation; explore/reviewer cannot use it.",
-			"Use subagent_control to steer, retarget, park, resume, or fork a thread by its stable run id.",
-			"It starts agents in the background and immediately returns control to the main window; completion messages automatically wake the main agent to continue.",
-			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output).",
-			"Results arrive as wake-up messages automatically — you do NOT need to wait. If you must get a result in-turn, subagent_wait is a non-blocking lookup by default (pass timeoutMs to block).",
-			"Vision: set vision: true when the task may require viewing images (screenshots, mockups, design files — e.g. frontend work) — the configured vision model is used first, then model-level failures hand directly to the current main-window model.",
+			"Dispatch enabled specialized agents as isolated leaf Pi child processes, singly or in parallel.",
+			"Built-ins: explorer for broad read-only reconnaissance; worker for implementation; cleaner only for explicitly authorized cleanup/removal/simplification edits; reviewer for generic read-only assessments and pre-commit gates.",
+			"Work starts in the background; completion automatically resumes the main agent and is already shown to the user, so do not poll or restate it. Give each child a self-contained brief because it has no conversation memory.",
+			"Single tasks default to shared; parallel workers default to detached Git worktrees. Only write-capable agents can use worktree isolation, and failures never fall back silently to shared.",
+			"A selected-model or provider failure continues the retained session on the current main model; ordinary tool/task failures do not.",
+			"Use subagent_control to steer, retarget, park, resume, or fork by stable run id.",
 		].join(" "),
 		promptSnippet:
-			"Start background subagents: explore (read-only search), worker (implement), cleaner (explicit evidence-first cleanup), reviewer (pre-commit review); completion automatically resumes the main agent. Simple tasks: use direct tools, not subagents.",
-		promptGuidelines: [
-			"Delegate only when an isolated context genuinely pays: broad exploration, a self-contained implementation, explicit evidence-first cleanup, or a review gate. Handle simple lookups and one-line edits inline with direct tools — never spawn a sub-agent for them.",
-			"Use subagent with agent 'explore' for broad or open-ended code search before large changes; a targeted 'where is X' is a direct grep/read.",
-			"Treat explore output as a retrieval index, not authority: re-read load-bearing files before editing or deciding deletion, security, compatibility, persistence, or dynamic reachability. The cheapest model can cost more through rework on complex dynamic, concurrent, migration, or security-sensitive code; choose a stronger model or specialist there.",
-			"Use subagent with agent 'worker' for a self-contained implementation task worth a separate context; it plans internally.",
-			"When cleaner is enabled, use subagent with agent 'cleaner' only for explicit cleanup intent in any language (for example dead code, redundancy, simplification, or over-engineering) or a requested periodic cleanup pass. Audit/find/inspect/report means read-only ranked evidence; apply only for explicit remove/clean/simplify/refactor wording. Generic code review goes to reviewer. Never trigger cleaner from PR count or as a pre-commit gate; send non-trivial cleaner edits to reviewer.",
-			"Use subagent with agent 'reviewer' for the fresh read-only gate before reporting non-trivial work done or committing, including after cleaner edits.",
-			"subagent launches work in the background and ends the current turn; when a result arrives, the main agent is automatically resumed with it.",
-			"Run independent tasks in parallel by passing a tasks array to subagent; parallel worker items default to isolation: worktree so their edits are integrated independently. Pass isolation: shared only when workers intentionally need the caller's live uncommitted tree.",
-			"Use isolation: worktree only for worker, cleaner, or another write-capable agent and only inside a Git repository with a committed HEAD; parallel worker tasks default to worktree, while cleaner must opt in. Setup or integration failures never silently fall back to shared.",
-			"NEVER sleep or poll, and do NOT call subagent_wait to hold the turn — subagent ends the turn immediately and the result arrives as a message that wakes you automatically (even mid-turn). Ending your turn is the default and the only correct way to wait.",
-			"If you must keep the turn for a result, call subagent_wait with an explicit timeoutMs (non-blocking by default) — never bash sleep/timeout to wait for a sub-agent.",
-			"When a delegated task may require viewing images (frontend screenshots, mockups, design comparisons), pass vision: true and give the sub-agent the exact image paths — it reads them with its read tool. The configured vision model is used first; model-level failures hand directly to the current main-window model.",
-			"When a sub-agent result arrives it is already shown to the user — do NOT restate, paraphrase, or summarize it; reply with only your own conclusion or next action (often just one line), since duplicating the result wastes tokens for nothing.",
-		],
+			"Dispatch isolated background agents: explorer (recon), worker (implementation), cleaner (authorized cleanup), reviewer (read-only assessment/gate); results resume automatically. Use direct tools for trivial work.",
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
@@ -320,13 +272,10 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				executionCwd: string,
 				signal: AbortSignal,
 				meta: RunChainMeta,
-				vision = false,
 			): Promise<{ runId?: number; result: SingleResult }> => {
 				const agent = agents.find((candidate) => candidate.name === agentName);
 				if (!agent) return { result: failedStartResult(agentName, task, `Unknown agent: "${agentName}".`) };
-				// Vision chains use the vision override first; every model-level failure
-				// hands directly to the current main model with re-clamped thinking.
-				const route = resolveDispatchModelRoute(agent, config, ctx, vision);
+				const route = resolveDispatchModelRoute(agent, config, ctx);
 				const thinkingLevel = route.thinkingLevel;
 				const runId = monitor.addRun(agent.name, task, route.agent.model, thinkingLevel, meta);
 				const onLive = makeLiveHandler(runId);
@@ -397,7 +346,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				parentGroupId: string,
 				parentRunId: number,
 				executionCwd: string,
-				vision = false,
 			): void => {
 				const parentThreadAtStart = runtime.threads.get(parentRunId);
 				if (!parentThreadAtStart) return;
@@ -446,7 +394,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 								groupId: parentGroupId,
 								relationLabel: `fix round ${round}`,
 								parentRunId,
-							}, vision);
+							});
 							// Preserve the newest sub-step before checking chain ownership. A
 							// destructive stop invalidates ownsParent() while this child is
 							// aborting, and its partial output must become the parent's stopped
@@ -470,7 +418,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 								groupId: parentGroupId,
 								relationLabel: `re-review round ${round}`,
 								parentRunId,
-							}, vision);
+							});
 							if (
 								runtime.threads.get(parentRunId) === parentThreadAtStart &&
 								parentThreadAtStart.generation === parentGeneration
@@ -649,7 +597,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 						item.agent,
 						item.task,
 						item.cwd,
-						wantsVision(item.vision, item.task),
 						defaultIsolationMode("parallel", item.agent, item.isolation as IsolationMode | undefined),
 					));
 				}
@@ -687,7 +634,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 				params.agent as string,
 				params.task as string,
 				params.cwd,
-				wantsVision(params.vision, params.task as string),
 				defaultIsolationMode("single", params.agent as string, params.isolation as IsolationMode | undefined),
 			);
 			if (result.exitCode !== -1) {

package/src/index.ts

@@ -69,7 +69,7 @@ export default function (pi: ExtensionAPI): void {
 	registerLookupTools(pi, runtime);
 
 	pi.registerCommand("subagents-setup", {
-		description: "Configure pi-subagents: agents, selected models, capability-aware thinking, vision, and runtime settings",
+		description: "Configure pi-subagents: agents, selected models, capability-aware thinking, and runtime settings",
 		handler: async (_args, ctx) => {
 			await runSetup(ctx, configPath);
 		},

package/src/models.ts

@@ -1,7 +1,7 @@
 /*
  * Model routing, capability-aware thinking, and setup-picker helpers.
  *
- * Runtime has one explicit fallback only: a configured agent/vision model hands
+ * Runtime has one explicit fallback only: a configured agent model hands
  * off directly to the current main-window model. Setup lists only currently
  * available models and derives thinking choices from Pi's model metadata.
  */
@@ -20,8 +20,6 @@ export type ModelContext = Pick<ExtensionContext, "model" | "modelRegistry"> &
 
 export const CURRENT_MAIN_MODEL = "__current_main_model__";
 
-export type ModelPickerSlot = "agent" | "vision";
-
 export interface ModelPickerItem {
 	value: string;
 	label: string;
@@ -136,11 +134,10 @@ function modelCapabilities(model: ModelListEntry): string {
 	return `${input} · thinking: ${thinking}`;
 }
 
-/** Build one searchable list for agent or vision selection. Only models Pi
+/** Build one searchable list for agent model selection. Only models Pi
  * currently reports as available are supplied by setup. */
 export function buildModelPickerItems(options: {
 	models: readonly ModelListEntry[];
-	slot: ModelPickerSlot;
 	configuredRef?: string;
 	mainRef?: string;
 }): ModelPickerItem[] {
@@ -153,7 +150,6 @@ export function buildModelPickerItems(options: {
 	}
 
 	const refs = [...byRef.keys()]
-		.filter((ref) => options.slot !== "vision" || byRef.get(ref)?.input.includes("image") === true)
 		.sort((left, right) => {
 			const leftRank = left === configuredRef ? 0 : left === mainRef ? 1 : 2;
 			const rightRank = right === configuredRef ? 0 : right === mainRef ? 1 : 2;
@@ -163,9 +159,7 @@ export function buildModelPickerItems(options: {
 	const dynamic: ModelPickerItem = {
 		value: CURRENT_MAIN_MODEL,
 		label: "Current main model (dynamic)",
-		description: options.slot === "vision"
-			? "Clear vision override; use the current main model for image tasks"
-			: "Clear agent override; use the current main model dynamically",
+		description: "Clear agent override; use the current main model dynamically",
 	};
 	const items: ModelPickerItem[] = [dynamic];
 	for (const ref of refs) {

package/src/monitor.ts

@@ -165,7 +165,7 @@ function tailGraphemes(segments: string[], maxWidth: number): string {
  * One-line task preview, capped by `maxWidth` display columns (default 80).
  * `keysOnly` (default): extracted key fragments (paths, quoted phrases,
  * symbols) are shown bare — the agent name is already displayed next to the
- * task line, so templated prose ("explore: trace how ...") adds nothing.
+ * task line, so templated prose ("explorer: trace how ...") adds nothing.
  * `keysOnly: false` keeps the prose as `head…tail` (used for completion
  * messages, where the Task line is the reader's only context).
  * Grapheme-safe — CJK, ZWJ emoji and combining sequences are never split.

package/src/prompt.ts

@@ -1,84 +1,97 @@
 /**
- * Builds the delegation directive injected into the parent model's system prompt
- * via the `before_agent_start` hook. This is the lever that makes the main model
- * actually USE the subagent tool proactively (pi never shows it the per-agent
- * descriptions otherwise).
- *
- * The directive is a self-contained replacement for the "Sub-agent Dispatch" and
- * "Review, Verification & Commit" sections users otherwise keep in a global
- * AGENTS.md — so installing this extension lets them delete those sections without
- * losing the behavior. (Other AGENTS.md sections — Behavior, Git & Security,
- * platform/language rules — are unrelated and stay put.)
+ * Builds the authoritative delegation directive injected into the parent model's
+ * system prompt via `before_agent_start`. Tool metadata stays intentionally
+ * minimal so role/process guidance is not paid for twice.
  */
 
 import type { AgentConfig } from "./agents.ts";
 import { formatCatalogEntry } from "./agents.ts";
 
-/** Compact role routing hints, emitted only for roles that are enabled. */
-const ROLE_ROUTING: Record<string, string> = {
-	explore: "explore — codebase reconnaissance: broad/open-ended search, multi-file lookups, mapping unfamiliar code, tracing symbols/dependencies (read-only, competent fast model); NOT for one-line lookups.",
-	worker: "worker — implement/fix/refactor/test a self-contained task worth a separate context (full tools; plans internally).",
-	cleaner: "cleaner — evidence-first cleanup for explicit cleanup intent in any language (for example dead code, redundancy, simplification, or over-engineering) or a requested periodic cleanup pass; audit/find/inspect/report is read-only, while explicit remove/clean/simplify/refactor wording permits verified edits; never PR-count or pre-commit driven (reviewer remains the gate).",
-	reviewer: "reviewer — adversarial pre-commit review of a diff (read-only; independent context).",
-};
+function bullets(lines: readonly string[]): string {
+	return lines.map((line) => `- ${line}`).join("\n");
+}
 
 export function buildDelegationDirective(agents: AgentConfig[]): string {
 	if (agents.length === 0) return "";
 
 	const catalog = agents.map(formatCatalogEntry).join("\n");
-	const routing = agents
-		.map((a) => ROLE_ROUTING[a.name])
-		.filter((line): line is string => Boolean(line))
-		.map((line) => `- ${line}`)
-		.join("\n");
-	const hasExplore = agents.some((a) => a.name === "explore");
-	const hasCleaner = agents.some((a) => a.name === "cleaner");
-	const hasReviewer = agents.some((a) => a.name === "reviewer");
+	const hasExplorer = agents.some((agent) => agent.name === "explorer");
+	const hasWorker = agents.some((agent) => agent.name === "worker");
+	const hasCleaner = agents.some((agent) => agent.name === "cleaner");
+	const hasReviewer = agents.some((agent) => agent.name === "reviewer");
 	const hasMultiple = agents.length > 1;
+	const worktreeTargets = hasWorker && hasCleaner
+		? "worker, cleaner, or another"
+		: hasWorker
+			? "worker or another"
+			: hasCleaner
+				? "cleaner or another"
+				: "a";
+
+	const dispatchRules = [
+		"Handle simple work inline with direct tools: one-line lookups, known-target reads/edits, and quick questions do not justify a child process.",
+		...(hasExplorer
+			? [
+				"Use `explorer` proactively when reconnaissance becomes broad or crosses files: mapping unfamiliar code, tracing symbols/dependencies, or answering multi-file location/reference questions. Treat its output only as a retrieval index; re-read load-bearing files before edits or decisions about deletion, security, compatibility, persistence, or dynamic reachability. Use a stronger model/specialist for complex dynamic, concurrent, migration, or security-sensitive analysis.",
+			]
+			: []),
+		...(hasWorker
+			? ["Use `worker` for a self-contained implementation, fix, refactor, or test task whose separate context pays for itself."]
+			: []),
+		...(hasCleaner
+			? [
+				`Use \`cleaner\` only when the user explicitly authorizes cleanup/removal/simplification edits, including a requested maintenance pass. It gathers evidence, then applies every safe proven in-scope cut; zero edits is valid. Generic or read-only audit, inspect, report, review, code-health, plan, proposed-solution, or cleanup-candidate assessment goes to ${hasReviewer ? "`reviewer`" : "direct main-context inspection because `reviewer` is disabled"}. Never dispatch cleaner by PR count or as the pre-commit gate.`,
+			]
+			: []),
+		...(hasReviewer
+			? [
+				`Use \`reviewer\` for generic/read-only assessments and as the fresh independent pre-commit gate for non-trivial diffs${hasCleaner ? ", including cleaner edits" : ""}. Advisory findings do not authorize follow-up edits; only gate verdicts can enter auto-fix.`,
+			]
+			: []),
+		"Brief every child with the complete goal, exact paths, constraints, and expected output. It has no memory of this conversation.",
+		"Children are leaf processes without delegation tools. Do not ask them to spawn sub-agents; use `subagent_control fork` on a parked/settled retained thread for an independent continuation.",
+		...(hasMultiple
+			? [
+				"Dispatch independent work in one `tasks` array and let the resumed main agent start dependent work only after prerequisites finish.",
+			]
+			: []),
+		`Filesystem isolation: single tasks default to shared${hasWorker ? "; parallel worker tasks default to detached Git worktrees" : ""}${hasCleaner ? "; cleaner defaults to shared" : ""}. Request \`isolation: "worktree"\` only for ${worktreeTargets} write-capable agent in a Git repository with committed HEAD. Read-only agents reject it, and setup/integration failure never falls back silently to shared.`,
+		"A configured child model/provider failure automatically continues the same retained session on the current main model; do not redispatch. Ordinary tool/task failures stay on the selected model.",
+		"Trust but verify: inspect actual changes/results before reporting completion.",
+	];
+
+	const handoffRules = [
+		"Dispatch returns immediately and ends this turn. Never sleep, poll, or call `subagent_wait` to hold the turn; results arrive as messages that automatically resume the main agent, even mid-turn.",
+		"Use `subagent_wait` with explicit `timeoutMs` only when the user specifically asks you to remain in-turn and wait. Its default lookup is non-blocking.",
+		"A result is already shown to the user. Do not restate, paraphrase, or re-summarize it; add only your conclusion or next action, often one line.",
+		"A delivered result does not mean siblings are finished. Before declaring the overall task done, use `subagent_status` to confirm that no runs remain active.",
+	];
+
+	const verificationRules = [
+		"Never report an unrun check as passed; identify unavailable checks and pre-existing failures honestly.",
+		...(hasReviewer
+			? [
+				"Send every non-trivial diff through one fresh read-only `reviewer` gate before reporting done. Resolve every finding; do not bypass the configured auto-fix/re-review cap.",
+				"Use multi-model cross-review only when explicitly requested or for genuinely high-risk security, unsafe/FFI, persistence-migration, or concurrency changes.",
+			]
+			: []),
+		"Commit or push only when explicitly requested, applicable checks pass, and no review finding remains unresolved.",
+	];
 
 	return `
 ## Sub-agent delegation (pi-subagents)
 
-You have a \`subagent\` tool that starts specialized agents in ISOLATED background processes.
-It immediately ends the current main-agent turn so the user can keep working. When a child
-finishes, its result is sent back as a message that automatically resumes the main agent;
-if the main agent is busy, the result waits as a follow-up.
-
-NEVER run sleep, wait, or polling commands (e.g. Start-Sleep, sleep, timeout), and do NOT
-call subagent_wait to hold the turn — dispatching already ended it, and results arrive as
-messages that resume the main agent automatically (even mid-turn). Ending your turn is the
-default and the only correct way to wait; subagent_wait blocks the turn so the user cannot
-give you other work meanwhile. It is non-blocking by default: settled results return
-immediately, active runs return a "still running — end your turn" note. Pass an explicit
-timeoutMs only when you must stay in the turn (e.g. the user asked you to wait).
+The \`subagent\` tool starts specialized leaf agents in isolated Pi child processes and context windows. It returns immediately; completion messages automatically resume the main agent.
 
 Available agents:
 ${catalog}
 
-${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
-- Handle SIMPLE work INLINE with direct tools: a one-line lookup, single edit, or quick question is a grep/read/edit in the main context — never a sub-agent. Sub-agents cost startup time, tokens, and a context switch.
-- Use \`explore\` PROACTIVELY for codebase reconnaissance: mapping an unfamiliar area, multi-file lookups, tracing symbols across modules, or any "where is X / which files reference Y" question that would take several greps or reading multiple files. It should run on a competent fast code model and returns compressed findings, saving main-context space.
-- Delegate only when isolation genuinely pays: a self-contained implementation/fix with its own validation (worker)${hasCleaner ? ", explicit evidence-first cleanup (cleaner)" : ""}, or a fresh-context review gate (reviewer).
-${hasCleaner ? "- Route explicit cleanup intent in any language to `cleaner` (for example dead code, redundancy, simplification, or over-engineering), including a requested periodic maintenance pass. Audit/find/inspect/report wording means read-only evidence; apply only for explicit remove/clean/simplify/refactor wording. Generic code review without cleanup intent goes to `reviewer`. Never dispatch cleaner by PR count or automatically as the pre-commit gate; `reviewer` separately reviews cleaner edits.\n" : ""}- When in doubt, start with a direct tool call in the main context; escalate to \`explore\` as soon as the search turns broad or crosses multiple files.
-- For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
-${hasMultiple ? `- Run INDEPENDENT tasks in parallel: one subagent call with a \`tasks\` array, and track them with your todo list. Parallel worker items default to detached Git worktree isolation; pass \`isolation: "shared"\` only when a worker intentionally needs the caller's live uncommitted tree.${hasCleaner ? " Cleaner is also write-capable and may use explicit worktree isolation." : ""} Let the automatically resumed main agent launch dependent work only after its prerequisite result arrives (e.g. explore, then ${hasCleaner ? "worker/cleaner" : "worker"}, then reviewer).\n` : ""}- Single dispatch stays in the shared working tree by default. Use \`isolation: "worktree"\` only for ${hasCleaner ? "worker, cleaner, or another" : "worker or another"} write-capable agent in a Git repository; never request it for explore/reviewer, and never silently retry shared after setup fails.
-- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
-- Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool. Use \`subagent_control fork\` on a parked/settled retained thread when you need an independent continuation with preserved context and a new run id.
-- Trust but verify: a sub-agent's summary describes intent, not outcome. Check the actual changes/results before reporting work done.
-${hasExplore ? "- Treat `explore` findings as a retrieval index, never as sole proof for edits, deletion, security, compatibility, persistence, or dynamic reachability. Re-read load-bearing files before acting. An underpowered model can be false economy on complex dynamic, concurrent, migration, or security-sensitive code; use a stronger model or specialist there.\n" : ""}
-Vision tasks:
-- Judge whether a delegated task may require viewing images (frontend screenshots, mockups, design files, visual regression comparisons). If it might, pass \`vision: true\` in the subagent call and give the sub-agent the exact image paths — it reads them with its read tool. Naming an image file or describing frontend/UI work (Vue/React page, mockup, page styling) dispatches as vision automatically, but keep passing the flag for image work described without those signals.
-- \`vision: true\` runs the sub-agent on the vision-capable model configured in /subagents-setup; when none is configured it falls back to the main session's current model. Do not skip the flag because the agent's default model looks fast — a non-vision model cannot see the images.
+Dispatch:
+${bullets(dispatchRules)}
 
-Result handoff (do not re-state):
-- A sub-agent's result arrives as a message that is already shown to the user. Do NOT restate, paraphrase, or re-summarize its findings in your reply — that just burns tokens duplicating what is already visible. The user can read the result above.
-- Reply only with what you ADD: your own conclusion, the next action you are taking, or a one-line acknowledgement. When the result already answers the user, a single sentence is enough — then end your turn or proceed.
-- Read the result and act on it (verify, continue, commit). Keep your own output short.
-- A result arriving does NOT mean all work is finished: sub-agents run in the background and siblings may still be active (a delivery names any still-running runs). Do not report the overall task complete until no runs are active — call subagent_status to confirm before saying Done.
+Result handoff:
+${bullets(handoffRules)}
 
-Review & verification:
-- Never report an unrun check as passed; report it as unavailable or as a pre-existing failure.
-${hasReviewer ? `- For non-trivial diffs${hasCleaner ? " (including cleaner edits)" : ""}, run one fresh read-only \`reviewer\` sub-agent before reporting done. Fix every finding the reviewer reports and re-review at most once.
-- Use multi-model cross-review only when explicitly requested or for genuinely high-risk changes (security, unsafe/FFI, persistence-migration, concurrency). Reviewers are read-only; only the main agent edits.
-` : ""}- Commit or push only when explicitly requested, applicable checks pass, and no unresolved review findings remain.`;
+Review and verification:
+${bullets(verificationRules)}`;
 }

package/src/runtime.ts

@@ -52,7 +52,6 @@ export interface SubagentThread {
 	cwd: string;
 	/** Actual child cwd (the equivalent path inside an isolated worktree). */
 	executionCwd: string;
-	vision: boolean;
 	thinkingLevel?: ThinkingLevel;
 	isolation: IsolationMode;
 	worktree?: WorktreeIsolation;