@diousk/pi-subagents-fast 0.20.0

package/dist/invocation-config.d.ts

@@ -0,0 +1,107 @@
+import type { AgentConfig, IsolationMode, JoinMode, ThinkingLevel } from "./types.js";
+/**
+ * The model-facing `isolation` parameter, shared by the `Agent` tool and the
+ * nested delegation tool so the two cannot drift.
+ *
+ * Shape matters more than wording here. As a single-value optional literal,
+ * models that fill every optional parameter — the transcript on #231 shows one
+ * emitting `resume: ""`, `schedule: ""` and `model: "default"` alongside it —
+ * had only `"worktree"` available to fill it with, and kept spawning worktrees
+ * across three turns while their own reasoning said to omit the field. Every
+ * other optional parameter has an inert filler; this one did not. `"off"` is
+ * listed first and described as the default so the harmless value is the
+ * obvious one to reach for.
+ *
+ * The wording tracks Claude Code's own `isolation` parameter, whose phrasing
+ * models have the most exposure to: one description on the union rather than
+ * per-value ones, opening "Isolation mode.", then a sentence per value in
+ * schema order, each with its caveats in a trailing parenthetical. Two clauses
+ * are ours, because our shape is not theirs — `"off"` has no counterpart there
+ * (their enum is `worktree | remote`, so both of their values do something),
+ * and neither does the uncommitted-work warning, which is the specific trap
+ * #231 fell into. Deliberately absent is any "only use a worktree when…"
+ * restriction: Claude Code's `Agent` tool states the capability and stops, and
+ * a second legal value is what lets a model decline one, not being told to.
+ */
+declare const isolationParamShape: {
+    isolation: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"off">, import("@sinclair/typebox").TLiteral<"worktree">]>>;
+};
+/**
+ * Build the `isolation` parameter for a tool schema, or nothing when the
+ * project disabled worktrees (`worktreeIsolation: false`).
+ *
+ * Dropping the field beats accepting it and quietly downgrading. The setting is
+ * for a project whose model passes `"worktree"` on *every* call, so a
+ * per-result "isolation was disabled" note would be noise on every result and
+ * would keep raising the salience of a capability that isn't there. With no
+ * field there is nothing to pass, nothing to drop, and nothing to explain — the
+ * same trade `scheduleParam` makes for disabled scheduling, at zero LLM-context
+ * cost. The resolver gate and the `agent-manager` check still cover the paths a
+ * schema can't reach: agent files, the scheduler, and cross-extension RPC.
+ *
+ * Like `scheduleParam`, this is read once at tool registration — flipping the
+ * setting needs a new pi session for the schema to change.
+ */
+export declare function isolationParam(enabled: boolean): Partial<typeof isolationParamShape>;
+interface AgentInvocationParams {
+    model?: string;
+    thinking?: string;
+    max_turns?: number;
+    run_in_background?: boolean;
+    inherit_context?: boolean;
+    isolated?: boolean;
+    /**
+     * Untyped on purpose. Both tool schemas now build this field conditionally
+     * and spread it, which erases TypeBox's literal inference to `unknown` (the
+     * `schedule` param has the same shape). The resolver below narrows by
+     * comparison rather than trusting the declaration, which also makes it safe
+     * for the cross-extension RPC path, where options arrive unvalidated.
+     */
+    isolation?: unknown;
+}
+interface ResolveOptions {
+    /**
+     * Whether worktree isolation is permitted at all. False when the project set
+     * `worktreeIsolation: false`, which drops a requested worktree rather than
+     * failing the call: the fail-loud precedent covers spawns that *cannot* work,
+     * while this one is the user opting out, and throwing would break exactly the
+     * calls the `"off"` value exists to tolerate. Defaults to allowed.
+     */
+    worktreeAllowed?: boolean;
+    /**
+     * What an unqualified spawn means — neither the call nor the agent file said.
+     *
+     * Top-level callers pass the `backgroundByDefault` setting (default `true`,
+     * following Claude Code). Nested callers pass `false` unconditionally: a
+     * detached child is killed by `abortOwnedChildren` when its parent settles
+     * and has no notification path of its own, so backgrounding one loses its
+     * work. Both call sites pass it explicitly; the `false` fallback only covers
+     * a caller that supplies no options at all, which in-tree means tests.
+     */
+    defaultRunInBackground?: boolean;
+}
+export declare function resolveAgentInvocationConfig(agentConfig: AgentConfig | undefined, params: AgentInvocationParams, opts?: ResolveOptions): {
+    modelInput?: string;
+    modelFromParams: boolean;
+    thinking?: ThinkingLevel;
+    maxTurns?: number;
+    inheritContext: boolean;
+    runInBackground: boolean;
+    isolated: boolean;
+    isolation?: IsolationMode;
+    /**
+     * Caller parameters an agent file's frontmatter outranked, so the surfaces can
+     * say "(asked X)" instead of presenting the effective value as the requested
+     * one (#182). Populated only where both sides named something and they
+     * disagree — a caller who asked for what they got was still honored.
+     *
+     * `max_turns` is deliberately absent: no surface renders a requested-vs-
+     * effective turn limit, so recording one would be dead data.
+     */
+    overridden?: {
+        thinking?: ThinkingLevel;
+        model?: string;
+    };
+};
+export declare function resolveJoinMode(defaultJoinMode: JoinMode, runInBackground: boolean): JoinMode | undefined;
+export {};

