@diousk/pi-subagents-fast 0.20.0

package/dist/cross-extension-rpc.js

@@ -0,0 +1,138 @@
+/**
+ * Cross-extension RPC handlers for the subagents extension.
+ *
+ * Exposes ping, spawn, stop, and consume RPCs over the pi.events event bus,
+ * using per-request scoped reply channels.
+ *
+ * Reply envelope follows pi-mono convention:
+ *   success → { success: true, data?: T }
+ *   error   → { success: false, error: string }
+ *
+ * @see docs/rpc.md — the caller-facing integration reference: spawn options
+ * (including the fields spawnTopLevel strips), every error string, the
+ * completion-notification race, and what protocol version 2 does not promise.
+ */
+import { isTopLevelAgent } from "./agent-manager.js";
+import { resolveModel } from "./model-resolver.js";
+import { checkModelScope } from "./model-scope.js";
+/** RPC protocol version — bumped when the envelope or method contracts change. */
+export const PROTOCOL_VERSION = 2;
+/**
+ * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
+ * emit the reply envelope on `channel:reply:${requestId}`.
+ */
+function handleRpc(events, channel, fn) {
+    return events.on(channel, async (raw) => {
+        const params = raw;
+        try {
+            const data = await fn(params);
+            const reply = { success: true };
+            if (data !== undefined)
+                reply.data = data;
+            events.emit(`${channel}:reply:${params.requestId}`, reply);
+        }
+        catch (err) {
+            events.emit(`${channel}:reply:${params.requestId}`, {
+                success: false, error: err?.message ?? String(err),
+            });
+        }
+    });
+}
+/**
+ * Register ping, spawn, stop, and consume RPC handlers on the event bus.
+ * Returns unsub functions for cleanup.
+ */
+export function registerRpcHandlers(deps) {
+    const { events, pi, getCtx, manager } = deps;
+    const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
+        return { version: PROTOCOL_VERSION };
+    });
+    const unsubSpawn = handleRpc(events, "subagents:rpc:spawn", async ({ type, prompt, options }) => {
+        const ctx = getCtx();
+        if (!ctx)
+            throw new Error("No active session");
+        // Cross-extension RPC callers (e.g. pi-tasks TaskExecute) naturally
+        // forward serializable values, so options.model can be a string like
+        // "openai-codex/gpt-5.5". Resolve it to a real Model instance here
+        // — same pattern the scheduler path already uses — so the spawned
+        // agent's auth lookup doesn't crash with "No API key found for
+        // undefined".
+        let normalizedOptions = options ?? {};
+        // `!= null` on purpose: a JSON-forwarding caller can serialize an unset
+        // field as null, and the runner reads `options.model ?? default`, so null
+        // means "inherit" — not an override to resolve or scope-check.
+        const override = normalizedOptions.model;
+        if (override != null) {
+            const { modelRegistry, cwd } = ctx;
+            // Names the override the same way in both messages below; an object
+            // override would otherwise interpolate as "[object Object]".
+            const label = typeof override === "string" ? override : `${override.provider}/${override.id}`;
+            if (!modelRegistry) {
+                throw new Error(`Model override "${label}" provided but ctx.modelRegistry is unavailable`);
+            }
+            let model = override;
+            if (typeof override === "string") {
+                const resolved = resolveModel(override, modelRegistry);
+                if (typeof resolved === "string") {
+                    // resolveModel returns a human-readable error string when the
+                    // input doesn't match any available model. Surface it instead of
+                    // silently falling back so the caller sees the auth/typo issue.
+                    throw new Error(resolved);
+                }
+                model = resolved;
+                normalizedOptions = { ...normalizedOptions, model: resolved };
+            }
+            // A model on the RPC payload is an orchestrator-level choice, exactly
+            // like Agent({ model }) — so it gets the Agent tool's hard error, never
+            // the frontmatter warn (#240). The check reads the RESOLVED model:
+            // resolveModel is fuzzy, so a bare "sonnet" can land on a provider the
+            // caller never named. Frontmatter-pinned and parent-inherited models are
+            // resolved later, in agent-runner, and keep warn-and-proceed.
+            const verdict = checkModelScope({
+                model,
+                cwd: cwd ?? process.cwd(),
+                modelRegistry,
+                callerSupplied: true,
+                agentLabel: type,
+                modelInput: label,
+            });
+            if (verdict.kind === "error")
+                throw new Error(verdict.message);
+        }
+        const id = manager.spawn(pi, ctx, type, prompt, normalizedOptions);
+        // With isolation: "worktree" the agent starts asynchronously — wait for
+        // it, so a strict-isolation failure is still an error envelope rather
+        // than an id for an agent that never ran.
+        await manager.awaitStartup(id);
+        return { id };
+    });
+    const unsubStop = handleRpc(events, "subagents:rpc:stop", ({ agentId }) => {
+        const record = manager.getRecord(agentId);
+        if (!record)
+            throw new Error("Agent not found");
+        // Only the session's own agents are this RPC's to stop. A nested child or
+        // a workflow's agent is owned by something that is *waiting on it*, and
+        // aborting it out from under that owner turns another extension's stop
+        // into a failed step here. Defence in depth rather than a live hole: no
+        // RPC hands out agent ids, so a caller has no ordinary way to name one it
+        // does not own — but the guard is cheap and the id may leak some other
+        // way. Same refuse-what-we-should-not-touch stance as `consume` below.
+        if (!isTopLevelAgent(record))
+            throw new Error("Agent is owned by another agent or workflow");
+        // Not "not found" — the lookup above already proved it exists. `abort`
+        // returns false only for a record that is neither running nor queued,
+        // which is an agent that has already finished.
+        if (!manager.abort(agentId))
+            throw new Error("Agent is not running");
+    });
+    // A caller that has already shown the model an agent's result — pi-tasks'
+    // TaskOutput is the one in practice — says so here, so the completion
+    // notification for that same result is not delivered on top of it and does
+    // not cost the parent a turn. Deliberately outside the ping version
+    // handshake: an extension built against protocol v2 simply never calls it.
+    const unsubConsume = handleRpc(events, "subagents:rpc:consume", ({ agentId }) => {
+        if (!manager.consumeResult(agentId))
+            throw new Error("Agent not found or still running");
+    });
+    return { unsubPing, unsubSpawn, unsubStop, unsubConsume };
+}

