@selesai/code 0.13.40 → 0.14.3

package/dist/core/resource-loader.js

@@ -1,5 +1,7 @@
+import { stripBom } from "../utils/text.js";
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve, sep } from "node:path";
+import { detectCapabilities, getTerminalColorMode } from "@earendil-works/pi-tui";
 import chalk from "chalk";
 import { CONFIG_DIR_NAME } from "../config.js";
 import { loadThemeFromPath } from "../modes/interactive/theme/theme.js";
@@ -13,15 +15,97 @@ import { loadPromptTemplates } from "./prompt-templates.js";
 import { SettingsManager } from "./settings-manager.js";
 import { loadAgents } from "./agents.js";
 import { loadSkills } from "./skills.js";
-import { createSourceInfo } from "./source-info.js";
+import { BUILTIN_PATH_PREFIX, createSourceInfo, getSyntheticPathSource, isSyntheticPath, } from "./source-info.js";
 import { resetTimings } from "./timings.js";
+const HOST_PROVIDED_EXTENSION_PACKAGES = new Set([
+    "@earendil-works/pi-agent-core",
+    "@earendil-works/pi-ai",
+    "@earendil-works/pi-coding-agent",
+    "@earendil-works/pi-tui",
+    "@mariozechner/pi-agent-core",
+    "@mariozechner/pi-ai",
+    "@mariozechner/pi-coding-agent",
+    "@mariozechner/pi-tui",
+    "@sinclair/typebox",
+    "typebox",
+]);
+function collectExtensionPackageWarnings(extensionPaths, metadataByPath) {
+    const warnings = [];
+    const packageRoots = new Set(extensionPaths
+        .map((extensionPath) => metadataByPath.get(extensionPath)?.packageRoot)
+        .filter((packageRoot) => packageRoot !== undefined));
+    for (const packageRoot of packageRoots) {
+        const packageJsonPath = join(packageRoot, "package.json");
+        if (!existsSync(packageJsonPath))
+            continue;
+        const manifest = JSON.parse(stripBom(readFileSync(packageJsonPath, "utf-8")));
+        if (typeof manifest.dependencies !== "object" ||
+            manifest.dependencies === null ||
+            Array.isArray(manifest.dependencies)) {
+            continue;
+        }
+        const hostDependencies = Object.keys(manifest.dependencies)
+            .filter((name) => HOST_PROVIDED_EXTENSION_PACKAGES.has(name))
+            .sort();
+        if (hostDependencies.length === 0)
+            continue;
+        warnings.push({
+            path: packageJsonPath,
+            warning: `Host-provided extension packages must be declared in peerDependencies with a "*" range, not dependencies: ${hostDependencies.join(", ")}. Installed copies can bypass the extension loader and create duplicate runtime modules.`,
+        });
+    }
+    return warnings;
+}
+function mergeExtensionWarnings(result, warnings) {
+    result.warnings = [
+        ...new Map([...(result.warnings ?? []), ...warnings].map((warning) => [warning.path, warning])).values(),
+    ];
+}
+/** Built-in extensions supply the code of `builtin:<name>` extension paths (see `InlineExtension`). */
+export function isBuiltinExtension(input) {
+    return typeof input !== "function" && input.builtin === true;
+}
+/**
+ * Leave out replaceable extensions (see `InlineExtension`) that share a tool, command, or flag name
+ * with another extension. For example, a third-party MCP extension that registers `/mcp` replaces
+ * the built-in MCP extension instead of both connecting the same servers.
+ */
+function omitReplacedExtensions(extensions, warnings) {
+    const names = (extension) => [
+        ...[...extension.tools.keys()].map((name) => `tool:${name}`),
+        ...[...extension.commands.keys()].map((name) => `command:${name}`),
+        ...[...extension.flags.keys()].map((name) => `flag:${name}`),
+    ];
+    const taken = new Map(extensions
+        .filter((extension) => !extension.replaceable)
+        .flatMap((extension) => names(extension).map((name) => [name, extension])));
+    return extensions.filter((extension) => {
+        if (!extension.replaceable)
+            return true;
+        const replacement = names(extension)
+            .map((name) => ({ name, extension: taken.get(name) }))
+            .find((value) => value.extension !== undefined);
+        if (!replacement)
+            return true;
+        if (extension.path.startsWith(BUILTIN_PATH_PREFIX)) {
+            const builtinName = extension.path.slice(BUILTIN_PATH_PREFIX.length);
+            const [kind, rawName] = replacement.name.split(":", 2);
+            const registeredName = kind === "command" ? `/${rawName}` : kind === "flag" ? `--${rawName}` : rawName;
+            warnings?.push({
+                path: extension.path,
+                warning: `Extension ${replacement.extension.path} registers ${kind} \`${registeredName}\`, so built-in extension \`${builtinName}\` was not loaded. To use \`${builtinName}\`, run \`pi config\` and make sure it is enabled under Built-in extensions, then disable or remove the existing extension. We recommend only having one or the other loaded at a time.`,
+            });
+        }
+        return false;
+    });
+}
 function resolvePromptInput(input, description) {
     if (!input) {
         return undefined;
     }
     if (existsSync(input)) {
         try {
-            return readFileSync(input, "utf-8");
+            return stripBom(readFileSync(input, "utf-8"));
         }
         catch (error) {
             console.error(chalk.yellow(`Warning: Could not read ${description} file ${input}: ${error}`));
@@ -31,7 +115,7 @@ function resolvePromptInput(input, description) {
     return input;
 }
 function loadContextFileFromDir(dir) {
-    const candidates = ["AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
+    const candidates = ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
     for (const filename of candidates) {
         const filePath = join(dir, filename);
         if (existsSync(filePath)) {
@@ -41,7 +125,7 @@ function loadContextFileFromDir(dir) {
                 }
                 return {
                     path: filePath,
-                    content: readFileSync(filePath, "utf-8"),
+                    content: stripBom(readFileSync(filePath, "utf-8")),
                 };
             }
             catch (error) {
@@ -53,7 +137,7 @@ function loadContextFileFromDir(dir) {
 }
 /**
  * The main repo's context file that a nested linked worktree's own copy shadows: both
- * are the same tracked AGENTS.md/CLAUDE.md, so loading both loads it twice. Returns
+ * occupy the same logical repository scope, so loading both applies that context twice. Returns
  * undefined when nothing is shadowed, leaving normal ancestor inheritance alone.
  *
  * Returned canonicalized (realpath), because `git worktree add` writes the `.git`
@@ -120,7 +204,9 @@ export class DefaultResourceLoader {
     additionalPromptTemplatePaths;
     additionalThemePaths;
     extensionFactories;
+    builtinExtensions;
     noExtensions;
+    disabledBuiltinExtensions;
     noSkills;
     noAgents;
     noPromptTemplates;
@@ -166,18 +252,22 @@ export class DefaultResourceLoader {
         this.agentDir = resolvePath(options.agentDir);
         this.settingsManager = options.settingsManager ?? SettingsManager.create(this.cwd, this.agentDir);
         this.eventBus = options.eventBus ?? createEventBus();
+        const factories = options.extensionFactories ?? [];
+        this.extensionFactories = factories.filter((input) => !isBuiltinExtension(input));
+        this.builtinExtensions = new Map(factories.filter(isBuiltinExtension).map((input) => [input.name, input]));
         this.packageManager = new DefaultPackageManager({
             cwd: this.cwd,
             agentDir: this.agentDir,
             settingsManager: this.settingsManager,
+            builtinExtensions: [...this.builtinExtensions.keys()],
         });
         this.additionalExtensionPaths = options.additionalExtensionPaths ?? [];
         this.additionalSkillPaths = options.additionalSkillPaths ?? [];
         this.additionalAgentPaths = options.additionalAgentPaths ?? [];
         this.additionalPromptTemplatePaths = options.additionalPromptTemplatePaths ?? [];
         this.additionalThemePaths = options.additionalThemePaths ?? [];
-        this.extensionFactories = options.extensionFactories ?? [];
         this.noExtensions = options.noExtensions ?? false;
+        this.disabledBuiltinExtensions = new Set(options.disabledBuiltinExtensions);
         this.noSkills = options.noSkills ?? false;
         this.noAgents = options.noAgents ?? false;
         this.noPromptTemplates = options.noPromptTemplates ?? false;
@@ -299,6 +389,8 @@ export class DefaultResourceLoader {
         if (this.loaded) {
             clearExtensionCache();
         }
+        // The filter closes over the previous extension runtime (now stale); the reloaded extensions re-register theirs.
+        this.skillsIndexFilter = undefined;
         let preTrustExtensions;
         if (options?.resolveProjectTrust) {
             preTrustExtensions = await this.loadProjectTrustExtensions();
@@ -353,12 +445,13 @@ export class DefaultResourceLoader {
         const cliEnabledSkills = getEnabledPaths(cliExtensionPaths.skills);
         const cliEnabledPrompts = getEnabledPaths(cliExtensionPaths.prompts);
         const cliEnabledThemes = getEnabledPaths(cliExtensionPaths.themes);
-        const extensionPaths = this.noExtensions
-            ? cliEnabledExtensions
-            : this.mergePaths(cliEnabledExtensions, enabledExtensions);
+        const extensionPaths = (this.noExtensions ? cliEnabledExtensions : this.mergePaths(cliEnabledExtensions, enabledExtensions)).filter((path) => !path.startsWith(BUILTIN_PATH_PREFIX) ||
+            !this.disabledBuiltinExtensions.has(path.slice(BUILTIN_PATH_PREFIX.length)));
+        const packageWarnings = collectExtensionPackageWarnings(extensionPaths, metadataByPath);
         const extensionsResult = await this.loadFinalExtensionSet(extensionPaths, preTrustExtensions);
+        mergeExtensionWarnings(extensionsResult, packageWarnings);
         for (const p of this.additionalExtensionPaths) {
-            if (isLocalPath(p)) {
+            if (!isSyntheticPath(p) && isLocalPath(p)) {
                 const resolved = this.resolveResourcePath(p);
                 if (!existsSync(resolved)) {
                     extensionsResult.errors.push({ path: resolved, error: `Extension path does not exist: ${resolved}` });
@@ -458,53 +551,83 @@ export class DefaultResourceLoader {
         });
         const enabledExtensions = resolvedPaths.extensions.filter((r) => r.enabled).map((r) => r.path);
         const cliEnabledExtensions = cliExtensionPaths.extensions.filter((r) => r.enabled).map((r) => r.path);
-        const extensionPaths = this.noExtensions
-            ? cliEnabledExtensions
-            : this.mergePaths(cliEnabledExtensions, enabledExtensions);
+        // Built-in extensions wait for the final pass: project settings can disable them, and a loaded
+        // extension cannot be unloaded.
+        const extensionPaths = (this.noExtensions ? cliEnabledExtensions : this.mergePaths(cliEnabledExtensions, enabledExtensions)).filter((path) => !path.startsWith(BUILTIN_PATH_PREFIX));
+        const metadataByPath = new Map([...resolvedPaths.extensions, ...cliExtensionPaths.extensions].map((resource) => [
+            resource.path,
+            resource.metadata,
+        ]));
+        const packageWarnings = collectExtensionPackageWarnings(extensionPaths, metadataByPath);
         const extensionsResult = await loadExtensionsCached(extensionPaths, this.cwd, this.eventBus);
+        mergeExtensionWarnings(extensionsResult, packageWarnings);
         if (!options.includeInlineFactories) {
             return extensionsResult;
         }
         const inlineExtensions = await this.loadExtensionFactories(extensionsResult.runtime);
         extensionsResult.extensions.push(...inlineExtensions.extensions);
         extensionsResult.errors.push(...inlineExtensions.errors);
+        const replacementWarnings = [];
+        extensionsResult.extensions = omitReplacedExtensions(extensionsResult.extensions, replacementWarnings);
+        mergeExtensionWarnings(extensionsResult, replacementWarnings);
         return extensionsResult;
     }
     resolveExtensionLoadPath(path) {
-        return resolvePath(path, this.cwd, { normalizeUnicodeSpaces: true });
+        return isSyntheticPath(path) ? path : resolvePath(path, this.cwd, { normalizeUnicodeSpaces: true });
     }
-    async loadFinalExtensionSet(extensionPaths, preTrustExtensions) {
-        if (!preTrustExtensions) {
-            const extensionsResult = await loadExtensionsCached(extensionPaths, this.cwd, this.eventBus);
-            const inlineExtensions = await this.loadExtensionFactories(extensionsResult.runtime);
-            extensionsResult.extensions.push(...inlineExtensions.extensions);
-            extensionsResult.errors.push(...inlineExtensions.errors);
-            this.addExtensionConflictDiagnostics(extensionsResult);
-            return extensionsResult;
+    /** Load extension paths: files from disk and `builtin:<name>` paths from the built-in extensions. */
+    async loadExtensionPaths(paths, runtime) {
+        const isBuiltinPath = (path) => path.startsWith(BUILTIN_PATH_PREFIX);
+        const result = await loadExtensionsCached(paths.filter((path) => !isBuiltinPath(path)), this.cwd, this.eventBus, runtime);
+        for (const path of paths.filter(isBuiltinPath)) {
+            const builtin = this.builtinExtensions.get(path.slice(BUILTIN_PATH_PREFIX.length));
+            if (!builtin) {
+                result.errors.push({ path, error: `Unknown built-in extension: ${path}` });
+                continue;
+            }
+            try {
+                const extension = await loadExtensionFromFactory(builtin.factory, this.cwd, this.eventBus, result.runtime, path);
+                extension.hidden = true;
+                extension.replaceable = builtin.replaceable === true;
+                result.extensions.push(extension);
+            }
+            catch (error) {
+                result.errors.push({ path, error: error instanceof Error ? error.message : "failed to load extension" });
+            }
         }
-        const preloadedByPath = new Map(preTrustExtensions.extensions
+        return result;
+    }
+    async loadFinalExtensionSet(extensionPaths, preTrustExtensions) {
+        // Without a pre-trust pass nothing is preloaded, and inline extensions load here.
+        const preloaded = preTrustExtensions?.extensions ?? [];
+        const preloadedByPath = new Map(preloaded
             .filter((extension) => !extension.path.startsWith("<inline:"))
             .map((extension) => [extension.resolvedPath, extension]));
-        const failedPreloadPaths = new Set(preTrustExtensions.errors.map((error) => this.resolveExtensionLoadPath(error.path)));
+        const failedPreloadPaths = new Set((preTrustExtensions?.errors ?? []).map((error) => this.resolveExtensionLoadPath(error.path)));
         const remainingPaths = extensionPaths.filter((path) => {
             const resolvedPath = this.resolveExtensionLoadPath(path);
             return !preloadedByPath.has(resolvedPath) && !failedPreloadPaths.has(resolvedPath);
         });
-        const remainingExtensions = await loadExtensionsCached(remainingPaths, this.cwd, this.eventBus, preTrustExtensions.runtime);
+        const remainingExtensions = await this.loadExtensionPaths(remainingPaths, preTrustExtensions?.runtime);
         const loadedByPath = new Map(preloadedByPath);
         for (const extension of remainingExtensions.extensions) {
             loadedByPath.set(extension.resolvedPath, extension);
         }
-        const inlineExtensions = preTrustExtensions.extensions.filter((extension) => extension.path.startsWith("<inline:"));
+        const inlineExtensions = preTrustExtensions
+            ? { extensions: preloaded.filter((extension) => extension.path.startsWith("<inline:")), errors: [] }
+            : await this.loadExtensionFactories(remainingExtensions.runtime);
         const orderedExtensions = extensionPaths
             .map((path) => loadedByPath.get(this.resolveExtensionLoadPath(path)))
             .filter((extension) => extension !== undefined);
-        orderedExtensions.push(...inlineExtensions);
+        orderedExtensions.push(...inlineExtensions.extensions);
+        const replacementWarnings = [];
         const extensionsResult = {
-            extensions: orderedExtensions,
-            errors: [...preTrustExtensions.errors, ...remainingExtensions.errors],
-            runtime: preTrustExtensions.runtime,
+            extensions: omitReplacedExtensions(orderedExtensions, replacementWarnings),
+            errors: [...(preTrustExtensions?.errors ?? []), ...remainingExtensions.errors, ...inlineExtensions.errors],
+            warnings: [...(preTrustExtensions?.warnings ?? []), ...(remainingExtensions.warnings ?? [])],
+            runtime: remainingExtensions.runtime,
         };
+        mergeExtensionWarnings(extensionsResult, replacementWarnings);
         this.addExtensionConflictDiagnostics(extensionsResult);
         return extensionsResult;
     }
@@ -614,13 +737,17 @@ export class DefaultResourceLoader {
             promptsResult = { prompts: [], diagnostics: [] };
         }
         else {
-            const allPrompts = loadPromptTemplates({
+            const loaded = loadPromptTemplates({
                 cwd: this.cwd,
                 agentDir: this.agentDir,
                 promptPaths,
                 includeDefaults: false,
             });
-            promptsResult = this.dedupePrompts(allPrompts);
+            const deduped = this.dedupePrompts(loaded.templates);
+            promptsResult = {
+                prompts: deduped.prompts,
+                diagnostics: [...loaded.diagnostics, ...deduped.diagnostics],
+            };
         }
         const resolvedPrompts = this.promptsOverride ? this.promptsOverride(promptsResult) : promptsResult;
         this.prompts = resolvedPrompts.prompts.map((prompt) => ({
@@ -637,7 +764,12 @@ export class DefaultResourceLoader {
             themesResult = { themes: [], diagnostics: [] };
         }
         else {
-            const loaded = this.loadThemes(themePaths, false);
+            // Theme construction only needs trueColor, so skip the unrelated tmux hyperlink probe.
+            const colorMode = getTerminalColorMode({
+                ...detectCapabilities(() => false),
+                ...this.settingsManager.getTerminalCapabilityOverrides(),
+            });
+            const loaded = this.loadThemes(themePaths, false, colorMode);
             const deduped = this.dedupeThemes(loaded.themes);
             themesResult = { themes: deduped.themes, diagnostics: [...loaded.diagnostics, ...deduped.diagnostics] };
         }
@@ -692,7 +824,7 @@ export class DefaultResourceLoader {
         if (!resourcePath) {
             return undefined;
         }
-        if (resourcePath.startsWith("<")) {
+        if (isSyntheticPath(resourcePath)) {
             return this.getDefaultSourceInfoForPath(resourcePath);
         }
         const normalizedResourcePath = resolve(resourcePath);
@@ -721,10 +853,11 @@ export class DefaultResourceLoader {
         return undefined;
     }
     getDefaultSourceInfoForPath(filePath) {
-        if (filePath.startsWith("<") && filePath.endsWith(">")) {
+        const syntheticSource = getSyntheticPathSource(filePath);
+        if (syntheticSource) {
             return {
                 path: filePath,
-                source: filePath.slice(1, -1).split(":")[0] || "temporary",
+                source: syntheticSource,
                 scope: "temporary",
                 origin: "top-level",
             };
@@ -774,15 +907,15 @@ export class DefaultResourceLoader {
         return merged;
     }
     resolveResourcePath(p) {
-        return resolvePath(p, this.cwd, { trim: true });
+        return isSyntheticPath(p) ? p : resolvePath(p, this.cwd, { trim: true });
     }
-    loadThemes(paths, includeDefaults = true) {
+    loadThemes(paths, includeDefaults, colorMode) {
         const themes = [];
         const diagnostics = [];
         if (includeDefaults) {
             const defaultDirs = [join(this.agentDir, "themes"), join(this.cwd, CONFIG_DIR_NAME, "themes")];
             for (const dir of defaultDirs) {
-                this.loadThemesFromDir(dir, themes, diagnostics);
+                this.loadThemesFromDir(dir, themes, diagnostics, colorMode);
             }
         }
         for (const p of paths) {
@@ -794,10 +927,10 @@ export class DefaultResourceLoader {
             try {
                 const stats = statSync(resolved);
                 if (stats.isDirectory()) {
-                    this.loadThemesFromDir(resolved, themes, diagnostics);
+                    this.loadThemesFromDir(resolved, themes, diagnostics, colorMode);
                 }
                 else if (stats.isFile() && resolved.endsWith(".json")) {
-                    this.loadThemeFromFile(resolved, themes, diagnostics);
+                    this.loadThemeFromFile(resolved, themes, diagnostics, colorMode);
                 }
                 else {
                     diagnostics.push({ type: "warning", message: "theme path is not a json file", path: resolved });
@@ -810,7 +943,7 @@ export class DefaultResourceLoader {
         }
         return { themes, diagnostics };
     }
-    loadThemesFromDir(dir, themes, diagnostics) {
+    loadThemesFromDir(dir, themes, diagnostics, colorMode) {
         if (!existsSync(dir)) {
             return;
         }
@@ -832,7 +965,7 @@ export class DefaultResourceLoader {
                 if (!entry.name.endsWith(".json")) {
                     continue;
                 }
-                this.loadThemeFromFile(join(dir, entry.name), themes, diagnostics);
+                this.loadThemeFromFile(join(dir, entry.name), themes, diagnostics, colorMode);
             }
         }
         catch (error) {
@@ -840,9 +973,9 @@ export class DefaultResourceLoader {
             diagnostics.push({ type: "warning", message, path: dir });
         }
     }
-    loadThemeFromFile(filePath, themes, diagnostics) {
+    loadThemeFromFile(filePath, themes, diagnostics, colorMode) {
         try {
-            themes.push(loadThemeFromPath(filePath));
+            themes.push(loadThemeFromPath(filePath, colorMode));
         }
         catch (error) {
             const message = error instanceof Error ? error.message : "failed to load theme";
@@ -859,6 +992,7 @@ export class DefaultResourceLoader {
             try {
                 const extension = await loadExtensionFromFactory(factory, this.cwd, this.eventBus, runtime, extensionPath);
                 extension.hidden = isNamed && input.hidden;
+                extension.replaceable = isNamed && input.replaceable === true;
                 extensions.push(extension);
             }
             catch (error) {

package/dist/core/runtime-credentials.d.ts

@@ -1,4 +1,4 @@
-import type { Credential, CredentialInfo, CredentialStore } from "@earendil-works/pi-ai";
+import type { AuthOperationOptions, Credential, CredentialInfo, CredentialStore } from "@earendil-works/pi-ai";
 /** Async credential store overlay for non-persistent runtime API keys. */
 export declare class RuntimeCredentials implements CredentialStore {
     private readonly store;
@@ -9,8 +9,8 @@ export declare class RuntimeCredentials implements CredentialStore {
     hasRuntimeApiKey(providerId: string): boolean;
     getStore(): CredentialStore;
     reload(): void;
-    read(providerId: string): Promise<Credential | undefined>;
-    list(): Promise<readonly CredentialInfo[]>;
-    modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>): Promise<Credential | undefined>;
-    delete(providerId: string): Promise<void>;
+    read(providerId: string, options?: AuthOperationOptions): Promise<Credential | undefined>;
+    list(options?: AuthOperationOptions): Promise<readonly CredentialInfo[]>;
+    modify(providerId: string, fn: (current: Credential | undefined) => Promise<Credential | undefined>, options?: AuthOperationOptions): Promise<Credential | undefined>;
+    delete(providerId: string, options?: AuthOperationOptions): Promise<void>;
 }

package/dist/core/runtime-credentials.js

@@ -20,22 +20,25 @@ export class RuntimeCredentials {
     reload() {
         this.store.reload?.();
     }
-    async read(providerId) {
+    async read(providerId, options) {
+        options?.signal?.throwIfAborted();
         const override = this.overrides.get(providerId);
-        return override ? { type: "api_key", key: override } : this.store.read(providerId);
+        return override ? { type: "api_key", key: override } : this.store.read(providerId, options);
     }
-    async list() {
-        const entries = new Map((await this.store.list()).map((entry) => [entry.providerId, entry]));
+    async list(options) {
+        const entries = new Map((await this.store.list(options)).map((entry) => [entry.providerId, entry]));
+        options?.signal?.throwIfAborted();
         for (const providerId of this.overrides.keys()) {
             entries.set(providerId, { providerId, type: "api_key" });
         }
         return [...entries.values()];
     }
-    modify(providerId, fn) {
-        return this.store.modify(providerId, fn);
+    modify(providerId, fn, options) {
+        return this.store.modify(providerId, fn, options);
     }
-    async delete(providerId) {
+    async delete(providerId, options) {
+        options?.signal?.throwIfAborted();
+        await this.store.delete(providerId, options);
         this.overrides.delete(providerId);
-        await this.store.delete(providerId);
     }
 }

package/dist/core/sdk.d.ts

@@ -32,16 +32,25 @@ export interface CreateAgentSessionOptions {
      */
     noTools?: "all" | "builtin";
     /**
-     * Optional allowlist of tool names.
+     * Optional allowlist of tool names or patterns, where `*` matches any characters.
      *
-     * When omitted, pi uses the `defaultTools` setting for the initial built-in
+     * When omitted, pi uses the resolved `defaultTools` setting for the initial
      * selection when configured. Otherwise it enables the default built-in tools
-     * (read, bash, edit, write, grep, find, ls). Extension/custom tools are inactive by default;
-     * `noTools: "builtin"` enables them instead. When provided, only the listed
-     * tool names are enabled.
+     * (read, bash, edit, write, grep, find, ls). Extension/custom tools use their
+     * declared exposure/defaultActive; `noTools: "builtin"` enables extension/custom tools. When provided, only matching tools are
+     * enabled. MCP tools stay registered for codemode and tool search unless an
+     * entry starts with `mcp__`; then only matching MCP tools are kept. An empty
+     * list, like `noTools: "all"`, disables MCP tools too.
+     *
+     * A list of only `+name` and `-name` entries is not an allowlist: it adds tools
+     * to or removes them from the default selection, like the `defaultTools` setting.
+     * These entries take exact names. Mixing them with plain entries throws.
      */
     tools?: string[];
-    /** Optional denylist of tool names to disable. Applies after `tools` when both are provided. */
+    /**
+     * Optional denylist of tool names or patterns to disable. Applies after `tools` when both are
+     * provided, MCP tools included.
+     */
     excludeTools?: string[];
     /** Custom tools to register (in addition to built-in tools). */
     customTools?: ToolDefinition[];
@@ -68,7 +77,7 @@ export type { ExtensionAPI, ExtensionCommandContext, ExtensionContext, Extension
 export type { PromptTemplate } from "./prompt-templates.ts";
 export type { Skill } from "./skills.ts";
 export type { Tool } from "./tools/index.ts";
-export { withFileMutationQueue, createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createPowerShellTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, };
+export { withFileMutationQueue, createCodingTools, createReadOnlyTools, createReadTool, createBashTool, createEditTool, createWriteTool, createGrepTool, createFindTool, createLsTool, createPowerShellTool, };
 /**
  * Create an AgentSession with the specified options.
  *