@esso0428/pi-subagents 0.17.5 → 0.17.7

package/src/structured-output.ts

@@ -0,0 +1,130 @@
+/**
+ * structured-output.ts — the synthetic tool behind `agent(prompt, { schema })`.
+ *
+ * A workflow script that passes a `schema` wants an *object* back, not prose it
+ * has to parse. Claude Code does this by giving the child a `StructuredOutput`
+ * tool whose input schema is the caller's schema, so the provider fills the
+ * fields, and returning the validated payload as the agent's result.
+ *
+ * We do the same, with one gap named up front: Claude Code *forces* the call,
+ * and we cannot. `toolChoice` exists in pi-ai's provider layer but is not
+ * plumbed through `AgentSession`, so an extension has no way to require a
+ * particular tool. What we have instead is three softer pressures —
+ *
+ *   1. `constrainedSampling`, so providers that support it hold the payload to
+ *      the schema at sampling time;
+ *   2. the tool's description, snippet and guideline, which say the answer must
+ *      come through this call;
+ *   3. validation here, answering a bad payload with `isError` so the model
+ *      sees what was wrong and calls again inside the same run.
+ *
+ * — and, when all three fail, one more prompt from `runAgent`. See
+ * {@link structuredRetryPrompt}.
+ *
+ * The name matches Claude Code's exactly, so a ported prompt that mentions
+ * `StructuredOutput` is still telling the truth.
+ */
+
+import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { CompiledSchema } from "./workflow/json-schema.js";
+
+/**
+ * Deliberately NOT added to `SUBAGENT_TOOL_NAMES`: that list becomes
+ * `EXCLUDED_TOOL_NAMES`, which is exactly the denial this tool has to avoid.
+ * Nor to `BUILTIN_TOOL_NAMES` — it is ours to inject, never a name a user may
+ * ask for in an agent's `tools:` frontmatter.
+ */
+export const STRUCTURED_OUTPUT_TOOL_NAME = "StructuredOutput";
+
+/** What the child produced, filled in as the tool is called. */
+export interface StructuredCapture {
+  /** The last payload that validated, canonicalised. Absent until one does. */
+  json?: string;
+  /** Why the most recent attempt was rejected, for the retry prompt. */
+  lastError?: string;
+  /** Whether the tool was called at all — "never tried" reads differently. */
+  called: boolean;
+}
+
+export function createStructuredCapture(): StructuredCapture {
+  return { called: false };
+}
+
+/**
+ * Build the tool for one child.
+ *
+ * `capture` is the box the caller reads afterwards. It is passed in rather than
+ * returned so `runAgent` owns its lifetime and can consult it on every exit
+ * path, including the ones where the tool was never reached.
+ */
+export function createStructuredOutputTool(
+  compiled: CompiledSchema,
+  capture: StructuredCapture,
+): ToolDefinition {
+  return defineTool({
+    name: STRUCTURED_OUTPUT_TOOL_NAME,
+    label: "Structured Output",
+    description:
+      "Report your final answer. Call this exactly once, with the complete result, and put everything the "
+      + "caller needs inside the arguments — text written outside this call is discarded. If a call is "
+      + "rejected for not matching the schema, fix the reported fields and call it again.",
+    promptSnippet: "Report your final answer as structured data",
+    promptGuidelines: [
+      "Your final answer MUST be reported by calling StructuredOutput. Prose outside that call is discarded.",
+    ],
+    // The caller's schema *is* the tool's input schema, verbatim — that is what
+    // makes the provider fill the fields. pi types this as TypeBox's `TSchema`,
+    // which v1 defines as an open interface, so a plain JSON Schema satisfies
+    // it without a cast at runtime or a conversion at author time.
+    parameters: compiled.schema as never,
+    // "prefer", not "require": a provider that cannot constrain sampling should
+    // fall through to validation-and-retry rather than fail the call outright.
+    constrainedSampling: { type: "json_schema", strict: "prefer" },
+    // Models occasionally send the whole payload as one JSON string instead of
+    // an object. Recovering that costs nothing and saves a whole retry.
+    prepareArguments: (args: unknown) => {
+      if (typeof args !== "string") return args as never;
+      try {
+        return JSON.parse(args) as never;
+      } catch {
+        return args as never;
+      }
+    },
+    execute: async (_toolCallId, params) => {
+      capture.called = true;
+      const verdict = compiled.check(params);
+      if (verdict !== true) {
+        capture.lastError = verdict;
+        // `isError` puts the reason in front of the model as a tool result, so
+        // it can correct itself inside this same run. This is where most
+        // mismatches are resolved; the prompt-level retry is the backstop.
+        return {
+          content: [{
+            type: "text",
+            text: `StructuredOutput did not match the required schema:\n${verdict}\nCall it again with a corrected value.`,
+          }],
+          isError: true,
+          details: {},
+        };
+      }
+      // Last valid call wins: a model that calls twice meant the second one.
+      capture.json = JSON.stringify(params);
+      capture.lastError = undefined;
+      return { content: [{ type: "text", text: "Recorded." }], details: {} };
+    },
+  }) as ToolDefinition;
+}
+
+/**
+ * The one extra prompt sent when a run ended with nothing captured.
+ *
+ * Distinguishes "never called it" from "called it wrongly" — the two need
+ * different corrections, and telling a model it got the shape wrong when it
+ * never answered at all sends it looking for a mistake it did not make.
+ */
+export function structuredRetryPrompt(capture: StructuredCapture): string {
+  const reason = capture.called && capture.lastError !== undefined
+    ? `Your last ${STRUCTURED_OUTPUT_TOOL_NAME} call did not match the required schema: ${capture.lastError}`
+    : `You did not call ${STRUCTURED_OUTPUT_TOOL_NAME}, so your answer was not recorded.`;
+  return `${reason}\n\nCall ${STRUCTURED_OUTPUT_TOOL_NAME} now with your complete final answer. Do not reply with prose.`;
+}