package/dist/custom-agents.d.ts

@@ -0,0 +1,54 @@
+/**
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/, plus the shared .agents/agents/ workspace) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations.
+ */
+import type { AgentConfig } from "./types.js";
+/**
+ * Scan for custom agent .md files from multiple locations.
+ * Discovery hierarchy (higher priority wins):
+ *   1. Project:   <cwd>/.pi/agents/*.md (authoritative — also where /agents writes)
+ *   2. Workspace: <cwd>/.agents/agents/*.md (shared cross-tool .agents workspace, read-only)
+ *   3. Global:    $PI_CODING_AGENT_DIR/agents/*.md (default: ~/.pi/agent/agents/*.md)
+ *
+ * Project-level agents override global ones with the same name. On a name clash
+ * between the two project locations, .pi/agents wins — .pi stays the project
+ * authority; .agents/agents is an additional read location.
+ * Any name is allowed — names matching defaults (e.g. "Explore") override them.
+ *
+ * An agent's type comes from its frontmatter `name:`, falling back to the
+ * filename — Claude Code's rule, where "the filename doesn't have to match".
+ * Because the type is now declared rather than derived from a unique path, two
+ * files can claim the same one; the later load wins, as it always has for a
+ * filename clash, and `warnSkippedOverride` reports the substitution.
+ */
+export declare function loadCustomAgents(cwd: string, strict?: boolean): Map<string, AgentConfig>;
+/**
+ * Read and parse one agent file, or warn and return undefined for the caller to
+ * skip. One bad file must not take the whole extension down with it — an
+ * unparseable `.md` used to abort activation, so pi exited before the TUI.
+ *
+ * The path is as much of the fix as the recovery: a bare YAML error ("line 2,
+ * column 14") is unactionable when agents come from three directories at once,
+ * and the only other symptom is `Unknown agent type`, which reads like a typo.
+ *
+ * Under `strict` the same failure rethrows, still naming the path, so callers
+ * that opted into failing closed stop rather than run a substituted agent.
+ */
+/**
+ * Parse an agent file's frontmatter, tolerating a leading UTF-8 BOM.
+ *
+ * Editors across the Windows/CJK world write UTF-8 with a BOM by default, and
+ * pi's parser did not look past one before 0.84.3: the fence never matched, so
+ * the frontmatter came back empty and the *whole file* — YAML and all — became
+ * the body. An agent authored that way silently lost every field. `tools: none`
+ * going missing is the sharp edge: the agent registers with the default
+ * toolset rather than none, which is a wider grant than its author wrote.
+ *
+ * Stripped here rather than detected per pi version, because this is the only
+ * place agent files are read and the BOM is a file-encoding artifact, not
+ * content — normalising it at the boundary keeps one behaviour across the whole
+ * supported peer range instead of forking on what happens to be installed.
+ */
+export declare function parseAgentFrontmatter<T extends Record<string, unknown>>(content: string): {
+    frontmatter: T;
+    body: string;
+};

