@tintinweb/pi-subagents 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.3] - 2026-03-13
+
+### Added
+- **Persistent agent memory** — new `memory` frontmatter field with three scopes: `"user"` (global `~/.pi/`), `"project"` (per-project `.pi/`), `"local"` (gitignored `.pi/`). Agents with write/edit tools get full read-write memory; read-only agents get a read-only fallback that injects existing MEMORY.md content without granting write access or creating directories.
+- **Git worktree isolation** — new `isolation: "worktree"` frontmatter field and Agent tool parameter. Creates a temporary `git worktree` so agents work on an isolated copy of the repo. On completion, changes are auto-committed to a `pi-agent-<id>` branch; clean worktrees are removed. Includes crash recovery via `pruneWorktrees()`.
+- **Skill preloading** — `skills` frontmatter now accepts a comma-separated list of skill names (e.g. `skills: planning, review`). Reads from `.pi/skills/` (project) then `~/.pi/skills/` (global), tries `.md`/`.txt`/bare extensions. Content injected into the system prompt as `# Preloaded Skill: {name}`.
+- **Tool denylist** — new `disallowed_tools` frontmatter field (e.g. `disallowed_tools: bash, write`). Blocks specified tools even if `builtinToolNames` or extensions would provide them. Enforced for both extension-enabled and extension-disabled agents.
+- **Prompt extras system** — new `PromptExtras` interface in `prompts.ts`; `buildAgentPrompt()` accepts optional memory and skill blocks appended in both `replace` and `append` modes.
+- `getMemoryTools()`, `getReadOnlyMemoryTools()` in `agent-types.ts`.
+- `buildMemoryBlock()`, `buildReadOnlyMemoryBlock()`, `isSymlink()`, `safeReadFile()` in `memory.ts`.
+- `preloadSkills()` in `skill-loader.ts`.
+- `createWorktree()`, `cleanupWorktree()`, `pruneWorktrees()` in `worktree.ts`.
+- `MemoryScope`, `IsolationMode` types; `memory`, `isolation`, `disallowedTools` fields on `AgentConfig`; `worktree`, `worktreeResult` fields on `AgentRecord`.
+- 177 total tests across 8 test files (41 new tests).
+
+### Fixed
+- **Read-only agents no longer escalated to read-write** — enabling `memory` on a read-only agent (e.g. Explore) previously auto-added `write`/`edit` tools. Now the runner detects write capability and branches: read-write agents get full memory tools, read-only agents get read-only memory prompt with only the `read` tool added.
+- **Denylist-aware memory detection** — write capability check now accounts for `disallowedTools`. An agent with `tools: write` + `disallowed_tools: write` correctly gets read-only memory instead of broken read-write instructions.
+- **Worktree requires commits** — repos with no commits (empty HEAD) are now rejected early with a warning instead of failing silently at `git worktree add`.
+- **Worktree failure warning** — when worktree creation fails, a warning is prepended to the agent's prompt instead of silently falling through to the main cwd.
+- **No force-branch overwrite** — worktree cleanup appends a timestamp suffix on branch name conflict instead of using `git branch -f`.
+
+### Security
+- **Whitelist name validation** — agent/skill names must match `^[a-zA-Z0-9][a-zA-Z0-9._-]*$`, max 128 chars. Rejects path traversal, leading dots, spaces, and special characters.
+- **Symlink protection** — `safeReadFile()` and `isSymlink()` reject symlinks in memory directories, MEMORY.md files, and skill files, preventing arbitrary file reads.
+- **Symlink-safe directory creation** — `ensureMemoryDir()` throws on symlinked directories.
+
+### Changed
+- `agent-runner.ts`: tool/extension/skill resolution moved before memory detection; `ctx.cwd` → `effectiveCwd` throughout.
+- `custom-agents.ts`: extracted `parseCsvField()` helper; added `csvListOptional()` and `parseMemory()`.
+- `skill-loader.ts`: uses `safeReadFile()` from `memory.ts` instead of raw `readFileSync`.
+- Agent tool schema updated with `isolation` parameter and help text for `memory`, `isolation`, `disallowed_tools`, and skill list.
+
+## [0.4.2] - 2026-03-12
+
+### Added
+- **Event bus** — agent lifecycle events emitted via `pi.events.emit()`, enabling other extensions to react to sub-agent activity:
+  - `subagents:created` — background agent registered (includes `id`, `type`, `description`, `isBackground`)
+  - `subagents:started` — agent transitions to running (includes queued→running)
+  - `subagents:completed` — agent finished successfully (includes `durationMs`, `tokens`, `toolUses`, `result`)
+  - `subagents:failed` — agent errored, stopped, or aborted (same payload as completed)
+  - `subagents:steered` — steering message sent to a running agent
+- `OnAgentStart` callback and `onStart` constructor parameter on `AgentManager`.
+- **Cross-package manager** now also exposes `spawn()` and `getRecord()` via the `Symbol.for("pi-subagents:manager")` global.
+
 ## [0.4.1] - 2026-03-11
 
 ### Fixed
@@ -197,6 +242,8 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.4.3]: https://github.com/tintinweb/pi-subagents/compare/v0.4.2...v0.4.3
+[0.4.2]: https://github.com/tintinweb/pi-subagents/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/tintinweb/pi-subagents/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/tintinweb/pi-subagents/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/tintinweb/pi-subagents/compare/v0.3.0...v0.3.1

package/README.md

@@ -23,6 +23,11 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Case-insensitive agent types** — `"explore"`, `"Explore"`, `"EXPLORE"` all work. Unknown types fall back to general-purpose with a note
 - **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs, with automatic filtering to only available/configured models
 - **Context inheritance** — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
+- **Persistent agent memory** — three scopes (project, local, user) with automatic read-only fallback for agents without write tools
+- **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
+- **Skill preloading** — inject named skill files from `.pi/skills/` into agent system prompts
+- **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
+- **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
 
 ## Install
 
