@diousk/pi-subagents-fast 0.20.0

package/dist/nested-tools.js

@@ -0,0 +1,299 @@
+import { defineTool, } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { abortable } from "./abortable.js";
+import { buildAgentRegistry, getAgentConfigIn, getAvailableTypesIn, resolveEnabledTypeIn, resolveTypeIn, } from "./agent-types.js";
+import { loadCustomAgents } from "./custom-agents.js";
+import { isolationParam, resolveAgentInvocationConfig } from "./invocation-config.js";
+import { resolveModel } from "./model-resolver.js";
+import { checkModelScope } from "./model-scope.js";
+import { createOutputFilePath, getOutputTranscriptDefault, streamToOutputFile, writeInitialEntry, } from "./output-file.js";
+import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix } from "./status-note.js";
+import { addUsage } from "./usage.js";
+import { isWorktreeIsolationEnabled } from "./worktree.js";
+/**
+ * Hard ceiling on nesting for every branch: main session = 0, its subagents = 1,
+ * their children = 2. `0`/`1` disables nesting entirely. Set from
+ * `subagents.json` (`maxSubagentDepth`). Read when a subagent session is built,
+ * so a change applies to sessions started after it.
+ */
+let maxSubagentDepth = 2;
+export function getMaxSubagentDepth() { return maxSubagentDepth; }
+export function setMaxSubagentDepth(n) { maxSubagentDepth = Math.max(0, Math.floor(n)); }
+const NESTED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
+function textResult(text, isError = false) {
+    return { content: [{ type: "text", text }], isError, details: {} };
+}
+function ownsRecord(record, parentAgentId) {
+    return record?.parentAgentId === parentAgentId;
+}
+function formatRecord(record, position) {
+    if (record.status === "error") {
+        return `Agent failed: ${record.error ?? "unknown error"}${partialOutputSuffix(record)}`;
+    }
+    if (record.status === "queued" || record.status === "running") {
+        return `Agent ${record.id} is ${record.status}.`;
+    }
+    // A truncated run must not read as a finished one. The top-level path carries
+    // this in its result headline; a nested result has no headline, so the note
+    // leads — appended, it would look like part of the child's own output.
+    const text = record.result?.trim() || record.error?.trim() || "No output.";
+    const note = position === "inline"
+        ? getForegroundOutcomeNote(record.status)
+        : getStatusNote(record.status);
+    return note ? `Nested agent${note}.\n\n${text}` : text;
+}
+/** Build child-safe orchestration tools scoped to one parent agent instance. */
+export function createNestedSubagentTools(context) {
+    // Agents resolve from a registry built for THIS branch's config root (under
+    // worktree isolation, the copy). Never via registerAgents — that is
+    // process-global state shared with the main session and every other agent.
+    const loadRegistry = () => buildAgentRegistry(loadCustomAgents(context.configCwd));
+    const allowedTypesIn = (registry) => context.allowedSubagents === "all"
+        ? undefined
+        : new Set(context.allowedSubagents.map(name => resolveTypeIn(registry, name) ?? name));
+    const availableIn = (registry) => {
+        const allowed = allowedTypesIn(registry);
+        return getAvailableTypesIn(registry).filter(name => allowed === undefined || allowed.has(name));
+    };
+    const agentTool = defineTool({
+        name: NESTED_TOOL_NAMES[0],
+        label: "Agent",
+        description: "Launch a child-safe nested subagent for bounded delegated work. " +
+            "Only use agent types allowed by this parent agent; nesting is depth-limited.",
+        parameters: Type.Object({
+            prompt: Type.String({ description: "Self-contained task for the nested agent." }),
+            description: Type.String({ description: "Short 3-5 word task description." }),
+            subagent_type: Type.String({ description: `Allowed nested agent type. Available: ${availableIn(loadRegistry()).join(", ") || "none"}.` }),
+            model: Type.Optional(Type.String({ description: "Optional provider/model override." })),
+            thinking: Type.Optional(Type.String({ description: "Optional thinking level." })),
+            max_turns: Type.Optional(Type.Number({ minimum: 1 })),
+            run_in_background: Type.Optional(Type.Boolean({
+                description: "Defaults to false for nested spawns — the call blocks and returns the child's result inline. Set true only for work you will collect later with get_subagent_result; a detached child is stopped when you finish.",
+            })),
+            resume: Type.Optional(Type.String({ description: "Resume a nested agent owned by this parent." })),
+            isolated: Type.Optional(Type.Boolean()),
+            inherit_context: Type.Optional(Type.Boolean()),
+            ...isolationParam(isWorktreeIsolationEnabled()),
+        }),
+        execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
+            if (params.resume) {
+                const existing = context.manager.getRecord(params.resume);
+                if (!ownsRecord(existing, context.parentAgentId)) {
+                    return textResult(`Nested agent not found or not owned by this parent: "${params.resume}".`, true);
+                }
+                const resumed = await context.manager.resume(params.resume, params.prompt, signal);
+                return resumed
+                    ? textResult(formatRecord(resumed, "inline"), resumed.status === "error")
+                    : textResult(`Failed to resume nested agent "${params.resume}".`, true);
+            }
+            if (context.depth >= context.maxSubagentDepth) {
+                return textResult(`Nested subagent call blocked (depth=${context.depth}, max=${context.maxSubagentDepth}). Complete the task directly.`, true);
+            }
+            // Reloaded per call so new agent files are picked up without a restart.
+            const registry = loadRegistry();
+            const rawType = params.subagent_type;
+            // Strict resolve, never the fallback policy: a project-level
+            // `fallbackSubagent` must not hand a nested caller an agent its allowlist
+            // never named. The list stays allowlist-filtered so a typo can't enumerate
+            // agents this parent may not reach.
+            const resolvedType = resolveEnabledTypeIn(registry, rawType);
+            if (resolvedType === undefined) {
+                return textResult(`Unknown or disabled nested agent type: "${rawType}". Allowed: ${availableIn(registry).join(", ") || "none"}.`, true);
+            }
+            const allowed = allowedTypesIn(registry);
+            if (allowed !== undefined && !allowed.has(resolvedType)) {
+                return textResult(`Nested agent type "${resolvedType}" is not allowed for this parent. Allowed: ${[...allowed].join(", ")}.`, true);
+            }
+            const config = getAgentConfigIn(registry, resolvedType);
+            // Foreground regardless of `backgroundByDefault` — see the reasoning on
+            // ResolveOptions. An explicit `true` here still opts in.
+            const invocation = resolveAgentInvocationConfig(config, params, {
+                worktreeAllowed: isWorktreeIsolationEnabled(),
+                defaultRunInBackground: false,
+            });
+            let model = ctx.model;
+            if (invocation.modelInput) {
+                const resolvedModel = resolveModel(invocation.modelInput, ctx.modelRegistry);
+                if (typeof resolvedModel === "string") {
+                    if (invocation.modelFromParams)
+                        return textResult(resolvedModel, true);
+                }
+                else {
+                    model = resolvedModel;
+                }
+            }
+            // Same scopeModels policy as the top-level Agent tool — a nested spawn
+            // must not escape the allowlist. A "warn" verdict proceeds silently:
+            // child sessions have no UI surface to toast to.
+            const scopeVerdict = checkModelScope({
+                model,
+                cwd: context.configCwd,
+                modelRegistry: ctx.modelRegistry,
+                callerSupplied: invocation.modelFromParams,
+                agentLabel: config?.displayName ?? resolvedType,
+                modelInput: invocation.modelInput,
+            });
+            if (scopeVerdict.kind === "error")
+                return textResult(scopeVerdict.message, true);
+            // The whole branch shares the root session's transcript directory; read it
+            // off the owning parent rather than this child session's own id.
+            const rootSessionId = context.manager.getRecord(context.parentAgentId)?.rootSessionId;
+            const childDepth = context.depth + 1;
+            const options = {
+                description: params.description,
+                model,
+                maxTurns: invocation.maxTurns,
+                isolated: invocation.isolated,
+                inheritContext: invocation.inheritContext,
+                thinkingLevel: invocation.thinking,
+                isolation: invocation.isolation,
+                invocation: {
+                    thinking: invocation.thinking,
+                    maxTurns: invocation.maxTurns,
+                    isolated: invocation.isolated,
+                    inheritContext: invocation.inheritContext,
+                    runInBackground: invocation.runInBackground,
+                    isolation: invocation.isolation,
+                },
+                // Nested children are hidden from every reporting surface, so their spend
+                // would otherwise be unattributable. Fold it into every ancestor's record:
+                // the top-level one appears in lifecycle events, completion notifications,
+                // and `/agents`, and those all read `lifetimeUsage`. The whole chain is
+                // walked, not just the immediate parent — a spawn callback only fires for
+                // that child's OWN turns, so stopping at one level would hide a
+                // great-grandchild from the only record anyone can see. (The live
+                // widget/fleet counters read their own per-agent activity tracker, which
+                // still sees only the top-level agent's own turns.)
+                onAssistantUsage: (usage) => {
+                    for (let id = context.parentAgentId; id !== undefined;) {
+                        const ancestor = context.manager.getRecord(id);
+                        if (!ancestor)
+                            break;
+                        addUsage(ancestor.lifetimeUsage, usage);
+                        id = ancestor.parentAgentId;
+                    }
+                },
+                depth: childDepth,
+                parentAgentId: context.parentAgentId,
+                maxSubagentDepth: context.maxSubagentDepth,
+                configCwd: context.configCwd,
+                rootSessionId,
+            };
+            // Transcript wiring, same gate as the top-level path: the child's
+            // `output_transcript` frontmatter wins, else the project default. Without
+            // it a nested run leaves no artifact but the string it returned — the
+            // parent's own transcript records the call and the answer, never the tool
+            // calls in between, which is exactly what a misbehaving child needs to
+            // explain itself. Filed under the ROOT session and this branch's config
+            // root, so a nested transcript lands in the same `tasks/` directory as its
+            // ancestors' rather than in a directory of its own.
+            const transcriptSessionId = rootSessionId !== undefined && (config?.outputTranscript ?? getOutputTranscriptDefault())
+                ? rootSessionId
+                : undefined;
+            let childId;
+            const attachTranscript = (id) => {
+                childId = id;
+                if (transcriptSessionId === undefined)
+                    return;
+                const rec = context.manager.getRecord(id);
+                if (!rec)
+                    return;
+                rec.outputFile = createOutputFilePath(context.configCwd, id, transcriptSessionId);
+                writeInitialEntry(rec.outputFile, id, params.prompt, ctx.cwd);
+            };
+            options.onSessionCreated = (session) => {
+                const rec = childId === undefined ? undefined : context.manager.getRecord(childId);
+                if (rec?.outputFile && childId !== undefined) {
+                    rec.outputCleanup = streamToOutputFile(session, rec.outputFile, childId, ctx.cwd);
+                }
+            };
+            // `ctx` is forwarded to the manager unmodified, never captured at tool-build
+            // time: each AgentSession builds its own ExtensionRunner from that session's
+            // cwd/sessionManager/modelRegistry, so this is the CHILD's context. Capturing
+            // one earlier would silently give a grandchild the wrong worktree base, the
+            // wrong conversation under inherit_context, and the wrong inherited model.
+            //
+            // spawn() throws on strict worktree-isolation failure and cwd validation —
+            // report it as a tool error, like the top-level Agent tool does, instead of
+            // letting it escape into the child's turn.
+            try {
+                if (invocation.runInBackground) {
+                    const id = context.manager.spawn(context.pi, ctx, resolvedType, params.prompt, {
+                        ...options,
+                        isBackground: true,
+                    });
+                    // Synchronous, before the event loop yields — onSessionCreated fires
+                    // asynchronously inside runAgent, so the file is attached in time.
+                    attachTranscript(id);
+                    // Worktree isolation starts the agent asynchronously; surface its
+                    // failure as a tool error, like the synchronous throw used to.
+                    await context.manager.awaitStartup(id);
+                    return textResult(`Nested agent started in background. Agent ID: ${id}`);
+                }
+                const { record } = await context.manager.spawnAndWait(context.pi, ctx, resolvedType, params.prompt, { ...options, signal }, attachTranscript);
+                return textResult(formatRecord(record, "inline"), record.status === "error");
+            }
+            catch (err) {
+                return textResult(err instanceof Error ? err.message : String(err), true);
+            }
+        },
+    });
+    const resultTool = defineTool({
+        name: NESTED_TOOL_NAMES[1],
+        label: "Get Nested Agent Result",
+        description: "Check or wait for a background nested agent owned by this parent.",
+        parameters: Type.Object({
+            agent_id: Type.String(),
+            wait: Type.Optional(Type.Boolean()),
+        }),
+        execute: async (_toolCallId, params, signal) => {
+            const record = context.manager.getRecord(params.agent_id);
+            if (!ownsRecord(record, context.parentAgentId)) {
+                return textResult(`Nested agent not found or not owned by this parent: "${params.agent_id}".`, true);
+            }
+            // Wait for completion if requested. Cancellation (e.g. the parent's tool
+            // call is aborted) stops only this wait; the nested child keeps running and
+            // stays unconsumed. Queued records have no promise until the manager starts
+            // them, so poll — abortably — until they leave the queue, then await.
+            if (params.wait && (record.status === "queued" || record.status === "running")) {
+                while (record.status === "queued") {
+                    await abortable(new Promise(resolve => setTimeout(resolve, 250)), signal);
+                }
+                if (record.promise)
+                    await abortable(record.promise, signal);
+            }
+            return textResult(formatRecord(record, "fetched"), record.status === "error");
+        },
+    });
+    const steerTool = defineTool({
+        name: NESTED_TOOL_NAMES[2],
+        label: "Steer Nested Agent",
+        description: "Send guidance to a running nested agent owned by this parent.",
+        parameters: Type.Object({
+            agent_id: Type.String(),
+            message: Type.String(),
+        }),
+        execute: async (_toolCallId, params) => {
+            const record = context.manager.getRecord(params.agent_id);
+            if (!ownsRecord(record, context.parentAgentId) || record.status !== "running") {
+                return textResult(`Running nested agent not found or not owned by this parent: "${params.agent_id}".`, true);
+            }
+            // Session not ready yet — queue the steer. The manager flushes pending
+            // steers when the session is created (same contract as the top-level tool).
+            if (!record.session) {
+                if (!record.pendingSteers)
+                    record.pendingSteers = [];
+                record.pendingSteers.push(params.message);
+                return textResult(`Steering message queued for nested agent ${params.agent_id}.`);
+            }
+            try {
+                await record.session.steer(params.message);
+            }
+            catch (err) {
+                return textResult(`Failed to steer nested agent: ${err instanceof Error ? err.message : String(err)}`, true);
+            }
+            return textResult(`Steering message sent to nested agent ${params.agent_id}.`);
+        },
+    });
+    return [agentTool, resultTool, steerTool];
+}