package/dist/invocation-config.js

@@ -0,0 +1,83 @@
+import { Type } from "@sinclair/typebox";
+/**
+ * The model-facing `isolation` parameter, shared by the `Agent` tool and the
+ * nested delegation tool so the two cannot drift.
+ *
+ * Shape matters more than wording here. As a single-value optional literal,
+ * models that fill every optional parameter — the transcript on #231 shows one
+ * emitting `resume: ""`, `schedule: ""` and `model: "default"` alongside it —
+ * had only `"worktree"` available to fill it with, and kept spawning worktrees
+ * across three turns while their own reasoning said to omit the field. Every
+ * other optional parameter has an inert filler; this one did not. `"off"` is
+ * listed first and described as the default so the harmless value is the
+ * obvious one to reach for.
+ *
+ * The wording tracks Claude Code's own `isolation` parameter, whose phrasing
+ * models have the most exposure to: one description on the union rather than
+ * per-value ones, opening "Isolation mode.", then a sentence per value in
+ * schema order, each with its caveats in a trailing parenthetical. Two clauses
+ * are ours, because our shape is not theirs — `"off"` has no counterpart there
+ * (their enum is `worktree | remote`, so both of their values do something),
+ * and neither does the uncommitted-work warning, which is the specific trap
+ * #231 fell into. Deliberately absent is any "only use a worktree when…"
+ * restriction: Claude Code's `Agent` tool states the capability and stops, and
+ * a second legal value is what lets a model decline one, not being told to.
+ */
+const isolationParamShape = {
+    isolation: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("worktree")], {
+        description: 'Isolation mode. Default "off". "off" runs the agent in the current checkout, the same as omitting the field. "worktree" creates a temporary git worktree so the agent works on an isolated copy of the repo (a copy cannot see uncommitted or staged changes in the main checkout).',
+    })),
+};
+/**
+ * Build the `isolation` parameter for a tool schema, or nothing when the
+ * project disabled worktrees (`worktreeIsolation: false`).
+ *
+ * Dropping the field beats accepting it and quietly downgrading. The setting is
+ * for a project whose model passes `"worktree"` on *every* call, so a
+ * per-result "isolation was disabled" note would be noise on every result and
+ * would keep raising the salience of a capability that isn't there. With no
+ * field there is nothing to pass, nothing to drop, and nothing to explain — the
+ * same trade `scheduleParam` makes for disabled scheduling, at zero LLM-context
+ * cost. The resolver gate and the `agent-manager` check still cover the paths a
+ * schema can't reach: agent files, the scheduler, and cross-extension RPC.
+ *
+ * Like `scheduleParam`, this is read once at tool registration — flipping the
+ * setting needs a new pi session for the schema to change.
+ */
+export function isolationParam(enabled) {
+    return enabled ? isolationParamShape : {};
+}
+export function resolveAgentInvocationConfig(agentConfig, params, opts) {
+    // Precedence first, collapse second — reversing these loses the veto, since
+    // an agent file's "off" only outranks a caller's "worktree" while it is still
+    // a value. Everything downstream then sees "worktree" or nothing at all.
+    const requested = agentConfig?.isolation ?? params.isolation;
+    const isolation = requested === "worktree" && opts?.worktreeAllowed !== false ? "worktree" : undefined;
+    const overriddenThinking = agentConfig?.thinking != null && params.thinking != null
+        && agentConfig.thinking !== params.thinking
+        ? params.thinking
+        : undefined;
+    const overriddenModel = agentConfig?.model != null && params.model != null
+        && agentConfig.model !== params.model
+        ? params.model
+        : undefined;
+    return {
+        modelInput: agentConfig?.model ?? params.model,
+        modelFromParams: agentConfig?.model == null && params.model != null,
+        thinking: (agentConfig?.thinking ?? params.thinking),
+        maxTurns: agentConfig?.maxTurns ?? params.max_turns,
+        inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
+        runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? opts?.defaultRunInBackground ?? false,
+        isolated: agentConfig?.isolated ?? params.isolated ?? false,
+        isolation,
+        // Undefined rather than an empty object when nothing was overridden: callers
+        // spread this into the invocation snapshot, and an always-present key would
+        // put `requestedThinking: undefined` on every record.
+        overridden: overriddenThinking || overriddenModel
+            ? { thinking: overriddenThinking, model: overriddenModel }
+            : undefined,
+    };
+}
+export function resolveJoinMode(defaultJoinMode, runInBackground) {
+    return runInBackground ? defaultJoinMode : undefined;
+}