package/src/types.ts

@@ -17,13 +17,26 @@ export const DEFAULT_AGENT_NAMES = ["general-purpose", "Explore", "Plan"] as con
 /** Memory scope for persistent agent memory. */
 export type MemoryScope = "user" | "project" | "local";
 
-/** Isolation mode for agent execution. */
-export type IsolationMode = "worktree";
+/**
+ * Isolation mode for agent execution.
+ *
+ * `"off"` exists for the caller's benefit, not the runtime's: models that fill
+ * every optional parameter had no legal way to decline a single-value
+ * `isolation` field and kept spawning worktrees they had just reasoned their
+ * way out of (#231, #184). It is an input spelling only —
+ * `resolveAgentInvocationConfig` collapses it to `undefined`, so nothing
+ * downstream sees a value other than `"worktree"`. In an agent file it is a
+ * genuine veto, since agent config outranks tool-call params.
+ */
+export type IsolationMode = "worktree" | "off";
 
 /** Unified agent configuration — used for both default and user-defined agents. */
 export interface AgentConfig {
   name: string;
+  /** UI name. `display_name` wins; Claude Code's `name` is accepted as a fallback. */
   displayName?: string;
+  /** Claude Code-compatible name color (named color or #RRGGBB). */
+  color?: string;
   description: string;
   builtinToolNames?: string[];
   /** Raw `ext:` selector entries from the `tools:` CSV, e.g. ["ext:foo", "ext:bar/x"].
@@ -47,6 +60,11 @@ export interface AgentConfig {
   outputTranscript?: boolean;
   /** Optional session directory used when persistSession is true. Omitted = pi's normal session location. */
   sessionDir?: string;
+  /**
+   * Nested delegation, off by default: undefined = no nested tools;
+   * "all" = any enabled agent; string[] = only those agent types.
+   */
+  allowedSubagents?: "all" | string[];
   systemPrompt: string;
   promptMode: "replace" | "append";
   /** Default for spawn: fork parent conversation. undefined = caller decides. */
@@ -57,7 +75,10 @@ export interface AgentConfig {
   isolated?: boolean;
   /** Persistent memory scope — agents with memory get a persistent directory and MEMORY.md */
   memory?: MemoryScope;
-  /** Isolation mode — "worktree" runs the agent in a temporary git worktree */
+  /**
+   * Isolation mode — "worktree" runs the agent in a temporary git worktree,
+   * "off" refuses one even when the caller asks (frontmatter outranks params).
+   */
   isolation?: IsolationMode;
   /** true = this is an embedded default agent (informational) */
   isDefault?: boolean;
@@ -65,6 +86,8 @@ export interface AgentConfig {
   enabled?: boolean;
   /** Where this agent was loaded from */
   source?: "default" | "project" | "global";
+  /** Path of the .md it was loaded from. Unset for embedded defaults. */
+  sourcePath?: string;
 }
 
 export type JoinMode = 'async' | 'group' | 'smart';
@@ -78,9 +101,75 @@ export type JoinMode = 'async' | 'group' | 'smart';
  */
 export type WidgetMode = 'all' | 'background' | 'off';
 
+/**
+ * How much of the conversation viewer's transcript is rendered as Markdown.
+ * - `off`: every line wraps as literal text, as it did before the mode existed.
+ * - `assistant`: assistant text renders as Markdown; tool results stay verbatim
+ *   and dim. The default, because assistant text *is* Markdown by contract
+ *   while a tool result is arbitrary bytes — a Markdown pass over a log or a
+ *   diff eats `#` from shell comments, swallows a `---` line into a setext
+ *   heading, re-fences indented output and redraws `| a | b |` as a table.
+ *   (Ordered-list renumbering is the one such rewrite actively suppressed —
+ *   see `MARKDOWN_OPTIONS` — because it silently changes data, not layout.)
+ * - `all`: tool results render as Markdown too, for tools that genuinely emit
+ *   it (#210's `ctx_execute`), accepting the rewrites above on ones that don't.
+ */
+export type ViewerMarkdownMode = 'off' | 'assistant' | 'all';
+
+/**
+ * How `@handle message` starts an agent that is not already running.
+ * - `model`: inject Claude Code's `agent_mention` reminder and let the main
+ *   model spawn it with the `Agent` tool, which is what Claude Code does.
+ * - `direct`: spawn it here, immediately, with the typed message as its prompt
+ *   and no main-model turn spent.
+ * - `off`: `@` means only "attach a file" again.
+ *
+ * Messaging a running agent and resuming a finished one are direct in every
+ * mode — Claude Code only differs from us on the *new* invocation.
+ */
+export type AgentMentionMode = 'model' | 'direct' | 'off';
+
+/**
+ * What survives a record's eviction so `@handle` keeps working. The live record
+ * is discarded after ~10 minutes, but the pi session it wrote is still on disk,
+ * and this is the little that is needed to find and describe it again.
+ */
+export interface AgentTombstone {
+  handle: string;
+  alias?: string;
+  id: string;
+  type: SubagentType;
+  description: string;
+  /** Always set — a record with no session file is never tombstoned. */
+  sessionFile: string;
+  completedAt: number;
+}
+
+/**
+ * What `@handle` resolved to: an agent still in memory, or the remains of one
+ * whose conversation can be reopened from disk.
+ */
+export type MentionResolution =
+  | { kind: "live"; record: AgentRecord }
+  | { kind: "tombstone"; entry: AgentTombstone };
+
 export interface AgentRecord {
   id: string;
   type: SubagentType;
+  /**
+   * Typeable name for the `@handle message` prompt mention, derived from the
+   * agent type and numbered when siblings collide (`explore`, `explore-2`).
+   * Top-level agents only — nested children are hidden from every top-level
+   * surface, so nothing can address them.
+   */
+  handle?: string;
+  /**
+   * A second, memorable handle from the spawner's `name` (`@auth-audit`), drawn
+   * from the same namespace as `handle` so the two can never collide. Purely
+   * additive: `handle` is assigned regardless, so a named agent stays reachable
+   * by its type and `@explore` never comes to mean "start another one".
+   */
+  alias?: string;
   description: string;
   status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
   result?: string;
@@ -91,6 +180,22 @@ export interface AgentRecord {
   session?: AgentSession;
   abortController?: AbortController;
   promise?: Promise<string>;
+  /**
+   * A caller is awaiting this agent inline (`spawnAndWait`) — what
+   * `maxConcurrentForeground` bounds. Distinct from `isBackground === false`,
+   * which says only that the agent has an inline result surface: a detached
+   * cross-extension RPC spawn is foreground by that measure and yet blocks
+   * nobody, so it takes no slot.
+   */
+  blocking?: boolean;
+  /**
+   * Present only while the record is "queued": resolves when it leaves the
+   * queue, started or aborted. `spawnAndWait` waits on this because a queued
+   * record has no `promise` yet. Always resolves, never rejects — a rejection
+   * would escape into the caller's tool `execute` and take down pi's whole
+   * Promise.all tool batch.
+   */
+  startGate?: Promise<void>;
   groupId?: string;
   joinMode?: JoinMode;
   /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
@@ -109,8 +214,17 @@ export interface AgentRecord {
   historyFile?: string;
   /** Project-relative durable transcript path persisted in the parent session. */
   transcriptPath?: string;
-  /** Cleanup function for the output file stream subscription. */
+  /**
+   * The agent's pi session file, when it was persisted (`persist_session`, or
+   * the `rememberAgents` default). Captured so a mention can reopen the
+   * conversation after the record itself has been evicted; undefined for an
+   * in-memory session, which leaves nothing to reopen.
+   */
+  sessionFile?: string;
+  /** Cleanup function for the optional `.output` stream subscription. */
   outputCleanup?: () => void;
+  /** Cleanup function for the mandatory durable `.pi-subagents` history stream. */
+  historyCleanup?: () => void;
   /**
    * Lifetime usage breakdown, accumulated via `message_end` events. Survives
    * compaction. Total = input + output + cacheWrite (cacheRead deliberately
@@ -132,16 +246,63 @@ export interface AgentRecord {
   isBackground?: boolean;
   /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
   invocation?: AgentInvocation;
+  /** Nesting depth: top-level subagent = 1. */
+  depth?: number;
+  /**
+   * The validated `StructuredOutput` payload, as canonical JSON.
+   *
+   * Set only when the spawn asked for a schema. Separate from `result` because
+   * `result` is prose for a reader — previewed in the widget, written to the
+   * transcript, and appended to with the worktree branch note — and JSON that
+   * has been appended to no longer parses.
+   */
+  structuredJson?: string;
+  /** Whether the child needed the extra structured-output prompt. */
+  structuredRetried?: boolean;
+  /** Parent agent ID for ownership-scoped nested controls. */
+  parentAgentId?: string;
+  /**
+   * The workflow run that owns this child, when a workflow spawned it.
+   *
+   * Owned the same way a nested child is owned by its parent: filtered out of
+   * every top-level surface, and outside the `maxConcurrent` pool. See
+   * `isTopLevelAgent`.
+   */
+  workflowId?: string;
+  /** Effective inherited nesting cap for this branch. */
+  maxSubagentDepth?: number;
+  /**
+   * Session id of the root (main) session this branch descends from. Nested
+   * spawns inherit it so their transcripts file under the same session
+   * directory as their ancestors' instead of the child session's own id.
+   */
+  rootSessionId?: string;
 }
 
+/**
+ * What a session reports as its level: pi's `ThinkingLevel` plus the `"off"` a
+ * model with thinking disabled reports. Display-only — spawning still takes a
+ * `ThinkingLevel`, so this widening cannot leak into an invocation.
+ */
+export type EffectiveThinkingLevel = ThinkingLevel | "off";
+
 export interface AgentInvocation {
-  /** Short display name, e.g. "haiku" — only set when different from parent. */
+  /** Short display name for tight rows, e.g. "haiku 4.5". Always set once known. */
   modelName?: string;
-  /** Effective model captured from the child session, including inherited models. */
-  effectiveModelName?: string;
-  /** Requested/ effective thinking level. */
-  effectiveThinking?: AgentSession["thinkingLevel"];
-  thinking?: ThinkingLevel;
+  /** Canonical `provider/id`, for surfaces with room to disambiguate providers. */
+  modelId?: string;
+  /** The level actually in effect, once a session exists to report one. */
+  thinking?: EffectiveThinkingLevel;
+  /**
+   * What the caller asked for, kept only when they did not get it — pi clamped
+   * the level to the model's capabilities, or an agent file's frontmatter
+   * outranked the parameter (#182). The snapshot exists to answer "did the spawn
+   * honor my instructions?" (#62), which it cannot do if the request is lost, so
+   * neither `requested*` field is overwritten once set.
+   */
+  requestedThinking?: EffectiveThinkingLevel;
+  /** The caller's `model` parameter, as written, when an agent file's pin won. */
+  requestedModel?: string;
   maxTurns?: number;
   isolated?: boolean;
   inheritContext?: boolean;
@@ -158,6 +319,12 @@ export interface NotificationDetails {
   turnCount: number;
   maxTurns?: number;
   totalTokens: number;
+  /**
+   * Estimated cost in USD, from pi's per-message `usage.cost.total`. Always
+   * populated (0 when the model has no pricing); the renderer decides whether
+   * to show it, per the `showCost` setting.
+   */
+  totalCost?: number;
   durationMs: number;
   outputFile?: string;
   error?: string;

package/src/ui/agent-mention.ts

@@ -0,0 +1,216 @@
+/**
+ * agent-mention.ts — what `@` can address, and the suggestions pi renders for it.
+ *
+ * A subagent is addressable whether or not it is currently running: a live
+ * record is messaged or resumed, an evicted one whose session is still on disk
+ * is reopened, and an agent *type* with no instance at all is started. That is
+ * the point of the handle — `@explore` means the Explore agent, not "the
+ * Explore process that happens to exist right now" — so the roster below unions
+ * all three, and the dispatcher and the popup read the same list.
+ *
+ * Rows are per *agent*, not per handle. An agent given a `name` holds two names
+ * (its alias and its type-derived handle) and both resolve, but it lists once,
+ * under the alias, with its type moved into the description so the row still
+ * says what it is.
+ *
+ * pi's `CombinedAutocompleteProvider` already owns `@`, where it means "attach a
+ * file". Extensions can wrap it (`ctx.ui.addAutocompleteProvider`), so this
+ * provider adds the `@` tokens that name an agent and delegates everything else
+ * — including all of `applyCompletion`, whose `@`-branch already inserts
+ * `item.value` plus a trailing space, which is exactly what a handle needs.
+ *
+ * Matching mirrors Claude Code: case-insensitive prefix, not fuzzy. What it does
+ * NOT mirror is Claude Code dropping files whenever an agent matches. Here `@` is
+ * pi's file picker first, and the handles are additive, so a token matching both
+ * lists both — agents first. Suppressing on any match sounds narrow and is not:
+ * an empty token prefix-matches every handle, so a bare `@` — the gesture people
+ * use to browse files — would offer no files at all, and a single letter
+ * beginning any handle would do the same.
+ *
+ * Both halves ship under ONE `prefix`, which is sound because wherever BOTH sides
+ * produce rows they measured the same span. pi's `extractAtPrefix` takes the
+ * token after the last of `{space, tab, ", ', =}` and keeps it only if it starts
+ * with `@`; `MENTION_TRIGGER` matches `@[\w-]*` at the cursor, after start-of-line
+ * or `[\s。、？！]`. Where those two disagree, exactly one side answers and there
+ * is nothing to merge: `@src/index.ts` and `@"my file` are pi's alone (no handle
+ * matches), `=@ex` is pi's alone (`=` is a delimiter to pi, not a boundary to us),
+ * and `。@ex` is ours alone (the reverse). A merged response therefore never
+ * carries a prefix from one side and an item from the other.
+ *
+ * Offering never-started types is a deliberate step beyond Claude Code, whose
+ * registry holds only live tasks, so an agent you had not launched yet was
+ * unaddressable.
+ */
+
+import type { AutocompleteItem, AutocompleteProvider, AutocompleteSuggestions } from "@earendil-works/pi-tui";
+import type { AgentManager } from "../agent-manager.js";
+import { handleBase, MENTION_TRIGGER } from "../mention.js";
+import type { AgentRecord, AgentTombstone } from "../types.js";
+
+/**
+ * One thing `@` can address, and what sending to it will do. `typeLabel` is the
+ * agent's `display_name`, resolved by the caller: this module stays independent
+ * of the type registry, but the popup must agree with FleetView and the widget,
+ * which both render the label rather than the raw type.
+ */
+export type MentionTarget =
+  | { kind: "record"; handle: string; record: AgentRecord; typeLabel: string }
+  | { kind: "tombstone"; handle: string; entry: AgentTombstone; typeLabel: string }
+  | { kind: "type"; handle: string; type: string; description: string };
+
+/** The registry facts the roster needs, so it stays independent of agent-types. */
+export type TypeInfo = { name: string; description: string };
+
+/**
+ * Everything `@` can reach, in the order the popup lists it: steerable agents
+ * first, then the other live ones earliest-launched, then agent types with no
+ * live instance. A type whose handle a record already holds is omitted — that
+ * name addresses the existing agent, which is what makes `@explore` mean
+ * "message the one that's running" and only otherwise "start one".
+ */
+export function mentionRoster(
+  manager: AgentManager,
+  types: readonly TypeInfo[],
+  // Identity by default: a caller with no registry to consult gets the raw
+  // type, which is also what `getConfig` falls back to when no label is set.
+  displayNameOf: (type: string) => string = type => type,
+): MentionTarget[] {
+  const live = (r: AgentRecord) => r.status === "running" || r.status === "queued";
+  const records = manager.listAgents()
+    .filter(r => r.handle !== undefined && r.parentAgentId === undefined)
+    .sort((a, b) => (Number(live(b)) - Number(live(a))) || (a.startedAt - b.startedAt));
+
+  const taken = new Set<string>();
+  const targets: MentionTarget[] = [];
+
+  // One row per agent, not per handle. An aliased agent lists under its alias
+  // only — both names resolve, but showing two rows for one agent reads as two
+  // agents. The type handle stays addressable whether or not it is listed.
+  for (const record of records) {
+    const handle = record.alias ?? record.handle!;
+    taken.add(handle.toLowerCase());
+    if (record.handle) taken.add(record.handle.toLowerCase());
+    targets.push({ kind: "record", handle, record, typeLabel: displayNameOf(record.type) });
+  }
+
+  // Then agents that are gone but whose conversation can be reopened. After the
+  // live ones: a running agent is the likelier target, and this keeps the
+  // ordering "what exists now, then what can be brought back, then what can be
+  // started".
+  for (const entry of manager.listTombstones()) {
+    const handle = entry.alias ?? entry.handle;
+    if (taken.has(handle.toLowerCase())) continue;
+    taken.add(handle.toLowerCase());
+    taken.add(entry.handle.toLowerCase());
+    targets.push({ kind: "tombstone", handle, entry, typeLabel: displayNameOf(entry.type) });
+  }
+
+  for (const type of types) {
+    const handle = handleBase(type.name);
+    if (taken.has(handle)) continue;
+    taken.add(handle);
+    targets.push({ kind: "type", handle, type: type.name, description: type.description });
+  }
+  return targets;
+}
+
+export function createMentionProvider(
+  current: AutocompleteProvider,
+  roster: () => MentionTarget[],
+  isEnabled: () => boolean,
+): AutocompleteProvider {
+  // One warning per provider, not per keystroke: `getSuggestions` runs on every
+  // character typed after `@`, so an unguarded log would bury the terminal in
+  // the time it takes to finish a word.
+  let warnedInnerFailure = false;
+  return {
+    // Only `@` — the contract is "characters that should naturally trigger
+    // THIS provider", and pi unions each wrapper's own set onto the outermost
+    // one itself (interactive-mode.js:432), so re-declaring the wrapped
+    // provider's characters here would both misreport us and duplicate that.
+    triggerCharacters: ["@"],
+
+    async getSuggestions(lines, cursorLine, cursorCol, options): Promise<AutocompleteSuggestions | null> {
+      const mine = isEnabled() ? mentionItems(roster(), lines[cursorLine] ?? "", cursorCol) : null;
+      // Asked unconditionally: pi owns `@` and must keep answering for it even
+      // when a handle matches too. That is the same work vanilla pi does on any
+      // `@` keystroke — a capped `fd` search, or nothing at all when the host
+      // configured no `fd` path — but we now do it on tokens we used to answer
+      // alone, so it must not be able to take the popup down with it. The
+      // wrapped provider is not always pi's: another extension may sit inside
+      // us, and before this it was never called for a token naming an agent.
+      // try/catch, not `.catch()`: a provider that throws SYNCHRONOUSLY never
+      // returns the promise a `.catch()` would attach to, and the throw escapes
+      // this method as a rejection — which pi does not handle either
+      // (components/editor.js:1892 awaits with no catch of its own).
+      let theirs: AutocompleteSuggestions | null = null;
+      try {
+        theirs = await current.getSuggestions(lines, cursorLine, cursorCol, options);
+      } catch (err) {
+        // Safe to treat as "no files": pi discards any response whose request is
+        // no longer current, so an aborted search that surfaces as a rejection
+        // cannot leave a stale popup behind (`isAutocompleteRequestCurrent`).
+        // Warned rather than swallowed outright — the failure is invisible in
+        // the popup, and the same `console.warn` channel already carries this
+        // extension's other non-fatal failures.
+        if (!warnedInnerFailure) {
+          warnedInnerFailure = true;
+          console.warn("[pi-subagents] the autocomplete provider below us failed; showing agent rows only:", err);
+        }
+        theirs = null;
+      }
+      if (!mine) return theirs;
+      if (!theirs) return mine;
+      // Agents first: there are a handful of them against pi's 20 file rows, and
+      // a handle buried under fuzzy path matches is a handle nobody finds. The
+      // prefix is ours by the span argument in the header — identical to pi's
+      // whenever both sides have something to say.
+      return { items: [...mine.items, ...theirs.items], prefix: mine.prefix };
+    },
+
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    },
+
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  };
+}
+
+/** Suggestions for the `@…` token under the cursor, or null when it names no agent. */
+function mentionItems(roster: MentionTarget[], line: string, cursorCol: number): AutocompleteSuggestions | null {
+  const match = MENTION_TRIGGER.exec(line.slice(0, cursorCol));
+  if (!match) return null;
+
+  const typed = match[2].toLowerCase();
+  const items: AutocompleteItem[] = [];
+  for (const target of roster) {
+    if (!target.handle.toLowerCase().startsWith(typed)) continue;
+    items.push({ value: `@${target.handle}`, label: `@${target.handle}`, description: describeTarget(target) });
+  }
+  return items.length > 0 ? { items, prefix: `@${match[2]}` } : null;
+}
+
+/** Name the action that will actually happen, so the list never mispromises. */
+function describeTarget(target: MentionTarget): string {
+  if (target.kind === "type") return `start agent · ${summarize(target.description)}`;
+  if (target.kind === "tombstone") {
+    // No status: the record is gone, and "completed" would imply one is still
+    // being tracked. The type carries the identity the handle may not.
+    return `resume · ${target.typeLabel} · ${target.entry.description}`;
+  }
+  const { status, description, alias } = target.record;
+  const action = status === "running" || status === "queued" ? "send message" : "resume";
+  // A row listed under its alias has lost the type its handle would have shown,
+  // so name it — `@auth-audit` alone says nothing about what the agent is.
+  // A type-derived row already reads as its type and would just repeat itself.
+  const identity = alias ? `${target.typeLabel} · ` : "";
+  return `${action} · ${identity}${status} · ${description}`;
+}
+
+/** First sentence of an agent description, clipped — these run to paragraphs. */
+function summarize(description: string): string {
+  const first = (description.match(/^.*?[.!?](?=\s|$)/s)?.[0] ?? description).replace(/\s+/g, " ").trim();
+  return first.length > 60 ? `${first.slice(0, 59).trimEnd()}…` : first;
+}