package/dist/custom-agents.js

@@ -0,0 +1,316 @@
+/**
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/, plus the shared .agents/agents/ workspace) and global ($PI_CODING_AGENT_DIR/agents/, default ~/.pi/agent/agents/) locations.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
+/**
+ * The one thing a declared `name:` may not contain, matching Claude Code
+ * exactly: it reserves `:` for plugin-scoped identifiers (`my-plugin:reviewer`)
+ * and refuses to load a file whose name uses one.
+ *
+ * Nothing else is rejected. Claude Code's docs describe names as "lowercase
+ * letters and hyphens", but that is guidance — the only stated load failure is
+ * the colon, so `name: Code Reviewer` must work here too. (The stricter
+ * letters/digits/underscore/hyphen regex in Claude Code applies to the Agent
+ * tool's spawn-time `name` parameter, which is a different field.) Mixed case
+ * has to be allowed regardless: the built-in types `Explore` and `Plan` use it,
+ * and a file must be able to override one.
+ */
+const RESERVED_IN_TYPE = ":";
+/**
+ * Scan for custom agent .md files from multiple locations.
+ * Discovery hierarchy (higher priority wins):
+ *   1. Project:   <cwd>/.pi/agents/*.md (authoritative — also where /agents writes)
+ *   2. Workspace: <cwd>/.agents/agents/*.md (shared cross-tool .agents workspace, read-only)
+ *   3. Global:    $PI_CODING_AGENT_DIR/agents/*.md (default: ~/.pi/agent/agents/*.md)
+ *
+ * Project-level agents override global ones with the same name. On a name clash
+ * between the two project locations, .pi/agents wins — .pi stays the project
+ * authority; .agents/agents is an additional read location.
+ * Any name is allowed — names matching defaults (e.g. "Explore") override them.
+ *
+ * An agent's type comes from its frontmatter `name:`, falling back to the
+ * filename — Claude Code's rule, where "the filename doesn't have to match".
+ * Because the type is now declared rather than derived from a unique path, two
+ * files can claim the same one; the later load wins, as it always has for a
+ * filename clash, and `warnSkippedOverride` reports the substitution.
+ */
+export function loadCustomAgents(cwd, strict = false) {
+    const globalDir = join(getAgentDir(), "agents");
+    const workspaceProjectDir = join(cwd, ".agents", "agents");
+    const projectDir = join(cwd, ".pi", "agents");
+    const agents = new Map();
+    loadFromDir(globalDir, agents, "global", strict); // lowest priority
+    loadFromDir(workspaceProjectDir, agents, "project", strict); // shared workspace
+    loadFromDir(projectDir, agents, "project", strict); // highest priority (overwrites)
+    warnedLastLoad = warnedThisLoad;
+    warnedThisLoad = new Set();
+    return agents;
+}
+/** Load agent configs from a directory into the map. */
+function loadFromDir(dir, agents, source, strict) {
+    if (!existsSync(dir))
+        return;
+    let files;
+    try {
+        files = readdirSync(dir).filter(f => f.endsWith(".md"));
+    }
+    catch {
+        return;
+    }
+    for (const file of files) {
+        const filenameType = basename(file, ".md");
+        const path = join(dir, file);
+        const parsed = readAgentFile(path, strict);
+        if (!parsed) {
+            warnSkippedOverride(filenameType, agents);
+            continue;
+        }
+        const { frontmatter: fm, body } = parsed;
+        // Claude Code's rule: `name:` IS the agent type, and the filename need not
+        // match. Absent, the filename stands in — Claude Code requires the field,
+        // but most files here predate it and must keep loading.
+        const declared = str(fm.name)?.trim();
+        if (declared?.includes(RESERVED_IN_TYPE)) {
+            // Refusing beats silently substituting: the file would otherwise load
+            // under its filename, so `Agent({subagent_type})` would succeed against
+            // an agent whose declared identity nothing honoured.
+            warnIfNew(`Agent file ${path} declares name "${declared}", which contains "${RESERVED_IN_TYPE}" — reserved for `
+                + "plugin-scoped identifiers. Rename it, or move the label to `display_name:`. Skipping.");
+            // No `warnSkippedOverride`: this file would have registered under its
+            // *declared* name, which nothing else can hold (a colon keeps it out of
+            // the registry), so it shadowed nothing. Passing the filename instead
+            // would report a substitution of an unrelated agent that never happened.
+            continue;
+        }
+        // `||`, not `??`: a quoted empty or all-whitespace `name:` would otherwise
+        // register the agent under the empty type — unspawnable, and it takes the
+        // filename-derived one down with it.
+        const name = declared || filenameType;
+        const { builtinToolNames, extSelectors } = parseToolsField(fm.tools);
+        agents.set(name, {
+            name,
+            // Only `display_name` now: `name` is the type, and `getConfig` already
+            // falls back to the type when no label is set — so a Claude Code file
+            // with `name: code-reviewer` still badges as "code-reviewer".
+            displayName: str(fm.display_name),
+            color: str(fm.color),
+            description: str(fm.description) ?? name,
+            builtinToolNames,
+            extSelectors,
+            disallowedTools: csvListOptional(fm.disallowed_tools),
+            extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+            excludeExtensions: csvListOptional(fm.exclude_extensions),
+            skills: inheritField(fm.skills ?? fm.inherit_skills),
+            model: str(fm.model),
+            thinking: str(fm.thinking),
+            serviceTier: parseServiceTier(fm.service_tier),
+            maxTurns: nonNegativeInt(fm.max_turns),
+            persistSession: fm.persist_session != null ? fm.persist_session === true : undefined,
+            outputTranscript: fm.output_transcript != null ? fm.output_transcript !== false : undefined,
+            sessionDir: str(fm.session_dir),
+            allowedSubagents: parseAllowedSubagents(fm.allowed_subagents),
+            systemPrompt: body.trim(),
+            promptMode: fm.prompt_mode === "append" ? "append" : "replace",
+            inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
+            runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
+            isolated: fm.isolated != null ? fm.isolated === true : undefined,
+            memory: parseMemory(fm.memory),
+            isolation: parseIsolation(fm.isolation),
+            enabled: fm.enabled !== false, // default true; explicitly false disables
+            source,
+            sourcePath: path,
+        });
+    }
+}
+/**
+ * Read and parse one agent file, or warn and return undefined for the caller to
+ * skip. One bad file must not take the whole extension down with it — an
+ * unparseable `.md` used to abort activation, so pi exited before the TUI.
+ *
+ * The path is as much of the fix as the recovery: a bare YAML error ("line 2,
+ * column 14") is unactionable when agents come from three directories at once,
+ * and the only other symptom is `Unknown agent type`, which reads like a typo.
+ *
+ * Under `strict` the same failure rethrows, still naming the path, so callers
+ * that opted into failing closed stop rather than run a substituted agent.
+ */
+/**
+ * Parse an agent file's frontmatter, tolerating a leading UTF-8 BOM.
+ *
+ * Editors across the Windows/CJK world write UTF-8 with a BOM by default, and
+ * pi's parser did not look past one before 0.84.3: the fence never matched, so
+ * the frontmatter came back empty and the *whole file* — YAML and all — became
+ * the body. An agent authored that way silently lost every field. `tools: none`
+ * going missing is the sharp edge: the agent registers with the default
+ * toolset rather than none, which is a wider grant than its author wrote.
+ *
+ * Stripped here rather than detected per pi version, because this is the only
+ * place agent files are read and the BOM is a file-encoding artifact, not
+ * content — normalising it at the boundary keeps one behaviour across the whole
+ * supported peer range instead of forking on what happens to be installed.
+ */
+export function parseAgentFrontmatter(content) {
+    return parseFrontmatter(content.startsWith("\uFEFF") ? content.slice(1) : content);
+}
+function readAgentFile(path, strict) {
+    try {
+        return parseAgentFrontmatter(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        if (strict)
+            throw new Error(`${path}: ${reason}`);
+        warnIfNew(`Skipping agent file ${path}: ${reason}`);
+        return undefined;
+    }
+}
+/**
+ * A skipped file that was overriding an already-loaded agent leaves the name
+ * pointing at a *different* file — its own prompt, model and tools. Nothing
+ * downstream can flag that: unlike an unknown type, the `Agent` call succeeds.
+ */
+function warnSkippedOverride(name, agents) {
+    const surviving = agents.get(name);
+    // Nothing shadowed, or what it shadowed is disabled: dispatch refuses the type
+    // either way (see resolveEnabledTypeIn), so there is no substitution to report.
+    if (!surviving?.sourcePath || surviving.enabled === false)
+        return;
+    warnIfNew(`Agent "${name}" now loads from ${surviving.sourcePath} instead`);
+}
+let warnedLastLoad = new Set();
+let warnedThisLoad = new Set();
+/**
+ * Agents reload on activation and again on every `Agent` call, so an unchanged
+ * problem would re-warn all session — over a painted TUI, since pi does not
+ * redirect console output. Compare against the previous load rather than every
+ * load ever, so a file that is fixed and then broken again still reports.
+ */
+function warnIfNew(message) {
+    warnedThisLoad.add(message);
+    if (warnedLastLoad.has(message))
+        return;
+    console.warn(`[pi-subagents] ${message}`);
+}
+// ---- Field parsers ----
+// All follow the same convention: omitted → default, "none"/empty → nothing, value → exact.
+/** Extract a string or undefined. */
+function str(val) {
+    return typeof val === "string" ? val : undefined;
+}
+/** Extract a non-negative integer or undefined. 0 means unlimited for max_turns. */
+function nonNegativeInt(val) {
+    return typeof val === "number" && val >= 0 ? val : undefined;
+}
+/**
+ * Parse a raw CSV field value into items, or undefined if absent/empty/"none".
+ */
+function parseCsvField(val) {
+    if (val === undefined || val === null)
+        return undefined;
+    const s = String(val).trim();
+    if (!s || s === "none")
+        return undefined;
+    const items = s.split(",").map(t => t.trim()).filter(Boolean);
+    return items.length > 0 ? items : undefined;
+}
+/**
+ * Parse the nested-delegation allowlist. Single field, default-off:
+ * omitted/empty/"none"/`false` → undefined (no nested tools); "all"/"*"/`true`
+ * → "all" (any enabled agent); csv → only the listed types.
+ *
+ * Booleans are accepted because `extensions:`/`skills:` take them and users
+ * generalize: without this, YAML's `true` stringifies into an agent type
+ * literally named "true", so the tools appear and every spawn is refused.
+ */
+function parseAllowedSubagents(val) {
+    if (typeof val === "boolean")
+        return val ? "all" : undefined;
+    const items = parseCsvField(val);
+    if (!items)
+        return undefined;
+    return items.some(i => i === "*" || i.toLowerCase() === "all") ? "all" : items;
+}
+/**
+ * Parse a comma-separated list field with defaults.
+ * omitted → defaults; "none"/empty → []; csv → listed items.
+ */
+function csvList(val, defaults) {
+    if (val === undefined || val === null)
+        return defaults;
+    return parseCsvField(val) ?? [];
+}
+/**
+ * Partition the `tools:` CSV into the built-in tool allowlist and raw `ext:` selectors.
+ * `*` (and the case-insensitive alias `all`, for `tools: all`) expands to all
+ * built-ins; plain entries are built-in names; `ext:` entries are extension-tool
+ * selectors parsed later by the runner. omitted → all built-ins, no selectors.
+ * `tools:` present with only `ext:` entries → zero built-ins (use `*`).
+ */
+function parseToolsField(val) {
+    const entries = csvList(val, BUILTIN_TOOL_NAMES);
+    const isWildcard = (e) => e === "*" || e.toLowerCase() === "all";
+    const hasWildcard = entries.some(isWildcard);
+    const plain = entries.filter(e => !isWildcard(e) && !e.startsWith("ext:"));
+    const extEntries = entries.filter(e => e.startsWith("ext:"));
+    return {
+        builtinToolNames: hasWildcard ? [...new Set([...BUILTIN_TOOL_NAMES, ...plain])] : plain,
+        extSelectors: extEntries.length > 0 ? extEntries : undefined,
+    };
+}
+/**
+ * Parse an optional comma-separated list field.
+ * omitted → undefined; "none"/empty → undefined; csv → listed items.
+ */
+function csvListOptional(val) {
+    return parseCsvField(val);
+}
+/**
+ * Parse a memory scope field.
+ * omitted → undefined; "user"/"project"/"local" → MemoryScope.
+ */
+function parseMemory(val) {
+    if (val === "user" || val === "project" || val === "local")
+        return val;
+    return undefined;
+}
+/** Parse the OpenAI Responses/Codex `service_tier` frontmatter field. */
+function parseServiceTier(val) {
+    if (val === "auto" || val === "default" || val === "flex" || val === "priority" || val === "scale") {
+        return val;
+    }
+    return undefined;
+}
+/**
+ * Parse the `isolation` frontmatter field.
+ *
+ * `off` is kept as a value rather than folded into `undefined` because the two
+ * do not mean the same thing here: agent config outranks tool-call params, so
+ * `off` vetoes a caller's `worktree` while an absent field lets it through.
+ *
+ * pi's frontmatter parser is not YAML 1.1 — bare `off` and `no` arrive as
+ * strings and only `false` becomes a boolean — so all three spellings are
+ * accepted rather than leaving an author's intent silently dropped. Anything
+ * else stays `undefined`, as before.
+ */
+function parseIsolation(val) {
+    if (val === "worktree")
+        return "worktree";
+    if (val === "off" || val === "none" || val === "no" || val === false)
+        return "off";
+    return undefined;
+}
+/**
+ * Parse an inherit field (extensions, skills).
+ * omitted/true → true (inherit all); false/"none"/empty → false; csv → listed names.
+ */
+function inheritField(val) {
+    if (val === undefined || val === null || val === true)
+        return true;
+    if (val === false || val === "none")
+        return false;
+    const items = csvList(val, []);
+    return items.length > 0 ? items : false;
+}

package/dist/default-agents.d.ts

@@ -0,0 +1,7 @@
+/**
+ * default-agents.ts — Embedded default agent configurations.
+ *
+ * These are always available but can be overridden by user .md files with the same name.
+ */
+import type { AgentConfig } from "./types.js";
+export declare const DEFAULT_AGENTS: Map<string, AgentConfig>;

package/dist/default-agents.js

@@ -0,0 +1,122 @@
+/**
+ * default-agents.ts — Embedded default agent configurations.
+ *
+ * These are always available but can be overridden by user .md files with the same name.
+ */
+const READ_ONLY_TOOLS = ["read", "bash", "grep", "find", "ls"];
+export const DEFAULT_AGENTS = new Map([
+    [
+        "general-purpose",
+        {
+            name: "general-purpose",
+            displayName: "Agent",
+            description: "General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.",
+            // builtinToolNames omitted — means "all available tools" (resolved at lookup time)
+            // inheritContext / runInBackground / isolated omitted — strategy fields, callers decide per-call.
+            // Setting them to false would lock callsite intent (see resolveAgentInvocationConfig in invocation-config.ts).
+            extensions: true,
+            skills: true,
+            systemPrompt: "",
+            promptMode: "append",
+            isDefault: true,
+        },
+    ],
+    [
+        "Explore",
+        {
+            name: "Explore",
+            displayName: "Explore",
+            description: "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions.",
+            builtinToolNames: READ_ONLY_TOOLS,
+            extensions: true,
+            skills: true,
+            // Fast/cheap model for read-only search. Provider-preferred but resilient:
+            // resolveModel matches this fuzzily (date-stamp optional) and falls back to
+            // the same model under another provider if anthropic doesn't expose it.
+            model: "anthropic/claude-haiku-4-5",
+            systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+- Make independent tool calls in parallel for efficiency
+- Adapt search approach based on thoroughness level specified
+
+# Output
+- Use absolute file paths in all references
+- Report findings as regular messages
+- Do not use emojis
+- Be thorough and precise`,
+            promptMode: "replace",
+            isDefault: true,
+        },
+    ],
+    [
+        "Plan",
+        {
+            name: "Plan",
+            displayName: "Plan",
+            description: "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.",
+            builtinToolNames: READ_ONLY_TOOLS,
+            extensions: true,
+            skills: true,
+            systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a software architect and planning specialist.
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans.
+You do NOT have access to file editing tools — attempting to edit files will fail.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+# Planning Process
+1. Understand requirements
+2. Explore thoroughly (read files, find patterns, understand architecture)
+3. Design solution based on your assigned perspective
+4. Detail the plan with step-by-step implementation strategy
+
+# Requirements
+- Consider trade-offs and architectural decisions
+- Identify dependencies and sequencing
+- Anticipate potential challenges
+- Follow existing patterns where appropriate
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+
+# Output Format
+- Use absolute file paths
+- Do not use emojis
+- End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- /absolute/path/to/file.ts - [Brief reason]`,
+            promptMode: "replace",
+            isDefault: true,
+        },
+    ],
+]);