@herbertgao/pi-subagents 0.19.0 → 0.22.0-local.1

package/src/agent-runner.ts

@@ -14,9 +14,13 @@ import {
   type AgentSession,
   type AgentSessionEvent,
   createAgentSession,
+  createCodemodeExtension,
+  createMcpExtension,
+  createToolSearchExtension,
   DefaultResourceLoader,
   type ExtensionAPI,
   getAgentDir,
+  type InlineExtension,
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent"
@@ -101,6 +105,8 @@ export function extensionCanonicalName(extPath: string): string {
  * co-located file to `pi-subagents`.
  */
 function extensionPackageName(extPath: string): string | undefined {
+  // `builtin:<name>` names no file; climbing from it would read the process cwd's manifest.
+  if (extPath.startsWith("builtin:")) return undefined
   const entry = resolve(extPath)
   let dir = dirname(extPath)
   for (;;) {
@@ -269,6 +275,8 @@ export function installExtensionToolScope(
      * seeded from `toolNames`.
      */
     readmitToolNames: Set<string>
+    /** Receives the scope check the child's nested-call gate extension applies. */
+    nestedCallGate: NestedCallGate
   },
 ): void {
   const {
@@ -278,6 +286,7 @@ export function installExtensionToolScope(
     extNames,
     narrowing,
     readmitToolNames,
+    nestedCallGate,
   } = ctx
 
   // The names allowed right now. Mirrors the `ext:` opt-in flip: when any `ext:`
@@ -308,13 +317,36 @@ export function installExtensionToolScope(
     return keep
   }
 
+  // Names this agent selects explicitly: its built-ins, injected tools, and
+  // `ext:foo/bar` narrowings. pi activates a named tool even when it is
+  // `defaultActive: false`, as `--tools` does.
+  const named = new Set([
+    ...toolNames,
+    ...readmitToolNames,
+    ...[...narrowing.values()].flatMap((s) => [...s]),
+  ])
+
+  // Activate what pi itself would: only tools declared to the model (`direct`/
+  // `model-only` exposure), and of those only named ones or ones not opted out
+  // with `defaultActive: false`. `codemode`/`deferred` tools (pi's MCP tools by
+  // default) stay undeclared until their extension or `tool_search` activates
+  // them — so an already-active tool is kept, or turn_end would undo that.
   const renarrow = () => {
     const allowed = inScope()
+    const current = session.getActiveToolNames()
+    const active = new Set(current)
     const next = session
       .getAllTools()
+      .filter(({ name, exposure = "direct" }) => {
+        if (!allowed.has(name)) return false
+        if (active.has(name)) return true
+        if (exposure !== "direct" && exposure !== "model-only") return false
+        return (
+          named.has(name) ||
+          session.getToolDefinition(name)?.defaultActive !== false
+        )
+      })
       .map((t) => t.name)
-      .filter((n) => allowed.has(n))
-    const current = session.getActiveToolNames()
     // setActiveToolsByName unconditionally rebuilds the system prompt, so skip
     // the no-op that steady-state turns would otherwise pay for every turn.
     if (
@@ -333,6 +365,8 @@ export function installExtensionToolScope(
     if (event.type === "turn_end") renarrow()
   })
 
+  nestedCallGate.allows = (name) => inScope().has(name)
+
   const priorBeforeToolCall = session.agent.beforeToolCall
   session.agent.beforeToolCall = async (context, signal) => {
     if (!inScope().has(context.toolCall.name)) {
@@ -345,6 +379,35 @@ export function installExtensionToolScope(
   }
 }
 
+/** Set once the child's tool scope is installed; until then the gate admits everything. */
+type NestedCallGate = { allows?: (name: string) => boolean }
+
+/**
+ * Inline extension that applies the subagent's tool scope to calls a tool makes
+ * through `ctx.executeTool()` — codemode scripts calling MCP tools. pi runs those
+ * past extensions' `tool_call` handlers only, never `agent.beforeToolCall`, and
+ * every registered `codemode`/`deferred` tool is callable there whether or not
+ * it is in scope.
+ */
+const SCOPE_GATE_NAME = "pi-subagents-scope"
+
+function scopeGateExtension(gate: NestedCallGate): InlineExtension {
+  return {
+    name: SCOPE_GATE_NAME,
+    hidden: true,
+    factory: (ext) => {
+      ext.on("tool_call", (event) =>
+        gate.allows?.(event.toolName) === false
+          ? {
+              block: true,
+              reason: `Tool "${event.toolName}" is not available to this subagent.`,
+            }
+          : undefined,
+      )
+    },
+  }
+}
+
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns: number | undefined
 
@@ -459,6 +522,7 @@ export interface RunOptions {
   model?: Model<any>
   maxTurns?: number
   signal?: AbortSignal
+  /** Applies only when the agent file leaves `isolated:` unset — frontmatter is authoritative. */
   isolated?: boolean
   inheritContext?: boolean
   thinkingLevel?: ThinkingLevel
@@ -708,14 +772,15 @@ export async function runAgent(
   if (options.worktreeBase) extras.worktreeBase = options.worktreeBase
   if (options.workflow && !options.structuredOutput) extras.workflowChild = true
 
+  // Resolved here, not by each caller: mention and RPC spawns pass no `isolated`,
+  // and the agent file's value must hold on every path.
+  const isolated = agentConfig?.isolated ?? options.isolated
   // Resolve extensions/skills: isolated overrides to false
-  const extensions = options.isolated ? false : config.extensions
+  const extensions = isolated ? false : config.extensions
   // Nulling excludes under isolated also suppresses the orphaned-exclude warning —
   // isolation is an intentional override, not a misconfiguration.
-  const excludeExtensions = options.isolated
-    ? undefined
-    : config.excludeExtensions
-  const skills = options.isolated ? false : config.skills
+  const excludeExtensions = isolated ? undefined : config.excludeExtensions
+  const skills = isolated ? false : config.skills
 
   // Skill preloading: when skills is string[], preload their content into prompt
   if (Array.isArray(skills)) {
@@ -808,7 +873,7 @@ export async function runAgent(
   // which extensions load. `ext:foo` against an extension that `extensions:` excluded
   // is an orphan and warns after reload. `isolated` means no extension tools at all.
   const { extNames, narrowing } = parseExtSelectors(
-    options.isolated ? [] : (agentConfig?.extSelectors ?? []),
+    isolated ? [] : (agentConfig?.extSelectors ?? []),
   )
   const noExtensions = extensions === false
 
@@ -847,6 +912,7 @@ export async function runAgent(
           return {
             ...base,
             extensions: base.extensions.filter((e) => {
+              if (e.path === `<inline:${SCOPE_GATE_NAME}>`) return true // ours, not the agent's
               const canons = extensionCanonicalNames(e.path)
               if (canons.some((n) => excludeNames.has(n))) return false // exclude wins
               return loadAll || canons.some((n) => keepNames.has(n))
@@ -854,7 +920,68 @@ export async function runAgent(
           }
         }
 
+  // The child inherits the parent's project-trust decision. pi's SettingsManager
+  // defaults to trusted, so without this a subagent in a project the user declined
+  // to trust would load its `.pi` extensions and settings, and pi's built-in MCP
+  // would start the stdio servers in its `.pi/mcp.json`.
+  const projectTrusted = ctx.isProjectTrusted()
+  const settingsManager = SettingsManager.create(configCwd, agentDir, {
+    projectTrusted,
+  })
+  // That trust covers the parent's project (`configCwd`), not a directory a spawn
+  // was sent into. The session answers `ctx.isProjectTrusted()` for its own cwd,
+  // which pi's MCP uses to read `<cwd>/.pi/mcp.json` — so a cross-directory session
+  // keeps the parent project's settings but reports its cwd as untrusted. The
+  // loader keeps the trusted manager: it loads the parent project's extensions.
+  const sessionSettingsManager =
+    resolve(effectiveCwd) === resolve(configCwd)
+      ? settingsManager
+      : Object.assign(
+          SettingsManager.create(configCwd, agentDir, { projectTrusted }),
+          {
+            isProjectTrusted: () => false,
+          },
+        )
+  const nestedCallGate: NestedCallGate = {}
+
   const loader = new DefaultResourceLoader({
+    settingsManager,
+    // pi's CLI hands its built-in extensions to the loader it builds; this one starts
+    // with none. Forwarded as `builtin:` resources they load as in the main session —
+    // default-on, disabled by `-builtin:<name>` in settings — and the per-agent
+    // allowlist filters them like any other extension. pi's `llama.cpp` built-in is
+    // CLI-only (not exported). Fresh factories per spawn: MCP state lives in the closure.
+    extensionFactories: [
+      {
+        name: "codemode",
+        factory: createCodemodeExtension(),
+        builtin: true,
+        replaceable: true,
+      },
+      {
+        name: "tool-search",
+        factory: createToolSearchExtension(),
+        builtin: true,
+        replaceable: true,
+      },
+      {
+        name: "mcp",
+        factory: createMcpExtension(),
+        builtin: true,
+        replaceable: true,
+      },
+      // Under `noExtensions` the static allowlist gates the registry itself.
+      ...(noExtensions ? [] : [scopeGateExtension(nestedCallGate)]),
+    ],
+    // Mirrors pi's CLI: `--no-mcp` keeps MCP out of subagents too, and `--no-extensions`
+    // keeps all the built-ins out. Discovered extensions still follow `extensions:`.
+    disabledBuiltinExtensions: process.argv.some(
+      (a) => a === "--no-extensions" || a === "-ne",
+    )
+      ? ["codemode", "tool-search", "mcp"]
+      : process.argv.includes("--no-mcp")
+        ? ["mcp"]
+        : undefined,
     cwd: configCwd,
     agentDir,
     noExtensions,
@@ -967,7 +1094,7 @@ export async function runAgent(
       ? options.nestedRuntime
       : undefined
   const nestedTools =
-    agentConfig?.allowedSubagents && nestedRuntime && !options.isolated
+    agentConfig?.allowedSubagents && nestedRuntime && !isolated
       ? createNestedSubagentTools({
           manager: nestedRuntime.manager,
           pi: options.pi,
@@ -1075,7 +1202,6 @@ export async function runAgent(
     sessionExcludeTools = [...denyTools]
   }
 
-  const settingsManager = SettingsManager.create(configCwd, agentDir)
   const configuredSessionDir = resolveConfiguredSessionDir(
     agentConfig?.sessionDir,
     effectiveCwd,
@@ -1125,7 +1251,7 @@ export async function runAgent(
     cwd: effectiveCwd,
     agentDir,
     sessionManager,
-    settingsManager,
+    settingsManager: sessionSettingsManager,
     modelRegistry: ctx.modelRegistry,
     // `as never` is what keeps this assignable across the supported Pi range:
     // pre-0.80.8 the field exists only via the `modelRuntime?: unknown` shim
@@ -1184,6 +1310,7 @@ export async function runAgent(
       extNames,
       narrowing,
       readmitToolNames,
+      nestedCallGate,
     })
   }
 
@@ -1267,7 +1394,10 @@ export async function runAgent(
   const startLen = session.messages.length
   let structuredRetried = false
   try {
-    await session.prompt(effectivePrompt)
+    // A signal that fired before this point never calls the listener above, and
+    // pi's `session.abort()` is a no-op until a run is active — so a child whose
+    // parent is already gone is not prompted at all.
+    if (options.signal?.aborted !== true) await session.prompt(effectivePrompt)
 
     // One more prompt when a schema was asked for and nothing usable came back
     // — the model answered in prose, or only ever called the tool invalidly.
@@ -1374,7 +1504,8 @@ export async function resumeAgent(
       : () => {}
 
   try {
-    await session.prompt(prompt)
+    // Already aborted: not prompted, as in `runAgent`.
+    if (options.signal?.aborted !== true) await session.prompt(prompt)
   } finally {
     collector.unsubscribe()
     unsubEvents()

package/src/agent-source-badge.ts

@@ -0,0 +1,78 @@
+/**
+ * agent-source-badge.ts — How `/agents → Agent types` shows where an agent came
+ * from: the per-row badge, the legend that explains the badges actually on
+ * screen, and the description line under the highlighted row.
+ *
+ * These live outside src/index.ts for the same reason as agent-file-toggle.ts:
+ * the `/agents` handler is a large closure reached only through
+ * `registerCommand`, which every test mocks, so nothing inside it can be
+ * asserted on directly.
+ *
+ * The badges are deliberately terse — the list is one row per agent and the
+ * model already occupies the right-hand column. Anything wordier than a glyph
+ * (the package's name, in particular) goes on the description line, which
+ * `SettingsList` renders for the highlighted row only.
+ */
+
+import type { AgentConfig } from "./types.js"
+
+/**
+ * The badge column: a two-cell glyph plus a space, so every label starts at the
+ * same offset whether or not the agent is badged.
+ *
+ * Built-in defaults are unmarked. They are the majority of the list, and a
+ * badge on them would make the three that matter — the agents the user or a
+ * package put there — harder to pick out, not easier.
+ */
+export function sourceIndicator(cfg: AgentConfig | undefined): string {
+  const disabled = cfg?.enabled === false
+  if (cfg?.source === "project") return disabled ? "✕• " : "•  "
+  if (cfg?.source === "global") return disabled ? "✕◦ " : "◦  "
+  if (cfg?.source === "package") return disabled ? "✕▪ " : "▪  "
+  if (disabled) return "✕  "
+  return "   "
+}
+
+/**
+ * The legend line, naming only the badges the given roster actually renders.
+ *
+ * Keyed on what `sourceIndicator` would emit, so the two cannot drift into a
+ * glyph with no key (which is what `▪` was) or a key for a glyph that is not on
+ * screen. A defaults-only roster returns "", and the caller omits the line.
+ *
+ * `source` is undefined for built-in defaults — the `"default"` member of the
+ * union is declared but never assigned, since default-agents.ts sets only
+ * `isDefault` — so they contribute no key, matching their blank badge.
+ */
+export function sourceLegend(
+  cfgs: readonly (AgentConfig | undefined)[],
+): string {
+  const parts: string[] = []
+  if (cfgs.some((c) => c?.source === "project")) parts.push("• = project")
+  if (cfgs.some((c) => c?.source === "global")) parts.push("◦ = global")
+  if (cfgs.some((c) => c?.source === "package")) parts.push("▪ = package")
+  if (cfgs.some((c) => c?.enabled === false)) parts.push("✕ = disabled")
+  return parts.join("  ")
+}
+
+/**
+ * The description line under the highlighted row.
+ *
+ * `packageName` is the one piece of provenance a badge cannot carry: with two
+ * agent-providing packages installed, `▪` says only that *some* package won.
+ * It is prefixed rather than appended so it stays visible when a long
+ * description wraps, and it prefixes "(disabled)" too — a disabled package
+ * agent is exactly the case where you want to know whose it was.
+ *
+ * Falls back to the agent's own name when it has no description, which is what
+ * a hand-written agent file without one already showed.
+ */
+export function rowDescription(
+  name: string,
+  cfg: AgentConfig | undefined,
+  packageName?: string,
+): string {
+  const base =
+    cfg?.enabled === false ? "(disabled)" : (cfg?.description ?? name)
+  return packageName ? `${packageName} · ${base}` : base
+}

package/src/completion-outbox.ts

@@ -0,0 +1,122 @@
+/**
+ * completion-outbox.ts — When background completions reach the parent.
+ *
+ * Claude Code queues each completion and, after every tool batch, hands the
+ * model everything that queued up in one go: a busy parent sees what finished
+ * during the batch before its next model call, and nothing waits for a sibling.
+ * pi's steering queue would split those into one model call each under its
+ * default `one-at-a-time` mode, so the outbox holds them and sends ONE message
+ * at the boundary instead.
+ *
+ * - Parent busy: held until `turn_end`, which pi emits after the tool batch and
+ *   before it reads the steering queue.
+ * - Parent idle: sent after a short hold, so near-simultaneous completions
+ *   share a turn and `get_subagent_result` still gets a moment to consume one.
+ * - Parent turn aborted (Esc) or failed: held through it — pi clears its own
+ *   queues on Esc — and sent once the run has ended, starting a turn. Claude
+ *   Code keeps an agent's completion queued through Esc the same way and runs
+ *   it as soon as the interrupted turn stops.
+ */
+
+import type { NotificationDetails } from "./types.js"
+
+/** How long an idle parent's notification is held before it is sent. */
+export const NOTIFICATION_HOLD_MS = 200
+
+export interface OutboxMessage {
+  content: string
+  details: NotificationDetails
+}
+
+/**
+ * A notification for one or more agents, built when they finished: a resume
+ * before the send must not rewrite it. Reading an agent's result cancels its
+ * id, and an item left with none is dropped; `build` gets the ids still pending.
+ */
+export interface OutboxItem {
+  ids: string[]
+  build(ids: readonly string[]): OutboxMessage
+}
+
+export class CompletionOutbox {
+  private items: OutboxItem[] = []
+  private timer: ReturnType<typeof setTimeout> | undefined
+
+  constructor(
+    /** Delivers one message as a steer that triggers a turn when the parent is idle. */
+    private send: (message: OutboxMessage) => void,
+    /** Whether the parent has a run in flight, so a `turn_end` is coming. */
+    private parentRunning: () => boolean,
+  ) {}
+
+  /** A newer completion of the same agent (a resume) replaces its pending one. */
+  add(item: OutboxItem): void {
+    for (const id of item.ids) this.cancel(id)
+    this.items.push(item)
+    if (!this.parentRunning()) this.arm()
+  }
+
+  /** The parent finished a turn: its tool batch is done, the next model call is not. */
+  onTurnEnd(stopReason: string | undefined): void {
+    // An aborted turn ends its run; a failed one may be retried. Either way
+    // what is held waits for the next boundary or the run's end — sent now,
+    // it would sit in a queue pi is about to clear.
+    if (stopReason !== "aborted" && stopReason !== "error") this.flush()
+  }
+
+  /** The agent's result was read: it must not also be notified. */
+  cancel(id: string): void {
+    for (const item of this.items) item.ids = item.ids.filter((i) => i !== id)
+    this.items = this.items.filter((item) => item.ids.length > 0)
+  }
+
+  /**
+   * Completions that landed after the run's last `turn_end` would otherwise wait for the next run.
+   * Called at `agent_end` and again at `agent_settled`: one can land while the ending run is still open.
+   */
+  onAgentEnd(): void {
+    if (this.items.length > 0) this.arm()
+  }
+
+  dispose(): void {
+    if (this.timer) clearTimeout(this.timer)
+    this.timer = undefined
+    this.items = []
+  }
+
+  /** Not reset by later items: the first completion is never pushed back. */
+  private arm(): void {
+    this.timer ??= setTimeout(() => {
+      this.timer = undefined
+      this.flush()
+    }, NOTIFICATION_HOLD_MS)
+  }
+
+  private flush(): void {
+    if (this.timer) clearTimeout(this.timer)
+    this.timer = undefined
+    const items = this.items
+    this.items = []
+    const messages = items.map((item) => item.build(item.ids))
+    if (messages.length === 0) return
+    // A send from a timer can outlive the session it was meant for (pi -p
+    // tearing down): pi throws on the stale context, and nothing is left to tell.
+    try {
+      this.send(combine(messages))
+    } catch {
+      /* stale context */
+    }
+  }
+}
+
+/** One message stays as it was built; several become one message with every agent's details. */
+function combine(messages: OutboxMessage[]): OutboxMessage {
+  if (messages.length === 1) return messages[0]
+  const [first, ...rest] = messages.flatMap(
+    ({ details: { others, ...own } }) => [own, ...(others ?? [])],
+  )
+  return {
+    content: `${messages.length} background tasks finished.\n\n${messages.map((m) => m.content).join("\n\n")}`,
+    details: { ...first, others: rest },
+  }
+}