@tintinweb/pi-subagents 0.10.1 → 0.10.3

package/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.3] - 2026-06-12
+
+### Added
+- **`SpawnOptions.cwd` — spawn a subagent in a different working directory** ([#96](https://github.com/tintinweb/pi-subagents/issues/96) — thanks [@madeleineostoja](https://github.com/madeleineostoja)). For RPC/programmatic callers (not exposed on the `Agent` tool — the LLM-visible surface is unchanged). The agent's tools operate in the target directory and the prompt's environment block describes it, but **`.pi` config keeps loading from the parent session's project** (new `RunOptions.configCwd` split): the target's `.pi` extensions never execute, and its agents/skills/settings/memory are not picked up — spawning into an untrusted directory sends a worker there with the parent's toolbox, rather than "opening pi there." Composes with `isolation: "worktree"`: the worktree is created *from* the target directory's repo, the agent works at the equivalent subdirectory inside the copy (a monorepo-package cwd keeps its scoping instead of silently widening to the repo root — new `WorktreeInfo.workPath`), and the resulting `pi-agent-*` branch lands in that repo, with the completion message naming it so the orchestrator merges in the right place. Validation is strict, typed, and early — non-strings, relative paths, nonexistent paths, and files all throw curated errors at `spawn()` (before queueing) and are re-checked at queue drain, surfacing as RPC error envelopes (`null` is treated as unset). On dispose, worktree registrations are pruned in every repo that received one; only a hard crash can leave a stale entry (then: `git worktree prune` in the target repo).
+
+## [0.10.2] - 2026-06-10
+
+### Added
+- **`exclude_extensions:` agent frontmatter — extension denylist for subagents** ([#94](https://github.com/tintinweb/pi-subagents/issues/94) — thanks [@ramhaidar](https://github.com/ramhaidar)). Applied after the `extensions:` include set; exclude wins, including over `tools: ext:` selectors (an excluded extension never loads, so its `ext:` reference becomes the usual orphan warning). The key use case: `extensions: true` + `exclude_extensions: pi-notify` — all extensions except a noisy one, without hand-maintaining an allowlist. Plain canonical names only (case-insensitive); paths, `*`, and unmatched names fire `extension-error:…` warnings (warn-not-abort, as with `extensions:` mismatches); `extensions: false` + an exclude warns that the exclude has no effect. **Not a sandbox:** excluded extensions' factory code still executes once during loading — exclusion suppresses handler binding and tool registration, not load-time side effects. The negation syntax `extensions: ["*", "!name"]` was deliberately rejected: an unquoted `!name` is a YAML tag and silently mis-parses.
+- **`toolDescriptionMode` setting — opt-in compact Agent tool description** ([#91](https://github.com/tintinweb/pi-subagents/issues/91) — thanks [@tiberiuichim](https://github.com/tiberiuichim)). The full Claude Code-style description costs ~1,400 tokens with the default agents and grows with each custom agent (the type list embeds full agent descriptions) — significant for small/local models. `toolDescriptionMode: "compact"` (via `/agents → Settings → Tool description` or `subagents.json`) swaps in a ~75% smaller description: one-line type list (first sentence of each agent description), terse usage notes, per-option details left to the parameter descriptions. Default `"full"` is byte-identical to before — the rich description's guardrails are deliberately load-bearing and stay the default. A third mode, `"custom"`, registers a user-authored description from `<cwd>/.pi/agent-tool-description.md` (project) or `<agentDir>/agent-tool-description.md` (global; project wins), with `{{placeholder}}` substitution keeping the dynamic parts live — `{{typeList}}`, `{{compactTypeList}}`, `{{agentDir}}`, `{{scheduleGuideline}}` — so a hand-written description can't drift out of sync with the registered agents (the advertised-vs-spawnable staleness [#92](https://github.com/tintinweb/pi-subagents/issues/92) just fixed). Unknown placeholders are left verbatim with a stderr warning; a missing/empty file falls back to `"full"`. Only the prose is customizable — the parameter schema stays code-owned. A ready-made starting point ships at `examples/agent-tool-description.md`, reproducing the full description exactly (CI-enforced byte-identical, so the example can't go stale). Like `schedulingEnabled`, the mode is read at tool registration — changing it applies on the next pi session. The issue's original ask (move the description to a skill) isn't possible in pi: tools must register their description in the tool schema for the model to call them; skills are lazily-loaded instructions, not tool registrations.
+
+### Fixed
+- **Conversation viewer honors custom `tui.select.*` keybindings** ([#99](https://github.com/tintinweb/pi-subagents/issues/99) — thanks [@owenniles](https://github.com/owenniles)). The viewer hardcoded its scroll keys and discarded the `KeybindingsManager` pi injects into `ctx.ui.custom()`, so user bindings (e.g. emacs-style `ctrl+p`/`ctrl+n` on `tui.select.up`/`down`) worked in pi core selectors but not here. Scrolling now resolves through `tui.select.up`/`down`/`pageUp`/`pageDown`; the viewer-specific `k`/`j` and `shift+arrow` aliases still work alongside, and behavior without custom bindings is unchanged (the `tui.select.*` defaults are the previously hardcoded keys).
+
 ## [0.10.1] - 2026-06-10
 
 ### Added

package/README.md

@@ -196,6 +196,7 @@ All fields are optional — sensible defaults for everything.
 | `display_name` | — | Display name for UI (e.g. widget, agent list) |
 | `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 |
+| `exclude_extensions` | — | Extension denylist applied after `extensions:` — exclude wins. Plain names only (case-insensitive), no paths or `*`. Useful with `extensions: true` to drop one extension (e.g. `pi-notify`) |
 | `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 |
@@ -227,6 +228,8 @@ extensions: false                 # no extensions load
 extensions: [mcp]                 # only mcp loads
 extensions: ["*", "/abs/foo.ts"]  # all defaults plus one path-loaded extension
 
+exclude_extensions: pi-notify     # everything except pi-notify (with extensions: true)
+
 # Specialist: load one extension, expose only one of its tools, keep built-ins
 extensions: [mcp]
 tools: "*, ext:mcp/search"
@@ -240,6 +243,8 @@ A few rules the examples don't make obvious:
 - 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.
+- `exclude_extensions:` wins over `extensions:` and over `ext:` selectors — an excluded extension never loads and a `tools: ext:` entry can't pull it back. Plain names only (no paths, no `*`); a name matching nothing fires an `extension-error:…` warning.
+- `exclude_extensions:` is **not a sandbox**: excluded extensions' factory code still executes once during loading — exclusion suppresses their handlers and tools, not their load-time side effects. Don't rely on it to contain an untrusted extension.
 - Array and string forms are equivalent: `[a, b]` == `"a, b"`.
 
 ## Tools
@@ -365,7 +370,7 @@ When on, each subagent spawn's effective model is validated against pi's own `en
 
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, default join mode, scheduling on/off, scope models on/off, disable defaults on/off) persist across pi restarts. Two files, merged on load:
+Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, default join mode, scheduling on/off, scope models on/off, disable defaults on/off, tool description full/compact/custom) persist across pi restarts. Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults. Edit by hand; the `/agents` menu never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides. Written by `/agents` → Settings.
@@ -374,6 +379,21 @@ Runtime tuning values set via `/agents` → Settings (max concurrency, default m
 
 **Disable defaults** (`disableDefaultAgents`, default `false`): when on, the three built-in agents (general-purpose, Explore, Plan) are not registered — only your `.pi/agents/*.md` agents are advertised and spawnable. User-defined agents are unaffected, including ones that override a default by name. The Agent tool's type list updates on the next pi session (the tool schema is registered at startup).
 
+**Tool description** (`toolDescriptionMode`, default `"full"`): which Agent tool description the LLM sees. `"full"` is the rich Claude Code-style prompt (~1,400 tokens with the default agents); `"compact"` is ~75% smaller — one-line agent type list, terse usage notes — for small/local models where tool-spec tokens are expensive. Per-option details stay in the parameter descriptions in every mode (the parameter schema is never customizable). Applies on the next pi session.
+
+`"custom"` registers your own description from `<cwd>/.pi/agent-tool-description.md` (project) or `<agentDir>/agent-tool-description.md` (global; project wins). The file is read once at tool registration, so edits also apply on the next pi session. Dynamic parts stay live via placeholders — a static agent list would go stale the moment you add a custom agent:
+
+```markdown
+Launch an autonomous agent. Available types:
+{{typeList}}
+
+Custom agents live in .pi/agents/ or {{agentDir}}/agents/.
+```
+
+Placeholders: `{{typeList}}` (full per-agent descriptions), `{{compactTypeList}}` (first sentence each), `{{agentDir}}`, `{{scheduleGuideline}}` (expands with its own leading newline + `- ` bullet when scheduling is on — place it directly after your last rule line; empty when scheduling is off). Unknown placeholders are left verbatim with a stderr warning; a missing or empty file falls back to `"full"` with a warning. Note the usual trust umbrella: a project-level file shapes the orchestrator's prompt, same as project agents and extensions do.
+
+**Starting point:** copy [`examples/agent-tool-description.md`](examples/agent-tool-description.md) — it reproduces the default full description exactly (a CI test keeps it in sync), so you can trim from a known-good baseline instead of writing from scratch.
+
 **Example — global defaults for a beefy machine:**
 
 ```bash
@@ -463,6 +483,8 @@ pi.events.emit("subagents:rpc:spawn", {
 
 `options.model` accepts either a `Model` object (e.g. `ctx.model`) or a `"provider/modelId"` string — strings are resolved against `ctx.modelRegistry` at the RPC boundary, so cross-extension callers can forward serializable values without losing auth context.
 
+`options.cwd` (absolute path to an existing directory — anything else returns an error envelope; `null` means unset) runs the agent in a different working directory than the parent session. Its tools operate there and the prompt's environment block describes it, but **`.pi` config still loads from the parent session's project** — the target directory's `.pi` extensions never execute, and its agents/skills/settings are not picked up. Combined with `isolation: "worktree"`, the worktree is created *from* the target directory's repo, the agent works at the equivalent subdirectory inside the copy (a monorepo-package cwd stays scoped to that package), and the resulting `pi-agent-*` branch lands in that repo — the completion message names it. On session end, worktree registrations are pruned in every repo that received one; only a hard crash can leave a stale entry (then: `git worktree prune` in the target repo). Agents with `memory:` keep reading/writing the parent project's memory.
+
 ### Stop
 
 Stop a running agent by ID:

package/dist/agent-manager.d.ts

@@ -32,6 +32,15 @@ interface SpawnOptions {
     bypassQueue?: boolean;
     /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
     isolation?: IsolationMode;
+    /**
+     * Working directory for the agent (absolute path). Default: parent session
+     * cwd. The agent's tools operate here, but .pi config (extensions, skills,
+     * settings, memory) still loads from the parent session's project — the
+     * target directory's `.pi` extensions never execute. With isolation:
+     * "worktree", the worktree is created FROM this directory and the result
+     * branch lands in that repo.
+     */
+    cwd?: string;
     /** Resolved invocation snapshot captured for UI display. */
     invocation?: AgentInvocation;
     /** Parent abort signal — when aborted, the subagent is also stopped. */
@@ -60,6 +69,9 @@ export declare class AgentManager {
     private onStart?;
     private onCompact?;
     private maxConcurrent;
+    /** Base repos worktrees were created from — so dispose() can prune them all,
+     *  not just the parent repo (caller-supplied cwd can target other repos). */
+    private worktreeRepos;
     /** Queue of background agents waiting to start. */
     private queue;
     /** Number of currently running background agents. */

package/dist/agent-manager.js

@@ -6,11 +6,36 @@
  * Foreground agents bypass the queue (they block the parent anyway).
  */
 import { randomUUID } from "node:crypto";
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import { resumeAgent, runAgent } from "./agent-runner.js";
 import { addUsage } from "./usage.js";
 import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
+/**
+ * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
+ * (parent cwd). Anything else must be an absolute path to an existing
+ * directory — curated errors instead of TypeErrors from path/fs internals
+ * (RPC callers send arbitrary JSON: null, numbers, file paths).
+ */
+function assertValidSpawnCwd(cwd) {
+    if (cwd == null)
+        return;
+    if (typeof cwd !== "string" || !isAbsolute(cwd)) {
+        throw new Error(`SpawnOptions.cwd must be an absolute path: "${String(cwd)}"`);
+    }
+    let isDirectory = false;
+    try {
+        isDirectory = statSync(cwd).isDirectory();
+    }
+    catch {
+        throw new Error(`SpawnOptions.cwd does not exist: "${cwd}"`);
+    }
+    if (!isDirectory) {
+        throw new Error(`SpawnOptions.cwd is not a directory: "${cwd}"`);
+    }
+}
 export class AgentManager {
     agents = new Map();
     cleanupInterval;
@@ -18,6 +43,9 @@ export class AgentManager {
     onStart;
     onCompact;
     maxConcurrent;
+    /** Base repos worktrees were created from — so dispose() can prune them all,
+     *  not just the parent repo (caller-supplied cwd can target other repos). */
+    worktreeRepos = new Set();
     /** Queue of background agents waiting to start. */
     queue = [];
     /** Number of currently running background agents. */
@@ -45,6 +73,10 @@ export class AgentManager {
      * If the concurrency limit is reached, the agent is queued.
      */
     spawn(pi, ctx, type, prompt, options) {
+        // Validate before the queue branch — a queued spawn should fail at the
+        // call, not minutes later at drain. Throw (not warn): programmatic callers
+        // can fix and retry; the RPC layer converts throws into error envelopes.
+        assertValidSpawnCwd(options.cwd);
         const id = randomUUID().slice(0, 17);
         const abortController = new AbortController();
         const record = {
@@ -79,18 +111,33 @@ export class AgentManager {
     }
     /** Actually start an agent (called immediately or from queue drain). */
     startAgent(id, record, { pi, ctx, type, prompt, options }) {
+        // Re-validate a caller-supplied cwd: queued spawns can start minutes after
+        // spawn()'s check, and the directory may be gone by then (TOCTOU). Same
+        // curated errors; drainQueue parks a throw on the record as an error.
+        assertValidSpawnCwd(options.cwd);
+        // Single resolution point for the caller-supplied cwd — the worktree base
+        // repo and both cleanup calls below MUST agree on this value forever.
+        const customCwd = options.cwd ?? undefined; // null (RPC "unset") → undefined
+        const baseCwd = customCwd ?? ctx.cwd;
         // Worktree isolation: try to create a temporary git worktree. Strict —
         // fail loud if not possible (no silent fallback to main tree). Done
         // BEFORE state mutation so a throw doesn't leave the record half-running.
         let worktreeCwd;
         if (options.isolation === "worktree") {
-            const wt = createWorktree(ctx.cwd, id);
+            const wt = createWorktree(baseCwd, id);
             if (!wt) {
                 throw new Error('Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
                     'Initialize git and commit at least once, or omit `isolation`.');
             }
             record.worktree = wt;
-            worktreeCwd = wt.path;
+            // workPath preserves subdirectory scoping for caller-supplied cwds: a
+            // cwd deep in a monorepo maps to the same subdir inside the copy, not
+            // the copied repo's root. Plain worktree spawns keep the historical
+            // behavior (agent at the copy's root) — moving them to workPath would
+            // also move .pi config discovery when the parent session sits in a repo
+            // subdirectory, silently dropping extensions/skills.
+            worktreeCwd = customCwd !== undefined ? wt.workPath : wt.path;
+            this.worktreeRepos.add(baseCwd);
         }
         record.status = "running";
         record.startedAt = Date.now();
@@ -113,7 +160,13 @@ export class AgentManager {
             isolated: options.isolated,
             inheritContext: options.inheritContext,
             thinkingLevel: options.thinkingLevel,
-            cwd: worktreeCwd,
+            // Worktree wins for the working dir (the agent must run in the copy —
+            // which, with a custom cwd, was created from that target). Config stays
+            // with the parent project when a caller-supplied cwd is in play; it must
+            // stay undefined otherwise so plain worktree runs keep resolving config
+            // (incl. relative extension paths and memory) inside the worktree copy.
+            cwd: worktreeCwd ?? customCwd,
+            configCwd: customCwd !== undefined ? ctx.cwd : undefined,
             signal: record.abortController.signal,
             onToolActivity: (activity) => {
                 if (activity.type === "end")
@@ -162,11 +215,14 @@ export class AgentManager {
             }
             // Clean up worktree if used
             if (record.worktree) {
-                const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+                const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
                 record.worktreeResult = wtResult;
                 if (wtResult.hasChanges && wtResult.branch) {
+                    // With a caller-supplied cwd the branch lives in THAT repo, not the
+                    // parent session's — say so, or the orchestrator merges in the wrong repo.
+                    const repoNote = customCwd !== undefined ? ` in \`${baseCwd}\`` : "";
                     record.result = (record.result ?? "") +
-                        `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+                        `\n\n---\nChanges saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git merge ${wtResult.branch}\`${customCwd !== undefined ? ` (run in \`${baseCwd}\`)` : ""}`;
                 }
             }
             if (options.isBackground) {
@@ -198,7 +254,7 @@ export class AgentManager {
             // Best-effort worktree cleanup on error
             if (record.worktree) {
                 try {
-                    const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+                    const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
                     record.worktreeResult = wtResult;
                 }
                 catch { /* ignore cleanup errors */ }
@@ -387,5 +443,13 @@ export class AgentManager {
             pruneWorktrees(process.cwd());
         }
         catch { /* ignore */ }
+        // Also prune repos that caller-supplied cwds created worktrees in — a clean
+        // exit with in-flight agents would otherwise leave stale registrations there.
+        for (const repo of this.worktreeRepos) {
+            try {
+                pruneWorktrees(repo);
+            }
+            catch { /* ignore */ }
+        }
     }
 }

package/dist/agent-runner.d.ts

@@ -82,6 +82,20 @@ export interface RunOptions {
     thinkingLevel?: ThinkingLevel;
     /** Override working directory (e.g. for worktree isolation). */
     cwd?: string;
+    /**
+     * Where .pi config is discovered (project extensions, skills, pi settings,
+     * agent memory). Default: same as the working directory. The manager sets
+     * this to the parent session's cwd when `SpawnOptions.cwd` points the
+     * working directory elsewhere — the agent works *there* but carries the
+     * parent project's config (the target's `.pi` extensions never execute).
+     *
+     * WARNING for future callers: if you pass `cwd` pointing at a directory the
+     * user didn't open, you almost certainly must pass `configCwd` too —
+     * omitting it makes the target's `.pi` extensions execute in this process.
+     * (Worktree isolation is the one intentional exception: its copy IS the
+     * parent's repo, so config resolving inside it is correct.)
+     */
+    configCwd?: string;
     /** Called on tool start/end with activity info. */
     onToolActivity?: (activity: ToolActivity) => void;
     /** Called on streaming text deltas from the assistant response. */

package/dist/agent-runner.js

@@ -199,6 +199,9 @@ export async function runAgent(ctx, type, prompt, options) {
     const agentConfig = getAgentConfig(type);
     // Resolve working directory: worktree override > parent cwd
     const effectiveCwd = options.cwd ?? ctx.cwd;
+    // Filesystem work happens in effectiveCwd; config discovery in configCwd.
+    // They differ only for SpawnOptions.cwd spawns (config stays with the parent).
+    const configCwd = options.configCwd ?? effectiveCwd;
     const env = await detectEnv(options.pi, effectiveCwd);
     // Get parent system prompt for append-mode agents
     const parentSystemPrompt = ctx.getSystemPrompt();
@@ -206,10 +209,13 @@ export async function runAgent(ctx, type, prompt, options) {
     const extras = {};
     // Resolve extensions/skills: isolated overrides to false
     const extensions = options.isolated ? false : config.extensions;
+    // Nulling excludes under isolated also suppresses the orphaned-exclude warning —
+    // isolation is an intentional override, not a misconfiguration.
+    const excludeExtensions = options.isolated ? undefined : config.excludeExtensions;
     const skills = options.isolated ? false : config.skills;
     // Skill preloading: when skills is string[], preload their content into prompt
     if (Array.isArray(skills)) {
-        const loaded = preloadSkills(skills, effectiveCwd);
+        const loaded = preloadSkills(skills, configCwd);
         if (loaded.length > 0) {
             extras.skillBlocks = loaded;
         }
@@ -227,14 +233,14 @@ export async function runAgent(ctx, type, prompt, options) {
             const extraNames = getMemoryToolNames(existingNames);
             if (extraNames.length > 0)
                 toolNames = [...toolNames, ...extraNames];
-            extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
+            extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, configCwd);
         }
         else {
             // Read-only memory: only add read tool name, use read-only prompt
             const extraNames = getReadOnlyMemoryToolNames(existingNames);
             if (extraNames.length > 0)
                 toolNames = [...toolNames, ...extraNames];
-            extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
+            extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, configCwd);
         }
     }
     // Build system prompt from agent config
@@ -274,22 +280,40 @@ export async function runAgent(ctx, type, prompt, options) {
     const { extNames, narrowing } = parseExtSelectors(options.isolated ? [] : (agentConfig?.extSelectors ?? []));
     const noExtensions = extensions === false;
     const extensionsSpec = Array.isArray(extensions)
-        ? parseExtensionsSpec(extensions, effectiveCwd)
+        ? parseExtensionsSpec(extensions, configCwd)
         : 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`).
+    // `exclude_extensions:` is a denylist applied AFTER the include set — exclude wins.
+    // Plain canonical names only (case-insensitive). Note: excluded extensions'
+    // factories still run once during reload() (see comment above) — exclusion
+    // suppresses handler binding and tool registration; it is not a sandbox.
+    const excludeNames = new Set((excludeExtensions ?? []).map((n) => n.toLowerCase()));
+    const hasExcludes = excludeNames.size > 0;
+    // The override filters loaded extensions down to `keepNames` minus `excludeNames`.
+    // It's only needed when we're neither loading everything without excludes
+    // (`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
+    // Pre-filter discovered set, captured by the override — the exclude-typo warning
+    // must compare against this, not the surviving set (absence from survivors is
+    // an exclude *succeeding*).
+    let discoveredNames;
+    const extensionsOverride = noExtensions || (loadAll && !hasExcludes)
         ? undefined
-        : (base) => ({
-            ...base,
-            extensions: base.extensions.filter((e) => keepNames.has(extensionCanonicalName(e.path))),
-        });
+        : (base) => {
+            discoveredNames = new Set(base.extensions.map((e) => extensionCanonicalName(e.path)));
+            return {
+                ...base,
+                extensions: base.extensions.filter((e) => {
+                    const name = extensionCanonicalName(e.path);
+                    if (excludeNames.has(name))
+                        return false; // exclude wins
+                    return loadAll || keepNames.has(name);
+                }),
+            };
+        };
     const loader = new DefaultResourceLoader({
-        cwd: effectiveCwd,
+        cwd: configCwd,
         agentDir,
         noExtensions,
         additionalExtensionPaths,
@@ -325,13 +349,36 @@ export async function runAgent(ctx, type, prompt, options) {
     //   - `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.
+    // An exclude_extensions: alongside extensions: false is contradictory — nothing
+    // loads, so there is nothing to exclude.
+    if (hasExcludes && noExtensions) {
+        options.onToolActivity?.({
+            type: "end",
+            toolName: `extension-error:exclude_extensions has no effect for agent "${type}" — extensions: false loads nothing`,
+        });
+    }
+    // Exclude typo check: compares against the PRE-filter discovered set (an excluded
+    // name absent from the surviving set is the exclude working as intended). Also
+    // flags path-like and "*" entries — excludes are plain names only.
+    if (hasExcludes && discoveredNames) {
+        for (const name of excludeNames) {
+            if (!discoveredNames.has(name)) {
+                options.onToolActivity?.({
+                    type: "end",
+                    toolName: `extension-error:exclude_extensions: "${name}" for agent "${type}" did not match any discovered extension`,
+                });
+            }
+        }
+    }
     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`,
+                    toolName: excludeNames.has(name)
+                        ? `extension-error:extension "${name}" is in both extensions: and exclude_extensions: for agent "${type}" — exclude wins`
+                        : `extension-error:extension "${name}" requested by agent "${type}" was not loaded`,
                 });
             }
         }
@@ -339,7 +386,7 @@ export async function runAgent(ctx, type, prompt, options) {
             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:)`,
+                    toolName: `extension-error:ext:${name} referenced by agent "${type}" but extension "${name}" is not loaded (check extensions:/exclude_extensions:)`,
                 });
             }
         }
@@ -394,7 +441,7 @@ export async function runAgent(ctx, type, prompt, options) {
         cwd: effectiveCwd,
         agentDir,
         sessionManager: SessionManager.inMemory(effectiveCwd),
-        settingsManager: SettingsManager.create(effectiveCwd, agentDir),
+        settingsManager: SettingsManager.create(configCwd, agentDir),
         modelRegistry: ctx.modelRegistry,
         model,
         tools: allowedTools,

package/dist/agent-types.d.ts

@@ -54,6 +54,7 @@ export declare function getConfig(type: string): {
     description: string;
     builtinToolNames: string[];
     extensions: true | string[] | false;
+    excludeExtensions?: string[];
     skills: true | string[] | false;
     promptMode: "replace" | "append";
 };

package/dist/agent-types.js

@@ -127,6 +127,7 @@ export function getConfig(type) {
             description: config.description,
             builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
             extensions: config.extensions,
+            excludeExtensions: config.excludeExtensions,
             skills: config.skills,
             promptMode: config.promptMode,
         };
@@ -139,6 +140,7 @@ export function getConfig(type) {
             description: gp.description,
             builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
             extensions: gp.extensions,
+            excludeExtensions: gp.excludeExtensions,
             skills: gp.skills,
             promptMode: gp.promptMode,
         };

package/dist/custom-agents.js

@@ -52,6 +52,7 @@ function loadFromDir(dir, agents, source) {
             extSelectors,
             disallowedTools: csvListOptional(fm.disallowed_tools),
             extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
+            excludeExtensions: csvListOptional(fm.exclude_extensions),
             skills: inheritField(fm.skills ?? fm.inherit_skills),
             model: str(fm.model),
             thinking: str(fm.thinking),