@@ -138,13 +143,17 @@ All fields are optional — sensible defaults for everything.
 | `display_name` | — | Display name for UI (e.g. widget, agent list) |
 | `tools` | all 7 | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` for no tools |
 | `extensions` | `true` | Inherit MCP/extension tools. `false` to disable |
-| `skills` | `true` | Inherit skills from parent |
+| `skills` | `true` | Inherit skills from parent. Can be a comma-separated list of skill names to preload from `.pi/skills/` |
+| `memory` | — | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents |
+| `disallowed_tools` | — | Comma-separated tools to deny even if extensions provide them |
+| `isolation` | — | Set to `worktree` to run in an isolated git worktree |
 | `model` | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`) |
 | `thinking` | inherit | off, minimal, low, medium, high, xhigh |
 | `max_turns` | 50 | Max agentic turns before graceful shutdown |
 | `prompt_mode` | `replace` | `replace`: body is the full system prompt. `append`: body appended to parent's prompt (agent acts as a "parent twin" with optional extra instructions) |
 | `inherit_context` | `false` | Fork parent conversation into agent |
 | `run_in_background` | `false` | Run in background by default |
+| `isolation` | — | `worktree`: run in a temporary git worktree for full repo isolation |
 | `isolated` | `false` | No extension/MCP tools, only built-in |
 | `enabled` | `true` | Set to `false` to disable an agent (useful for hiding a default agent per-project) |
 
@@ -167,6 +176,7 @@ Launch a sub-agent.
 | `run_in_background` | boolean | no | Run without blocking |
 | `resume` | string | no | Agent ID to resume a previous session |
 | `isolated` | boolean | no | No extension/MCP tools |
+| `isolation` | `"worktree"` | no | Run in an isolated git worktree |
 | `inherit_context` | boolean | no | Fork parent conversation into agent |
 | `join_mode` | `"async"` \| `"group"` | no | Override join strategy for background completion notifications (default: smart) |
 
@@ -251,6 +261,77 @@ When background agents complete, they notify the main agent. The **join mode** c
 - Per-call: `Agent({ ..., join_mode: "async" })` overrides for that agent
 - Global default: `/agents` → Settings → Join mode
 
