@tintinweb/pi-subagents 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.0] - 2026-06-01
+
+> **⚠️ Breaking: `extensions:` and `tools:` in agent frontmatter semantics changed.** The `extensions: [...]` array now selects which extensions *load*, not which tool names surface. Agents that previously used the array form will behave differently — see migration below. The `tools:` field also grew new `ext:` and `*` selector forms; existing `tools:` values without these selectors are unchanged.
+> - `extensions: [...]` is now an **extension allowlist applied at load time**, not a tool-name substring filter. Each entry is an extension *name*, a *path* (absolute, `~/`-prefixed, or relative-to-cwd), or `"*"`. **Migration:** `extensions: ["mcp"]` previously loaded *every* extension and then surfaced only tools whose names contained `mcp`. To keep all extensions, use `extensions: true` or `extensions: "*"`. To narrow, name the extensions or point at their files. `"*"` composes: `extensions: "*, /abs/path/extra-ext.ts"` is all defaults plus one path-loaded.
+> - `tools:` now accepts `ext:` selectors and `*`. **Gotcha:** a `tools:` value containing **only** `ext:` entries yields **zero built-in tools** — add `*` (e.g. `tools: "*, ext:foo"`) to keep the built-ins. And **any** `ext:` entry flips extension tools to an explicit allowlist (non-listed extensions stay loaded but expose no tools). A `tools:` with no `ext:` entries is unchanged.
+> - **`extensions:` is the sole loading authority.** `ext:foo` only narrows tool *exposure* within the already-loaded set; it cannot pull an extension in. `extensions: false` + `tools: "ext:foo"` loads nothing and warns that `ext:foo` is orphaned. To expose one extension's tool from an otherwise-narrow agent, name the extension explicitly: `extensions: [foo]` + `tools: "ext:foo/bar"`.
+
+> **⚠️ Heads-up — widget glyphs changed (visual only):** turn count now renders as `↻N` (was `⟳N`) and compaction count as `⇊N` (was `↻N`). Fix for [#84](https://github.com/tintinweb/pi-subagents/issues/84) — `⟳` overflowed its cell in common monospace fonts. **No API, behavior, or output-format changes — only the glyphs.** If you grep agent stats lines or pipe widget output through scripts, update your patterns: `⟳` → `↻` (turns), `↻` → `⇊` (compactions).
+
+### Added
+- **`tools:` accepts `ext:` extension-tool selectors and a `*` built-in wildcard.** Entries in the `tools:` CSV are now partitioned: plain names are the built-in allowlist (unchanged); `*` expands to all built-ins (symmetric with `extensions: "*"`); `ext:foo` / `ext:foo/bar` select extension tools. **Any `ext:` entry flips extension tools to an explicit allowlist** — only tools named by an `ext:` selector reach the LLM, and extensions not named stay loaded (their `session_start` etc. handlers still fire) but expose no tools. `ext:foo` exposes all of `foo`'s tools; `ext:foo/bar` narrows `foo` to just `bar` (multiple `ext:foo/x` entries union; a bare `ext:foo` alongside `ext:foo/bar` lets narrowing win). `ext:` is **narrowing-only** — it does not load extensions. `extensions:` remains the sole loading authority; an `ext:foo` against an extension that `extensions:` excluded (including `extensions: false`) is orphaned and warns via `onToolActivity` (`extension-error:ext:foo …`). With no `ext:` entry present, extension-tool behaviour is unchanged. `ext:` is name-only (matched by canonical name, so it composes with path-loaded extensions); paths still go in `extensions:`. `isolated: true` ignores `ext:` selectors.
+- **Stop a running agent from the conversation viewer.** In `/agents → Running agents`, select an agent and press `x` (then `x` again to confirm) to abort it. The two-press guard prevents an accidental kill; the footer shows `x stop` → `x again to STOP`. This works for **background** agents — which a global `Esc` can't unambiguously target — while `Esc` still stops a blocking foreground `Agent` call. Wires the existing `AgentManager.abort(id)` to the viewer (`onStop` callback); the affordance only appears while the agent is `running`/`queued`. Addresses the common "how do I stop a background subagent?" question ([#88](https://github.com/tintinweb/pi-subagents/issues/88)).
+
+### Changed
+- **BREAKING: `extensions: [...]` in agent frontmatter is now a loader-level extension allowlist, not a tool-name filter.** Previously a `string[]` value filtered exposed *tool names* by substring (`t.startsWith(e) || t.includes(e)`) while every discovered extension still loaded and ran its handlers. Now each entry selects an *extension*: a bare name keeps the matching default-discovered extension, a path (absolute, `~/`-prefixed, or relative-to-cwd) loads that extension fresh via `additionalExtensionPaths`, and `"*"` keeps all default-discovered extensions. Entries compose — `["*", "/abs/foo.ts"]` is all defaults plus foo, `["mcp", "/abs/foo.ts"]` is just those two. Excluded extensions no longer bind handlers or register tools (their factory still runs once during `reload()`). Directory extensions (`foo/index.ts`) match by the parent directory name. **Extension names match case-insensitively** (`extensions: [Mcp]` resolves the same as `[mcp]`); tool names within `ext:foo/bar` selectors remain case-sensitive (they're matched against pi-mono's registered identifiers). Unmatched names and failed paths warn via `onToolActivity` but do not abort the subagent (see the heads-up above for migration).
+- **Non-normal subagent outcomes are now stated explicitly in the text delivered to the parent**, so the orchestrator can't mistake a stopped/incomplete agent for a completed one. The foreground `Agent` result, `get_subagent_result`, and the `<task-notification>` summary all append a clear note for `stopped` (user abort) → `(STOPPED BY THE USER before completion — output is partial; the task was NOT finished)`, `aborted` (turn limit) → `(aborted — hit the turn limit before completion; output may be incomplete)`, and `steered` → `(wrapped up at the turn limit — output may be partial)`. `stopped` (human intervention) is kept distinct from `aborted` (turn-budget cutoff); a clean `completed` adds no note. Extracted as `getStatusNote` in `src/status-note.ts`.
+- **`BUILTIN_TOOL_NAMES` is derived from pi's tool factories** (`createCodingTools` + `createReadOnlyTools`) rather than a hardcoded list, so the built-in set tracks pi-mono automatically. Internal; no behavior change (the resolved set is the same seven names).
+
+### Fixed
+- **Turn-count glyph in the agent widget no longer overflows its monospace cell** ([#84](https://github.com/tintinweb/pi-subagents/issues/84) — thanks [@linozen](https://github.com/linozen)). `formatTurns` used `⟳` (U+27F3 CLOCKWISE GAPPED CIRCLE ARROW) from the Miscellaneous Mathematical Symbols-A block, where common monospace fonts (Iosevka Nerd Font Mono, Menlo, SF Mono, JetBrains Mono) draw the glyph visually wider than one cell despite its Neutral East Asian Width — making the next character (the digit) overlap the glyph. Replaced with `↻` (U+21BB CLOCKWISE OPEN CIRCLE ARROW) from the standard Arrows block, which renders cleanly at one cell in those fonts. To avoid colliding with the existing compaction indicator (which previously also used `↻`), the compaction glyph moves to `⇊` (U+21CA DOWNWARDS PAIRED ARROWS) — same Arrows block, also single-cell, visually distinct. Widget vocabulary now reads: `↻5≤30` for turns, `⇊2` for compactions. Pi UI consumers / scripts grepping for the glyph in stats lines must update.
+- **`tools: none` now actually yields zero built-in tools.** `getToolNamesForType` treated an explicit empty `builtinToolNames` (`[]`, produced by `tools: none`) as "unspecified" and fell back to all 7 built-ins. It now distinguishes an omitted field (`undefined` → all built-ins, for default agents) from an explicit empty list (`[]` → zero), consistent with `getConfig`. Same fix makes `tools:` values containing only `ext:` selectors yield zero built-ins as documented.
+- **`tools:` typos no longer silently break tool-calling** ([#75](https://github.com/tintinweb/pi-subagents/issues/75)). Two parts: (a) `all` was previously parsed as a literal tool name, producing a one-element allowlist of the non-existent tool `"all"` — the model then returned an empty response or emitted raw XML tool calls, all with `status: completed` and no error. `parseToolsField` now treats `all` (case-insensitive) as an alias for the `*` wildcard, both standalone and inside a CSV. (b) Plain entries in `tools:` are expected to be built-in names (extension tools route through `ext:`), so an unknown name there is unambiguously a typo. `runAgent` now emits a `tools-error:tool "X" requested by agent "Y" is not a known built-in` event via `onToolActivity` for each unrecognized plain entry — same surfacing channel as the existing `extension-error:` warnings.
+- **Subagents with `extensions: true` now actually expose extension-registered tools (MCP, etc.)** ([#47](https://github.com/tintinweb/pi-subagents/issues/47)). `runAgent` previously passed only the built-in tool names as the `tools:` allowlist to `createAgentSession`, so pi-mono's `allowedToolNames` gate rejected every extension-registered tool at registration — `extensions: true` agents silently got only the 7 built-ins. `runAgent` now enumerates extension tool names from the resource loader after `reload()` and builds the full master allowlist (built-ins + permitted extension tools), so pi-mono's gate admits them from the first instant of the session. `disallowedTools` and the internal `Agent`/`get_subagent_result`/`steer_subagent` exclusions are applied uniformly to built-in and extension tools at construction — no post-construction `setActiveToolsByName` narrowing.
+- **Append-mode subagents no longer defeat the LLM's KV cache** ([#73](https://github.com/tintinweb/pi-subagents/pull/73) — reported by [@jeffutter](https://github.com/jeffutter)). The assembled child prompt placed the per-spawn-varying `<active_agent>` tag and `# Environment` block *before* the ~8k-token inherited parent prompt, and wrapped the parent prompt in `<inherited_system_prompt>` tags. Because KV caches key on a byte-identical prefix, every subagent spawn reprocessed all ~8k shared tokens from scratch (~40s on slower hardware). The parent prompt is now emitted **verbatim at the start** of the prompt (wrapper dropped), so it forms an identical, cacheable prefix with the parent session and across every spawn; the static `<sub_agent_context>` bridge follows, then the varying `<active_agent>` tag and env block. `replace` mode is unchanged (it inherits no parent prefix). The `<active_agent>` tag stays present and is parsed position-independently, so downstream permission resolution is unaffected. Mirrors the fix in [gotgenes/pi-packages#180](https://github.com/gotgenes/pi-packages/issues/180).
+
+## [0.9.1] - 2026-05-30
+
+### Added
+- **`Agent`, `get_subagent_result`, and `steer_subagent` now surface in pi's default system prompt** ([#87](https://github.com/tintinweb/pi-subagents/pull/87) — thanks [@that-yolanda](https://github.com/that-yolanda)). Adds `promptSnippet` to all three (a line in the prompt's `Available tools:` section) and `promptGuidelines` to `Agent` (bullets in `Guidelines:`). The tools were always callable via the tool-call API; this only adds system-prompt reinforcement for prompt-following models. No schema or tool-call changes.
+
 ## [0.9.0] - 2026-05-30
 
 > **Heads-up — orchestrator behavior may shift.** This release substantially rewrites the `Agent` tool description and the three default-agent descriptions (`general-purpose`, `Explore`, `Plan`) to mirror Claude Code's upstream wording. No API, schema, or tool-call shape changes — purely a prompt-engineering shift, but a load-bearing one:

package/README.md

@@ -15,7 +15,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Claude Code look & feel** — same tool names, calling conventions, and UI patterns (`Agent`, `get_subagent_result`, `steer_subagent`) — feels native
 - **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and smart group join (consolidated notifications)
 - **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
-- **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause)
+- **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause). Stop a still-running agent from here by pressing `x` (then `x` again to confirm) — works for background agents too
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting
 - **Session resume** — pick up where an agent left off, preserving full conversation context
@@ -98,29 +98,29 @@ The extension renders a persistent widget above the editor showing all active ag
 
 ```
 ● Agents
-├─ ⠹ Agent  Refactor auth module · ⟳5≤30 · 5 tool uses · 33.8k token (62%) · 12.3s
+├─ ⠹ Agent  Refactor auth module · ↻5≤30 · 5 tool uses · 33.8k token (62%) · 12.3s
 │    ⎿  editing 2 files…
-├─ ⠹ Explore  Find auth files · ⟳3 · 3 tool uses · 12.4k token (8%) · 4.1s
+├─ ⠹ Explore  Find auth files · ↻3 · 3 tool uses · 12.4k token (8%) · 4.1s
 │    ⎿  searching…
-├─ ⠹ Agent  Long-running task · ⟳42 · 38 tool uses · 91.0k token (84% · ↻2) · 2m17s
+├─ ⠹ Agent  Long-running task · ↻42 · 38 tool uses · 91.0k token (84% · ⇊2) · 2m17s
 │    ⎿  reading…
 └─ 2 queued
 ```
 
 The token field is annotated with two optional signals inside parens:
 - **`NN%`** — context-window utilization (color-coded: <70% dim, 70–85% warning, ≥85% error). Omitted when the model has no declared `contextWindow`, or briefly right after compaction.
-- **`↻N`** — number of times the session has compacted, when > 0. Stays dim; the percent's color carries urgency.
+- **`⇊N`** — number of times the session has compacted, when > 0. Stays dim; the percent's color carries urgency.
 
 Individual agent results render Claude Code-style in the conversation:
 
 | State | Example |
 |-------|---------|
-| **Running** | `⠹ ⟳3≤30 · 3 tool uses · 12.4k token (8%)` / `⎿ searching, reading 3 files…` |
-| **Completed** | `✓ ⟳8 · 5 tool uses · 33.8k token (62%) · 12.3s` / `⎿ Done` |
-| **Wrapped up** | `✓ ⟳50≤50 · 50 tool uses · 89.1k token (84% · ↻2) · 45.2s` / `⎿ Wrapped up (turn limit)` |
-| **Stopped** | `■ ⟳3 · 3 tool uses · 12.4k token (8%)` / `⎿ Stopped` |
-| **Error** | `✗ ⟳3 · 3 tool uses · 12.4k token (8%)` / `⎿ Error: timeout` |
-| **Aborted** | `✗ ⟳55≤50 · 55 tool uses · 102.3k token (95% · ↻3)` / `⎿ Aborted (max turns exceeded)` |
+| **Running** | `⠹ ↻3≤30 · 3 tool uses · 12.4k token (8%)` / `⎿ searching, reading 3 files…` |
+| **Completed** | `✓ ↻8 · 5 tool uses · 33.8k token (62%) · 12.3s` / `⎿ Done` |
+| **Wrapped up** | `✓ ↻50≤50 · 50 tool uses · 89.1k token (84% · ⇊2) · 45.2s` / `⎿ Wrapped up (turn limit)` |
+| **Stopped** | `■ ↻3 · 3 tool uses · 12.4k token (8%)` / `⎿ Stopped` |
+| **Error** | `✗ ↻3 · 3 tool uses · 12.4k token (8%)` / `⎿ Error: timeout` |
+| **Aborted** | `✗ ↻55≤50 · 55 tool uses · 102.3k token (95% · ⇊3)` / `⎿ Aborted (max turns exceeded)` |
 
 Completed results can be expanded (ctrl+o in pi) to show the full agent output inline.
 
@@ -128,7 +128,7 @@ Background agent completion notifications render as styled boxes:
 
 ```
 ✓ Find auth files completed
-  ⟳3 · 3 tool uses · 12.4k token · 4.1s
+  ↻3 · 3 tool uses · 12.4k token · 4.1s
   ⎿  Found 5 files related to authentication...
   transcript: .pi/output/agent-abc123.jsonl
 ```
@@ -194,8 +194,8 @@ All fields are optional — sensible defaults for everything.
 |-------|---------|-------------|
 | `description` | filename | Agent description shown in tool listings |
 | `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 |
+| `tools` | all 7 | Which tools the agent can call. Built-in names (`read, grep, …`), `*` / `all` (all built-ins), `none`, and `ext:<extension>` / `ext:<extension>/<tool>` selectors for extension tools. See [Tool & extension scoping](#tool--extension-scoping) below |
+| `extensions` | `true` | Which extensions to load for the agent. `true` (all defaults), `false` (none), or an explicit list: `[mcp, "/abs/path.ts", "*"]`. See [Tool & extension scoping](#tool--extension-scoping) below |
 | `skills` | `true` | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations) |
 | `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 |
@@ -206,11 +206,42 @@ All fields are optional — sensible defaults for everything.
 | `prompt_mode` | `replace` | `replace`: body is the full system prompt (no AGENTS.md / CLAUDE.md inheritance). `append`: body appended to parent's prompt (agent acts as a "parent twin" — inherits parent's AGENTS.md / CLAUDE.md) |
 | `inherit_context` | `false` | Fork parent conversation into agent |
 | `run_in_background` | `false` | Run in background by default |
-| `isolated` | `false` | No extension/MCP tools, only built-in |
+| `isolated` | `false` | Hermetic specialist mode: forces `extensions: false` + `skills: false` + drops `ext:` selectors. Only built-in tools. Distinct from `isolation: worktree` (filesystem) |
 | `enabled` | `true` | Set to `false` to disable an agent (useful for hiding a default agent per-project) |
 
 Frontmatter is authoritative. If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, or `isolation`, those values are locked for that agent. `Agent` tool parameters only fill fields the agent config leaves unspecified.
 
+### Tool & extension scoping
+
+`extensions:` decides **which extensions load**, `tools:` decides **which tools surface to the LLM**. They compose:
+
+```yaml
+# Default (both omitted): all extensions load, all 7 built-ins surface
+
+tools: read, grep, find           # narrow to listed built-ins; extensions still load
+tools: "*"                        # all 7 built-ins (alias: `all`)
+tools: none                       # zero built-ins (alias: `""`)
+tools: "*, ext:mcp/search"        # built-ins plus one extension tool
+
+extensions: false                 # no extensions load
+extensions: [mcp]                 # only mcp loads
+extensions: ["*", "/abs/foo.ts"]  # all defaults plus one path-loaded extension
+
+# Specialist: load one extension, expose only one of its tools, keep built-ins
+extensions: [mcp]
+tools: "*, ext:mcp/search"
+
+isolated: true                    # hermetic: built-ins only, no extensions/skills/context
+```
+
+A few rules the examples don't make obvious:
+
+- `extensions:` is the sole loading authority. `ext:foo` in `tools:` narrows what surfaces; it can't load `foo` on its own. Mismatches fire `extension-error:…` warnings.
+- Any `ext:` entry flips extension tools to an explicit allowlist — unnamed extensions still load (handlers fire) but expose no tools. So `tools: "*, ext:mcp/search"` exposes only `search` from `mcp`, nothing from any other extension.
+- Extension names match case-insensitively (`[Mcp]` = `[mcp]`); tool names in `ext:foo/bar` stay case-sensitive.
+- Plain `tools:` typos fail loudly: `tools: reed, grep` fires `tools-error:…` instead of silently producing an under-tooled agent.
+- Array and string forms are equivalent: `[a, b]` == `"a, b"`.
+
 ## Tools
 
 ### `Agent`
@@ -265,6 +296,7 @@ Create new agent                            ← manual wizard or AI-generated
 Settings                                    ← max concurrency, max turns, grace turns, join mode
 ```
 
+- **Running agents** — select one to open its live conversation viewer. While it's still running, press `x` (then `x` again to confirm) to stop/abort it — including **background** agents, which a global Esc can't unambiguously target (Esc still stops a blocking foreground `Agent` call). A stopped agent reports its partial output flagged as incomplete, not as a completion.
 - **Agent types** — unified list with source indicators: `•` (project), `◦` (global), `✕` (disabled). Select an agent to manage it:
   - **Default agents** (no override): Eject (export as `.md`), Disable
   - **Default agents** (ejected/overridden): Edit, Disable, Reset to default, Delete

package/dist/agent-runner.d.ts

@@ -5,6 +5,55 @@ import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type AgentSession, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { SubagentType, ThinkingLevel } from "./types.js";
+/**
+ * Tool names registered by THIS extension. Single source of truth so the
+ * registration sites (index.ts) and the subagent exclusion list below can't
+ * drift apart. These are our own tools, not pi built-ins, so they can't be
+ * derived from pi — but they only need defining once.
+ */
+export declare const SUBAGENT_TOOL_NAMES: {
+    readonly AGENT: "Agent";
+    readonly GET_RESULT: "get_subagent_result";
+    readonly STEER: "steer_subagent";
+};
+/**
+ * Canonical name of an extension for `extensions: [...]` allowlist matching.
+ * Lowercased — extension names match case-insensitively so `extensions: [Mcp]`
+ * resolves the same as `[mcp]`. Tool names within `ext:foo/bar` are not affected.
+ * Directory extensions (`foo/index.ts`) resolve to the parent directory name;
+ * single-file extensions to the basename minus `.ts`/`.js`.
+ */
+export declare function extensionCanonicalName(extPath: string): string;
+/**
+ * Classify `extensions: string[]` frontmatter entries for the loader-level filter.
+ *
+ * An entry is a PATH iff it contains a path separator or starts with `~`; otherwise
+ * it is a NAME. `"*"` sets the wildcard flag (keep all default-discovered extensions).
+ *
+ * Path entries are resolved (`~` expanded, made absolute against `cwd`) into `paths`
+ * — and their canonical name is also added to `names`. The loader override matches
+ * everything by canonical name, so path-loaded extensions are matched via their name
+ * rather than their post-staging `Extension.path`.
+ */
+export declare function parseExtensionsSpec(entries: string[], cwd: string): {
+    names: Set<string>;
+    paths: string[];
+    wildcard: boolean;
+};
+/**
+ * Parse raw `ext:` selector strings (from the `tools:` CSV) into the set of
+ * extension names to keep loaded and a per-extension tool-narrowing map.
+ *
+ * `ext:foo` → `extNames` has `foo`, no narrowing entry (all of foo's tools).
+ * `ext:foo/bar` → `extNames` has `foo`, `narrowing.foo` has `bar` (only `bar`).
+ * A name lands in `narrowing` only when a `/tool` form is seen, so a bare
+ * `ext:foo` alongside `ext:foo/bar` leaves narrowing in effect (narrowing wins).
+ * The split is on the first `/`; extension canonical names never contain `/`.
+ */
+export declare function parseExtSelectors(entries: string[]): {
+    extNames: Set<string>;
+    narrowing: Map<string, Set<string>>;
+};
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
 export declare function normalizeMaxTurns(n: number | undefined): number | undefined;
 /** Get the default max turns value. undefined = unlimited. */

package/dist/agent-runner.js

@@ -1,16 +1,119 @@
 /**
  * agent-runner.ts — Core execution engine: creates sessions, runs agents, collects results.
  */
+import { homedir } from "node:os";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
 import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
-import { getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
+import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
 import { buildParentContext, extractText } from "./context.js";
 import { DEFAULT_AGENTS } from "./default-agents.js";
 import { detectEnv } from "./env.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
 import { buildAgentPrompt } from "./prompts.js";
 import { preloadSkills } from "./skill-loader.js";
+/**
+ * Tool names registered by THIS extension. Single source of truth so the
+ * registration sites (index.ts) and the subagent exclusion list below can't
+ * drift apart. These are our own tools, not pi built-ins, so they can't be
+ * derived from pi — but they only need defining once.
+ */
+export const SUBAGENT_TOOL_NAMES = {
+    AGENT: "Agent",
+    GET_RESULT: "get_subagent_result",
+    STEER: "steer_subagent",
+};
 /** Names of tools registered by this extension that subagents must NOT inherit. */
-const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
+const EXCLUDED_TOOL_NAMES = Object.values(SUBAGENT_TOOL_NAMES);
+/**
+ * Canonical name of an extension for `extensions: [...]` allowlist matching.
+ * Lowercased — extension names match case-insensitively so `extensions: [Mcp]`
+ * resolves the same as `[mcp]`. Tool names within `ext:foo/bar` are not affected.
+ * Directory extensions (`foo/index.ts`) resolve to the parent directory name;
+ * single-file extensions to the basename minus `.ts`/`.js`.
+ */
+export function extensionCanonicalName(extPath) {
+    const base = basename(extPath);
+    const name = base === "index.ts" || base === "index.js"
+        ? basename(dirname(extPath))
+        : base.replace(/\.(ts|js)$/, "");
+    return name.toLowerCase();
+}
+/**
+ * Classify `extensions: string[]` frontmatter entries for the loader-level filter.
+ *
+ * An entry is a PATH iff it contains a path separator or starts with `~`; otherwise
+ * it is a NAME. `"*"` sets the wildcard flag (keep all default-discovered extensions).
+ *
+ * Path entries are resolved (`~` expanded, made absolute against `cwd`) into `paths`
+ * — and their canonical name is also added to `names`. The loader override matches
+ * everything by canonical name, so path-loaded extensions are matched via their name
+ * rather than their post-staging `Extension.path`.
+ */
+export function parseExtensionsSpec(entries, cwd) {
+    const names = new Set();
+    const paths = [];
+    let wildcard = false;
+    for (const entry of entries) {
+        if (!entry)
+            continue;
+        if (entry === "*") {
+            wildcard = true;
+            continue;
+        }
+        const isPathEntry = entry.includes("/") || entry.includes("\\") || entry.startsWith("~");
+        if (!isPathEntry) {
+            names.add(entry.toLowerCase());
+            continue;
+        }
+        let p = entry;
+        if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) {
+            p = homedir() + p.slice(1);
+        }
+        const abs = isAbsolute(p) ? p : resolve(cwd, p);
+        paths.push(abs);
+        names.add(extensionCanonicalName(abs));
+    }
+    return { names, paths, wildcard };
+}
+/**
+ * Parse raw `ext:` selector strings (from the `tools:` CSV) into the set of
+ * extension names to keep loaded and a per-extension tool-narrowing map.
+ *
+ * `ext:foo` → `extNames` has `foo`, no narrowing entry (all of foo's tools).
+ * `ext:foo/bar` → `extNames` has `foo`, `narrowing.foo` has `bar` (only `bar`).
+ * A name lands in `narrowing` only when a `/tool` form is seen, so a bare
+ * `ext:foo` alongside `ext:foo/bar` leaves narrowing in effect (narrowing wins).
+ * The split is on the first `/`; extension canonical names never contain `/`.
+ */
+export function parseExtSelectors(entries) {
+    const extNames = new Set();
+    const narrowing = new Map();
+    for (const raw of entries) {
+        if (!raw)
+            continue;
+        const body = raw.slice("ext:".length);
+        const slash = body.indexOf("/");
+        // Extension name matches case-insensitively (matches the loader-side canonical
+        // name). Tool names are case-preserved — they're matched against pi-mono's
+        // registered identifiers, which are case-sensitive.
+        const name = (slash === -1 ? body : body.slice(0, slash)).trim().toLowerCase();
+        if (!name)
+            continue;
+        extNames.add(name);
+        if (slash === -1)
+            continue;
+        const tool = body.slice(slash + 1).trim();
+        if (!tool)
+            continue;
+        let set = narrowing.get(name);
+        if (!set) {
+            set = new Set();
+            narrowing.set(name, set);
+        }
+        set.add(tool);
+    }
+    return { extNames, narrowing };
+}
 /** Default max turns. undefined = unlimited (no turn limit). */
 let defaultMaxTurns;
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
@@ -151,16 +254,46 @@ export async function runAgent(ctx, type, prompt, options) {
     // Still pass noSkills: true since we don't need the skill loader to load them again.
     const noSkills = skills === false || Array.isArray(skills);
     const agentDir = getAgentDir();
-    // Load extensions/skills: true or string[] → load; false → don't.
+    // Extension loading:
+    // - true  → all default-discovered extensions
+    // - false → none (noExtensions)
+    // - string[] → loader-level allowlist. Bare names keep the matching
+    //   default-discovered extension; path entries load that extension fresh;
+    //   "*" keeps all default-discovered extensions. Excluded extensions never
+    //   bind handlers or register tools (their factory still runs once).
+    //
     // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md — upstream's
     // buildSystemPrompt() re-appends both AFTER systemPromptOverride, which
     // would defeat prompt_mode: replace and isolated: true. Parent context, if
     // wanted, reaches the subagent via prompt_mode: append (parentSystemPrompt
     // is embedded in systemPromptOverride) or inherit_context (conversation).
+    // `ext:` selectors from the `tools:` CSV narrow which extension tools surface to
+    // the LLM. They do NOT control loading — `extensions:` is the sole authority for
+    // which extensions load. `ext:foo` against an extension that `extensions:` excluded
+    // is an orphan and warns after reload. `isolated` means no extension tools at all.
+    const { extNames, narrowing } = parseExtSelectors(options.isolated ? [] : (agentConfig?.extSelectors ?? []));
+    const noExtensions = extensions === false;
+    const extensionsSpec = Array.isArray(extensions)
+        ? parseExtensionsSpec(extensions, effectiveCwd)
+        : undefined;
+    const keepNames = extensionsSpec?.names ?? new Set();
+    // The override filters loaded extensions down to `keepNames`. It's only needed
+    // when we're neither loading everything (`extensions: true` or a `"*"` wildcard)
+    // nor nothing (`noExtensions`).
+    const loadAll = extensions === true || extensionsSpec?.wildcard === true;
+    const additionalExtensionPaths = extensionsSpec?.paths.length ? extensionsSpec.paths : undefined;
+    const extensionsOverride = loadAll || noExtensions
+        ? undefined
+        : (base) => ({
+            ...base,
+            extensions: base.extensions.filter((e) => keepNames.has(extensionCanonicalName(e.path))),
+        });
     const loader = new DefaultResourceLoader({
         cwd: effectiveCwd,
         agentDir,
-        noExtensions: extensions === false,
+        noExtensions,
+        additionalExtensionPaths,
+        extensionsOverride,
         noSkills,
         noPromptTemplates: true,
         noThemes: true,
@@ -169,10 +302,94 @@ export async function runAgent(ctx, type, prompt, options) {
         appendSystemPromptOverride: () => [],
     });
     await loader.reload();
+    // Plain entries in `tools:` are expected to be built-in names (extension tools
+    // go through `ext:`), so an unknown name there is unambiguously a typo. Previously
+    // this produced a silently broken agent (#75) — pi-mono accepted the bogus name
+    // into the allowlist, then dropped it at registration with no signal back.
+    if (agentConfig?.builtinToolNames?.length) {
+        const knownBuiltins = new Set(BUILTIN_TOOL_NAMES);
+        for (const name of agentConfig.builtinToolNames) {
+            if (!knownBuiltins.has(name)) {
+                options.onToolActivity?.({
+                    type: "end",
+                    toolName: `tools-error:tool "${name}" requested by agent "${type}" is not a known built-in`,
+                });
+            }
+        }
+    }
+    // A subagent spawns mid-task, so a bad `extensions:`/`ext:` entry warns rather
+    // than aborts. Two distinct misconfigurations to catch:
+    //   - `extensions: [foo]` but no extension named foo was discovered (typo or
+    //     path that failed to load — path entries fold their canonical name into
+    //     `keepNames`, so this covers them too).
+    //   - `tools: ext:foo` but foo isn't in the loaded set (because `extensions:`
+    //     didn't include it). Since v0.9, `ext:` no longer pulls extensions in;
+    //     loading is `extensions:`-authoritative.
+    if (keepNames.size > 0 || extNames.size > 0) {
+        const survivingNames = new Set(loader.getExtensions().extensions.map((e) => extensionCanonicalName(e.path)));
+        for (const name of keepNames) {
+            if (!survivingNames.has(name)) {
+                options.onToolActivity?.({
+                    type: "end",
+                    toolName: `extension-error:extension "${name}" requested by agent "${type}" was not loaded`,
+                });
+            }
+        }
+        for (const name of extNames) {
+            if (!survivingNames.has(name)) {
+                options.onToolActivity?.({
+                    type: "end",
+                    toolName: `extension-error:ext:${name} referenced by agent "${type}" but extension "${name}" is not loaded (add it to extensions:)`,
+                });
+            }
+        }
+    }
     // Resolve model: explicit option > config.model > parent model
     const model = options.model ?? resolveDefaultModel(ctx.model, ctx.modelRegistry, agentConfig?.model);
     // Resolve thinking level: explicit option > agent config > undefined (inherit)
     const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
+    const disallowedSet = agentConfig?.disallowedTools
+        ? new Set(agentConfig.disallowedTools)
+        : undefined;
+    // Enumerate extension-registered tool names from the loaded resource loader.
+    // Extensions populate `extension.tools` during `loader.reload()` and the set
+    // is stable afterwards — `bindExtensions` does not register new tools.
+    //
+    // Opt-in flip: when any `ext:` selector is present, extension tools become an
+    // explicit allowlist — a loaded extension not named by a selector contributes
+    // no tools (its handlers still ran), and `ext:foo/bar` narrows `foo` to `bar`.
+    const extensionToolNames = [];
+    if (!noExtensions) {
+        const optInActive = extNames.size > 0;
+        for (const extension of loader.getExtensions().extensions) {
+            const canon = extensionCanonicalName(extension.path);
+            if (optInActive && !extNames.has(canon))
+                continue;
+            const narrowed = narrowing.get(canon);
+            for (const toolName of extension.tools.keys()) {
+                if (narrowed && !narrowed.has(toolName))
+                    continue;
+                extensionToolNames.push(toolName);
+            }
+        }
+    }
+    // Build the master tool allowlist applied at session construction.
+    // pi-mono's `allowedToolNames` gates BOTH registration and the initial active
+    // set, so listing the exact final set here means the session is correctly
+    // scoped from the first instant — no post-construction narrowing required.
+    const builtinToolNameSet = new Set(toolNames);
+    const allowedTools = [...toolNames, ...extensionToolNames].filter((t) => {
+        if (EXCLUDED_TOOL_NAMES.includes(t))
+            return false;
+        if (disallowedSet?.has(t))
+            return false;
+        if (builtinToolNameSet.has(t))
+            return true;
+        // Reached only for extension tools. The extension set was already filtered
+        // at the loader (extensionsOverride / noExtensions) and at enumeration
+        // (`ext:` opt-in flip), so any extension tool in `extensionToolNames` is allowed.
+        return !noExtensions;
+    });
     const sessionOpts = {
         cwd: effectiveCwd,
         agentDir,
@@ -180,7 +397,7 @@ export async function runAgent(ctx, type, prompt, options) {
         settingsManager: SettingsManager.create(effectiveCwd, agentDir),
         modelRegistry: ctx.modelRegistry,
         model,
-        tools: toolNames,
+        tools: allowedTools,
         resourceLoader: loader,
     };
     if (thinkingLevel) {
@@ -189,37 +406,10 @@ export async function runAgent(ctx, type, prompt, options) {
     const { session } = await createAgentSession(sessionOpts);
     const baseSessionName = agentConfig?.name ?? type;
     session.setSessionName(options.agentId ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName);
-    // 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,
-    // apply extension allowlist if specified, and apply disallowedTools denylist
-    if (extensions !== false) {
-        const builtinToolNameSet = new Set(toolNames);
-        const activeTools = session.getActiveToolNames().filter((t) => {
-            if (EXCLUDED_TOOL_NAMES.includes(t))
-                return false;
-            if (disallowedSet?.has(t))
-                return false;
-            if (builtinToolNameSet.has(t))
-                return true;
-            if (Array.isArray(extensions)) {
-                return extensions.some(ext => t.startsWith(ext) || t.includes(ext));
-            }
-            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);
-    }
     // Bind extensions so that session_start fires and extensions can initialize
-    // (e.g. loading credentials, setting up state). Placed after tool filtering
-    // so extension-provided skills/prompts from extendResourcesFromExtensions()
-    // respect the active tool set. All ExtensionBindings fields are optional.
+    // (e.g. loading credentials, setting up state). Tool gating already happened
+    // at session construction via the `tools:` allowlist above — no separate
+    // post-bind filter is needed. All ExtensionBindings fields are optional.
     await session.bindExtensions({
         onError: (err) => {
             options.onToolActivity?.({

package/dist/agent-types.d.ts

@@ -5,7 +5,14 @@
  * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
  */
 import type { AgentConfig } from "./types.js";
-/** All known built-in tool names. */
+/**
+ * All known built-in tool names, derived from pi's own tool factories rather
+ * than hardcoded so the set tracks pi-mono if it adds/renames a built-in.
+ * `createCodingTools` → read/bash/edit/write; `createReadOnlyTools` →
+ * read/grep/find/ls; their de-duplicated union is the 7 built-ins
+ * (read, bash, edit, write, grep, find, ls). The `cwd` only binds tool
+ * operations we never invoke here — we read each tool's `.name` and discard it.
+ */
 export declare const BUILTIN_TOOL_NAMES: string[];
 /**
  * Register agents into the unified registry.

package/dist/agent-types.js

@@ -4,9 +4,19 @@
  * Merges embedded default agents with user-defined agents from .pi/agents/*.md.
  * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
  */
+import { createCodingTools, createReadOnlyTools } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_AGENTS } from "./default-agents.js";
-/** All known built-in tool names. */
-export const BUILTIN_TOOL_NAMES = ["read", "bash", "edit", "write", "grep", "find", "ls"];
+/**
+ * All known built-in tool names, derived from pi's own tool factories rather
+ * than hardcoded so the set tracks pi-mono if it adds/renames a built-in.
+ * `createCodingTools` → read/bash/edit/write; `createReadOnlyTools` →
+ * read/grep/find/ls; their de-duplicated union is the 7 built-ins
+ * (read, bash, edit, write, grep, find, ls). The `cwd` only binds tool
+ * operations we never invoke here — we read each tool's `.name` and discard it.
+ */
+export const BUILTIN_TOOL_NAMES = [
+    ...new Set([...createCodingTools("."), ...createReadOnlyTools(".")].map((t) => t.name)),
+];
 /** Unified runtime registry of all agents (defaults + user-defined). */
 const agents = new Map();
 /**
@@ -95,8 +105,9 @@ export function getToolNamesForType(type) {
     const key = resolveKey(type);
     const raw = key ? agents.get(key) : undefined;
     const config = raw?.enabled !== false ? raw : undefined;
-    const names = config?.builtinToolNames?.length ? config.builtinToolNames : [...BUILTIN_TOOL_NAMES];
-    return names;
+    // `undefined` (definition omitted the field) → all built-ins; an explicit `[]`
+    // (`tools: none` or a `tools:` with only `ext:` entries) → zero built-ins.
+    return config?.builtinToolNames ?? [...BUILTIN_TOOL_NAMES];
 }
 /** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
 export function getConfig(type) {

package/dist/custom-agents.js

@@ -43,11 +43,13 @@ function loadFromDir(dir, agents, source) {
             continue;
         }
         const { frontmatter: fm, body } = parseFrontmatter(content);
+        const { builtinToolNames, extSelectors } = parseToolsField(fm.tools);
         agents.set(name, {
             name,
             displayName: str(fm.display_name),
             description: str(fm.description) ?? name,
-            builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
+            builtinToolNames,
+            extSelectors,
             disallowedTools: csvListOptional(fm.disallowed_tools),
             extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
             skills: inheritField(fm.skills ?? fm.inherit_skills),
@@ -97,6 +99,24 @@ function csvList(val, defaults) {
         return defaults;
     return parseCsvField(val) ?? [];
 }
+/**
+ * Partition the `tools:` CSV into the built-in tool allowlist and raw `ext:` selectors.
+ * `*` (and the case-insensitive alias `all`, for `tools: all`) expands to all
+ * built-ins; plain entries are built-in names; `ext:` entries are extension-tool
+ * selectors parsed later by the runner. omitted → all built-ins, no selectors.
+ * `tools:` present with only `ext:` entries → zero built-ins (use `*`).
+ */
+function parseToolsField(val) {
+    const entries = csvList(val, BUILTIN_TOOL_NAMES);
+    const isWildcard = (e) => e === "*" || e.toLowerCase() === "all";
+    const hasWildcard = entries.some(isWildcard);
+    const plain = entries.filter(e => !isWildcard(e) && !e.startsWith("ext:"));
+    const extEntries = entries.filter(e => e.startsWith("ext:"));
+    return {
+        builtinToolNames: hasWildcard ? [...new Set([...BUILTIN_TOOL_NAMES, ...plain])] : plain,
+        extSelectors: extEntries.length > 0 ? extEntries : undefined,
+    };
+}
 /**
  * Parse an optional comma-separated list field.
  * omitted → undefined; "none"/empty → undefined; csv → listed items.