@trim21/personal-pi-extensions 0.0.156 → 0.0.161

package/README.md

@@ -4,13 +4,12 @@
 
 ## 扩展概览
 
-| 扩展                                              | 描述                                                         |
-| ------------------------------------------------- | ------------------------------------------------------------ |
-| [bwrap](#bwrap)                                   | 基于 bubblewrap 的 OS 级沙箱，提供文件系统和网络隔离         |
-| [workspace-guard](#workspace-guard)               | 限制文件写入在 workspace 内，外部写入需用户审批              |
-| [opencode-edit](#opencode-edit)                   | 替换内置 edit 工具，使用 opencode 的 schema 和匹配引擎       |
-| [bash-default-timeout](#bash-default-timeout)     | 为 bash 工具设置默认超时（180 秒）                           |
-| [agents-md-user-message](#agents-md-user-message) | 将项目级 AGENTS.md 移至 user message，避免占用 system prompt |
+| 扩展                                          | 描述                                                   |
+| --------------------------------------------- | ------------------------------------------------------ |
+| [bwrap](#bwrap)                               | 基于 bubblewrap 的 OS 级沙箱，提供文件系统和网络隔离   |
+| [workspace-guard](#workspace-guard)           | 限制文件写入在 workspace 内，外部写入需用户审批        |
+| [opencode-edit](#opencode-edit)               | 替换内置 edit 工具，使用 opencode 的 schema 和匹配引擎 |
+| [bash-default-timeout](#bash-default-timeout) | 为 bash 工具设置默认超时（180 秒）                     |
 
 ---
 
@@ -134,23 +133,6 @@ pi -e ./src/bash-default-timeout.ts
 
 ---
 
-## agents-md-user-message
-
-将项目级 `AGENTS.md` 从 system prompt 移至 user message，减少 system prompt 占用。
-
-- 项目级 `AGENTS.md` → 放入 user message（仅首次消息注入一次）
-- 全局 `~/.pi/agent/AGENTS.md` → 保留在 system prompt
-
-需要配合 `--no-context-files` 参数禁用 pi 默认的上下文文件加载。
-
-### 使用
-
-```bash
-pi -e ./src/agents-md-user-message.ts --no-context-files
-```
-
----
-
 ## 安装
 
 ### 通过 npm/git 包

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.156",
+  "version": "0.0.161",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [

package/src/bwrap/index.ts

@@ -104,8 +104,29 @@ work inside the sandbox, run it WITHOUT full access first. If it fails with
 and set \`request_full_access_reason\` to describe the failure.
 `;
 
+const SUBAGENT_SANDBOX_PROMPT = `
+## Command Execution (subagent sandbox)
+
+You are running inside a read-only sandbox in a subagent session.
+
+- The bash tool is read-only: no filesystem writes, no network access, and
+  \`request_full_access\` is denied. Do not pass \`request_full_access\`.
+- Use the write/edit tools for file changes inside your workspace.
+- Writes outside the workspace are rejected. If a change outside the
+  workspace is needed, ask the parent session to apply it.
+- If a command truly requires network or system-level access, stop and ask
+  the parent session to run it, where the user can approve it.
+`;
+
 const PROTECTED_DIRS = [".git", ".pi", ".agent"];
 
+/**
+ * pi-subagents sets PI_SUBAGENT_CHILD=1 in every spawned child session
+ * (foreground and async alike). Subagent sessions are headless and must not
+ * be able to bypass the sandbox, so bwrap forces read-only bash there.
+ */
+const isSubagentChild = process.env.PI_SUBAGENT_CHILD === "1";
+
 const bwrapPath = findDefaultBwrap();
 
 function findDefaultBwrap(): string {
@@ -134,7 +155,7 @@ function findBwrap(override?: string): string {
 
 type BwrapMode = "allow-all" | "workspace-write" | "readonly";
 
-interface BwrapConfig {
+export interface BwrapConfig {
   mode: BwrapMode;
   bwrapPath?: string;
   writablePaths?: string[];
@@ -143,7 +164,7 @@ interface BwrapConfig {
   extraArgs?: string[];
 }
 
-interface ResolvedBwrap {
+export interface ResolvedBwrap {
   mode: BwrapMode;
   bwrapEnabled: boolean;
   network: boolean;
@@ -176,6 +197,22 @@ function resolveBwrap(config: BwrapConfig): ResolvedBwrap {
   }
 }
 
+/**
+ * Subagent sessions are forced read-only regardless of config: no writable
+ * paths (including configured extraWritablePaths), no network, and no
+ * user-supplied extra args that could add writable mounts.
+ */
+export function resolveSubagentBwrap(config: BwrapConfig): ResolvedBwrap {
+  return resolveBwrap({
+    ...config,
+    mode: "readonly",
+    writablePaths: [],
+    extraWritablePaths: [],
+    tmpfsPaths: [],
+    extraArgs: [],
+  });
+}
+
 const DEFAULT_CONFIG: BwrapConfig = {
   mode: "workspace-write",
   writablePaths: [".", "/tmp"],
@@ -483,6 +520,36 @@ function notifyMode(
   ctx.ui.notify(labels[mode], "info");
 }
 
+export type EscalationDecision = { kind: "dialog" } | { kind: "deny"; reason: string };
+
+/**
+ * Escalation (`request_full_access`) policy:
+ * - Subagent sessions are always denied: bash is read-only there and there is
+ *   no approval path (headless), so escalation would silently bypass the sandbox.
+ * - Any other headless session is denied: there is no user to approve.
+ * - Interactive sessions require the user approval dialog.
+ */
+export function resolveEscalation(opts: {
+  hasUI: boolean;
+  isSubagentChild: boolean;
+}): EscalationDecision {
+  if (opts.isSubagentChild) {
+    return {
+      kind: "deny",
+      reason:
+        "request_full_access is disabled in subagent sessions: the bash tool is read-only and cannot escalate. Ask the parent session to run this command.",
+    };
+  }
+  if (!opts.hasUI) {
+    return {
+      kind: "deny",
+      reason:
+        "request_full_access requires an interactive session with user approval; no UI is available in this session.",
+    };
+  }
+  return { kind: "dialog" };
+}
+
 const sandboxedBashSchema = Type.Object({
   command: Type.String({ description: "Bash command to execute" }),
   timeout: Type.Optional(
@@ -517,6 +584,10 @@ export default function bwrapExtension(pi: ExtensionAPI) {
   let resolved: ResolvedBwrap | null = null;
 
   function getResolved(): ResolvedBwrap {
+    // Subagents ignore config and runtime switches: bash is always read-only.
+    if (isSubagentChild) {
+      return resolveSubagentBwrap(loadConfig(localCwd));
+    }
     if (!resolved) {
       resolved = resolveBwrap(loadConfig(localCwd));
     }
@@ -524,6 +595,7 @@ export default function bwrapExtension(pi: ExtensionAPI) {
   }
 
   function setMode(mode: BwrapMode) {
+    if (isSubagentChild) return; // mode switching is not allowed in subagents
     const config = loadConfig(localCwd);
     config.mode = mode;
     resolved = resolveBwrap(config);
@@ -550,6 +622,11 @@ export default function bwrapExtension(pi: ExtensionAPI) {
       const escalate = params.request_full_access === true;
 
       if (escalate) {
+        const policy = resolveEscalation({ hasUI: ctx?.hasUI ?? false, isSubagentChild });
+        if (policy.kind === "deny") {
+          throw new Error(policy.reason);
+        }
+
         if (ctx?.hasUI) {
           const reason = params.request_full_access_reason;
           const reasonText = reason
@@ -595,7 +672,9 @@ export default function bwrapExtension(pi: ExtensionAPI) {
   pi.on("session_start", (_event, ctx) => {
     const noBwrap = pi.getFlag("no-bwrap") === true;
 
-    if (noBwrap) {
+    // Subagent sessions are always sandboxed read-only; --no-bwrap must not
+    // disable that (the flag is only honored in the parent session).
+    if (noBwrap && !isSubagentChild) {
       resolved = null;
       ctx.ui.notify("bwrap sandbox disabled via --no-bwrap", "warning");
       return;
@@ -612,7 +691,7 @@ export default function bwrapExtension(pi: ExtensionAPI) {
     }
 
     const config = loadConfig(ctx.cwd);
-    resolved = resolveBwrap(config);
+    resolved = isSubagentChild ? resolveSubagentBwrap(config) : resolveBwrap(config);
 
     if (resolved.bwrapEnabled) {
       try {
@@ -644,8 +723,9 @@ export default function bwrapExtension(pi: ExtensionAPI) {
     const r = getResolved();
 
     return {
-      systemPrompt:
-        event.systemPrompt + "\n\n" + SANDBOX_PROMPT + `\n\nCurrent mode: **${r.mode}**\n`,
+      systemPrompt: isSubagentChild
+        ? event.systemPrompt + "\n\n" + SUBAGENT_SANDBOX_PROMPT
+        : event.systemPrompt + "\n\n" + SANDBOX_PROMPT + `\n\nCurrent mode: **${r.mode}**\n`,
     };
   });
 

package/src/gh-readonly.ts

@@ -177,7 +177,7 @@ export class GhError extends Error {
 /** Run `gh` and return stdout. On non-zero exit, throws a `GhError` carrying the toolcall input and raw command. */
 export async function ghExec(
   args: string[],
-  ctx: { cwd?: string; signal?: AbortSignal; input?: unknown },
+  ctx: { cwd?: string; signal?: AbortSignal; input?: unknown; timeout?: number },
 ): Promise<string> {
   const result = await runGh(args, ctx);
   if (result.code !== 0) {

package/src/spawn-agent-agents.ts

@@ -0,0 +1,106 @@
+/**
+ * Agent discovery for the `spawn_agent` tool.
+ *
+ * Subagents are defined as markdown files in `~/.pi/agent/agents/*.md`
+ * (user-level only; project-local agents are intentionally not supported).
+ * Each file carries YAML frontmatter plus a system-prompt body:
+ *
+ *   ---
+ *   name: scout
+ *   description: Fast codebase recon
+ *   tools:
+ *     - read
+ *     - grep
+ *     - find
+ *     - ls
+ *   model: claude-haiku-4-5     # optional
+ *   thinkingLevel: high         # optional; applied as "model:high"
+ *   ---
+ *   System prompt for the agent goes here.
+ *
+ * Frontmatter is validated with a typebox schema; files that fail validation
+ * (missing name/description, wrong field types) are skipped. If `tools` is
+ * omitted, the subagent runs with the read-only default toolset from the
+ * spawn-agent config (read/grep/find/ls) unless overridden there.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
+/** Valid thinking levels, mirroring pi's ThinkingLevel type. */
+const THINKING_LEVELS = ["minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+const agentFrontmatterSchema = Type.Object({
+  name: Type.String({ minLength: 1 }),
+  description: Type.String({ minLength: 1 }),
+  tools: Type.Optional(Type.Array(Type.String())),
+  model: Type.Optional(Type.String()),
+  thinkingLevel: Type.Optional(Type.Union(THINKING_LEVELS.map((level) => Type.Literal(level)))),
+});
+
+function parseAgentFrontmatter(frontmatter: unknown) {
+  try {
+    return Value.Parse(agentFrontmatterSchema, frontmatter);
+  } catch {
+    return null;
+  }
+}
+
+export interface AgentConfig {
+  name: string;
+  description: string;
+  /** Toolset from the frontmatter; undefined means "use the config default". */
+  tools?: string[];
+  model?: string;
+  /** Thinking level, applied as a ":level" suffix on the model id. */
+  thinkingLevel?: (typeof THINKING_LEVELS)[number];
+  systemPrompt: string;
+  filePath: string;
+}
+
+export function discoverAgents(dir = join(getAgentDir(), "agents")): AgentConfig[] {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const agents: AgentConfig[] = [];
+  for (const entry of entries) {
+    if (!entry.name.endsWith(".md")) continue;
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+    const filePath = join(dir, entry.name);
+    let content: string;
+    try {
+      content = readFileSync(filePath, "utf8");
+    } catch {
+      continue;
+    }
+
+    const { frontmatter, body } = parseFrontmatter(content);
+    const fm = parseAgentFrontmatter(frontmatter);
+    if (!fm) continue; // missing name/description or wrong field types → not an agent
+
+    agents.push({
+      name: fm.name,
+      description: fm.description,
+      tools: fm.tools,
+      model: fm.model,
+      thinkingLevel: fm.thinkingLevel,
+      systemPrompt: body,
+      filePath,
+    });
+  }
+  return agents;
+}
+
+export function formatAgentList(agents: AgentConfig[]): string {
+  if (agents.length === 0) return "none";
+  return agents.map((a) => `${a.name}: ${a.description}`).join("; ");
+}

package/src/spawn-agent.ts

@@ -0,0 +1,452 @@
+/**
+ * spawn_agent tool — delegate a task to a subagent running in a separate pi
+ * process with an isolated context window.
+ *
+ * The subagent definition comes from `~/.pi/agent/agents/*.md` (markdown with
+ * YAML frontmatter, see spawn-agent-agents.ts). The extension discovers the
+ * available subagent types once at startup and appends them to the system
+ * prompt on every agent start (same pattern as the bwrap extension), so the
+ * model always knows which `agent` names it can pass to the tool. Execution
+ * is blocking: the tool awaits the subagent process until it exits and
+ * returns its final output to the parent model. Progress is streamed through
+ * `onUpdate`, the same channel the built-in bash tool uses for live output.
+ *
+ * Security default: without an explicit `tools:` in the frontmatter, the
+ * subagent only gets read-only tools (read/grep/find/ls) — no bash/write/edit.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { Message } from "@earendil-works/pi-ai";
+import {
+  type ExtensionAPI,
+  getMarkdownTheme,
+  truncateTail,
+  withFileMutationQueue,
+} from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import { type AgentConfig, discoverAgents, formatAgentList } from "./spawn-agent-agents.js";
+
+// ── constants ────────────────────────────────────────────────────────────────
+
+/** Subagent output returned to the parent model is capped at 50KB. */
+const MAX_OUTPUT_BYTES = 50 * 1024;
+/** Read-only toolset used when an agent does not declare `tools`. */
+const DEFAULT_TOOLS = ["read", "grep", "find", "ls"];
+
+// ── schema ───────────────────────────────────────────────────────────────────
+
+const spawnAgentSchema = Type.Object({
+  agent: Type.String({
+    description:
+      "Name of the subagent type to invoke. Choose one of the available subagent types listed in your system prompt.",
+  }),
+  task: Type.String({ description: "Task to delegate to the subagent" }),
+});
+
+// ── result types ─────────────────────────────────────────────────────────────
+
+interface UsageStats {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextTokens: number;
+  turns: number;
+}
+
+interface SubagentDetails {
+  agent: string;
+  task: string;
+  exitCode: number;
+  messages: Message[];
+  stderr: string;
+  usage: UsageStats;
+  model?: string;
+  stopReason?: string;
+  errorMessage?: string;
+}
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function getFinalOutput(messages: Message[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role === "assistant") {
+      for (const part of msg.content) {
+        if (part.type === "text") return part.text;
+      }
+    }
+  }
+  return "";
+}
+
+function formatTokens(count: number): string {
+  if (count < 1000) return count.toString();
+  if (count < 10_000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1_000_000) return `${Math.round(count / 1000)}k`;
+  return `${(count / 1_000_000).toFixed(1)}M`;
+}
+
+function formatUsageStats(usage: UsageStats, model?: string): string {
+  const parts: string[] = [];
+  if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
+  if (usage.input) parts.push(`↑${formatTokens(usage.input)}`);
+  if (usage.output) parts.push(`↓${formatTokens(usage.output)}`);
+  if (usage.cacheRead) parts.push(`R${formatTokens(usage.cacheRead)}`);
+  if (usage.cacheWrite) parts.push(`W${formatTokens(usage.cacheWrite)}`);
+  if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
+  if (usage.contextTokens > 0) parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
+  if (model) parts.push(model);
+  return parts.join(" ");
+}
+
+/**
+ * Resolve how to spawn the subagent process. Running through the current
+ * entry script (when available) keeps model/tool/extension config identical
+ * to the parent; otherwise fall back to the `pi` binary on PATH.
+ */
+function getPiInvocation(args: string[]): { command: string; args: string[] } {
+  const currentScript = process.argv[1];
+  const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
+  if (currentScript && !isBunVirtualScript && existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...args] };
+  }
+  const execName = basename(process.execPath).toLowerCase();
+  const isGenericRuntime = /^(node|bun)(\.exe)?$/.test(execName);
+  if (!isGenericRuntime) return { command: process.execPath, args };
+  return { command: "pi", args };
+}
+
+async function writePromptToTempFile(agentName: string, prompt: string): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), "pi-spawn-agent-"));
+  const safeName = agentName.replaceAll(/[^\w.-]+/g, "_");
+  const filePath = join(dir, `prompt-${safeName}.md`);
+  await withFileMutationQueue(filePath, async () => {
+    await writeFile(filePath, prompt, { encoding: "utf8", mode: 0o600 });
+  });
+  return filePath;
+}
+
+export function buildSubagentArgs(
+  agent: AgentConfig,
+  task: string,
+  systemPromptPath: string | undefined,
+): string[] {
+  // --mode json: emit events as JSON lines; -p: single-shot answer;
+  // --no-session: ephemeral, do not persist. --no-extensions keeps the
+  // subagent clean (no recursive spawn_agent, no sandbox surprises).
+  const args: string[] = ["--mode", "json", "-p", "--no-session", "--no-extensions"];
+  // Thinking level rides on the model shorthand ("model:level"); it cannot be
+  // set without a model, so a level without a model is ignored.
+  const model =
+    agent.model !== undefined && agent.thinkingLevel !== undefined
+      ? `${agent.model}:${agent.thinkingLevel}`
+      : agent.model;
+  if (model) args.push("--model", model);
+  // Read-only default unless the agent explicitly declares a toolset.
+  const tools = agent.tools ?? DEFAULT_TOOLS;
+  args.push("--tools", tools.join(","));
+  if (systemPromptPath) args.push("--append-system-prompt", systemPromptPath);
+  args.push(`Task: ${task}`);
+  return args;
+}
+
+// ── subagent runner ──────────────────────────────────────────────────────────
+
+type OnUpdateCallback = (partial: AgentToolResult<SubagentDetails>) => void;
+
+export async function runAgent(
+  agent: AgentConfig,
+  task: string,
+  cwd: string,
+  signal: AbortSignal | undefined,
+  onUpdate: OnUpdateCallback | undefined,
+): Promise<SubagentDetails> {
+  const result: SubagentDetails = {
+    agent: agent.name,
+    task,
+    exitCode: 0,
+    messages: [],
+    stderr: "",
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      cost: 0,
+      contextTokens: 0,
+      turns: 0,
+    },
+    model: agent.model,
+  };
+
+  let tmpPromptPath: string | null = null;
+  try {
+    if (agent.systemPrompt.trim()) {
+      tmpPromptPath = await writePromptToTempFile(agent.name, agent.systemPrompt);
+    }
+    const args = buildSubagentArgs(agent, task, tmpPromptPath ?? undefined);
+    const invocation = getPiInvocation(args);
+    const proc = spawn(invocation.command, invocation.args, {
+      cwd,
+      shell: false,
+      stdio: ["ignore", "pipe", "pipe"],
+      // Mark the child as a subagent so extensions running inside it (e.g.
+      // bwrap's subagent policy) can recognize and treat it accordingly.
+      env: { ...process.env, PI_SUBAGENT_CHILD: "1" },
+    });
+
+    const emitUpdate = () => {
+      onUpdate?.({
+        content: [{ type: "text", text: getFinalOutput(result.messages) || "(running...)" }],
+        details: { ...result },
+      });
+    };
+
+    let buffer = "";
+
+    const processLine = (line: string) => {
+      if (!line.trim()) return;
+      let event: unknown;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        return; // not a JSON event line
+      }
+      if (!isRecord(event)) return;
+
+      if (event.type === "message_end" && isRecord(event.message)) {
+        const msg = event.message as unknown as Message;
+        result.messages.push(msg);
+        if (msg.role === "assistant") {
+          result.usage.turns++;
+          const usage: Record<string, unknown> = isRecord(msg.usage) ? msg.usage : {};
+          result.usage.input += num(usage.input);
+          result.usage.output += num(usage.output);
+          result.usage.cacheRead += num(usage.cacheRead);
+          result.usage.cacheWrite += num(usage.cacheWrite);
+          result.usage.cost += num(isRecord(usage.cost) ? usage.cost.total : undefined);
+          result.usage.contextTokens = num(usage.totalTokens);
+          if (!result.model && typeof msg.model === "string") result.model = msg.model;
+          if (typeof msg.stopReason === "string") result.stopReason = msg.stopReason;
+          if (typeof msg.errorMessage === "string") result.errorMessage = msg.errorMessage;
+        }
+        emitUpdate();
+      } else if (event.type === "tool_result_end" && isRecord(event.message)) {
+        result.messages.push(event.message as unknown as Message);
+        emitUpdate();
+      }
+    };
+
+    proc.stdout.on("data", (data: Buffer) => {
+      buffer += data.toString();
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) processLine(line);
+    });
+
+    proc.stderr.on("data", (data: Buffer) => {
+      result.stderr += data.toString();
+    });
+
+    const exitCode = await new Promise<number>((resolve) => {
+      proc.on("close", (code) => {
+        if (buffer.trim()) processLine(buffer);
+        resolve(code ?? 0);
+      });
+      proc.on("error", () => resolve(1));
+
+      const kill = () => {
+        proc.kill("SIGTERM");
+        setTimeout(() => {
+          if (!proc.killed) proc.kill("SIGKILL");
+        }, 5000);
+      };
+      if (signal) {
+        if (signal.aborted) kill();
+        else signal.addEventListener("abort", kill, { once: true });
+      }
+    });
+
+    result.exitCode = exitCode;
+    return result;
+  } finally {
+    if (tmpPromptPath) {
+      try {
+        await rm(tmpPromptPath, { force: true });
+        await rm(dirname(tmpPromptPath), { recursive: true, force: true });
+      } catch {
+        // best-effort cleanup
+      }
+    }
+  }
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+/** Session entry customType used to mark the injected subagent list. */
+export function formatAgentListSection(agents: AgentConfig[]): string {
+  const lines = agents.map((a) => `- \`${a.name}\`: ${a.description}`);
+  return [
+    "## Available subagents",
+    "",
+    "You can delegate tasks to the following subagent types by calling the `spawn_agent` tool with their name in the `agent` parameter:",
+    "",
+    ...lines,
+  ].join("\n");
+}
+
+// ── extension ────────────────────────────────────────────────────────────────
+
+export default function spawnAgent(pi: ExtensionAPI) {
+  // Discover the available subagent types once at extension startup. The
+  // extension owns this discovery: the model never has to guess agent names
+  // or read the agent directory itself. Editing ~/.pi/agent/agents/*.md
+  // requires /reload to take effect.
+  const agents = discoverAgents();
+  const agentListSection = agents.length > 0 ? formatAgentListSection(agents) : null;
+
+  if (agentListSection) {
+    // Same pattern as the bwrap extension: append the list to the system
+    // prompt on every agent start. The system prompt is rebuilt each turn
+    // anyway, so a persistent per-session injection would add no value.
+    pi.on("before_agent_start", (event) => {
+      return { systemPrompt: `${event.systemPrompt}\n\n${agentListSection}` };
+    });
+  }
+
+  pi.registerTool<typeof spawnAgentSchema, SubagentDetails>({
+    name: "spawn_agent",
+    label: "spawn_agent",
+    description: [
+      "Delegate a task to a subagent running in a separate pi process with an isolated context window.",
+      "The `agent` parameter must be one of the available subagent types listed in the system prompt.",
+      `Subagents run read-only (${DEFAULT_TOOLS.join(", ")}) unless the agent declares an explicit toolset.`,
+    ].join(" "),
+    parameters: spawnAgentSchema,
+
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const agent = agents.find((a) => a.name === params.agent);
+      if (!agent) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Unknown agent "${params.agent}". Available agents: ${formatAgentList(agents)}`,
+            },
+          ],
+          details: {
+            agent: params.agent,
+            task: params.task,
+            exitCode: 1,
+            messages: [],
+            stderr: "",
+            usage: {
+              input: 0,
+              output: 0,
+              cacheRead: 0,
+              cacheWrite: 0,
+              cost: 0,
+              contextTokens: 0,
+              turns: 0,
+            },
+          },
+          isError: true,
+        };
+      }
+
+      const result = await runAgent(agent, params.task, ctx.cwd, signal, onUpdate);
+
+      const isError =
+        result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
+      if (isError) {
+        const reason =
+          result.stopReason ?? (result.exitCode === 0 ? "failed" : `exit ${result.exitCode}`);
+        const message =
+          result.errorMessage || result.stderr || getFinalOutput(result.messages) || "(no output)";
+        return {
+          content: [
+            { type: "text", text: `Subagent "${result.agent}" failed (${reason}): ${message}` },
+          ],
+          details: result,
+          isError: true,
+        };
+      }
+
+      const output = getFinalOutput(result.messages) || "(no output)";
+      const truncation = truncateTail(output, { maxBytes: MAX_OUTPUT_BYTES });
+      const text = truncation.truncated
+        ? `${truncation.content}\n\n[Output truncated to ${formatTokens(truncation.content.length)} bytes. Full result preserved in tool details.]`
+        : output;
+      return { content: [{ type: "text", text }], details: result };
+    },
+
+    renderCall(args, theme) {
+      const preview = args.task.length > 60 ? `${args.task.slice(0, 60)}...` : args.task;
+      let text = theme.fg("toolTitle", theme.bold("spawn_agent ")) + theme.fg("accent", args.agent);
+      text += `\n  ${theme.fg("dim", preview)}`;
+      return new Text(text, 0, 0);
+    },
+
+    renderResult(result, { expanded }, theme) {
+      const details = result.details;
+      const isError =
+        details.exitCode !== 0 ||
+        details.stopReason === "error" ||
+        details.stopReason === "aborted";
+      const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
+      const finalOutput = getFinalOutput(details.messages);
+      const usageStr = formatUsageStats(details.usage, details.model);
+
+      if (expanded) {
+        const container = new Container();
+        const header = `${icon} ${theme.fg("toolTitle", theme.bold(details.agent))}${
+          details.stopReason ? ` ${theme.fg("error", `[${details.stopReason}]`)}` : ""
+        }`;
+        container.addChild(new Text(header, 0, 0));
+        if (isError && details.errorMessage) {
+          container.addChild(new Text(theme.fg("error", `Error: ${details.errorMessage}`), 0, 0));
+        }
+        container.addChild(new Spacer(1));
+        container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
+        container.addChild(new Text(theme.fg("dim", details.task), 0, 0));
+        if (finalOutput) {
+          container.addChild(new Spacer(1));
+          container.addChild(new Text(theme.fg("muted", "─── Output ───"), 0, 0));
+          container.addChild(new Markdown(finalOutput.trim(), 0, 0, getMarkdownTheme()));
+        }
+        if (usageStr) {
+          container.addChild(new Spacer(1));
+          container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
+        }
+        return container;
+      }
+
+      let text = `${icon} ${theme.fg("toolTitle", theme.bold(details.agent))}`;
+      if (isError && details.errorMessage) {
+        text += `\n${theme.fg("error", `Error: ${details.errorMessage}`)}`;
+      } else if (finalOutput) {
+        text += `\n${theme.fg("toolOutput", finalOutput.split("\n").slice(0, 5).join("\n"))}`;
+      } else {
+        text += `\n${theme.fg("muted", "(no output)")}`;
+      }
+      if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
+      return new Text(text, 0, 0);
+    },
+  });
+}

package/src/workspace-guard.ts

@@ -27,6 +27,13 @@ import { normalizeForEdit, replace } from "./opencode-edit-engine.js";
 const WRITE_TOOLS = new Set(["write", "edit"]);
 const ALWAYS_ALLOW = ["/tmp"];
 
+/**
+ * pi-subagents sets PI_SUBAGENT_CHILD=1 in every spawned child session.
+ * Subagents are headless, so there is no approval path: writes outside the
+ * workspace are rejected outright instead of asking for approval.
+ */
+const isSubagentChild = process.env.PI_SUBAGENT_CHILD === "1";
+
 /** Maximum lines of the diff preview shown in the approval dialog. */
 const MAX_PREVIEW_LINES = 100;
 
@@ -173,15 +180,48 @@ export async function buildDiffPreview(
   return wrapDiff(generateUnifiedPatch(basename(resolvedPath), oldContent, newContent, 2));
 }
 
+export interface WriteGuardDecision {
+  block: boolean;
+  reason?: string;
+}
+
+/**
+ * Decide how to handle a write outside the workspace.
+ * Subagent sessions (and any other headless session) have no approval path,
+ * so the write is rejected outright.
+ */
+export function decideOutsideWorkspaceWrite(
+  rawPath: string,
+  opts: { hasUI: boolean; isSubagentChild: boolean },
+): WriteGuardDecision {
+  if (opts.isSubagentChild) {
+    return {
+      block: true,
+      reason: `Path "${rawPath}" is outside the subagent workspace. Writes outside the workspace are rejected in subagent sessions; ask the parent session to apply this change.`,
+    };
+  }
+  if (!opts.hasUI) {
+    return {
+      block: true,
+      reason: `Path "${rawPath}" is outside workspace. No UI available for approval.`,
+    };
+  }
+  return { block: false };
+}
+
 export default function workspaceGuard(pi: ExtensionAPI) {
   pi.on("before_agent_start", (event, ctx) => {
     const currentCwd = ctx.cwd;
     return {
-      systemPrompt:
-        event.systemPrompt +
-        `\nWorkspace write protection is active. ` +
-        `write and edit to paths inside the workspace "${currentCwd}" or /tmp are auto-allowed. ` +
-        `Paths outside require user approval before execution.`,
+      systemPrompt: isSubagentChild
+        ? event.systemPrompt +
+          `\nSubagent write protection is active. ` +
+          `write and edit are allowed inside "${currentCwd}" and /tmp. ` +
+          `Writes outside the workspace are rejected without approval — ask the parent session to make such changes.`
+        : event.systemPrompt +
+          `\nWorkspace write protection is active. ` +
+          `write and edit to paths inside the workspace "${currentCwd}" or /tmp are auto-allowed. ` +
+          `Paths outside require user approval before execution.`,
     };
   });
 
@@ -195,12 +235,11 @@ export default function workspaceGuard(pi: ExtensionAPI) {
 
     if (isPathAllowed(resolved, ctx.cwd)) return;
 
-    if (!ctx.hasUI) {
-      return {
-        block: true,
-        reason: `Path "${rawPath}" is outside workspace. No UI available for approval.`,
-      };
-    }
+    const decision = decideOutsideWorkspaceWrite(rawPath, {
+      hasUI: ctx.hasUI,
+      isSubagentChild,
+    });
+    if (decision.block) return decision;
 
     let choice: string | undefined;
     while (!choice) {

package/src/agents-md-user-message.ts

@@ -1,71 +0,0 @@
-/**
- * AGENTS.md User Message
- *
- * Moves project-level AGENTS.md from system prompt to user message.
- * Global ~/.pi/agent/AGENTS.md stays in system prompt.
- *
- * Requires --no-context-files to disable pi's default context file loading.
- *
- * Usage:
- *   pi -e ./agents-md-user-message --no-context-files
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { getAgentDir, loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
-
-export default function agentsMdUserMessage(pi: ExtensionAPI) {
-  let messageInjected = false;
-
-  pi.on("before_agent_start", (event) => {
-    const contextFiles = event.systemPromptOptions.contextFiles ?? [];
-    if (contextFiles.length > 0) return; // pi already handled them
-
-    // --no-context-files was used, we handle everything
-    const files = loadProjectContextFiles({
-      cwd: event.systemPromptOptions.cwd,
-      agentDir: getAgentDir(),
-    });
-    if (files.length === 0) return;
-
-    const agentDir = getAgentDir();
-    const globalFiles = files.filter((f) => f.path.startsWith(agentDir));
-    const projectFiles = files.filter((f) => !f.path.startsWith(agentDir));
-
-    if (projectFiles.length === 0) return;
-
-    let systemPrompt = event.systemPrompt;
-    if (globalFiles.length > 0) {
-      let block = "\n\n<project_context>\n\nProject-specific instructions and guidelines:\n\n";
-      for (const { path, content } of globalFiles) {
-        block += `<project_instructions path="${path}">\n${content}\n</project_instructions>\n\n`;
-      }
-      block += "</project_context>\n";
-      systemPrompt += block;
-    }
-
-    if (!messageInjected) {
-      messageInjected = true;
-
-      const content = projectFiles
-        .map(
-          (f) => `<project_instructions path="${f.path}">\n${f.content}\n</project_instructions>`,
-        )
-        .join("\n\n");
-
-      return {
-        systemPrompt,
-        message: {
-          customType: "agents-md-user",
-          content,
-          display: true,
-        },
-      };
-    }
-
-    return { systemPrompt };
-  });
-
-  pi.on("session_shutdown", () => {
-    messageInjected = false;
-  });
-}