@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.5

package/src/invocation-config.ts

@@ -0,0 +1,189 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { Type } from "typebox";
+import { configuredAgentModel } from "./model-resolver.js";
+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.
+ */
+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: boolean): Partial<typeof isolationParamShape> {
+  return enabled ? isolationParamShape : {};
+}
+
+/**
+ * The model-facing `cwd` parameter of the `Agent` tool.
+ *
+ * Exists because the worktree is made from the repo containing the agent's
+ * working directory, which used to always be the session cwd: a session started
+ * in `~` had no way to isolate an agent in `~/code/some-repo`.
+ */
+export const cwdParam = {
+  cwd: Type.Optional(
+    Type.String({
+      description:
+        'Working directory for the agent: absolute, "~/"-prefixed, or relative to the session cwd. Default: the session cwd. With isolation: "worktree", the worktree is created from the git repo containing this directory, the agent runs at the same subdirectory inside the copy, and the result branch lands in that repo. Pass it whenever the target repo is not the session cwd. Project config (.pi extensions, skills, settings) still loads from the session cwd.',
+    }),
+  ),
+};
+
+/**
+ * Resolve the `Agent` tool's `cwd` against the session cwd: `~` and `~/`
+ * expand to the home directory, a relative path resolves against `sessionCwd`.
+ * Blank means unset: models that fill every optional parameter send `""`.
+ * Existence is checked later by the manager, which re-checks at start time.
+ */
+export function resolveCwdParam(cwd: string | undefined, sessionCwd: string): string | undefined {
+  const trimmed = cwd?.trim();
+  if (!trimmed) return undefined;
+  // Bun 1.3 ignores HOME in os.homedir(); honor the same explicit override as Node.
+  const home = process.env[process.platform === "win32" ? "USERPROFILE" : "HOME"] || homedir();
+  if (trimmed === "~") return home;
+  if (trimmed.startsWith("~/")) return resolve(home, trimmed.slice(2));
+  return resolve(sessionCwd, trimmed);
+}
+
+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 {
+  /** The resolved agent type, for the `agentModels` lookup. Omitted → only the `"*"` entry applies. */
+  agentType?: string;
+  /**
+   * 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 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 thinking levels an agent file's frontmatter outranked, so surfaces
+   * can say "(asked X)" instead of presenting the effective value as requested.
+   * `model` deliberately does not behave this way: an explicit `Agent` model is
+   * an intentional dispatch choice and takes precedence over an agent default.
+   *
+   * `max_turns` is deliberately absent: no surface renders a requested-vs-
+   * effective turn limit, so recording one would be dead data.
+   */
+  overridden?: { thinking?: ThinkingLevel };
+} {
+  // 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 as ThinkingLevel
+    : undefined;
+  return {
+    // A frontmatter model is a portable default, not a policy boundary. An
+    // explicit model on the Agent call must win so an orchestrator can select a
+    // specific model (e.g. a `router/*` virtual model) for this dispatch. Below
+    // it, the global `agentModels` setting outranks the definition's own default.
+    modelInput: params.model ?? configuredAgentModel(opts?.agentType ?? agentConfig?.name ?? "", agentConfig?.model),
+    modelFromParams: params.model != null,
+    thinking: (agentConfig?.thinking ?? params.thinking) as ThinkingLevel | undefined,
+    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 ? { thinking: overriddenThinking } : undefined,
+  };
+}
+
+export function resolveJoinMode(defaultJoinMode: JoinMode, runInBackground: boolean): JoinMode | undefined {
+  return runInBackground ? defaultJoinMode : undefined;
+}

package/src/memory.ts