package/dist/output-file.d.ts

@@ -0,0 +1,43 @@
+/**
+ * output-file.ts — Streaming JSONL output file for agent transcripts.
+ *
+ * Creates a per-agent output file that streams conversation turns as JSONL,
+ * matching Claude Code's task output file format.
+ */
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
+export declare function getOutputTranscriptDefault(): boolean;
+export declare function setOutputTranscriptDefault(b: boolean): void;
+/**
+ * Encode a cwd path as a filesystem-safe directory name. Handles:
+ *   - POSIX:   "/home/user/project"        → "home-user-project"
+ *   - Windows: "C:\Users\foo\project"      → "Users-foo-project"
+ *   - UNC:     "\\\\server\\share\\project"  → "server-share-project"
+ */
+export declare function encodeCwd(cwd: string): string;
+/**
+ * The per-session scratch directory, created if missing.
+ * Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks
+ *
+ * Shared with the workflow tool, which persists each invocation's script here so
+ * iterating on one is edit-file-then-rerun — the same convention, one directory.
+ */
+export declare function sessionTaskDir(cwd: string, sessionId: string): string;
+/** Create the output file path, ensuring the directory exists. */
+export declare function createOutputFilePath(cwd: string, agentId: string, sessionId: string): string;
+/**
+ * Ensure a transcript file exists without disturbing what is already in it.
+ *
+ * A resume reuses the agent's existing transcript (same deterministic path), so
+ * it must never call `writeInitialEntry` — that truncates, discarding turns the
+ * completion notification still points the user at, and any history the session
+ * has since compacted away is gone for good. Appending nothing creates the file
+ * when this is the agent's first transcript and is a no-op when it is not.
+ */
+export declare function ensureOutputFile(path: string): void;
+/** Write the initial user prompt entry. */
+export declare function writeInitialEntry(path: string, agentId: string, prompt: string, cwd: string): void;
+/**
+ * Subscribe to session events and flush new messages to the output file on each turn_end.
+ * Returns a cleanup function that does a final flush and unsubscribes.
+ */
+export declare function streamToOutputFile(session: AgentSession, path: string, agentId: string, cwd: string, startIndex?: number): () => void;