+## Events
+
+Agent lifecycle events are emitted via `pi.events.emit()` so other extensions can react:
+
+| Event | When | Key fields |
+|-------|------|------------|
+| `subagents:created` | Background agent registered | `id`, `type`, `description`, `isBackground` |
+| `subagents:started` | Agent transitions to running (including queued→running) | `id`, `type`, `description` |
+| `subagents:completed` | Agent finished successfully | `id`, `type`, `durationMs`, `tokens`, `toolUses`, `result` |
+| `subagents:failed` | Agent errored, stopped, or aborted | same as completed + `error`, `status` |
+| `subagents:steered` | Steering message sent | `id`, `message` |
+
+## Persistent Agent Memory
+
+Agents can have persistent memory across sessions. Set `memory` in frontmatter to enable:
+
+```yaml
+---
+memory: project   # project | local | user
+---
+```
+
+| Scope | Location | Use case |
+|-------|----------|----------|
+| `project` | `.pi/agent-memory/<name>/` | Shared across the team (committed) |
+| `local` | `.pi/agent-memory-local/<name>/` | Machine-specific (gitignored) |
+| `user` | `~/.pi/agent-memory/<name>/` | Global personal memory |
+
+Memory uses a `MEMORY.md` index file and individual memory files with frontmatter. Agents with write tools get full read-write access. **Read-only agents** (no `write`/`edit` tools) automatically get read-only memory — they can consume memories written by other agents but cannot modify them. This prevents unintended tool escalation.
+
+The `disallowed_tools` field is respected when determining write capability — an agent with `tools: write` + `disallowed_tools: write` correctly gets read-only memory.
+
+## Worktree Isolation
+
+Set `isolation: worktree` to run an agent in a temporary git worktree:
+
+```
+Agent({ subagent_type: "refactor", prompt: "...", isolation: "worktree" })
+```
+
+The agent gets a full, isolated copy of the repository. On completion:
+- **No changes:** worktree is cleaned up automatically
+- **Changes made:** changes are committed to a new branch (`pi-agent-<id>`) and returned in the result
+
+If the worktree cannot be created (not a git repo, no commits), the agent falls back to the main working directory with a warning.
+
+## Skill Preloading
+
+Skills can be preloaded as named files from `.pi/skills/` or `~/.pi/skills/`:
+
+```yaml
+---
+skills: api-conventions, error-handling
+---
+```
+
+Skill files (`.md`, `.txt`, or extensionless) are read and injected into the agent's system prompt. Project-level skills take priority over global ones. Symlinked skill files are rejected for security.
+
+## Tool Denylist
+
+Block specific tools from an agent even if extensions provide them:
+
+```yaml
+---
+tools: read, bash, grep, write
+disallowed_tools: write, edit
+---
+```
+
+This is useful for creating agents that inherit extension tools but should not have write access.
+
 ## Architecture
 
 ```
@@ -263,6 +344,9 @@ src/
   agent-manager.ts    # Agent lifecycle, concurrency queue, completion notifications
   group-join.ts       # Group join manager: batched completion notifications with timeout
   custom-agents.ts    # Load user-defined agents from .pi/agents/*.md
+  memory.ts           # Persistent agent memory (resolve, read, build prompt blocks)
+  skill-loader.ts     # Preload skill files from .pi/skills/
+  worktree.ts         # Git worktree isolation (create, cleanup, prune)
   prompts.ts          # Config-driven system prompt builder
   context.ts          # Parent conversation context for inherit_context
   env.ts              # Environment detection (git, platform)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",

package/src/agent-manager.ts

@@ -11,9 +11,11 @@ import type { ExtensionContext, ExtensionAPI } from "@mariozechner/pi-coding-age
 import type { Model } from "@mariozechner/pi-ai";
 import type { AgentSession } from "@mariozechner/pi-coding-agent";
 import { runAgent, resumeAgent, type ToolActivity } from "./agent-runner.js";
-import type { SubagentType, AgentRecord, ThinkingLevel } from "./types.js";
+import type { SubagentType, AgentRecord, ThinkingLevel, IsolationMode } from "./types.js";
+import { createWorktree, cleanupWorktree, pruneWorktrees, type WorktreeInfo } from "./worktree.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
+export type OnAgentStart = (record: AgentRecord) => void;
 
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
@@ -34,6 +36,8 @@ interface SpawnOptions {
   inheritContext?: boolean;
   thinkingLevel?: ThinkingLevel;
   isBackground?: boolean;
+  /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
+  isolation?: IsolationMode;
   /** Called on tool start/end with activity info (for streaming progress to UI). */
   onToolActivity?: (activity: ToolActivity) => void;
   /** Called on streaming text deltas from the assistant response. */
@@ -46,6 +50,7 @@ export class AgentManager {
   private agents = new Map<string, AgentRecord>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private onComplete?: OnAgentComplete;
+  private onStart?: OnAgentStart;
   private maxConcurrent: number;
 
   /** Queue of background agents waiting to start. */
@@ -53,8 +58,9 @@ export class AgentManager {
   /** Number of currently running background agents. */
   private runningBackground = 0;
 
-  constructor(onComplete?: OnAgentComplete, maxConcurrent = DEFAULT_MAX_CONCURRENT) {
+  constructor(onComplete?: OnAgentComplete, maxConcurrent = DEFAULT_MAX_CONCURRENT, onStart?: OnAgentStart) {
     this.onComplete = onComplete;
+    this.onStart = onStart;
     this.maxConcurrent = maxConcurrent;
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
@@ -112,14 +118,32 @@ export class AgentManager {
     record.status = "running";
     record.startedAt = Date.now();
     if (options.isBackground) this.runningBackground++;
+    this.onStart?.(record);
+
+    // Worktree isolation: create a temporary git worktree if requested
+    let worktreeCwd: string | undefined;
+    let worktreeWarning = "";
+    if (options.isolation === "worktree") {
+      const wt = createWorktree(ctx.cwd, id);
+      if (wt) {
+        record.worktree = wt;
+        worktreeCwd = wt.path;
+      } else {
+        worktreeWarning = "\n\n[WARNING: Worktree isolation was requested but failed (not a git repo, or no commits yet). Running in the main working directory instead.]";
+      }
+    }
+
+    // Prepend worktree warning to prompt if isolation failed
+    const effectivePrompt = worktreeWarning ? worktreeWarning + "\n\n" + prompt : prompt;
 
-    const promise = runAgent(ctx, type, prompt, {
+    const promise = runAgent(ctx, type, effectivePrompt, {
       pi,
       model: options.model,
       maxTurns: options.maxTurns,
       isolated: options.isolated,
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
+      cwd: worktreeCwd,
       signal: record.abortController!.signal,
       onToolActivity: (activity) => {
         if (activity.type === "end") record.toolUses++;
@@ -139,6 +163,17 @@ export class AgentManager {
         record.result = responseText;
         record.session = session;
         record.completedAt ??= Date.now();
+
+        // Clean up worktree if used
+        if (record.worktree) {
+          const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+          record.worktreeResult = wtResult;
+          if (wtResult.hasChanges && wtResult.branch) {
+            record.result = (record.result ?? "") +
+              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+          }
+        }
+
         if (options.isBackground) {
           this.runningBackground--;
           this.onComplete?.(record);
@@ -153,6 +188,15 @@ export class AgentManager {
         }
         record.error = err instanceof Error ? err.message : String(err);
         record.completedAt ??= Date.now();
+
+        // Best-effort worktree cleanup on error
+        if (record.worktree) {
+          try {
+            const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+            record.worktreeResult = wtResult;
+          } catch { /* ignore cleanup errors */ }
+        }
+
         if (options.isBackground) {
           this.runningBackground--;
           this.onComplete?.(record);
@@ -301,5 +345,7 @@ export class AgentManager {
       record.session?.dispose();
     }
     this.agents.clear();
+    // Prune any orphaned git worktrees (crash recovery)
+    try { pruneWorktrees(process.cwd()); } catch { /* ignore */ }
   }
 }

package/src/agent-runner.ts

@@ -13,10 +13,12 @@ import {
 } from "@mariozechner/pi-coding-agent";
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { Model } from "@mariozechner/pi-ai";
-import { getToolsForType, getConfig, getAgentConfig } from "./agent-types.js";
-import { buildAgentPrompt } from "./prompts.js";
+import { getToolsForType, getConfig, getAgentConfig, getMemoryTools, getReadOnlyMemoryTools } from "./agent-types.js";
+import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { buildParentContext, extractText } from "./context.js";
 import { detectEnv } from "./env.js";
+import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
+import { preloadSkills } from "./skill-loader.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
@@ -84,6 +86,8 @@ export interface RunOptions {
   isolated?: boolean;
   inheritContext?: boolean;
   thinkingLevel?: ThinkingLevel;
+  /** Override working directory (e.g. for worktree isolation). */
+  cwd?: string;
   /** Called on tool start/end with activity info. */
   onToolActivity?: (activity: ToolActivity) => void;
   /** Called on streaming text deltas from the assistant response. */
@@ -136,15 +140,59 @@ export async function runAgent(
 ): Promise<RunResult> {
   const config = getConfig(type);
   const agentConfig = getAgentConfig(type);
-  const env = await detectEnv(options.pi, ctx.cwd);
+
+  // Resolve working directory: worktree override > parent cwd
+  const effectiveCwd = options.cwd ?? ctx.cwd;
+
+  const env = await detectEnv(options.pi, effectiveCwd);
 
   // Get parent system prompt for append-mode agents
   const parentSystemPrompt = ctx.getSystemPrompt();
 
+  // Build prompt extras (memory, skill preloading)
+  const extras: PromptExtras = {};
+
+  // Resolve extensions/skills: isolated overrides to false
+  const extensions = options.isolated ? false : config.extensions;
+  const skills = options.isolated ? false : config.skills;
+
+  // Skill preloading: when skills is string[], preload their content into prompt
+  if (Array.isArray(skills)) {
+    const loaded = preloadSkills(skills, effectiveCwd);
+    if (loaded.length > 0) {
+      extras.skillBlocks = loaded;
+    }
+  }
+
+  let tools = getToolsForType(type, effectiveCwd);
+
+  // Persistent memory: detect write capability and branch accordingly.
+  // Account for disallowedTools — a tool in the base set but on the denylist is not truly available.
+  if (agentConfig?.memory) {
+    const existingNames = new Set(tools.map(t => t.name));
+    const denied = agentConfig.disallowedTools ? new Set(agentConfig.disallowedTools) : undefined;
+    const effectivelyHas = (name: string) => existingNames.has(name) && !denied?.has(name);
+    const hasWriteTools = effectivelyHas("write") || effectivelyHas("edit");
+
+    if (hasWriteTools) {
+      // Read-write memory: add any missing memory tools (read/write/edit)
+      const memTools = getMemoryTools(effectiveCwd, existingNames);
+      if (memTools.length > 0) tools = [...tools, ...memTools];
+      extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
+    } else {
+      // Read-only memory: only add read tool, use read-only prompt
+      if (!existingNames.has("read")) {
+        const readTools = getReadOnlyMemoryTools(effectiveCwd, existingNames);
+        if (readTools.length > 0) tools = [...tools, ...readTools];
+      }
+      extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
+    }
+  }
+
   // Build system prompt from agent config
   let systemPrompt: string;
   if (agentConfig) {
-    systemPrompt = buildAgentPrompt(agentConfig, ctx.cwd, env, parentSystemPrompt);
+    systemPrompt = buildAgentPrompt(agentConfig, effectiveCwd, env, parentSystemPrompt, extras);
   } else {
     // Unknown type fallback: general-purpose (defensive — unreachable in practice
     // since index.ts resolves unknown types to "general-purpose" before calling runAgent)
@@ -158,20 +206,18 @@ export async function runAgent(
       inheritContext: false,
       runInBackground: false,
       isolated: false,
-    }, ctx.cwd, env, parentSystemPrompt);
+    }, effectiveCwd, env, parentSystemPrompt, extras);
   }
 
-  const tools = getToolsForType(type, ctx.cwd);
-
-  // Resolve extensions/skills: isolated overrides to false
-  const extensions = options.isolated ? false : config.extensions;
-  const skills = options.isolated ? false : config.skills;
+  // When skills is string[], we've already preloaded them into the prompt.
+  // Still pass noSkills: true since we don't need the skill loader to load them again.
+  const noSkills = skills === false || Array.isArray(skills);
 
   // Load extensions/skills: true or string[] → load; false → don't
   const loader = new DefaultResourceLoader({
-    cwd: ctx.cwd,
+    cwd: effectiveCwd,
     noExtensions: extensions === false,
-    noSkills: skills === false,
+    noSkills,
     noPromptTemplates: true,
     noThemes: true,
     systemPromptOverride: () => systemPrompt,
@@ -187,8 +233,8 @@ export async function runAgent(
   const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
 
   const sessionOpts: Record<string, unknown> = {
-    cwd: ctx.cwd,
-    sessionManager: SessionManager.inMemory(ctx.cwd),
+    cwd: effectiveCwd,
+    sessionManager: SessionManager.inMemory(effectiveCwd),
     settingsManager: SettingsManager.create(),
     modelRegistry: ctx.modelRegistry,
     model,
@@ -202,12 +248,18 @@ export async function runAgent(
   // createAgentSession's type signature may not include thinkingLevel yet
   const { session } = await createAgentSession(sessionOpts as Parameters<typeof createAgentSession>[0]);
 
+  // Build disallowed tools set from agent config
+  const disallowedSet = agentConfig?.disallowedTools
+    ? new Set(agentConfig.disallowedTools)
+    : undefined;
+
   // Filter active tools: remove our own tools to prevent nesting,
-  // and apply extension allowlist if specified
+  // apply extension allowlist if specified, and apply disallowedTools denylist
   if (extensions !== false) {
     const builtinToolNames = new Set(tools.map(t => t.name));
     const activeTools = session.getActiveToolNames().filter((t) => {
       if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
+      if (disallowedSet?.has(t)) return false;
       if (builtinToolNames.has(t)) return true;
       if (Array.isArray(extensions)) {
         return extensions.some(ext => t.startsWith(ext) || t.includes(ext));
@@ -215,6 +267,10 @@ export async function runAgent(
       return true;
     });
     session.setActiveToolsByName(activeTools);
+  } else if (disallowedSet) {
+    // Even with extensions disabled, apply denylist to built-in tools
+    const activeTools = session.getActiveToolNames().filter(t => !disallowedSet.has(t));
+    session.setActiveToolsByName(activeTools);
   }
 
   options.onSessionCreated?.(session);

package/src/agent-types.ts

@@ -109,6 +109,32 @@ export function isValidType(type: string): boolean {
   return agents.get(key)?.enabled !== false;
 }
 
+/** Tool names required for memory management. */
+const MEMORY_TOOL_NAMES = ["read", "write", "edit"];
+
+/**
+ * Get the tools needed for memory management (read, write, edit).
+ * Only returns tools that are NOT already in the provided set.
+ */
+export function getMemoryTools(cwd: string, existingToolNames: Set<string>): AgentTool<any>[] {
+  return MEMORY_TOOL_NAMES
+    .filter(n => !existingToolNames.has(n) && n in TOOL_FACTORIES)
+    .map(n => TOOL_FACTORIES[n](cwd));
+}
+
+/** Tool names needed for read-only memory access. */
+const READONLY_MEMORY_TOOL_NAMES = ["read"];
+
+/**
+ * Get only the read tool for read-only memory access.
+ * Only returns tools that are NOT already in the provided set.
+ */
+export function getReadOnlyMemoryTools(cwd: string, existingToolNames: Set<string>): AgentTool<any>[] {
+  return READONLY_MEMORY_TOOL_NAMES
+    .filter(n => !existingToolNames.has(n) && n in TOOL_FACTORIES)
+    .map(n => TOOL_FACTORIES[n](cwd));
+}
+
 /** Get built-in tools for a type (case-insensitive). */
 export function getToolsForType(type: string, cwd: string): AgentTool<any>[] {
   const key = resolveKey(type);

package/src/custom-agents.ts

@@ -6,7 +6,7 @@ import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join, basename } from "node:path";
 import { homedir } from "node:os";
-import type { AgentConfig, ThinkingLevel } from "./types.js";
+import type { AgentConfig, ThinkingLevel, MemoryScope, IsolationMode } from "./types.js";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
 
 /**
@@ -56,6 +56,7 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       displayName: str(fm.display_name),
       description: str(fm.description) ?? name,
       builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
+      disallowedTools: csvListOptional(fm.disallowed_tools),
       extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
       skills: inheritField(fm.skills ?? fm.inherit_skills),
       model: str(fm.model),
@@ -66,6 +67,8 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       inheritContext: fm.inherit_context === true,
       runInBackground: fm.run_in_background === true,
       isolated: fm.isolated === true,
+      memory: parseMemory(fm.memory),
+      isolation: fm.isolation === "worktree" ? "worktree" : undefined,
       enabled: fm.enabled !== false,  // default true; explicitly false disables
       source,
     });
@@ -86,14 +89,40 @@ function positiveInt(val: unknown): number | undefined {
 }
 
 /**
- * Parse a comma-separated list field.
+ * Parse a raw CSV field value into items, or undefined if absent/empty/"none".
+ */
+function parseCsvField(val: unknown): string[] | undefined {
+  if (val === undefined || val === null) return undefined;
+  const s = String(val).trim();
+  if (!s || s === "none") return undefined;
+  const items = s.split(",").map(t => t.trim()).filter(Boolean);
+  return items.length > 0 ? items : undefined;
+}
+
+/**
+ * Parse a comma-separated list field with defaults.
  * omitted → defaults; "none"/empty → []; csv → listed items.
  */
 function csvList(val: unknown, defaults: string[]): string[] {
   if (val === undefined || val === null) return defaults;
-  const s = String(val).trim();
-  if (!s || s === "none") return [];
-  return s.split(",").map(t => t.trim()).filter(Boolean);
+  return parseCsvField(val) ?? [];
+}
+
+/**
+ * Parse an optional comma-separated list field.
+ * omitted → undefined; "none"/empty → undefined; csv → listed items.
+ */
+function csvListOptional(val: unknown): string[] | undefined {
+  return parseCsvField(val);
+}
+
+/**
+ * Parse a memory scope field.
+ * omitted → undefined; "user"/"project"/"local" → MemoryScope.
+ */
+function parseMemory(val: unknown): MemoryScope | undefined {
+  if (val === "user" || val === "project" || val === "local") return val;
+  return undefined;
 }
 
 /**

package/src/index.ts

@@ -204,8 +204,44 @@ export default function (pi: ExtensionAPI) {
     30_000,
   );
 
+  /** Helper: build event data for lifecycle events from an AgentRecord. */
+  function buildEventData(record: AgentRecord) {
+    const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
+    let tokens: { input: number; output: number; total: number } | undefined;
+    try {
+      if (record.session) {
+        const stats = record.session.getSessionStats();
+        tokens = {
+          input: stats.tokens?.input ?? 0,
+          output: stats.tokens?.output ?? 0,
+          total: stats.tokens?.total ?? 0,
+        };
+      }
+    } catch { /* session stats unavailable */ }
+    return {
+      id: record.id,
+      type: record.type,
+      description: record.description,
+      result: record.result,
+      error: record.error,
+      status: record.status,
+      toolUses: record.toolUses,
+      durationMs,
+      tokens,
+    };
+  }
+
   // Background completion: route through group join or send individual nudge
   const manager = new AgentManager((record) => {
+    // Emit lifecycle event based on terminal status
+    const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+    const eventData = buildEventData(record);
+    if (isError) {
+      pi.events.emit("subagents:failed", eventData);
+    } else {
+      pi.events.emit("subagents:completed", eventData);
+    }
+
     // Skip notification if result was already consumed via get_subagent_result
     if (record.resultConsumed) {
       agentActivity.delete(record.id);
@@ -228,6 +264,13 @@ export default function (pi: ExtensionAPI) {
     // 'held' → do nothing, group will fire later
     // 'delivered' → group callback already fired
     widget.update();
+  }, undefined, (record) => {
+    // Emit started event when agent transitions to running (including from queue)
+    pi.events.emit("subagents:started", {
+      id: record.id,
+      type: record.type,
+      description: record.description,
+    });
   });
 
   // Expose manager via Symbol.for() global registry for cross-package access.
@@ -236,6 +279,9 @@ export default function (pi: ExtensionAPI) {
   (globalThis as any)[MANAGER_KEY] = {
     waitForAll: () => manager.waitForAll(),
     hasRunning: () => manager.hasRunning(),
+    spawn: (piRef: any, ctx: any, type: string, prompt: string, options: any) =>
+      manager.spawn(piRef, ctx, type, prompt, options),
+    getRecord: (id: string) => manager.getRecord(id),
   };
 
   // Wait for all subagents on shutdown, then dispose the manager
@@ -362,6 +408,7 @@ Guidelines:
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
 - Use thinking to control extended thinking level.
 - Use inherit_context if the agent needs the parent conversation history.
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).
 - Use join_mode to control how background completion notifications are delivered. By default (smart), 2+ background agents spawned in the same turn are grouped into a single notification. Use "async" for individual notifications or "group" to force grouping.`,
     parameters: Type.Object({
       prompt: Type.String({
@@ -410,6 +457,11 @@ Guidelines:
           description: "If true, fork parent conversation into the agent. Default: false (fresh context).",
         }),
       ),
+      isolation: Type.Optional(
+        Type.Literal("worktree", {
+          description: 'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
+        }),
+      ),
       join_mode: Type.Optional(
         Type.Union([
           Type.Literal("async"),
@@ -544,6 +596,7 @@ Guidelines:
       const inheritContext = params.inherit_context ?? customConfig?.inheritContext ?? false;
       const runInBackground = params.run_in_background ?? customConfig?.runInBackground ?? false;
       const isolated = params.isolated ?? customConfig?.isolated ?? false;
+      const isolation = params.isolation ?? customConfig?.isolation;
 
       // Build display tags for non-default config
       const parentModelId = ctx.model?.id;
@@ -556,6 +609,7 @@ Guidelines:
       if (modeLabel) agentTags.push(modeLabel);
       if (thinking) agentTags.push(`thinking: ${thinking}`);
       if (isolated) agentTags.push("isolated");
+      if (isolation === "worktree") agentTags.push("worktree");
       // Shared base fields for all AgentDetails in this call
       const detailBase = {
         displayName,
@@ -596,6 +650,7 @@ Guidelines:
           inheritContext,
           thinkingLevel: thinking,
           isBackground: true,
+          isolation,
           ...bgCallbacks,
         });
 
@@ -618,6 +673,15 @@ Guidelines:
         agentActivity.set(id, bgState);
         widget.ensureTimer();
         widget.update();
+
+        // Emit created event
+        pi.events.emit("subagents:created", {
+          id,
+          type: subagentType,
+          description: params.description,
+          isBackground: true,
+        });
+
         const isQueued = record?.status === "queued";
         return textResult(
           `Agent ${isQueued ? "queued" : "started"} in background.\n` +
@@ -684,6 +748,7 @@ Guidelines:
         isolated,
         inheritContext,
         thinkingLevel: thinking,
+        isolation,
         ...fgCallbacks,
       });
 
@@ -817,6 +882,7 @@ Guidelines:
 
       try {
         await steerAgent(record.session, params.message);
+        pi.events.emit("subagents:steered", { id: record.id, message: params.message });
         return textResult(`Steering message sent to agent ${record.id}. The agent will process it after its current tool execution.`);
       } catch (err) {
         return textResult(`Failed to steer agent: ${err instanceof Error ? err.message : String(err)}`);
@@ -1092,9 +1158,12 @@ Guidelines:
     else if (Array.isArray(cfg.extensions)) fmFields.push(`extensions: ${cfg.extensions.join(", ")}`);
     if (cfg.skills === false) fmFields.push("skills: false");
     else if (Array.isArray(cfg.skills)) fmFields.push(`skills: ${cfg.skills.join(", ")}`);
+    if (cfg.disallowedTools?.length) fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`);
     if (cfg.inheritContext) fmFields.push("inherit_context: true");
     if (cfg.runInBackground) fmFields.push("run_in_background: true");
     if (cfg.isolated) fmFields.push("isolated: true");
+    if (cfg.memory) fmFields.push(`memory: ${cfg.memory}`);
+    if (cfg.isolation) fmFields.push(`isolation: ${cfg.isolation}`);
 
     const content = `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
 
@@ -1214,10 +1283,13 @@ thinking: <optional thinking level: off, minimal, low, medium, high, xhigh. Omit
 max_turns: <optional max agentic turns, default 50. Omit for default>
 prompt_mode: <"replace" (body IS the full system prompt) or "append" (body is appended to default prompt). Default: replace>
 extensions: <true (inherit all MCP/extension tools), false (none), or comma-separated names. Default: true>
-skills: <true (inherit all), false (none). Default: true>
+skills: <true (inherit all), false (none), or comma-separated skill names to preload into prompt. Default: true>
+disallowed_tools: <comma-separated tool names to block, even if otherwise available. Omit for none>
 inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
 run_in_background: <true to run in background by default. Default: false>
 isolated: <true for no extension/MCP tools, only built-in tools. Default: false>
+memory: <"user" (global), "project" (per-project), or "local" (gitignored per-project) for persistent memory. Omit for none>
+isolation: <"worktree" to run in isolated git worktree. Omit for normal>
 ---
 
 <system prompt body — instructions for the agent>

package/src/memory.ts

@@ -0,0 +1,165 @@
+/**
+ * memory.ts — Persistent agent memory: per-agent memory directories that persist across sessions.
+ *
+ * Memory scopes:
+ *   - "user"    → ~/.pi/agent-memory/{agent-name}/
+ *   - "project" → .pi/agent-memory/{agent-name}/
+ *   - "local"   → .pi/agent-memory-local/{agent-name}/
+ */
+
+import { existsSync, readFileSync, mkdirSync, lstatSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import type { MemoryScope } from "./types.js";
+
+/** Maximum lines to read from MEMORY.md */
+const MAX_MEMORY_LINES = 200;
+
+/**
+ * Returns true if a name contains characters not allowed in agent/skill names.
+ * Uses a whitelist: only alphanumeric, hyphens, underscores, and dots (no leading dot).
+ */
+export function isUnsafeName(name: string): boolean {
+  if (!name || name.length > 128) return true;
+  return !/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name);
+}
+
+/**
+ * Returns true if the given path is a symlink (defense against symlink attacks).
+ */
+export function isSymlink(filePath: string): boolean {
+  try {
+    return lstatSync(filePath).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Safely read a file, rejecting symlinks.
+ * Returns undefined if the file doesn't exist, is a symlink, or can't be read.
+ */
+export function safeReadFile(filePath: string): string | undefined {
+  if (!existsSync(filePath)) return undefined;
+  if (isSymlink(filePath)) return undefined;
+  try {
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the memory directory path for a given agent + scope + cwd.
+ * Throws if agentName contains path traversal characters.
+ */
+export function resolveMemoryDir(agentName: string, scope: MemoryScope, cwd: string): string {
+  if (isUnsafeName(agentName)) {
+    throw new Error(`Unsafe agent name for memory directory: "${agentName}"`);
+  }
+  switch (scope) {
+    case "user":
+      return join(homedir(), ".pi", "agent-memory", agentName);
+    case "project":
+      return join(cwd, ".pi", "agent-memory", agentName);
+    case "local":
+      return join(cwd, ".pi", "agent-memory-local", agentName);
+  }
+}
+
+/**
+ * Ensure the memory directory exists, creating it if needed.
+ * Refuses to create directories if any component in the path is a symlink
+ * to prevent symlink-based directory traversal attacks.
+ */
+export function ensureMemoryDir(memoryDir: string): void {
+  // If the directory already exists, verify it's not a symlink
+  if (existsSync(memoryDir)) {
+    if (isSymlink(memoryDir)) {
+      throw new Error(`Refusing to use symlinked memory directory: ${memoryDir}`);
+    }
+    return;
+  }
+  mkdirSync(memoryDir, { recursive: true });
+}
+
+/**
+ * Read the first N lines of MEMORY.md from the memory directory, if it exists.
+ * Returns undefined if no MEMORY.md exists or if the path is a symlink.
+ */
+export function readMemoryIndex(memoryDir: string): string | undefined {
+  // Reject symlinked memory directories
+  if (isSymlink(memoryDir)) return undefined;
+
+  const memoryFile = join(memoryDir, "MEMORY.md");
+  const content = safeReadFile(memoryFile);
+  if (content === undefined) return undefined;
+
+  const lines = content.split("\n");
+  if (lines.length > MAX_MEMORY_LINES) {
+    return lines.slice(0, MAX_MEMORY_LINES).join("\n") + "\n... (truncated at 200 lines)";
+  }
+  return content;
+}
+
+/**
+ * Build the memory block to inject into the agent's system prompt.
+ * Also ensures the memory directory exists (creates it if needed).
+ */
+export function buildMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string {
+  const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+  // Create the memory directory so the agent can immediately write to it
+  ensureMemoryDir(memoryDir);
+
+  const existingMemory = readMemoryIndex(memoryDir);
+
+  const header = `# Agent Memory
+
+You have a persistent memory directory at: ${memoryDir}/
+Memory scope: ${scope}
+
+This memory persists across sessions. Use it to build up knowledge over time.`;
+
+  const memoryContent = existingMemory
+    ? `\n\n## Current MEMORY.md\n${existingMemory}`
+    : `\n\nNo MEMORY.md exists yet. Create one at ${join(memoryDir, "MEMORY.md")} to start building persistent memory.`;
+
+  const instructions = `
+
+## Memory Instructions
+- MEMORY.md is an index file — keep it concise (under 200 lines). Lines after 200 are truncated.
+- Store detailed memories in separate files within ${memoryDir}/ and link to them from MEMORY.md.
+- Each memory file should use this frontmatter format:
+  \`\`\`markdown
+  ---
+  name: <memory name>
+  description: <one-line description>
+  type: <user|feedback|project|reference>
+  ---
+  <memory content>
+  \`\`\`
+- Update or remove memories that become outdated. Check for existing memories before creating duplicates.
+- You have Read, Write, and Edit tools available for managing memory files.`;
+
+  return header + memoryContent + instructions;
+}
+
+/**
+ * Build a read-only memory block for agents that lack write/edit tools.
+ * Does NOT create the memory directory — agents can only consume existing memory.
+ */
+export function buildReadOnlyMemoryBlock(agentName: string, scope: MemoryScope, cwd: string): string {
+  const memoryDir = resolveMemoryDir(agentName, scope, cwd);
+  const existingMemory = readMemoryIndex(memoryDir);
+
+  const header = `# Agent Memory (read-only)
+
+Memory scope: ${scope}
+You have read-only access to memory. You can reference existing memories but cannot create or modify them.`;
+
+  const memoryContent = existingMemory
+    ? `\n\n## Current MEMORY.md\n${existingMemory}`
+    : `\n\nNo memory is available yet. Other agents or sessions with write access can create memories for you to consume.`;
+
+  return header + memoryContent;
+}

package/src/prompts.ts

@@ -4,6 +4,14 @@
 
 import type { AgentConfig, EnvInfo } from "./types.js";
 
+/** Extra sections to inject into the system prompt (memory, skills, etc.). */
+export interface PromptExtras {
+  /** Persistent memory content to inject (first 200 lines of MEMORY.md + instructions). */
+  memoryBlock?: string;
+  /** Preloaded skill contents to inject. */
+  skillBlocks?: { name: string; content: string }[];
+}
+
 /**
  * Build the system prompt for an agent from its config.
  *
@@ -12,18 +20,32 @@ import type { AgentConfig, EnvInfo } from "./types.js";
  * - "append" with empty systemPrompt: pure parent clone
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
 export function buildAgentPrompt(
   config: AgentConfig,
   cwd: string,
   env: EnvInfo,
   parentSystemPrompt?: string,
+  extras?: PromptExtras,
 ): string {
   const envBlock = `# Environment
 Working directory: ${cwd}
 ${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
 Platform: ${env.platform}`;
 
+  // Build optional extras suffix
+  const extraSections: string[] = [];
+  if (extras?.memoryBlock) {
+    extraSections.push(extras.memoryBlock);
+  }
+  if (extras?.skillBlocks?.length) {
+    for (const skill of extras.skillBlocks) {
+      extraSections.push(`\n# Preloaded Skill: ${skill.name}\n${skill.content}`);
+    }
+  }
+  const extrasSuffix = extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : "";
+
   if (config.promptMode === "append") {
     const identity = parentSystemPrompt || genericBase;
 
@@ -44,7 +66,7 @@ You are operating as a sub-agent invoked to handle a specific task.
       ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
       : "";
 
-    return envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection;
+    return envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
   }
 
   // "replace" mode — env header + the config's full system prompt
@@ -53,7 +75,7 @@ You have been invoked to handle a specific task autonomously.
 
 ${envBlock}`;
 
-  return replaceHeader + "\n\n" + config.systemPrompt;
+  return replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
 }
 
 /** Fallback base prompt when parent system prompt is unavailable in append mode. */

package/src/skill-loader.ts

@@ -0,0 +1,79 @@
+/**
+ * skill-loader.ts — Preload specific skill files and inject their content into the system prompt.
+ *
+ * When skills is a string[], reads each named skill from .pi/skills/ or ~/.pi/skills/
+ * and returns their content for injection into the agent's system prompt.
+ */
+
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { isUnsafeName, safeReadFile } from "./memory.js";
+
+export interface PreloadedSkill {
+  name: string;
+  content: string;
+}
+
+/**
+ * Attempt to load named skills from project and global skill directories.
+ * Looks for: <dir>/<name>.md, <dir>/<name>.txt, <dir>/<name>
+ *
+ * @param skillNames  List of skill names to preload.
+ * @param cwd         Working directory for project-level skills.
+ * @returns Array of loaded skills (missing skills are skipped with a warning comment).
+ */
+export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
+  const results: PreloadedSkill[] = [];
+
+  for (const name of skillNames) {
+    // Unlike memory (which throws on unsafe names because it's part of agent setup),
+    // skills are optional — skip gracefully to avoid blocking agent startup.
+    if (isUnsafeName(name)) {
+      results.push({ name, content: `(Skill "${name}" skipped: name contains path traversal characters)` });
+      continue;
+    }
+    const content = findAndReadSkill(name, cwd);
+    if (content !== undefined) {
+      results.push({ name, content });
+    } else {
+      // Include a note about missing skills so the agent knows it was requested but not found
+      results.push({ name, content: `(Skill "${name}" not found in .pi/skills/ or ~/.pi/skills/)` });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Search for a skill file in project and global directories.
+ * Project-level takes priority over global.
+ */
+function findAndReadSkill(name: string, cwd: string): string | undefined {
+  const projectDir = join(cwd, ".pi", "skills");
+  const globalDir = join(homedir(), ".pi", "skills");
+
+  // Try project first, then global
+  for (const dir of [projectDir, globalDir]) {
+    const content = tryReadSkillFile(dir, name);
+    if (content !== undefined) return content;
+  }
+
+  return undefined;
+}
+
+/**
+ * Try to read a skill file from a directory.
+ * Tries extensions in order: .md, .txt, (no extension)
+ */
+function tryReadSkillFile(dir: string, name: string): string | undefined {
+  const extensions = [".md", ".txt", ""];
+
+  for (const ext of extensions) {
+    const path = join(dir, name + ext);
+    // safeReadFile rejects symlinks to prevent reading arbitrary files
+    const content = safeReadFile(path);
+    if (content !== undefined) return content.trim();
+  }
+
+  return undefined;
+}

package/src/types.ts

@@ -13,12 +13,20 @@ export type SubagentType = string;
 /** Names of the three embedded default agents. */
 export const DEFAULT_AGENT_NAMES = ["general-purpose", "Explore", "Plan"] as const;
 
+/** Memory scope for persistent agent memory. */
+export type MemoryScope = "user" | "project" | "local";
+
+/** Isolation mode for agent execution. */
+export type IsolationMode = "worktree";
+
 /** Unified agent configuration — used for both default and user-defined agents. */
 export interface AgentConfig {
   name: string;
   displayName?: string;
   description: string;
   builtinToolNames?: string[];
+  /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
+  disallowedTools?: string[];
   /** true = inherit all, string[] = only listed, false = none */
   extensions: true | string[] | false;
   /** true = inherit all, string[] = only listed, false = none */
@@ -34,6 +42,10 @@ export interface AgentConfig {
   runInBackground: boolean;
   /** Default for spawn: no extension tools */
   isolated: boolean;
+  /** Persistent memory scope — agents with memory get a persistent directory and MEMORY.md */
+  memory?: MemoryScope;
+  /** Isolation mode — "worktree" runs the agent in a temporary git worktree */
+  isolation?: IsolationMode;
   /** true = this is an embedded default agent (informational) */
   isDefault?: boolean;
   /** false = agent is hidden from the registry */
@@ -61,6 +73,10 @@ export interface AgentRecord {
   joinMode?: JoinMode;
   /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
   resultConsumed?: boolean;
+  /** Worktree info if the agent is running in an isolated worktree. */
+  worktree?: { path: string; branch: string };
+  /** Worktree cleanup result after agent completion. */
+  worktreeResult?: { hasChanges: boolean; branch?: string };
 }
 
 export interface EnvInfo {

package/src/worktree.ts

@@ -0,0 +1,162 @@
+/**
+ * worktree.ts — Git worktree isolation for agents.
+ *
+ * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
+ * On completion, if no changes were made, the worktree is cleaned up.
+ * If changes exist, a branch is created and returned in the result.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+export interface WorktreeInfo {
+  /** Absolute path to the worktree directory. */
+  path: string;
+  /** Branch name created for this worktree (if changes exist). */
+  branch: string;
+}
+
+export interface WorktreeCleanupResult {
+  /** Whether changes were found in the worktree. */
+  hasChanges: boolean;
+  /** Branch name if changes were committed. */
+  branch?: string;
+  /** Worktree path if it was kept. */
+  path?: string;
+}
+
+/**
+ * Create a temporary git worktree for an agent.
+ * Returns the worktree path, or undefined if not in a git repo.
+ */
+export function createWorktree(cwd: string, agentId: string): WorktreeInfo | undefined {
+  // Verify we're in a git repo with at least one commit (HEAD must exist)
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe", timeout: 5000 });
+    execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 });
+  } catch {
+    return undefined;
+  }
+
+  const branch = `pi-agent-${agentId}`;
+  const suffix = randomUUID().slice(0, 8);
+  const worktreePath = join(tmpdir(), `pi-agent-${agentId}-${suffix}`);
+
+  try {
+    // Create detached worktree at HEAD
+    execFileSync("git", ["worktree", "add", "--detach", worktreePath, "HEAD"], {
+      cwd,
+      stdio: "pipe",
+      timeout: 30000,
+    });
+    return { path: worktreePath, branch };
+  } catch {
+    // If worktree creation fails, return undefined (agent runs in normal cwd)
+    return undefined;
+  }
+}
+
+/**
+ * Clean up a worktree after agent completion.
+ * - If no changes: remove worktree entirely.
+ * - If changes exist: create a branch, commit changes, return branch info.
+ */
+export function cleanupWorktree(
+  cwd: string,
+  worktree: WorktreeInfo,
+  agentDescription: string,
+): WorktreeCleanupResult {
+  if (!existsSync(worktree.path)) {
+    return { hasChanges: false };
+  }
+
+  try {
+    // Check for uncommitted changes in the worktree
+    const status = execFileSync("git", ["status", "--porcelain"], {
+      cwd: worktree.path,
+      stdio: "pipe",
+      timeout: 10000,
+    }).toString().trim();
+
+    if (!status) {
+      // No changes — remove worktree
+      removeWorktree(cwd, worktree.path);
+      return { hasChanges: false };
+    }
+
+    // Changes exist — stage, commit, and create a branch
+    execFileSync("git", ["add", "-A"], { cwd: worktree.path, stdio: "pipe", timeout: 10000 });
+    // Truncate description for commit message (no shell sanitization needed — execFileSync uses argv)
+    const safeDesc = agentDescription.slice(0, 200);
+    const commitMsg = `pi-agent: ${safeDesc}`;
+    execFileSync("git", ["commit", "-m", commitMsg], {
+      cwd: worktree.path,
+      stdio: "pipe",
+      timeout: 10000,
+    });
+
+    // Create a branch pointing to the worktree's HEAD.
+    // If the branch already exists, append a suffix to avoid overwriting previous work.
+    let branchName = worktree.branch;
+    try {
+      execFileSync("git", ["branch", branchName], {
+        cwd: worktree.path,
+        stdio: "pipe",
+        timeout: 5000,
+      });
+    } catch {
+      // Branch already exists — use a unique suffix
+      branchName = `${worktree.branch}-${Date.now()}`;
+      execFileSync("git", ["branch", branchName], {
+        cwd: worktree.path,
+        stdio: "pipe",
+        timeout: 5000,
+      });
+    }
+    // Update branch name in worktree info for the caller
+    worktree.branch = branchName;
+
+    // Remove the worktree (branch persists in main repo)
+    removeWorktree(cwd, worktree.path);
+
+    return {
+      hasChanges: true,
+      branch: worktree.branch,
+      path: worktree.path,
+    };
+  } catch {
+    // Best effort cleanup on error
+    try { removeWorktree(cwd, worktree.path); } catch { /* ignore */ }
+    return { hasChanges: false };
+  }
+}
+
+/**
+ * Force-remove a worktree.
+ */
+function removeWorktree(cwd: string, worktreePath: string): void {
+  try {
+    execFileSync("git", ["worktree", "remove", "--force", worktreePath], {
+      cwd,
+      stdio: "pipe",
+      timeout: 10000,
+    });
+  } catch {
+    // If git worktree remove fails, try pruning
+    try {
+      execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
+    } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Prune any orphaned worktrees (crash recovery).
+ */
+export function pruneWorktrees(cwd: string): void {
+  try {
+    execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
+  } catch { /* ignore */ }
+}