package/dist/memory.d.ts

@@ -0,0 +1,53 @@
+/**
+ * memory.ts — Persistent agent memory: per-agent memory directories that persist across sessions.
+ *
+ * Memory scopes:
+ *   - "user"    → getAgentDir()/agent-memory/{agent-name}/ (default ~/.pi/agent/agent-memory/, honors $PI_CODING_AGENT_DIR)
+ *   - "project" → .pi/agent-memory/{agent-name}/
+ *   - "local"   → .pi/agent-memory-local/{agent-name}/
+ *
+ * The user scope previously hardcoded ~/.pi/agent-memory/. That legacy location
+ * is still honored (read + write) when it exists and the new location doesn't,
+ * so existing memories aren't orphaned.
+ */
+import type { MemoryScope } from "./types.js";
+/**
+ * Returns true if a name contains characters not allowed in agent/skill names.
+ * Uses a whitelist: only alphanumeric, hyphens, underscores, and dots (no leading dot).
+ */
+export declare function isUnsafeName(name: string): boolean;
+/**
+ * Returns true if the given path is a symlink (defense against symlink attacks).
+ */
+export declare function isSymlink(filePath: string): boolean;
+/**
+ * Safely read a file, rejecting symlinks.
+ * Returns undefined if the file doesn't exist, is a symlink, or can't be read.
+ */
+export declare function safeReadFile(filePath: string): string | undefined;
+/**
+ * Resolve the memory directory path for a given agent + scope + cwd.
+ * Throws if agentName contains path traversal characters.
+ */
+export declare function resolveMemoryDir(agentName: string, scope: MemoryScope, cwd: string): string;
+/**
+ * Ensure the memory directory exists, creating it if needed.
+ * Refuses to create directories if any component in the path is a symlink
+ * to prevent symlink-based directory traversal attacks.
+ */
+export declare function ensureMemoryDir(memoryDir: string): void;
+/**
+ * Read the first N lines of MEMORY.md from the memory directory, if it exists.
+ * Returns undefined if no MEMORY.md exists or if the path is a symlink.
+ */
+export declare function readMemoryIndex(memoryDir: string): string | undefined;
+/**
+ * Build the memory block to inject into the agent's system prompt.
+ * Also ensures the memory directory exists (creates it if needed).
+ */
+export declare function buildMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string;
+/**
+ * Build a read-only memory block for agents that lack write/edit tools.
+ * Does NOT create the memory directory — agents can only consume existing memory.
+ */
+export declare function buildReadOnlyMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string;

