@bacnh85/pi-subagent 0.12.4 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # Changelog
 
+## 0.14.0 (2026-08-05)
+
+### Git worktree isolation (`sandbox: worktree`)
+
+Agents can now run in an isolated **git worktree** instead of the parent's
+working tree — the safe way to run parallel implementation agents that edit
+files. Set `sandbox: worktree` in agent frontmatter (see `agent-format.md`).
+
+- Child file mutations land in `.pi-worktrees/<id>` under the repo root; the
+  main checkout stays untouched, so two parallel `worker` agents can never
+  clobber each other's edits.
+- On completion, a unified diff of the child's changes is returned as
+  `result.patch` and shown in the thread viewer as a `🌿 worktree` badge.
+- **Merging is explicit** — the parent receives the diff and applies it via
+  `apply_patch` / cherry-pick / discard; nothing is auto-merged.
+- The worktree is removed in a `finally` on success, error, or abort.
+- Falls back to in-process execution with a warning when the cwd is not a git
+  repo (`ponytail`: isolation optimization, not a hard requirement).
+- Wired through the `subagent` tool, the service path (`pi-subagent:run` for
+  pi-review), and `runner.ts`'s `runSubAgent` (new `sandbox` + `exec` options).
+
+## 0.13.0 (2026-07-31)
+
+### Subagents inherit parent extensions & tools by default
+
+Subagents can now use the same tools the main agent has — including extension
+ tools like `web_search`, `serena_*`, `munin_*`, `obsidian`, and `notebooklm`.
+ Previously children were restricted to the 7 Pi built-in tools (`read, grep,
+ find, ls, bash, edit, write`) and could not load extensions, which made
+ delegation far less capable than the main agent.
+
+This follows the **Claude Code model**: subagents inherit the parent's tool set,
+ with a small denylist (`subagent` — recursive delegation is always prevented)
+ and per-agent restriction via an explicit `tools:` line.
+
+**Tool resolution:**
+- Agent **omits** `tools:` → inherits **all parent tools** (minus denylist).
+  `worker` and `general-purpose` now do this.
+- Agent **specifies** `tools:` → restricted to that list, validated against
+  built-ins ∪ parent tools.
+- `sandbox: read-only` / `readOnly` → filters the effective set to read-only.
+- Denied tools (`subagent`) are **silently stripped**, never errored — whether
+  explicitly listed or inherited. Inheritance must not crash on a tool the
+  child cannot have (the inherited set always includes `subagent`).
+
+**Smart lean optimization:** extensions are only loaded when the effective tool
+ set contains at least one non-built-in tool. Recon agents with a built-in-only
+ `tools:` line (scout, tester, planner, reviewer) stay cheap — zero extension
+ overhead, same fast cold-start.
+
+**Per-child extension loader.** Children that need extensions get a FRESH
+ `DefaultResourceLoader` each run (extensions only: no skills, prompt templates,
+ AGENTS.md, or themes). The loader must NOT be cached/shared: extensions capture
+ the ExtensionAPI at factory-load time, and its actions delegate to the runtime
+ the factory was given (pi.getAllTools() → runtime.getAllTools()). A shared
+ loader's runtime is never the one any single child binds — children then hit
+ the runtime's throwing "Extension runtime not initialized" stubs on the first
+ provider request (pi-model-tools' before_provider_request calls pi.getAllTools())
+ or stale-ctx errors after the first child's dispose invalidates the shared
+ runtime. A per-child loader keeps every captured `pi` pointing at a runtime the
+ child both binds and owns. reload() per child re-reads extension files +
+ re-runs factories; acceptable for short-lived children.
+
+Extension load errors in children are logged, not fatal. Project-extension trust
+ is inherited from the parent (children never prompt).
+
+### Bundled agent changes
+
+- `worker` and `general-purpose`: removed the explicit `tools:` line so they
+  inherit all parent tools.
+- `scout`, `tester`, `planner`, `reviewer`: unchanged (still lean + restricted).
+
 ## 0.12.4 (2026-07-30)
 
 ### Improvements

package/README.md

@@ -16,13 +16,15 @@ Requires Node.js >= 20.18.
 | --- | --- | --- | --- |
 | `scout` | `zai-coding-cn/glm-5-turbo` → `nvidia/openai/gpt-oss-20b` → `opencode-go/deepseek-v4-flash` | off | read, grep, find, ls |
 | `tester` | `zai-coding-cn/glm-5-turbo` → `nvidia/openai/gpt-oss-20b` → `opencode-go/deepseek-v4-flash` | off | read, bash, grep, find, ls |
-| `worker` | `zai-coding-cn/glm-5.1` → `nvidia/mistralai/mistral-small-4-119b-2603` → `openrouter/nvidia/nemotron-3-super-120b-a12b:free` → `opencode-go/deepseek-v4-flash` | medium | read, bash, edit, write, grep, find, ls |
-| `general-purpose` | `zai-coding-cn/glm-5.1` → `nvidia/mistralai/mistral-small-4-119b-2603` → `openrouter/nvidia/nemotron-3-super-120b-a12b:free` → `opencode-go/deepseek-v4-flash` | medium | read, bash, edit, write, grep, find, ls |
+| `worker` | `zai-coding-cn/glm-5.1` → `nvidia/mistralai/mistral-small-4-119b-2603` → `openrouter/nvidia/nemotron-3-super-120b-a12b:free` → `opencode-go/deepseek-v4-flash` | medium | **inherits all parent tools** |
+| `general-purpose` | `zai-coding-cn/glm-5.1` → `nvidia/mistralai/mistral-small-4-119b-2603` → `openrouter/nvidia/nemotron-3-super-120b-a12b:free` → `opencode-go/deepseek-v4-flash` | medium | **inherits all parent tools** |
 | `planner` | `zai-coding-cn/glm-5.2` → `openrouter/nvidia/nemotron-3-ultra-550b-a55b:free` → `opencode-go/deepseek-v4-pro` | high | read, grep, find, ls |
 | `reviewer` | `zai-coding-cn/glm-5.2` → `openrouter/nvidia/nemotron-3-ultra-550b-a55b:free` → `opencode-go/deepseek-v4-pro` | high | read, grep, find, ls |
 
 Each role uses the first authenticated preference available through Pi's model registry, then falls back to the authenticated parent model. Chains are **free-first** to conserve the metered opencode-go budget: **zai-coding-cn** (free GLM, primary) → free **nvidia** NIM and **openrouter** `:free` models → **opencode-go** (paid DeepSeek, last resort — one per role: `deepseek-v4-flash` for fast/strong-coding, `deepseek-v4-pro` for deep reasoning). opencode-go's GLM models cost ~$1.40/$4.40 per M versus zai-coding-cn's free GLM, so GLM stays on zai-coding-cn. Fallback models were live-verified on 2026-07-24; `nvidia/moonshotai/kimi-k2.6` and `nvidia/z-ai/glm-5.2` return 404/timeout on the user's account and were removed — non-rate-limit failures kill the subagent instead of advancing the chain. User/project agent files remain stronger overrides and may set legacy `model`, ordered `models`, and `thinking`.
 
+**Tool inheritance.** Agents without an explicit `tools:` line (worker, general-purpose) inherit every tool the parent session has — including extension tools like `web_search`, `serena_*`, `munin_*`, `obsidian`, and `notebooklm`. Agents with an explicit `tools:` list (scout, tester, planner, reviewer) are restricted to those tools and, when the list contains only built-ins, run in a lean loader with no extension overhead. To force an agent lean even while inheriting, set `tools: read, bash, edit, write, grep, find, ls`. The `subagent` tool itself is always denied to children (no recursive delegation).
+
 ## Agent files
 
 Create `~/.pi/agent/agents/*.md` or `.pi/agents/*.md`:
@@ -45,7 +47,7 @@ Agent definitions are cached with file-signature invalidation; `/subagent reload
 
 ## Context and limits
 
-Children use in-memory SDK sessions with no extensions, skills, prompt templates, or automatic `AGENTS.md` loading. The optional `instructions` argument passes a bounded 16 KB task/repository contract. Only Pi built-in tools are available; Serena, FFF, web, and Munin are not available in lean children.
+Children use in-memory SDK sessions. Agents that inherit parent tools load the parent's extensions (web, Serena, Munin, …) into the child; agents restricted to built-in tools run in a lean loader with no extensions, skills, prompt templates, or automatic `AGENTS.md` loading. The optional `instructions` argument passes a bounded 16 KB task/repository contract.
 
 Threads are session-memory only and are cleared when Pi replaces or reloads the session. Timeout and parent cancellation propagate to child sessions. Subagents cannot recursively invoke `subagent`.
 
@@ -82,6 +84,25 @@ Child agent tools are validated against a fixed allowlist:
 
 Unknown or misspelled tool names produce clear diagnostics. Duplicate tool names are deduplicated.
 
+### Git worktree isolation (`sandbox: worktree`)
+
+Set `sandbox: worktree` in an agent's frontmatter to run it in an isolated git
+worktree (`.pi-worktrees/<id>` under the repo root) instead of the parent's
+working tree. This is the safe way to run **parallel implementation** agents:
+two `worker` agents editing the same files can no longer clobber each other —
+each writes into its own checkout.
+
+- All file mutations land in the worktree; the main checkout stays untouched.
+- On completion, a unified diff of the child's changes is returned in the
+  result and shown in the thread viewer as a `🌿 worktree` badge.
+- **Merging is explicit**: the parent receives the diff and applies it via
+  `apply_patch` / cherry-pick / discard. Nothing is auto-merged.
+- The worktree is removed on completion (success, error, or abort).
+- Requires git; when the cwd is not a git repo, the agent falls back to
+  in-process execution with a warning (`ponytail`: isolation optimization,
+  not a hard requirement).
+
+
 ### Timeouts
 
 Every child execution receives a timeout:

package/agent-format.md

@@ -24,7 +24,7 @@ models:                   # Optional ordered fallbacks; comma form also accepted
   - provider/fast-model
   - provider/backup-model
 thinking: low             # Optional: off|minimal|low|medium|high|xhigh|max.
-sandbox: read-only        # Optional: read-only | workspace-write. Auto-derives tool restrictions.
+sandbox: read-only        # Optional: read-only | workspace-write | worktree. Auto-derives tool restrictions.
 color: cyan               # Optional: red|blue|green|yellow|purple|orange|pink|cyan.
 ---
 ```
@@ -33,6 +33,7 @@ color: cyan               # Optional: red|blue|green|yellow|purple|orange|pink|c
 
 - `read-only`: Restricts tools to `read`, `grep`, `find`, `ls`. Overrides any `tools` field.
 - `workspace-write` (default): Uses the agent's `tools` list or defaults to all tools.
+- `worktree`: Runs the agent in an isolated git worktree (`.pi-worktrees/<id>` under the repo root). All file mutations land in the worktree; the main checkout is untouched. On completion, a unified diff of the changes is returned in the result (visible in the thread viewer as a `🌿 worktree` badge) — the parent merges explicitly via `apply_patch`/cherry-pick; nothing is applied automatically. Falls back to in-process execution when the cwd is not a git repo (with a warning). Requires git.
 
 ### `color`
 

package/agents/general-purpose.md

@@ -1,7 +1,6 @@
 ---
 name: general-purpose
 description: General-purpose sub-agent for any delegated task. Use when no specialized agent fits. Good for complex research, multi-step operations, and code modifications.
-tools: read, bash, edit, write, grep, find, ls
 models:
   - zai-coding-cn/glm-5.1
   - nvidia/mistralai/mistral-small-4-119b-2603

package/extensions/agents.ts

@@ -22,7 +22,7 @@ export interface AgentConfig {
   model?: string;
   models?: string[];
   thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-  sandbox?: "read-only" | "workspace-write";
+  sandbox?: "read-only" | "workspace-write" | "worktree";
   color?: AgentColor;
   systemPrompt: string;
   source: "user" | "project" | "bundled";
@@ -203,7 +203,7 @@ function loadAgentsFromDir(
     }
 
     if (typeof frontmatter.sandbox === "string" && frontmatter.sandbox) {
-      const validSandboxes = ["read-only", "workspace-write"];
+      const validSandboxes = ["read-only", "workspace-write", "worktree"];
       if (!validSandboxes.includes(frontmatter.sandbox)) {
         diagnostics.push({
           filePath,
@@ -231,8 +231,8 @@ function loadAgentsFromDir(
       thinking: typeof frontmatter.thinking === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(frontmatter.thinking)
         ? frontmatter.thinking as AgentConfig["thinking"]
         : undefined,
-      sandbox: typeof frontmatter.sandbox === "string" && ["read-only", "workspace-write"].includes(frontmatter.sandbox)
-        ? frontmatter.sandbox as "read-only" | "workspace-write"
+      sandbox: typeof frontmatter.sandbox === "string" && ["read-only", "workspace-write", "worktree"].includes(frontmatter.sandbox)
+        ? frontmatter.sandbox as "read-only" | "workspace-write" | "worktree"
         : undefined,
       color: typeof frontmatter.color === "string" && VALID_COLORS.includes(frontmatter.color as any)
         ? frontmatter.color as AgentColor

package/extensions/index.ts

@@ -43,6 +43,7 @@ import {
   normalizeTimeout,
   resolveSafeCwd,
   validateAgentTools,
+  needsExtensions,
   truncateParallelOutput,
   validateExecutionRequest,
   READ_ONLY_TOOLS,
@@ -170,7 +171,9 @@ export default function (pi: ExtensionAPI) {
           : " (parent fallback)";
         const thinkingInfo = agent.thinking ? `, thinking: ${agent.thinking}` : "";
         const sandboxInfo = agent.sandbox ? `, sandbox: ${agent.sandbox}` : "";
-        return `- **${agent.name}**: ${agent.description}${modelInfo}${thinkingInfo}${sandboxInfo}`;
+        // ponytail: one-line inheritance hint; the model picks agents by description, this just sets expectations.
+        const toolsInfo = agent.tools ? `, tools: ${agent.tools.join(", ")}` : ", tools: inherits all parent tools";
+        return `- **${agent.name}**: ${agent.description}${modelInfo}${thinkingInfo}${sandboxInfo}${toolsInfo}`;
       })
       .join("\n");
     return {
@@ -179,6 +182,8 @@ export default function (pi: ExtensionAPI) {
         `\n\n## Available Subagents\n${catalog}\n\n` +
         "The subagent tool can delegate tasks to these specialized agents with isolated context. " +
         "Use for read-heavy exploration, parallel analysis, or work that would flood the main context.\n" +
+        "Agents marked `inherits all parent tools` can use web, Serena, Munin, and other extensions the main agent has; " +
+        "agents with an explicit tool list are leaner and restricted to those tools.\n" +
         "Prefer **scout** and **tester** for cheap routine work. " +
         "Prefer **worker** or **general-purpose** for normal coding. " +
         "Prefer **planner** and **reviewer** for consequential reasoning. " +
@@ -206,6 +211,7 @@ export default function (pi: ExtensionAPI) {
       timeout: request.timeout,
       instructions: request.instructions,
       signal: request.signal,
+      readOnly: request.readOnly,
       onMessage: (result) => threadStore.updateThread(thread.id, { result }),
       onProgress: (progress) => { threadStore.updateProgress(thread.id, progress); request.onProgress?.(progress); },
     }).then((result) => {
@@ -465,6 +471,12 @@ export default function (pi: ExtensionAPI) {
       const modelRuntime = (modelRegistry as any).runtime;
       const authStorage = (modelRegistry as any).authStorage;
 
+      // Parent session's registered tool names. Agents that omit `tools` inherit
+      // the full set (minus the denylist); agents with an explicit `tools` line
+      // are validated against built-ins ∪ this set.
+      const parentToolNames = pi.getAllTools().map((t) => t.name);
+      const projectTrusted = ctx.isProjectTrusted();
+
       // Helper: resolve a safe child working directory.
       function resolveChildCwd(childCwd: string | undefined): string {
         const safe = resolveSafeCwd({ workspaceRoot, childCwd, allowExternalCwd });
@@ -474,21 +486,22 @@ export default function (pi: ExtensionAPI) {
         return safe.path;
       }
 
-      // Helper: validate and normalise tools for an agent.
-      function resolveChildTools(agentTools: string[] | undefined, sandbox?: string, readOnly?: boolean): string[] {
-        const defaultTools = ["read", "bash", "edit", "write", "grep", "find", "ls"];
-        let rawTools = agentTools ?? defaultTools;
+      // Helper: validate and normalise tools for an agent. Returns the effective
+      // tool list and whether extensions must be loaded (any non-built-in tool).
+      function resolveChildTools(agentTools: string[] | undefined, sandbox?: string, readOnly?: boolean): { tools: string[]; loadExtensions: boolean } {
+        // Omitted tools => inherit all parent tools (Claude Code model).
+        let rawTools = agentTools ?? parentToolNames;
         // sandbox overrides tools: silently strip mutation tools, not an error
         if (sandbox === "read-only") {
           rawTools = rawTools.filter(t => READ_ONLY_TOOLS.includes(t));
           if (rawTools.length === 0) rawTools = [...READ_ONLY_TOOLS];
         }
         const effectiveReadOnly = readOnly || sandbox === "read-only";
-        const result = validateAgentTools({ tools: rawTools, readOnly: effectiveReadOnly });
+        const result = validateAgentTools({ tools: rawTools, readOnly: effectiveReadOnly, availableTools: parentToolNames });
         if (result.errors.length > 0) {
           throw new Error(`Tool validation errors: ${result.errors.join("; ")}`);
         }
-        return result.tools;
+        return { tools: result.tools, loadExtensions: needsExtensions(result.tools) };
       }
 
       // Helper: normalise timeout.
@@ -550,10 +563,13 @@ export default function (pi: ExtensionAPI) {
 
         // Security: validate tools, timeout, and cwd (wrapped in try/catch).
         let tools: string[];
+        let loadExtensions: boolean;
         let effectiveTimeoutMs: number | undefined;
         let safeCwd: string;
         try {
-          tools = resolveChildTools(agent.tools, agent.sandbox, isReadOnly);
+          const resolved = resolveChildTools(agent.tools, agent.sandbox, isReadOnly);
+          tools = resolved.tools;
+          loadExtensions = resolved.loadExtensions;
           effectiveTimeoutMs = resolveChildTimeout(timeoutMs, params.timeout);
           safeCwd = resolveChildCwd(cwd);
         } catch (err: unknown) {
@@ -631,6 +647,7 @@ export default function (pi: ExtensionAPI) {
 
             const result = await runSubAgent({
               cwd: safeCwd,
+              sandbox: agent.sandbox === "worktree" ? "worktree" : undefined,
               systemPrompt: params.instructions
               ? `${agent.systemPrompt}\n\n## Task Contract\n${params.instructions.slice(0, MAX_INSTRUCTIONS_LENGTH)}`
               : agent.systemPrompt,
@@ -646,6 +663,8 @@ export default function (pi: ExtensionAPI) {
               thinkingLevel: agent.thinking,
               onMessage: onProgress,
               onProgress: onActivity,
+              loadExtensions,
+              projectTrusted,
             });
 
             if (result.errorMessage && isRateLimitError(result.errorMessage)) {

package/extensions/render.ts

@@ -236,6 +236,15 @@ export function renderSingleResult(
       container.addChild(new Spacer(1));
       container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
     }
+    if (result.patch) {
+      container.addChild(new Spacer(1));
+      container.addChild(new Text(theme.fg("success", "🌿 worktree"), 0, 0));
+      const patchLines = result.patch.split("\n").length;
+      container.addChild(new Text(theme.fg("dim", `${patchLines} diff lines — merge explicitly via apply_patch/cherry-pick`), 0, 0));
+      if (result.patch !== "(no changes)") {
+        container.addChild(new Text(theme.fg("muted", result.patch.slice(0, 2000)), 0, 0));
+      }
+    }
     return container;
   }
 
@@ -258,6 +267,7 @@ export function renderSingleResult(
   }
   const usageStr = formatUsageStats(result.usage, result.model);
   if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
+  if (result.patch) text += `\n${theme.fg("success", "🌿 worktree")} (${result.patch.split("\n").length} diff lines)`;
   return new Text(text, 0, 0);
 }
 

package/extensions/runner.ts

@@ -16,9 +16,12 @@
 
 import type { Message, Model } from "@earendil-works/pi-ai";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import * as path from "node:path";
 import {
   createAgentSession,
   createExtensionRuntime,
+  DefaultResourceLoader,
+  getAgentDir,
   type ResourceLoader,
   SessionManager,
   SettingsManager,
@@ -46,6 +49,54 @@ export interface UsageStats {
 export const DEFAULT_INACTIVITY_TIMEOUT_MS = 3 * 60 * 1000;
 export const HARD_TIMEOUT_MS = 20 * 60 * 1000;
 
+// ---------------------------------------------------------------------------
+// Extension resource loader
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a FRESH lean DefaultResourceLoader for this child — no skills, prompt
+ * templates, context files (AGENTS.md), or themes. Extensions are loaded per
+ * child so their factories run against a runtime that THIS child's session will
+ * bind.
+ *
+ * Do NOT cache/share this loader. Extensions capture the ExtensionAPI (`pi`)
+ * at factory load time, and its actions delegate to the runtime passed to the
+ * factory (see createExtensionAPI: pi.getAllTools() → runtime.getAllTools()).
+ * If extensions were loaded once against a shared/cached runtime, that runtime
+ * is never the one any single child binds: a session binds the runtime its own
+ * getExtensions() returned (AgentSession constructor), while the factory-captured
+ * pi still points at the shared runtime. A child then hits the runtime's throwing
+ * "Extension runtime not initialized" stubs on the first provider request
+ * (pi-model-tools' before_provider_request calls pi.getAllTools()), or stale-ctx
+ * errors when the shared runtime is invalidated by the first child's dispose.
+ * A per-child loader keeps every captured `pi` pointing at a runtime this child
+ * both binds and owns.
+ *
+ * Project-extension trust is resolved from the parent (`projectTrusted`) so a
+ * child never prompts for trust (it has no UI). reload() per child re-reads
+ * extension files + re-runs factories; acceptable for short-lived children.
+ */
+async function getExtensionLoader(cwd: string, projectTrusted: boolean): Promise<ResourceLoader> {
+  const loader = new DefaultResourceLoader({
+    cwd,
+    agentDir: getAgentDir(),
+    noSkills: true,
+    noPromptTemplates: true,
+    noContextFiles: true,
+    noThemes: true,
+  });
+  await loader.reload({ resolveProjectTrust: async () => projectTrusted });
+  // Log (don't throw on) extension load errors — a misbehaving extension must
+  // not crash the child; the agent simply won't have that tool.
+  const loadErrors = loader.getExtensions().errors;
+  if (loadErrors.length > 0) {
+    process.stderr.write(
+      `[pi-subagent] extension load warnings in child loader: ${loadErrors.map((e) => `${e.path}: ${e.error}`).join("; ")}\n`,
+    );
+  }
+  return loader;
+}
+
 export interface SubAgentProgress {
   label: string;
   at: number;
@@ -65,6 +116,8 @@ export interface SubAgentResult {
   model?: string;
   stopReason?: string;
   errorMessage?: string;
+  /** Unified diff of changes made in an isolated worktree (sandbox: "worktree"). */
+  patch?: string;
   /** Canonical result status (added in 0.6.0). */
   status?: SubagentStatus;
 }
@@ -85,6 +138,8 @@ export async function runSubAgent(options: {
   task: string;
   tools: string[];
   model: Model<any>;
+  /** "worktree" runs the child in an isolated git worktree; the resulting diff is returned as result.patch. */
+  sandbox?: "worktree";
   /** Pi 0.80.10's canonical credential/model runtime. */
   modelRuntime?: unknown;
   /** Legacy Pi SDK session options retained for 0.80.6 tests and hosts. */
@@ -97,25 +152,42 @@ export async function runSubAgent(options: {
   onProgress?: (progress: SubAgentProgress) => void;
   timeoutMs?: number;
   hardTimeoutMs?: number;
+  /** Exec used for the git worktree lifecycle (add/remove/diff). Defaults to a child_process spawn when unset. */
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>;
+  /**
+   * When true, build a DefaultResourceLoader so the child inherits the parent's
+   * extensions (and thus extension tools: web, serena, munin, …). When false or
+   * unset, the lean empty-loader stub is used (no extensions).
+   */
+  loadExtensions?: boolean;
+  /**
+   * Whether the parent session trusts the project. Forwarded to the loader's
+   * resolveProjectTrust so children inherit the parent's trust decision and
+   * never prompt for project-extension trust (children have no UI). Defaults true.
+   */
+  projectTrusted?: boolean;
 }): Promise<SubAgentResult> {
   const {
     cwd, systemPrompt, task, tools, model, modelRuntime, authStorage, modelRegistry, signal,
     agentName = "subagent", thinkingLevel = "off", onMessage, onProgress,
     timeoutMs = DEFAULT_INACTIVITY_TIMEOUT_MS, hardTimeoutMs = HARD_TIMEOUT_MS,
+    loadExtensions = false, projectTrusted = true, sandbox, exec,
   } = options;
   const result: SubAgentResult = {
     agent: agentName, task, exitCode: 0, messages: [], stderr: "",
     usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
     model: `${model.provider}/${model.id}`, status: undefined,
   };
-  const resourceLoader: ResourceLoader = {
-    getExtensions: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
-    getSkills: () => ({ skills: [], diagnostics: [] }), getPrompts: () => ({ prompts: [], diagnostics: [] }),
-    getThemes: () => ({ themes: [], diagnostics: [] }), getAgentsFiles: () => ({ agentsFiles: [] }),
-    getSystemPrompt: () => systemPrompt, getSystemPromptSource: () => undefined,
-    getAppendSystemPrompt: () => [], getAppendSystemPromptSources: () => [],
-    extendResources: () => {}, reload: async () => {},
-  };
+  const resourceLoader: ResourceLoader = loadExtensions
+    ? await getExtensionLoader(cwd, projectTrusted)
+    : {
+        getExtensions: () => ({ extensions: [], errors: [], runtime: createExtensionRuntime() }),
+        getSkills: () => ({ skills: [], diagnostics: [] }), getPrompts: () => ({ prompts: [], diagnostics: [] }),
+        getThemes: () => ({ themes: [], diagnostics: [] }), getAgentsFiles: () => ({ agentsFiles: [] }),
+        getSystemPrompt: () => systemPrompt, getSystemPromptSource: () => undefined,
+        getAppendSystemPrompt: () => [], getAppendSystemPromptSources: () => [],
+        extendResources: () => {}, reload: async () => {},
+      };
   const settingsManager = SettingsManager.inMemory({ compaction: { enabled: false }, retry: { enabled: true, maxRetries: 1 } });
   const startedAt = Date.now();
   let inactivityDeadline = startedAt + timeoutMs;
@@ -145,12 +217,36 @@ export async function runSubAgent(options: {
       result.status = classifyStopReason(result.stopReason, !timedOut, timedOut);
       return result;
     }
-    const { session } = await createAgentSession({
-      cwd, model, thinkingLevel, resourceLoader, tools, sessionManager: SessionManager.inMemory(cwd), settingsManager,
-      ...(modelRuntime ? { modelRuntime } : {}),
-      // Pi 0.80.10 owns credentials in ModelRuntime; older SDKs still accept these.
-      ...(authStorage ? { authStorage, modelRegistry } : {}),
-    } as any);
+
+    // Isolated git worktree: the child edits a sibling checkout; the resulting
+    // diff is returned as result.patch and the worktree is removed on exit.
+    // ponytail: falls back to the in-process cwd when git is unavailable — the
+    // worktree is an isolation optimization, not a hard requirement.
+    let worktreeDir: string | undefined;
+    let childCwd = cwd;
+    if (sandbox === "worktree") {
+      const wt = await createWorktree(cwd, exec);
+      if (wt.ok) {
+        worktreeDir = wt.path;
+        childCwd = wt.path!;
+      } else if (wt.error) {
+        result.stderr = `Worktree unavailable (${wt.error}); running in workspace.`;
+      }
+    }
+
+    let session: Awaited<ReturnType<typeof createAgentSession>>["session"];
+    try {
+      const created = await createAgentSession({
+        cwd: childCwd, model, thinkingLevel, resourceLoader, tools, sessionManager: SessionManager.inMemory(childCwd), settingsManager,
+        ...(modelRuntime ? { modelRuntime } : {}),
+        // Pi 0.80.10 owns credentials in ModelRuntime; older SDKs still accept these.
+        ...(authStorage ? { authStorage, modelRegistry } : {}),
+      } as any);
+      session = created.session;
+    } catch (error) {
+      if (worktreeDir) await removeWorktree(cwd, worktreeDir, exec);
+      throw error;
+    }
     let unsubscribe: (() => void) | undefined;
     let removeAbort: (() => void) | undefined;
     try {
@@ -192,10 +288,17 @@ export async function runSubAgent(options: {
       else if (combinedSignal.aborted) { result.stopReason = "aborted"; result.errorMessage ||= "Sub-agent aborted"; }
       result.status = classifyStopReason(result.stopReason, result.stopReason === "aborted", result.stopReason === "timeout");
       result.exitCode = result.status === "success" || result.status === "partial" ? 0 : 1;
+      if (worktreeDir) {
+        // Capture the child's changes as a unified diff before tearing down.
+        const diff = await captureWorktreeDiff(cwd, worktreeDir, exec);
+        if (diff.ok) result.patch = diff.diff;
+        else if (diff.error) result.stderr = result.stderr ? `${result.stderr}; diff unavailable (${diff.error})` : `Diff unavailable (${diff.error})`;
+      }
       return result;
     } finally {
       unsubscribe?.(); removeAbort?.();
       try { session.dispose(); } catch { /* best effort */ }
+      if (worktreeDir) await removeWorktree(cwd, worktreeDir, exec);
     }
   } catch (error) {
     result.exitCode = 1;
@@ -212,6 +315,88 @@ export async function runSubAgent(options: {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** Minimal exec fallback (child_process spawn) used when no exec is injected. */
+async function defaultExec(
+  command: string,
+  args: string[],
+  options?: { cwd?: string; timeout?: number },
+): Promise<{ code: number; stdout: string; stderr: string }> {
+  const { spawn } = await import("node:child_process");
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd: options?.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    // Decode each chunk as a complete UTF-8 stream (Buffer.toString per chunk
+    // would corrupt multi-byte sequences straddling chunk boundaries).
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    let stdout = ""; let stderr = "";
+    const timer = options?.timeout ? setTimeout(() => child.kill("SIGKILL"), options.timeout) : undefined;
+    child.stdout.on("data", (d) => { stdout += d; });
+    child.stderr.on("data", (d) => { stderr += d; });
+    child.on("error", (err) => { if (timer) clearTimeout(timer); resolve({ code: 1, stdout, stderr: String(err.message ?? err) }); });
+    child.on("close", (code) => { if (timer) clearTimeout(timer); resolve({ code: code ?? 1, stdout, stderr }); });
+  });
+}
+
+async function runGit(
+  cwd: string,
+  args: string[],
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>,
+): Promise<{ ok: boolean; stdout: string; stderr: string }> {
+  const run = exec ?? defaultExec;
+  const res = await run("git", args, { cwd, timeout: 30_000 });
+  return { ok: res.code === 0, stdout: res.stdout, stderr: res.stderr };
+}
+
+/** Create a detached git worktree at .pi-worktrees/<rand> under the repo root. */
+export async function createWorktree(
+  cwd: string,
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>,
+): Promise<{ ok: boolean; path?: string; error?: string }> {
+  try {
+    const root = await runGit(cwd, ["rev-parse", "--show-toplevel"], exec);
+    if (!root.ok) return { ok: false, error: root.stderr.trim() || "not a git repo" };
+    const repoRoot = root.stdout.trim();
+    if (!repoRoot) return { ok: false, error: "empty git root" };
+    const id = `pi-subagent-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+    const wtPath = path.join(repoRoot, ".pi-worktrees", id);
+    const add = await runGit(repoRoot, ["worktree", "add", "--detach", wtPath, "HEAD"], exec);
+    if (!add.ok) return { ok: false, error: add.stderr.trim() || "git worktree add failed" };
+    return { ok: true, path: wtPath };
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/** Unified diff of ALL changes in the worktree vs HEAD (tracked edits, staged
+ *  changes, AND new untracked files). Stages first so untracked files are
+ *  captured — the worktree is removed right after, so mutating its index is
+ *  safe. A single `diff --cached HEAD` avoids duplicate hunks from combining
+ *  `diff HEAD` + `diff --cached`. */
+export async function captureWorktreeDiff(
+  repoRoot: string,
+  worktreeDir: string,
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>,
+): Promise<{ ok: boolean; diff?: string; error?: string }> {
+  const add = await runGit(worktreeDir, ["add", "-A"], exec);
+  if (!add.ok) return { ok: false, error: add.stderr.trim() || "git add -A failed" };
+  const diff = await runGit(worktreeDir, ["diff", "--cached", "HEAD"], exec);
+  if (!diff.ok) return { ok: false, error: diff.stderr.trim() || "git diff --cached HEAD failed" };
+  const text = diff.stdout.trim();
+  return { ok: true, diff: text || "(no changes)" };
+}
+
+/** Remove a worktree and its metadata, best-effort. */
+export async function removeWorktree(
+  repoRoot: string,
+  worktreeDir: string,
+  exec?: (command: string, args: string[], options?: { cwd?: string; timeout?: number }) => Promise<{ code: number; stdout: string; stderr: string }>,
+): Promise<void> {
+  try {
+    await runGit(repoRoot, ["worktree", "remove", "--force", worktreeDir], exec);
+  } catch { /* best effort */ }
+}
+
+
 export function getFinalOutput(messages: Message[]): string {
   for (let i = messages.length - 1; i >= 0; i--) {
     const msg = messages[i];

package/extensions/security.ts

@@ -12,8 +12,12 @@ import * as path from "node:path";
 // Constants
 // ---------------------------------------------------------------------------
 
-/** Tools that child agents may use. The subagent tool is never included. */
-export const ALLOWED_CHILD_TOOLS = [
+/**
+ * Pi's built-in tools. Agents whose effective tool set is a subset of these
+ * run in the cheap lean loader (no extensions loaded). Any other tool name
+ * (web_search, serena_*, munin_*, …) requires loading the parent's extensions.
+ */
+export const BUILTIN_TOOLS = [
   "read",
   "grep",
   "find",
@@ -23,6 +27,16 @@ export const ALLOWED_CHILD_TOOLS = [
   "write",
 ] as const;
 
+/** Backwards-compatible alias. */
+export const ALLOWED_CHILD_TOOLS = BUILTIN_TOOLS;
+
+/**
+ * Tools never available to child agents, regardless of inheritance.
+ * `subagent` is the only delegation primitive today; if another extension ever
+ * adds a delegation/spawn tool, it must be added here too (recursion guard).
+ */
+export const DENIED_CHILD_TOOLS = new Set(["subagent"]);
+
 export const READ_ONLY_TOOLS: readonly string[] = ["read", "grep", "find", "ls"];
 export const MUTATION_TOOLS: readonly string[] = ["edit", "write"];
 export const EXECUTION_TOOLS: readonly string[] = ["bash"];
@@ -208,6 +222,14 @@ export interface ValidateToolsOptions {
   tools: string[];
   /** When true, only read-only tools are permitted. Mutation/execution tools are rejected. */
   readOnly?: boolean;
+  /**
+   * Parent session's registered tool names. When provided, a tool is accepted if
+   * it is a built-in OR in this set (and not in DENIED_CHILD_TOOLS) — this is
+   * how children inherit extension tools (web, serena, munin, …). When omitted,
+   * only BUILTIN_TOOLS are accepted (lean/legacy mode).
+   * Callers must pass a stable snapshot and not mutate it afterwards.
+   */
+  availableTools?: readonly string[];
 }
 
 export interface ValidateToolsResult {
@@ -224,8 +246,20 @@ export interface ValidateToolsResult {
  * Deduplicates tool names.
  * When `readOnly` is true, only READ_ONLY_TOOLS are permitted.
  */
+/**
+ * Whether a tool set contains any extension tool (non-built-in). When true the
+ * runner loads the parent's extensions into the child; when false it uses the
+ * lean empty-loader stub, saving system-prompt tokens. Recon agents with an
+ * explicit built-in-only `tools` line stay cheap automatically.
+ */
+export function needsExtensions(tools: readonly string[]): boolean {
+  const builtins = new Set<string>(BUILTIN_TOOLS);
+  return tools.some((t) => !builtins.has(t));
+}
+
 export function validateAgentTools(options: ValidateToolsOptions): ValidateToolsResult {
-  const { readOnly = false } = options;
+  const { readOnly = false, availableTools } = options;
+  const extensionTools = availableTools ? new Set(availableTools) : undefined;
   const seen = new Set<string>();
   const tools: string[] = [];
   const errors: string[] = [];
@@ -234,16 +268,23 @@ export function validateAgentTools(options: ValidateToolsOptions): ValidateTools
     const tool = raw.trim();
     if (!tool) continue;
 
-    // Reject subagent regardless of casing (Pi tool names are case-sensitive
-    // but "subagent" should never pass through).
-    if (tool.toLowerCase() === "subagent") {
-      errors.push(`Tool "subagent" is not allowed in child agents (recursive delegation is prevented).`);
+    // Silently strip denied tools (e.g. "subagent") regardless of casing. They
+    // are never available to children — whether explicitly listed in an agent's
+    // `tools:` line or inherited via parentToolNames. This matches Claude Code,
+    // which removes denied tools from subagents "even when listed in the tools
+    // field". No error: inheritance must not crash on a tool the child can't have.
+    if (DENIED_CHILD_TOOLS.has(tool.toLowerCase())) {
       continue;
     }
 
-    // Check against allowlist
-    if (!ALLOWED_CHILD_TOOLS.includes(tool as any)) {
-      errors.push(`Unknown tool "${tool}". Allowed tools: ${ALLOWED_CHILD_TOOLS.join(", ")}.`);
+    // Check against allowlist: built-ins, plus inherited extension tools when availableTools given.
+    const isBuiltin = BUILTIN_TOOLS.includes(tool as any);
+    const isExtension = extensionTools?.has(tool) ?? false;
+    if (!isBuiltin && !isExtension) {
+      const allowed = extensionTools
+        ? "parent tools"
+        : BUILTIN_TOOLS.join(", ");
+      errors.push(`Unknown tool "${tool}". Allowed tools: ${allowed}.`);
       continue;
     }
 

package/extensions/service.ts

@@ -5,6 +5,7 @@ import { resolveModel } from "./model.ts";
 import {
   isRateLimitError,
   validateAgentTools,
+  needsExtensions,
   normalizeTimeout,
   resolveSafeCwd,
   MAX_INSTRUCTIONS_LENGTH,
@@ -39,6 +40,8 @@ export async function runNamedAgent(options: {
   timeout?: number;
   instructions?: string;
   signal?: AbortSignal;
+  /** When true, only read-only tools are permitted regardless of agent.sandbox. */
+  readOnly?: boolean;
   onMessage?: (result: SubAgentResult) => void;
   onProgress?: (progress: SubAgentProgress) => void;
 }): Promise<SubAgentResult> {
@@ -52,17 +55,25 @@ export async function runNamedAgent(options: {
   // Security: validate and normalise timeout.
   const effectiveTimeoutMs = normalizeTimeout({ requested: options.timeout }).timeoutMs;
 
-  // Security: validate tools against allowlist.
-  let rawTools = options.agent.tools ?? ["read", "bash", "edit", "write", "grep", "find", "ls"];
+  // Parent tool names — agents without an explicit `tools` line inherit them.
+  const parentToolNames = (options.ctx as any).getAllTools?.()?.map((t: { name: string }) => t.name) as string[] | undefined;
+
+  // Security: validate tools against allowlist (built-ins ∪ inherited parent tools).
+  // readOnly from the caller (e.g. pi-review) is enforced even when agent.sandbox
+  // is unset — never trust a caller-supplied tool list without the read-only filter.
+  const effectiveReadOnly = options.readOnly === true || options.agent.sandbox === "read-only";
+  let rawTools = options.agent.tools ?? parentToolNames ?? ["read", "bash", "edit", "write", "grep", "find", "ls"];
   // Enforce read-only sandbox: strip mutating and execution tools
-  if (options.agent.sandbox === "read-only") {
+  if (effectiveReadOnly) {
     rawTools = rawTools.filter(t => READ_ONLY_TOOLS.includes(t));
     if (rawTools.length === 0) rawTools = [...READ_ONLY_TOOLS];
   }
-  const toolValidation = validateAgentTools({ tools: rawTools, readOnly: options.agent.sandbox === "read-only" });
+  const toolValidation = validateAgentTools({ tools: rawTools, readOnly: effectiveReadOnly, availableTools: parentToolNames });
   if (toolValidation.errors.length > 0) {
     throw new Error(`Tool validation errors for agent "${options.agent.name}": ${toolValidation.errors.join("; ")}`);
   }
+  const loadExtensions = needsExtensions(toolValidation.tools);
+  const projectTrusted = options.ctx.isProjectTrusted();
 
   // Security: validate cwd (service caller must provide valid cwd).
   // The service path uses the same policy as the tool path.
@@ -106,6 +117,7 @@ export async function runNamedAgent(options: {
 
     const result = await runSubAgent({
       cwd: safeCwd.path,
+      sandbox: options.agent.sandbox === "worktree" ? "worktree" : undefined,
       systemPrompt: contract ? `${options.agent.systemPrompt}\n\n## Task Contract\n${contract}` : options.agent.systemPrompt,
       task: options.task,
       tools: toolValidation.tools,
@@ -119,6 +131,8 @@ export async function runNamedAgent(options: {
       thinkingLevel: options.agent.thinking,
       onMessage: options.onMessage,
       onProgress: options.onProgress,
+      loadExtensions,
+      projectTrusted,
     });
 
     if (result.errorMessage && isRateLimitError(result.errorMessage)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-subagent",
-  "version": "0.12.4",
+  "version": "0.14.0",
   "description": "In-process subagents for Pi with isolated SDK sessions, parallel and chained delegation, and inspectable threads.",
   "type": "module",
   "license": "MIT",