package/dist/output-file.js

@@ -0,0 +1,142 @@
+/**
+ * output-file.ts — Streaming JSONL output file for agent transcripts.
+ *
+ * Creates a per-agent output file that streams conversation turns as JSONL,
+ * matching Claude Code's task output file format.
+ */
+import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+/**
+ * Project/global default for writing a subagent's `.output` transcript; a custom
+ * agent's `output_transcript` overrides it per agent.
+ *
+ * State lives here rather than in an index.ts closure because both spawn paths
+ * need it — the top-level Agent tool and the nested delegation tools. Same
+ * reason `scopeModels` lives in model-scope.ts: a setting only one path can read
+ * is a setting the other path silently ignores.
+ */
+let outputTranscriptDefault = true;
+export function getOutputTranscriptDefault() { return outputTranscriptDefault; }
+export function setOutputTranscriptDefault(b) { outputTranscriptDefault = b; }
+/**
+ * Encode a cwd path as a filesystem-safe directory name. Handles:
+ *   - POSIX:   "/home/user/project"        → "home-user-project"
+ *   - Windows: "C:\Users\foo\project"      → "Users-foo-project"
+ *   - UNC:     "\\\\server\\share\\project"  → "server-share-project"
+ */
+export function encodeCwd(cwd) {
+    return cwd
+        .replace(/[/\\]/g, "-") // both separators → dash
+        .replace(/^[A-Za-z]:-/, "") // strip Windows drive prefix ("C:-")
+        .replace(/^-+/, ""); // strip leading dashes (POSIX root, UNC)
+}
+/**
+ * The per-session scratch directory, created if missing.
+ * Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks
+ *
+ * Shared with the workflow tool, which persists each invocation's script here so
+ * iterating on one is edit-file-then-rerun — the same convention, one directory.
+ */
+export function sessionTaskDir(cwd, sessionId) {
+    const encoded = encodeCwd(cwd);
+    const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    // chmod is a no-op on Windows and throws on some Windows filesystems.
+    // On Unix we still want to enforce 0o700 past umask, so only swallow on Windows.
+    try {
+        chmodSync(root, 0o700);
+    }
+    catch (err) {
+        if (process.platform !== "win32")
+            throw err;
+    }
+    const dir = join(root, encoded, sessionId, "tasks");
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** Create the output file path, ensuring the directory exists. */
+export function createOutputFilePath(cwd, agentId, sessionId) {
+    return join(sessionTaskDir(cwd, sessionId), `${agentId}.output`);
+}
+/**
+ * Ensure a transcript file exists without disturbing what is already in it.
+ *
+ * A resume reuses the agent's existing transcript (same deterministic path), so
+ * it must never call `writeInitialEntry` — that truncates, discarding turns the
+ * completion notification still points the user at, and any history the session
+ * has since compacted away is gone for good. Appending nothing creates the file
+ * when this is the agent's first transcript and is a no-op when it is not.
+ */
+export function ensureOutputFile(path) {
+    try {
+        appendFileSync(path, "", "utf-8");
+    }
+    catch { /* ignore — streaming writes are best-effort too */ }
+}
+/** Write the initial user prompt entry. */
+export function writeInitialEntry(path, agentId, prompt, cwd) {
+    const entry = {
+        isSidechain: true,
+        agentId,
+        type: "user",
+        message: { role: "user", content: prompt },
+        timestamp: new Date().toISOString(),
+        cwd,
+    };
+    writeFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+}
+/**
+ * Subscribe to session events and flush new messages to the output file on each turn_end.
+ * Returns a cleanup function that does a final flush and unsubscribes.
+ */
+export function streamToOutputFile(session, path, agentId, cwd, startIndex) {
+    // Index of the first message this stream is responsible for. A spawn writes
+    // messages[0] as the initial prompt entry, so it starts at 1. A resume hands
+    // in the session's length as of just before the run: the session already
+    // holds every prior turn, and re-emitting those would duplicate history that
+    // is already in the file.
+    let writtenCount = startIndex ?? 1;
+    const flush = () => {
+        const messages = session.messages;
+        while (writtenCount < messages.length) {
+            const msg = messages[writtenCount];
+            const entry = {
+                isSidechain: true,
+                agentId,
+                type: msg.role === "assistant" ? "assistant" : msg.role === "user" ? "user" : "toolResult",
+                message: msg,
+                timestamp: new Date().toISOString(),
+                cwd,
+            };
+            try {
+                appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+            }
+            catch { /* ignore write errors */ }
+            writtenCount++;
+        }
+    };
+    const unsubscribe = session.subscribe((event) => {
+        if (event.type === "turn_end")
+            flush();
+        // Compaction replaces session.messages with a shorter, summarized array,
+        // leaving writtenCount past the new end — without re-anchoring, the flush
+        // loop would never match again and streaming would halt for good (#145).
+        // Flush before it runs so any not-yet-flushed tail still reaches the file,
+        // then re-anchor to the rebuilt array once it lands. The re-anchor is
+        // deferred a microtask because on the overflow-retry path pi trims the
+        // trailing error assistant message AFTER emitting compaction_end —
+        // anchoring synchronously would sit one past the trimmed array and skip
+        // the first post-compaction message. Aborted/failed compactions leave
+        // session.messages untouched, so only successful ones re-anchor.
+        if (event.type === "compaction_start")
+            flush();
+        if (event.type === "compaction_end" && !event.aborted && event.result) {
+            queueMicrotask(() => { writtenCount = session.messages.length; });
+        }
+    });
+    return () => {
+        flush();
+        unsubscribe();
+    };
+}

package/dist/prompts.d.ts

@@ -0,0 +1,55 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+import type { AgentConfig, EnvInfo } from "./types.js";
+/** Extra sections to inject into the system prompt (memory, skills, etc.). */
+export interface PromptExtras {
+    /** Persistent memory content to inject (first 200 lines of MEMORY.md + instructions). */
+    memoryBlock?: string;
+    /** Preloaded skill contents to inject. */
+    skillBlocks?: {
+        name: string;
+        content: string;
+    }[];
+    /**
+     * Parent directory the worktree copy was created from. Set only for
+     * `isolation: "worktree"` spawns — triggers the block that tells the agent
+     * to stay in the copy.
+     */
+    worktreeBase?: string;
+    /**
+     * Set only for a workflow's own children, and only when they have no
+     * `StructuredOutput` tool to answer through.
+     *
+     * A workflow child's final text is not read by a human — it is the value
+     * `agent()` resolves to, and the script interpolates it straight into the
+     * next stage's prompt. Without this, children answer the way every other
+     * subagent does (a report addressed to a reader), and the padding becomes
+     * input tokens for the stage downstream. Claude Code's `Workflow` tool
+     * documents this contract to the script-writing model; this is the end of it
+     * that makes the documentation true.
+     *
+     * Deliberately NOT applied to every subagent. In pi an ordinary agent's
+     * output IS read by a human — through FleetView, the conversation viewer and
+     * `get_subagent_result` — so terse raw data would be the wrong answer there.
+     */
+    workflowChild?: boolean;
+}
+/**
+ * Build the system prompt for an agent from its config.
+ *
+ * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
+ * - "append" with empty systemPrompt: pure parent clone
+ *
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
+ *
+ * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * @param extras  Optional extra sections to inject (memory, preloaded skills).
+ */
+export declare function buildAgentPrompt(config: AgentConfig, cwd: string, env: EnvInfo, parentSystemPrompt?: string, extras?: PromptExtras): string;

package/dist/prompts.js

@@ -0,0 +1,91 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+/**
+ * Build the system prompt for an agent from its config.
+ *
+ * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
+ * - "append" with empty systemPrompt: pure parent clone
+ *
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
+ *
+ * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * @param extras  Optional extra sections to inject (memory, preloaded skills).
+ */
+export function buildAgentPrompt(config, cwd, env, parentSystemPrompt, extras) {
+    const activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
+    const envBlock = `# Environment
+Working directory: ${cwd}
+${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
+Platform: ${env.platform}`;
+    // A worktree agent is told its cwd twice: by the env block above (the copy)
+    // and by whatever names the main checkout — the inherited parent prompt in
+    // append mode, or the task prompt in either mode. It follows the latter and
+    // works in the shared tree (#187), so resolve the contradiction explicitly.
+    const worktreeBlock = extras?.worktreeBase
+        ? `\n\n<worktree_isolation>
+Your working directory is an isolated git worktree copy of ${extras.worktreeBase}.
+Work only inside it — never in ${extras.worktreeBase}, even if other instructions name that path as your working directory.
+</worktree_isolation>`
+        : "";
+    // The script, not a person, reads what this child returns — see
+    // `PromptExtras.workflowChild` for why only workflow children get this.
+    const workflowBlock = extras?.workflowChild
+        ? `\n\n<workflow_child>
+Your final message IS the return value of this task. A workflow script captures it and passes it to the next stage; no person reads it.
+Return only the answer, in exactly the shape the prompt asks for — no preamble, no summary of what you did, no offer to continue.
+</workflow_child>`
+        : "";
+    // Build optional extras suffix
+    const extraSections = [];
+    if (extras?.memoryBlock) {
+        extraSections.push(extras.memoryBlock);
+    }
+    if (extras?.skillBlocks?.length) {
+        for (const skill of extras.skillBlocks) {
+            extraSections.push(`\n# Preloaded Skill: ${skill.name}\n${skill.content}`);
+        }
+    }
+    const extrasSuffix = extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : "";
+    if (config.promptMode === "append") {
+        const identity = parentSystemPrompt || genericBase;
+        const bridge = `<sub_agent_context>
+You are operating as a sub-agent invoked to handle a specific task.
+- Use the read tool instead of cat/head/tail
+- Use the edit tool instead of sed/awk
+- Use the write tool instead of echo/heredoc
+- Use the find tool instead of bash find/ls for file search
+- Use the grep tool instead of bash grep/rg for content search
+- Make independent tool calls in parallel
+- Use absolute file paths
+- Do not use emojis
+- Be concise but complete
+</sub_agent_context>`;
+        const customSection = config.systemPrompt?.trim()
+            ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
+            : "";
+        // Place shared/stable content first so the LLM's KV cache can reuse the
+        // inherited prefix across all subagent invocations. The parent prompt is
+        // placed verbatim (no wrapper tag) so it forms an identical byte prefix
+        // with the parent session, maximising KV cache hits. The <active_agent>
+        // tag and env block vary per call and are placed after the cached prefix.
+        return identity + "\n\n" + bridge + "\n\n" + activeAgentTag + envBlock + worktreeBlock + workflowBlock + customSection + extrasSuffix;
+    }
+    // "replace" mode — env header + the config's full system prompt
+    const replaceHeader = `You are a pi coding agent sub-agent.
+You have been invoked to handle a specific task autonomously.
+
+${envBlock}`;
+    return activeAgentTag + replaceHeader + worktreeBlock + workflowBlock + "\n\n" + config.systemPrompt + extrasSuffix;
+}
+/** Fallback base prompt when parent system prompt is unavailable in append mode. */
+const genericBase = `# Role
+You are a general-purpose coding agent for complex, multi-step tasks.
+You have full access to read, write, edit files, and execute commands.
+Do what has been asked; nothing more, nothing less.`;