package/dist/memory.js

@@ -0,0 +1,165 @@
+/**
+ * memory.ts — Persistent agent memory: per-agent memory directories that persist across sessions.
+ *
+ * Memory scopes:
+ *   - "user"    → getAgentDir()/agent-memory/{agent-name}/ (default ~/.pi/agent/agent-memory/, honors $PI_CODING_AGENT_DIR)
+ *   - "project" → .pi/agent-memory/{agent-name}/
+ *   - "local"   → .pi/agent-memory-local/{agent-name}/
+ *
+ * The user scope previously hardcoded ~/.pi/agent-memory/. That legacy location
+ * is still honored (read + write) when it exists and the new location doesn't,
+ * so existing memories aren't orphaned.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+/** Maximum lines to read from MEMORY.md */
+const MAX_MEMORY_LINES = 200;
+/**
+ * Returns true if a name contains characters not allowed in agent/skill names.
+ * Uses a whitelist: only alphanumeric, hyphens, underscores, and dots (no leading dot).
+ */
+export function isUnsafeName(name) {
+    if (!name || name.length > 128)
+        return true;
+    return !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+/**
+ * Returns true if the given path is a symlink (defense against symlink attacks).
+ */
+export function isSymlink(filePath) {
+    try {
+        return lstatSync(filePath).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Safely read a file, rejecting symlinks.
+ * Returns undefined if the file doesn't exist, is a symlink, or can't be read.
+ */
+export function safeReadFile(filePath) {
+    if (!existsSync(filePath))
+        return undefined;
+    if (isSymlink(filePath))
+        return undefined;
+    try {
+        return readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve the memory directory path for a given agent + scope + cwd.
+ * Throws if agentName contains path traversal characters.
+ */
+export function resolveMemoryDir(agentName, scope, cwd) {
+    if (isUnsafeName(agentName)) {
+        throw new Error(`Unsafe agent name for memory directory: "${agentName}"`);
+    }
+    switch (scope) {
+        case "user": {
+            const current = join(getAgentDir(), "agent-memory", agentName);
+            // Legacy location from when this path was hardcoded. Keep using it if it
+            // already holds this agent's memory and the new location hasn't been
+            // created yet — otherwise existing memories would be silently orphaned.
+            const legacy = join(homedir(), ".pi", "agent-memory", agentName);
+            if (!existsSync(current) && existsSync(legacy) && !isSymlink(legacy)) {
+                return legacy;
+            }
+            return current;
+        }
+        case "project":
+            return join(cwd, ".pi", "agent-memory", agentName);
+        case "local":
+            return join(cwd, ".pi", "agent-memory-local", agentName);
+    }
+}
+/**
+ * Ensure the memory directory exists, creating it if needed.
+ * Refuses to create directories if any component in the path is a symlink
+ * to prevent symlink-based directory traversal attacks.
+ */
+export function ensureMemoryDir(memoryDir) {
+    // If the directory already exists, verify it's not a symlink
+    if (existsSync(memoryDir)) {
+        if (isSymlink(memoryDir)) {
+            throw new Error(`Refusing to use symlinked memory directory: ${memoryDir}`);
+        }
+        return;
+    }
+    mkdirSync(memoryDir, { recursive: true });
+}
+/**
+ * Read the first N lines of MEMORY.md from the memory directory, if it exists.
+ * Returns undefined if no MEMORY.md exists or if the path is a symlink.
+ */
+export function readMemoryIndex(memoryDir) {
+    // Reject symlinked memory directories
+    if (isSymlink(memoryDir))
+        return undefined;
+    const memoryFile = join(memoryDir, "MEMORY.md");
+    const content = safeReadFile(memoryFile);
+    if (content === undefined)
+        return undefined;
+    const lines = content.split("\n");
+    if (lines.length > MAX_MEMORY_LINES) {
+        return lines.slice(0, MAX_MEMORY_LINES).join("\n") + "\n... (truncated at 200 lines)";
+    }
+    return content;
+}
+/**
+ * Build the memory block to inject into the agent's system prompt.
+ * Also ensures the memory directory exists (creates it if needed).
+ */
+export function buildMemoryBlock(agentName, scope, cwd) {
+    const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+    // Create the memory directory so the agent can immediately write to it
+    ensureMemoryDir(memoryDir);
+    const existingMemory = readMemoryIndex(memoryDir);
+    const header = `# Agent Memory
+
+You have a persistent memory directory at: ${memoryDir}/
+Memory scope: ${scope}
+
+This memory persists across sessions. Use it to build up knowledge over time.`;
+    const memoryContent = existingMemory
+        ? `\n\n## Current MEMORY.md\n${existingMemory}`
+        : `\n\nNo MEMORY.md exists yet. Create one at ${join(memoryDir, "MEMORY.md")} to start building persistent memory.`;
+    const instructions = `
+
+## Memory Instructions
+- MEMORY.md is an index file — keep it concise (under 200 lines). Lines after 200 are truncated.
+- Store detailed memories in separate files within ${memoryDir}/ and link to them from MEMORY.md.
+- Each memory file should use this frontmatter format:
+  \`\`\`markdown
+  ---
+  name: <memory name>
+  description: <one-line description>
+  type: <user|feedback|project|reference>
+  ---
+  <memory content>
+  \`\`\`
+- Update or remove memories that become outdated. Check for existing memories before creating duplicates.
+- You have Read, Write, and Edit tools available for managing memory files.`;
+    return header + memoryContent + instructions;
+}
+/**
+ * Build a read-only memory block for agents that lack write/edit tools.
+ * Does NOT create the memory directory — agents can only consume existing memory.
+ */
+export function buildReadOnlyMemoryBlock(agentName, scope, cwd) {
+    const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+    const existingMemory = readMemoryIndex(memoryDir);
+    const header = `# Agent Memory (read-only)
+
+Memory scope: ${scope}
+You have read-only access to memory. You can reference existing memories but cannot create or modify them.`;
+    const memoryContent = existingMemory
+        ? `\n\n## Current MEMORY.md\n${existingMemory}`
+        : `\n\nNo memory is available yet. Other agents or sessions with write access can create memories for you to consume.`;
+    return header + memoryContent;
+}

package/dist/mention-clone.d.ts

@@ -0,0 +1,87 @@
+/**
+ * mention-clone.ts — start a mentioned agent through a clone of this
+ * conversation, without putting anything in the chat.
+ *
+ * Claude Code routes `@agent-<type>` through the main model: the mention
+ * becomes a `<system-reminder>` appended to the prompt and the model makes the
+ * tool call (see `agentMentionReminder`). That buys the spawned agent a prompt
+ * written with conversation context, and costs a visible turn — the model's
+ * reasoning and its tool block land in the transcript, for a decision the user
+ * already made when they typed the handle.
+ *
+ * So the turn happens somewhere else. The conversation is cloned into a
+ * throwaway in-memory session — same messages, same system prompt, same model —
+ * and that copy takes the turn off-screen. A literal clone: the session's own
+ * entries, projected by pi's own `sessionEntryToContextMessages`, not
+ * `inherit_context`'s text rendering of them.
+ *
+ * Cloned from memory rather than from the session file, which cannot be relied
+ * on: `SessionManager._persist` withholds every write until the first assistant
+ * message lands, so a fork taken before then reads an empty file and throws.
+ * `buildSessionContext()` has no such timing, and is compaction-aware — it walks
+ * the leaf path and substitutes the summary for entries folded into it, so a
+ * long conversation clones as what the main model is actually working from. A
+ * conversation with nothing in it yet clones to nothing in it yet, which is the
+ * correct answer rather than a failure.
+ *
+ * It is also the oldest of the equivalent Pi APIs — `buildContextEntries` on
+ * ReadonlySessionManager and the `sessionEntryToContextMessages` export both
+ * arrived in 0.80.5 — where this one has been exported unchanged from before
+ * the declared peer floor, and is the same code path (`byId` is only an index
+ * cache, so passing it or not cannot change the result). Keeping the floor
+ * honest costs nothing here: see the `compat-floor-pi` job.
+ *
+ * Its `thinkingLevel` is NOT used, and is the one place the newer API would be
+ * better. `getSessionContextSettings` starts at "off" and moves only on an
+ * explicit `thinking_level_change` entry, so a session where nobody ran
+ * `/think` reports "off" rather than the level it is really using. Omitting the
+ * field instead lets `createAgentSession` resolve it from settings, which is
+ * that real level.
+ *
+ * Three details make the spawn belong to the real session rather than the
+ * clone:
+ *
+ *   - the clone is handed the *registered* `Agent` tool, whose handler closes
+ *     over the main activation, so it spawns top-level: widget, fleet row,
+ *     handle, completion notification, all as if the main model had called it;
+ *   - that tool is re-bound to the main `ExtensionContext`, because the handler
+ *     reads `cwd`, `model` and `sessionManager.getSessionId()` off it to place
+ *     the transcript and the `rootSessionId`. The clone's own context would
+ *     file both under the throwaway fork;
+ *   - it is called with no tool-call id. The clone's turn produces one, but the
+ *     real session never issued it, and a `<tool-use-id>` pointing at nothing
+ *     is exactly the bug the mention-resume path had to fix;
+ *   - and it is forced into the background. A foreground agent returns its
+ *     answer as the tool result and is marked `resultConsumed` so no completion
+ *     notification is sent — correct when the caller is the real conversation,
+ *     silent loss when the caller is a fork about to be discarded. Background
+ *     delivery is the only route from a mention back to the main model.
+ *
+ * The clone gets one tool and one job. It cannot read, write or run anything —
+ * an invisible turn with the full toolset could do invisible work.
+ */
+import { type ExtensionContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { SubagentType } from "./types.js";
+export interface MentionCloneOptions {
+    /** The MAIN session's context — what the spawn is attributed to, and the
+     * source of both the conversation and the live system prompt. */
+    ctx: ExtensionContext;
+    /** Agent type the handle resolved to. */
+    type: SubagentType;
+    /** What the user typed after the handle. */
+    message: string;
+    /** The registered `Agent` tool, reused so the spawn is an ordinary one. */
+    agentTool: ToolDefinition;
+}
+export interface MentionCloneResult {
+    /** True once the clone actually called `Agent`. */
+    spawned: boolean;
+    /** Why not, when it didn't. Absent on success. */
+    error?: string;
+}
+/**
+ * Fork the conversation, let the copy make the tool call, throw the copy away.
+ * Never rejects: a clone that cannot run is reported so the caller can fall
+ * back to starting the agent directly.
+ */
+export declare function runMentionClone(opts: MentionCloneOptions): Promise<MentionCloneResult>;

package/dist/mention-clone.js

@@ -0,0 +1,153 @@
+/**
+ * mention-clone.ts — start a mentioned agent through a clone of this
+ * conversation, without putting anything in the chat.
+ *
+ * Claude Code routes `@agent-<type>` through the main model: the mention
+ * becomes a `<system-reminder>` appended to the prompt and the model makes the
+ * tool call (see `agentMentionReminder`). That buys the spawned agent a prompt
+ * written with conversation context, and costs a visible turn — the model's
+ * reasoning and its tool block land in the transcript, for a decision the user
+ * already made when they typed the handle.
+ *
+ * So the turn happens somewhere else. The conversation is cloned into a
+ * throwaway in-memory session — same messages, same system prompt, same model —
+ * and that copy takes the turn off-screen. A literal clone: the session's own
+ * entries, projected by pi's own `sessionEntryToContextMessages`, not
+ * `inherit_context`'s text rendering of them.
+ *
+ * Cloned from memory rather than from the session file, which cannot be relied
+ * on: `SessionManager._persist` withholds every write until the first assistant
+ * message lands, so a fork taken before then reads an empty file and throws.
+ * `buildSessionContext()` has no such timing, and is compaction-aware — it walks
+ * the leaf path and substitutes the summary for entries folded into it, so a
+ * long conversation clones as what the main model is actually working from. A
+ * conversation with nothing in it yet clones to nothing in it yet, which is the
+ * correct answer rather than a failure.
+ *
+ * It is also the oldest of the equivalent Pi APIs — `buildContextEntries` on
+ * ReadonlySessionManager and the `sessionEntryToContextMessages` export both
+ * arrived in 0.80.5 — where this one has been exported unchanged from before
+ * the declared peer floor, and is the same code path (`byId` is only an index
+ * cache, so passing it or not cannot change the result). Keeping the floor
+ * honest costs nothing here: see the `compat-floor-pi` job.
+ *
+ * Its `thinkingLevel` is NOT used, and is the one place the newer API would be
+ * better. `getSessionContextSettings` starts at "off" and moves only on an
+ * explicit `thinking_level_change` entry, so a session where nobody ran
+ * `/think` reports "off" rather than the level it is really using. Omitting the
+ * field instead lets `createAgentSession` resolve it from settings, which is
+ * that real level.
+ *
+ * Three details make the spawn belong to the real session rather than the
+ * clone:
+ *
+ *   - the clone is handed the *registered* `Agent` tool, whose handler closes
+ *     over the main activation, so it spawns top-level: widget, fleet row,
+ *     handle, completion notification, all as if the main model had called it;
+ *   - that tool is re-bound to the main `ExtensionContext`, because the handler
+ *     reads `cwd`, `model` and `sessionManager.getSessionId()` off it to place
+ *     the transcript and the `rootSessionId`. The clone's own context would
+ *     file both under the throwaway fork;
+ *   - it is called with no tool-call id. The clone's turn produces one, but the
+ *     real session never issued it, and a `<tool-use-id>` pointing at nothing
+ *     is exactly the bug the mention-resume path had to fix;
+ *   - and it is forced into the background. A foreground agent returns its
+ *     answer as the tool result and is marked `resultConsumed` so no completion
+ *     notification is sent — correct when the caller is the real conversation,
+ *     silent loss when the caller is a fork about to be discarded. Background
+ *     delivery is the only route from a mention back to the main model.
+ *
+ * The clone gets one tool and one job. It cannot read, write or run anything —
+ * an invisible turn with the full toolset could do invisible work.
+ */
+import { buildSessionContext, createAgentSession, SessionManager, } from "@earendil-works/pi-coding-agent";
+import { runInChildSessionContext } from "./child-context.js";
+import { agentMentionReminder } from "./mention.js";
+/**
+ * Fork the conversation, let the copy make the tool call, throw the copy away.
+ * Never rejects: a clone that cannot run is reported so the caller can fall
+ * back to starting the agent directly.
+ */
+export async function runMentionClone(opts) {
+    const { ctx, type, message, agentTool } = opts;
+    let spawned = false;
+    const cloneAgentTool = {
+        ...agentTool,
+        execute: (_cloneToolCallId, params, signal, onUpdate, _cloneCtx) => {
+            // One spawn per mention. The clone has a single tool and every reason to
+            // stop after using it, but a model that decides to "also" launch a second
+            // agent would do it where nobody can see and nobody asked.
+            if (spawned) {
+                return Promise.resolve({
+                    content: [{ type: "text", text: "Already started an agent for this mention. Stop here." }],
+                    details: undefined,
+                    isError: true,
+                });
+            }
+            spawned = true;
+            // undefined tool-call id + the main ctx: see the header. Background is
+            // forced rather than left to the clone: `run_in_background` defaults to
+            // false, and a foreground agent answers through its TOOL RESULT — which
+            // here is delivered into a session that is disposed moments later, so the
+            // agent would run, appear in the widget and the fleet, and reach nobody.
+            return agentTool.execute(undefined, { ...params, run_in_background: true }, signal, onUpdate, ctx);
+        },
+    };
+    let session;
+    try {
+        // Pi 0.80.8 moved createAgentSession from modelRegistry to modelRuntime;
+        // agent-runner.ts carries the same shim for the same reason — pass both so
+        // the clone keeps the parent's providers across the supported range.
+        const parentModelRuntime = ctx.modelRegistry.runtime;
+        // The conversation as the main session resolves it: compaction applied,
+        // branch summaries substituted.
+        const conversation = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId());
+        // Pi 0.82.0 added this; below it the field is absent and the clone takes
+        // the settings level instead, which is what a session that never ran
+        // `/think` is on anyway. Same shim shape as `modelRuntime` below.
+        const thinkingLevel = ctx.thinkingLevel;
+        const created = await runInChildSessionContext(() => createAgentSession({
+            cwd: ctx.cwd,
+            // Nothing about the copy is worth persisting, and an in-memory manager
+            // is also what keeps the real session untouched.
+            sessionManager: SessionManager.inMemory(ctx.cwd),
+            model: ctx.model,
+            ...(thinkingLevel && { thinkingLevel }),
+            modelRegistry: ctx.modelRegistry,
+            ...(parentModelRuntime !== undefined && { modelRuntime: parentModelRuntime }),
+            // An allowlist naming exactly the clone's own tool. NOT `noTools:
+            // "all"`, whose doc comment ("start with no tools enabled") reads like
+            // it spares custom tools and does not: it resolves to an EMPTY
+            // allowlist, and `isAllowedTool` then drops every tool from the
+            // registry — the custom one included. The clone would be prompted with
+            // nothing to call, answer in prose, and every mention would fall
+            // through to the direct start with a warning. Same idiom as
+            // agent-runner's `tools: sessionTools` beside its nested `customTools`.
+            tools: [cloneAgentTool.name],
+            customTools: [cloneAgentTool],
+        }));
+        session = created.session;
+        // The clone rebuilds a system prompt from cwd and agentDir, which is close
+        // but not the live one — extensions contribute to it per turn. Copy the
+        // real thing, so the copy reasons under the instructions the user's model
+        // is actually working under.
+        const systemPrompt = ctx.getSystemPrompt?.();
+        if (systemPrompt)
+            session.agent.state.systemPrompt = systemPrompt;
+        // The conversation itself. Pushed rather than assigned so the array the
+        // session was built around stays the one it goes on using.
+        session.agent.state.messages.push(...conversation.messages);
+        // User text first, reminder after — the order Claude Code's attachment
+        // renderer produces, where the reminder trails the message it is about.
+        await session.prompt(`${message}\n\n${agentMentionReminder(type)}`);
+    }
+    catch (err) {
+        return { spawned, error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        session?.dispose?.();
+    }
+    return spawned
+        ? { spawned: true }
+        : { spawned: false, error: "the conversation clone did not start it" };
+}