@@ -0,0 +1,179 @@
+/**
+ * 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";
+import type { MemoryScope } from "./types.js";
+
+/** 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: string): boolean {
+  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: string): boolean {
+  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: string): string | undefined {
+  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: string, scope: MemoryScope, cwd: string): string {
+  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: string): void {
+  // 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: string): string | undefined {
+  // 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: string, scope: MemoryScope, cwd: string): string {
+  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: string, scope: MemoryScope, cwd: string): string {
+  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/src/mention-clone.ts

@@ -0,0 +1,195 @@
+/**
+ * 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, not `inherit_context`'s text rendering of them.
+ *
+ * Pi builds every request from the session manager, so that is where the
+ * clone's history goes: the parent's root-to-leaf entries, handed to
+ * `SessionManager.inMemory`. The clone projects them itself, compaction and
+ * branch summaries included, 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.
+ *
+ * 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.
+ *
+ * The system prompt cannot ride along in those entries. Pi rebuilds it from the
+ * session's own options on every request and patches the difference over the
+ * transcript, so the parent's prompt would be replaced by the clone's. It goes
+ * in through the resource loader's prompt override instead.
+ *
+ * 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 { Model } from "@earendil-works/pi-ai";
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  type ExtensionContext,
+  type ExtensionToolContext,
+  getAgentDir,
+  SessionManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { runInChildSessionContext } from "./child-context.js";
+import { agentMentionReminder } from "./mention.js";
+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 async function runMentionClone(opts: MentionCloneOptions): Promise<MentionCloneResult> {
+  const { ctx, type, message, agentTool } = opts;
+
+  let spawned = false;
+  const cloneAgentTool: ToolDefinition = {
+    ...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" as const, 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 as never,
+        { ...(params as Record<string, unknown>), run_in_background: true } as typeof params,
+        signal,
+        onUpdate,
+        // A tool context adds `tools` and `executeTool`, for nested tool calls;
+        // the Agent handler reads neither, only the main session's own fields.
+        ctx as ExtensionToolContext,
+      );
+    },
+  };
+
+  let session: Awaited<ReturnType<typeof createAgentSession>>["session"] | undefined;
+  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 as unknown as { runtime?: unknown }).runtime;
+    // Absent when the session has no level of its own; the clone then takes the
+    // settings level, which is what a session that never ran `/think` is on.
+    const thinkingLevel = ctx.thinkingLevel;
+    // The live system prompt, not the one the clone would build from cwd and
+    // agentDir — extensions contribute to it per turn. Everything the loader
+    // would add on top (AGENTS.md, skills, APPEND_SYSTEM.md) is already in the
+    // rendered prompt, so it is suppressed, as agent-runner does.
+    const systemPrompt = ctx.getSystemPrompt();
+    const loader = new DefaultResourceLoader({
+      cwd: ctx.cwd,
+      agentDir: getAgentDir(),
+      noExtensions: true,
+      noSkills: true,
+      noPromptTemplates: true,
+      noThemes: true,
+      noContextFiles: true,
+      systemPromptOverride: (base: string | undefined) => systemPrompt || base,
+      appendSystemPromptOverride: () => [],
+    });
+    await runInChildSessionContext(() => loader.reload());
+    const created = await runInChildSessionContext(() =>
+      createAgentSession({
+        cwd: ctx.cwd,
+        // The parent's root-to-leaf path, which the clone projects itself:
+        // compaction applied, branch summaries substituted. Not `getEntries()`,
+        // whose last entry is not the leaf after `/tree` navigation. In memory,
+        // so nothing about the copy is persisted and the real session stays
+        // untouched.
+        sessionManager: SessionManager.inMemory(ctx.cwd, undefined, ctx.sessionManager.getBranch()),
+        resourceLoader: loader,
+        model: ctx.model as Model<never> | undefined,
+        ...(thinkingLevel && { thinkingLevel }),
+        modelRegistry: ctx.modelRegistry,
+        ...(parentModelRuntime !== undefined && { modelRuntime: parentModelRuntime as never }),
+        // 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],
+      } as Parameters<typeof createAgentSession>[0]),
+    );
+    session = created.session;
+
+    // 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" };
+}