@selesai/code 0.8.6 → 0.8.8

package/CHANGELOG.md

@@ -2,7 +2,37 @@
 
 All notable changes to `@selesai/code` will be documented in this file.
 
-## [Unreleased]
+## [0.8.8] - 2026-08-18
+
+### Added
+- **`--use-theme <name>` CLI flag.** Sets the initial interactive theme for a run; the fullscreen theme controller applies an invocation-level theme before settings load, so the flag wins until you change the theme in `/settings`.
+- **Transcript search highlighting.** The fullscreen TUI now highlights search matches live in the transcript, themeable via new optional `searchMatchBg`/`searchMatchText` colors (falling back to `selectedBg`/`text`).
+- **Fullscreen exit output option.** `/settings` gained a **Fullscreen exit output** entry: exiting fullscreen can print the transcript as before (`"transcript"`) or only a session resume hint (`"resume-hint"`) via the new `fullscreenExitOutput` setting.
+- **`defaultTools` setting.** Seeds the initial built-in tool selection for `createAgentSession`; when set, new sessions start with only the listed tools instead of the `read`/`bash`/`edit`/`write` default.
+- **`sendUserMessage` template expansion.** Extensions can pass `expandPromptTemplates: true` to dispatch extension commands and expand skill commands/prompt templates from a sent user message.
+- **Experimental strict tool sampling.** Under `PI_EXPERIMENTAL=1`, the built-in read/edit/write/bash tools request `json_schema` tool output with `strict: "prefer"`.
+
+### Changed
+- **Managed-tool downloads moved off the startup path.** The TUI mounts and stays responsive while `fd`/`rg` install; download progress and warnings are reported as chat status lines (with an `app.tools.expand` hint) instead of raw `console.log` output, and the interactive startup accepts input (with interrupt/exit/submit feedback) while it completes.
+- **Collapsed large tool output.** Tool components now preview only the first 10 lines with an inline `... (N more lines)` expand hint instead of dumping the whole block.
+- **Shared model-catalog refreshes.** Concurrent interactive all-catalog refreshes reuse one in-flight refresh while keeping each caller's cancellation independent, and refreshes are bounded by a short timeout.
+- **Runtime dependencies updated to Pi 0.84.2.** `@earendil-works/pi-ai`, `@earendil-works/pi-tui`, and `@earendil-works/pi-agent-core` moved to 0.84.2; `openAIResponses` model config gained an optional `supportsAdditionalTools` flag; `exportToHtml` accepts a `themeName` option.
+
+## [0.8.7] - 2026-08-17
+
+### Added
+- **Pi Subagents updated through upstream 0.50.0.** The bundled extension advances through upstream 0.49/0.50 (single-child `{ agent, task }` runs, per-tool-call `toolTimeoutMs` with config/env precedence, `debug.run` inspection, builtin role overrides with `tools: "inherit"`, resumable retained-child listings, indexed async result inboxes) with the Selesai fork layers on top: branding, `.selesai` config routing, `SELESAI_SUBAGENT*` env vars, declarative `chain`/`tasks`/`clarify` modes, workflow auto-relaunch wiring, and same-model retry for transient provider errors.
+- **`model-prompt-injector` extension.** Bundled and registered in the extensions manifest, it injects model-specific prompts into the system prompt when the active model matches a configured rule (provider/model globs, bare id/name patterns, first-match-wins, enabled toggle). Modes: `prepend`, `append`, or `replace`.
+- **Wire-level tool schema pruning.** `pruneToolDescriptions` (default `true`) strips every per-field `description` from tool input schemas before they reach the model, keeping one-line tool descriptions. Stripped schemas are memoized and never mutated; UI/docs definitions keep full descriptions; `keepParameterDescriptions` opts a tool out.
+- **Compact subagent tool description by default.** `toolDescriptionMode` now defaults to `"compact"` (~3.2 KB vs ~6.3 KB per model turn), and a missing/invalid custom description file falls back to compact.
+
+### Changed
+- **Slimmer default system prompt.** The always-on Pi-docs block shrank from 8 lines to 2 (paths only); docs are still read on demand when the user asks about pi.
+- **Bundled defaults** now set `pruneToolDescriptions: true`.
+- **Test coverage.** `src/extensions` (pi-* excluded) now enforces 100% stmt/branch/func/line coverage via vitest thresholds; `safeMaxTokens()` clamps missing/oversized context-window metadata to a sane default.
+
+### Fixed
+- **Subagent prompt-runtime suite passes inside subagent child environments.** The watchdog-lifecycle test now scrubs the steer env vars (`SELESAI_SUBAGENT_STEER_*`) before registering, so the steering inbox's extra `agent_end` handler cannot skew the handler count.
 
 ## [0.8.6] - 2026-08-15
 

package/dist/cli/args.d.ts

@@ -37,6 +37,7 @@ export interface Args {
     promptTemplates?: string[];
     noPromptTemplates?: boolean;
     themes?: string[];
+    useTheme?: string;
     noThemes?: boolean;
     noContextFiles?: boolean;
     listModels?: string | true;

package/dist/cli/args.js

@@ -142,6 +142,16 @@ export function parseArgs(args) {
         else if (arg === "--no-prompt-templates" || arg === "-np") {
             result.noPromptTemplates = true;
         }
+        else if (arg === "--use-theme") {
+            const themeName = args[i + 1];
+            if (themeName === undefined || themeName.startsWith("-")) {
+                result.diagnostics.push({ type: "error", message: "--use-theme requires a theme name" });
+            }
+            else {
+                result.useTheme = themeName;
+                i++;
+            }
+        }
         else if (arg === "--no-themes") {
             result.noThemes = true;
         }
@@ -272,6 +282,7 @@ ${chalk.bold("Options:")}
   --prompt-template <path>       Load a prompt template file or directory (can be used multiple times)
   --no-prompt-templates, -np     Disable prompt template discovery and loading
   --theme <path>                 Load a theme file or directory (can be used multiple times)
+  --use-theme <name[/name]>      Set the initial interactive theme for this run
   --no-themes                    Disable theme discovery and loading
   --no-context-files, -nc        Disable AGENTS.md and CLAUDE.md discovery and loading
   --export <file>                Export session file to HTML and exit

package/dist/cli/args.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli/args.test.js

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "vitest";
+import { parseArgs } from "./args.js";
+describe("parseArgs --use-theme", () => {
+    test("parses --use-theme with a theme name", () => {
+        const result = parseArgs(["--use-theme", "nord-border", "hello"]);
+        expect(result.useTheme).toBe("nord-border");
+        expect(result.messages).toEqual(["hello"]);
+    });
+    test("accepts light/dark slash form", () => {
+        const result = parseArgs(["--use-theme", "light/dark"]);
+        expect(result.useTheme).toBe("light/dark");
+    });
+    test("reports an error when --use-theme is missing a theme name", () => {
+        const result = parseArgs(["--use-theme"]);
+        expect(result.useTheme).toBeUndefined();
+        expect(result.diagnostics.some((d) => d.type === "error")).toBe(true);
+    });
+    test("reports an error when --use-theme precedes a flag", () => {
+        const result = parseArgs(["--use-theme", "--no-session"]);
+        expect(result.useTheme).toBeUndefined();
+        expect(result.noSession).toBe(true);
+        expect(result.diagnostics.some((d) => d.type === "error")).toBe(true);
+    });
+});

package/dist/core/agent-session.d.ts

@@ -423,6 +423,7 @@ export declare class AgentSession {
      */
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
+        expandPromptTemplates?: boolean;
     }): Promise<void>;
     /**
      * Clear all queued messages and return them.
@@ -634,7 +635,9 @@ export declare class AgentSession {
      * @param outputPath Optional output path (defaults to session directory)
      * @returns Path to exported file
      */
-    exportToHtml(outputPath?: string): Promise<string>;
+    exportToHtml(outputPath?: string, options?: {
+        themeName?: string;
+    }): Promise<string>;
     /**
      * Export the current session branch to a JSONL file.
      * Writes the session header followed by all entries on the current branch path.

package/dist/core/agent-session.js

@@ -35,7 +35,7 @@ import { CURRENT_SESSION_VERSION, getLatestCompactionEntry } from "./session-man
 import { createSyntheticSourceInfo } from "./source-info.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 import { createLocalBashOperations } from "./tools/bash.js";
-import { createAllToolDefinitions } from "./tools/index.js";
+import { createAllToolDefinitions, stripToolParameterDescriptions } from "./tools/index.js";
 import { createToolDefinitionFromAgentTool } from "./tools/tool-definition-wrapper.js";
 import { addUsageToTotals, createUsageTotals } from "./usage-totals.js";
 /** Parse consecutive skill blocks at the start of a user message. */
@@ -1133,7 +1133,7 @@ export class AgentSession {
         if (options?.deliverAs === "nextTurn") {
             this._pendingNextTurnMessages.push(appMessage);
         }
-        else if (this.isStreaming) {
+        else if (this.isStreaming && options?.triggerTurn !== false) {
             if (options?.deliverAs === "followUp") {
                 this.agent.followUp(appMessage);
             }
@@ -1180,9 +1180,9 @@ export class AgentSession {
             if (images.length === 0)
                 images = undefined;
         }
-        // Use prompt() with expandPromptTemplates: false to skip command handling and template expansion
+        // Use prompt() with expandPromptTemplates to control command handling and template expansion
         await this.prompt(text, {
-            expandPromptTemplates: false,
+            expandPromptTemplates: options?.expandPromptTemplates ?? false,
             streamingBehavior: options?.deliverAs,
             images,
             source: "extension",
@@ -2056,6 +2056,18 @@ export class AgentSession {
             toolRegistry.set(tool.name, tool);
         }
         this._toolRegistry = toolRegistry;
+        if (this.settingsManager.getPruneToolDescriptions()) {
+            const keepDescriptions = new Set();
+            for (const [name, entry] of definitionRegistry) {
+                if (entry.definition.keepParameterDescriptions)
+                    keepDescriptions.add(name);
+            }
+            for (const [name, tool] of toolRegistry) {
+                if (!keepDescriptions.has(name)) {
+                    toolRegistry.set(name, stripToolParameterDescriptions(tool));
+                }
+            }
+        }
         const nextActiveToolNames = (options?.activeToolNames ? [...options.activeToolNames] : [...previousActiveToolNames]).filter((name) => isAllowedTool(name));
         if (allowedToolNames) {
             for (const toolName of this._toolRegistry.keys()) {
@@ -2647,9 +2659,8 @@ export class AgentSession {
      * @param outputPath Optional output path (defaults to session directory)
      * @returns Path to exported file
      */
-    async exportToHtml(outputPath) {
-        const configuredThemeName = this.settingsManager.getTheme();
-        const themeName = configuredThemeName && getThemeByName(configuredThemeName) ? configuredThemeName : undefined;
+    async exportToHtml(outputPath, options = {}) {
+        const themeName = [options.themeName, this.settingsManager.getTheme()].find((candidate) => candidate !== undefined && getThemeByName(candidate) !== undefined);
         // Create tool renderer if we have an extension runner (for custom tool HTML rendering)
         const toolRenderer = createToolHtmlRenderer({
             getToolDefinition: (name) => this.getToolDefinition(name),

package/dist/core/experimental.d.ts

@@ -1 +1,5 @@
 export declare function areExperimentalFeaturesEnabled(): boolean;
+export declare function getExperimentalToolSampling(): {
+    readonly type: "json_schema";
+    readonly strict: "prefer";
+} | undefined;

package/dist/core/experimental.js

@@ -1,3 +1,7 @@
+const PREFER_STRICT_TOOL_SAMPLING = { type: "json_schema", strict: "prefer" };
 export function areExperimentalFeaturesEnabled() {
     return process.env.PI_EXPERIMENTAL === "1";
 }
+export function getExperimentalToolSampling() {
+    return areExperimentalFeaturesEnabled() ? PREFER_STRICT_TOOL_SAMPLING : undefined;
+}

package/dist/core/extensions/types.d.ts

@@ -301,6 +301,7 @@ export interface ReplacedSessionContext extends ExtensionCommandContext {
     }): Promise<void>;
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
+        expandPromptTemplates?: boolean;
     }): Promise<void>;
 }
 /** Rendering options for tool results */
@@ -353,6 +354,8 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
     promptGuidelines?: string[];
     /** Parameter schema (TypeBox) */
     parameters: TParams;
+    /** When global pruneToolDescriptions is enabled, keep this tool's per-field parameter descriptions on the wire (already pruned by the tool itself). */
+    keepParameterDescriptions?: boolean;
     /** Optional provider-side constrained sampling request for this tool. Set false to explicitly disable it, equivalent to leaving it undefined. */
     constrainedSampling?: false | ConstrainedSamplingConfig;
     /** Controls whether ToolExecutionComponent renders the standard colored shell or the tool renders its own framing. */
@@ -924,9 +927,11 @@ export interface ExtensionAPI {
     /**
      * Send a user message to the agent. Always triggers a turn.
      * When the agent is streaming, use deliverAs to specify how to queue the message.
+     * Set expandPromptTemplates to dispatch extension commands and expand skill commands and prompt templates.
      */
     sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
         deliverAs?: "steer" | "followUp";
+        expandPromptTemplates?: boolean;
     }): void;
     /** Append a custom entry to the session for state persistence (not sent to LLM). */
     appendEntry<T = unknown>(customType: string, data?: T): void;
@@ -1122,6 +1127,7 @@ export type SendMessageHandler = <T = unknown>(message: Pick<CustomMessage<T>, "
 }) => void;
 export type SendUserMessageHandler = (content: string | (TextContent | ImageContent)[], options?: {
     deliverAs?: "steer" | "followUp";
+    expandPromptTemplates?: boolean;
 }) => void;
 export type AppendEntryHandler = <T = unknown>(customType: string, data?: T) => void;
 export type SetSessionNameHandler = (name: string) => void;

package/dist/core/keybindings.d.ts

@@ -197,6 +197,14 @@ export declare const KEYBINDINGS: {
         readonly defaultKeys: [];
         readonly description: "Scroll viewport down half a page";
     };
+    readonly "tui.altScreen.lineUp": {
+        readonly defaultKeys: [];
+        readonly description: "Scroll viewport up one line";
+    };
+    readonly "tui.altScreen.lineDown": {
+        readonly defaultKeys: [];
+        readonly description: "Scroll viewport down one line";
+    };
     readonly "tui.altScreen.previousPrompt": {
         readonly defaultKeys: "ctrl+shift+up";
         readonly description: "Jump to previous semantic prompt";
@@ -205,6 +213,22 @@ export declare const KEYBINDINGS: {
         readonly defaultKeys: "ctrl+shift+down";
         readonly description: "Jump to next semantic prompt";
     };
+    readonly "tui.altScreen.search": {
+        readonly defaultKeys: "ctrl+shift+f";
+        readonly description: "Search the primary scroll view";
+    };
+    readonly "tui.altScreen.searchNext": {
+        readonly defaultKeys: ["enter", "ctrl+g"];
+        readonly description: "Select the next search match";
+    };
+    readonly "tui.altScreen.searchPrevious": {
+        readonly defaultKeys: ["shift+enter", "ctrl+shift+g"];
+        readonly description: "Select the previous search match";
+    };
+    readonly "tui.altScreen.searchClose": {
+        readonly defaultKeys: "escape";
+        readonly description: "Close transcript search";
+    };
     readonly "tui.altScreen.top": {
         readonly defaultKeys: "home";
         readonly description: "Scroll viewport to top";

package/dist/core/model-config.d.ts

@@ -98,6 +98,7 @@ declare const ModelDefinitionSchema: Type.TObject<{
         supportsLongCacheRetention: Type.TOptional<Type.TBoolean>;
         supportsStrictMode: Type.TOptional<Type.TBoolean>;
         supportsOpenAIGrammarTools: Type.TOptional<Type.TBoolean>;
+        supportsAdditionalTools: Type.TOptional<Type.TBoolean>;
         supportsToolSearch: Type.TOptional<Type.TBoolean>;
     }>, Type.TObject<{
         supportsEagerToolInputStreaming: Type.TOptional<Type.TBoolean>;
@@ -206,6 +207,7 @@ declare const ModelOverrideSchema: Type.TObject<{
         supportsLongCacheRetention: Type.TOptional<Type.TBoolean>;
         supportsStrictMode: Type.TOptional<Type.TBoolean>;
         supportsOpenAIGrammarTools: Type.TOptional<Type.TBoolean>;
+        supportsAdditionalTools: Type.TOptional<Type.TBoolean>;
         supportsToolSearch: Type.TOptional<Type.TBoolean>;
     }>, Type.TObject<{
         supportsEagerToolInputStreaming: Type.TOptional<Type.TBoolean>;
@@ -292,6 +294,7 @@ declare const ProviderConfigSchema: Type.TObject<{
         supportsLongCacheRetention: Type.TOptional<Type.TBoolean>;
         supportsStrictMode: Type.TOptional<Type.TBoolean>;
         supportsOpenAIGrammarTools: Type.TOptional<Type.TBoolean>;
+        supportsAdditionalTools: Type.TOptional<Type.TBoolean>;
         supportsToolSearch: Type.TOptional<Type.TBoolean>;
     }>, Type.TObject<{
         supportsEagerToolInputStreaming: Type.TOptional<Type.TBoolean>;
@@ -403,6 +406,7 @@ declare const ProviderConfigSchema: Type.TObject<{
             supportsLongCacheRetention: Type.TOptional<Type.TBoolean>;
             supportsStrictMode: Type.TOptional<Type.TBoolean>;
             supportsOpenAIGrammarTools: Type.TOptional<Type.TBoolean>;
+            supportsAdditionalTools: Type.TOptional<Type.TBoolean>;
             supportsToolSearch: Type.TOptional<Type.TBoolean>;
         }>, Type.TObject<{
             supportsEagerToolInputStreaming: Type.TOptional<Type.TBoolean>;
@@ -511,6 +515,7 @@ declare const ProviderConfigSchema: Type.TObject<{
             supportsLongCacheRetention: Type.TOptional<Type.TBoolean>;
             supportsStrictMode: Type.TOptional<Type.TBoolean>;
             supportsOpenAIGrammarTools: Type.TOptional<Type.TBoolean>;
+            supportsAdditionalTools: Type.TOptional<Type.TBoolean>;
             supportsToolSearch: Type.TOptional<Type.TBoolean>;
         }>, Type.TObject<{
             supportsEagerToolInputStreaming: Type.TOptional<Type.TBoolean>;

package/dist/core/model-config.js

@@ -96,6 +96,7 @@ const OpenAIResponsesCompatSchema = Type.Object({
     supportsLongCacheRetention: Type.Optional(Type.Boolean()),
     supportsStrictMode: Type.Optional(Type.Boolean()),
     supportsOpenAIGrammarTools: Type.Optional(Type.Boolean()),
+    supportsAdditionalTools: Type.Optional(Type.Boolean()),
     supportsToolSearch: Type.Optional(Type.Boolean()),
 });
 const AnthropicMessagesCompatSchema = Type.Object({

package/dist/core/project-trust.js

@@ -1,8 +1,8 @@
-import { CONFIG_DIR_NAME } from "../config.js";
+import { APP_NAME, CONFIG_DIR_NAME } from "../config.js";
 import { emitProjectTrustEvent } from "./extensions/runner.js";
 import { getProjectTrustOptions, hasTrustRequiringProjectResources, } from "./trust-manager.js";
 function formatProjectTrustPrompt(cwd) {
-    return `Trust project folder?\n${cwd}\n\nThis allows selesai to load ${CONFIG_DIR_NAME} settings and resources, install missing project packages, and execute project extensions.`;
+    return `Trust project folder?\n${cwd}\n\nThis allows ${APP_NAME} to load ${CONFIG_DIR_NAME} settings and resources, install missing project packages, and execute project extensions.`;
 }
 async function selectProjectTrustOption(cwd, ctx) {
     const options = getProjectTrustOptions(cwd, { includeSessionOnly: true });

package/dist/core/provider-composer.js

@@ -2,6 +2,17 @@ import { lazyStream, } from "@earendil-works/pi-ai";
 import { getApiProvider } from "@earendil-works/pi-ai/compat";
 import { clearConfigValueCache, getConfigValueEnvVarNames, isCommandConfigValue, isConfigValueConfigured, resolveConfigValueOrThrow, resolveHeadersOrThrow, } from "./resolve-config-value.js";
 export const clearApiKeyCache = clearConfigValueCache;
+/** Sane default when a model definition omits maxTokens (kept small so providers never reject it). */
+const DEFAULT_MAX_TOKENS = 16384;
+/**
+ * Resolve a safe max output token count. Missing or non-positive values fall back
+ * (to a sane default or an inherited value); explicit values are never allowed to
+ * exceed the model's context window.
+ */
+function safeMaxTokens(value, contextWindow, fallback = DEFAULT_MAX_TOKENS) {
+    const resolved = typeof value === "number" && value > 0 ? value : fallback;
+    return Math.min(resolved, Math.max(contextWindow, 1));
+}
 function mergeCompat(base, override) {
     if (!override)
         return base;
@@ -20,6 +31,7 @@ function mergeCompat(base, override) {
     return merged;
 }
 function applyModelOverride(model, override) {
+    const contextWindow = override.contextWindow ?? model.contextWindow;
     return {
         ...model,
         name: override.name ?? model.name,
@@ -37,8 +49,8 @@ function applyModelOverride(model, override) {
                 tiers: override.cost.tiers ?? model.cost.tiers,
             }
             : model.cost,
-        contextWindow: override.contextWindow ?? model.contextWindow,
-        maxTokens: override.maxTokens ?? model.maxTokens,
+        contextWindow,
+        maxTokens: safeMaxTokens(override.maxTokens ?? model.maxTokens, contextWindow, model.maxTokens),
         compat: mergeCompat(model.compat, override.compat),
     };
 }
@@ -56,6 +68,7 @@ function modelFromJson(providerId, definition, providerConfig, defaults) {
     if (definition.maxTokens !== undefined && definition.maxTokens <= 0) {
         throw new Error(`Provider ${providerId}, model ${definition.id}: invalid maxTokens`);
     }
+    const contextWindow = definition.contextWindow ?? 128000;
     return {
         id: definition.id,
         name: definition.name ?? definition.id,
@@ -66,8 +79,8 @@ function modelFromJson(providerId, definition, providerConfig, defaults) {
         thinkingLevelMap: definition.thinkingLevelMap,
         input: (definition.input ?? ["text"]),
         cost: definition.cost ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-        contextWindow: definition.contextWindow ?? 128000,
-        maxTokens: definition.maxTokens ?? 16384,
+        contextWindow,
+        maxTokens: safeMaxTokens(definition.maxTokens, contextWindow),
         headers: undefined,
         compat: mergeCompat(providerConfig.compat, definition.compat),
     };

package/dist/core/sdk.d.ts

@@ -34,9 +34,11 @@ export interface CreateAgentSessionOptions {
     /**
      * Optional allowlist of tool names.
      *
-     * When omitted, pi enables the default built-in tools (read, bash, edit, write)
-     * and leaves extension/custom tools enabled unless `noTools` changes that default.
-     * When provided, only the listed tool names are enabled.
+     * When omitted, pi uses the `defaultTools` setting for the initial built-in
+     * selection when configured. Otherwise it enables the default built-in tools
+     * (read, bash, edit, write). Extension/custom tools remain enabled unless
+     * `noTools` changes that default. When provided, only the listed tool names are
+     * enabled.
      */
     tools?: string[];
     /** Optional denylist of tool names to disable. Applies after `tools` when both are provided. */

package/dist/core/sdk.js

@@ -130,10 +130,11 @@ export async function createAgentSession(options = {}) {
         thinkingLevel = clampThinkingLevel(model, thinkingLevel);
     }
     const defaultActiveToolNames = ["read", "bash", "edit", "write"];
+    const configuredDefaultToolNames = settingsManager.getDefaultTools();
     const allowedToolNames = options.tools ?? (options.noTools === "all" ? [] : undefined);
     const excludedToolNames = options.excludeTools;
     const excludedToolNameSet = excludedToolNames ? new Set(excludedToolNames) : undefined;
-    const initialActiveToolNames = (options.tools ? [...options.tools] : options.noTools ? [] : defaultActiveToolNames).filter((name) => !excludedToolNameSet?.has(name));
+    const initialActiveToolNames = (options.tools ?? (options.noTools ? [] : (configuredDefaultToolNames ?? defaultActiveToolNames))).filter((name) => !excludedToolNameSet?.has(name));
     let agent;
     // Create convertToLlm wrapper that filters images if blockImages is enabled (defense-in-depth)
     const convertToLlmWithBlockImages = (messages) => {

package/dist/core/session-manager.js

@@ -5,7 +5,7 @@ import { readdir, stat } from "fs/promises";
 import { join, resolve } from "path";
 import { createInterface } from "readline";
 import { StringDecoder } from "string_decoder";
-import { getAgentDir as getDefaultAgentDir, getSessionsDir } from "../config.js";
+import { APP_NAME, getAgentDir as getDefaultAgentDir, getSessionsDir } from "../config.js";
 import { normalizePath, resolvePath } from "../utils/paths.js";
 import { createBranchSummaryMessage, createCompactionSummaryMessage, createCustomMessage, } from "./messages.js";
 export const CURRENT_SESSION_VERSION = 3;
@@ -620,7 +620,7 @@ export class SessionManager {
             if (this.fileEntries.length === 0) {
                 const explicitPath = this.sessionFile;
                 if (statSync(explicitPath).size > 0) {
-                    throw new Error(`Session file is not a valid pi session: ${explicitPath}`);
+                    throw new Error(`Session file is not a valid ${APP_NAME} session: ${explicitPath}`);
                 }
                 this.newSession();
                 this.sessionFile = explicitPath;

package/dist/core/settings-manager.d.ts

@@ -22,6 +22,7 @@ export interface RetrySettings {
     provider?: ProviderRetrySettings;
 }
 export type TuiMode = RendererTuiMode;
+export type FullscreenExitOutput = "transcript" | "resume-hint";
 export interface TerminalSettings {
     showImages?: boolean;
     imageWidthCells?: number;
@@ -77,6 +78,7 @@ export interface Settings {
     branchSummary?: BranchSummarySettings;
     retry?: RetrySettings;
     hideThinkingBlock?: boolean;
+    pruneToolDescriptions?: boolean;
     showCacheMissNotices?: boolean;
     externalEditor?: string;
     shellPath?: string;
@@ -96,6 +98,8 @@ export interface Settings {
     agents?: string[];
     terminal?: TerminalSettings;
     tuiMode?: TuiMode;
+    defaultTools?: string[];
+    fullscreenExitOutput?: FullscreenExitOutput;
     fullscreenScrollbar?: ScrollViewScrollbar;
     images?: ImageSettings;
     enabledModels?: string[];
@@ -236,6 +240,7 @@ export declare class SettingsManager {
     };
     getWebSocketConnectTimeoutMs(): number | undefined;
     getHideThinkingBlock(): boolean;
+    getPruneToolDescriptions(): boolean;
     getShowCacheMissNotices(): boolean;
     getExternalEditorCommand(): string;
     setHideThinkingBlock(hide: boolean): void;
@@ -286,11 +291,14 @@ export declare class SettingsManager {
     setTuiMode(mode: TuiMode): void;
     getFullscreenScrollbar(): ScrollViewScrollbar;
     setFullscreenScrollbar(mode: ScrollViewScrollbar): void;
+    getFullscreenExitOutput(): FullscreenExitOutput;
+    setFullscreenExitOutput(output: FullscreenExitOutput): void;
     getImageAutoResize(): boolean;
     setImageAutoResize(enabled: boolean): void;
     getBlockImages(): boolean;
     setBlockImages(blocked: boolean): void;
     getEnabledModels(): string[] | undefined;
+    getDefaultTools(): string[] | undefined;
     setEnabledModels(patterns: string[] | undefined): void;
     getDoubleEscapeAction(): "fork" | "tree" | "none";
     setDoubleEscapeAction(action: "fork" | "tree" | "none"): void;

package/dist/core/settings-manager.js

@@ -598,6 +598,9 @@ export class SettingsManager {
     getHideThinkingBlock() {
         return this.settings.hideThinkingBlock ?? false;
     }
+    getPruneToolDescriptions() {
+        return this.settings.pruneToolDescriptions ?? true;
+    }
     getShowCacheMissNotices() {
         return this.settings.showCacheMissNotices ?? false;
     }
@@ -834,6 +837,14 @@ export class SettingsManager {
         this.markModified("fullscreenScrollbar");
         this.save();
     }
+    getFullscreenExitOutput() {
+        return this.settings.fullscreenExitOutput === "resume-hint" ? "resume-hint" : "transcript";
+    }
+    setFullscreenExitOutput(output) {
+        this.globalSettings.fullscreenExitOutput = output;
+        this.markModified("fullscreenExitOutput");
+        this.save();
+    }
     getImageAutoResize() {
         return this.settings.images?.autoResize ?? true;
     }
@@ -859,6 +870,10 @@ export class SettingsManager {
     getEnabledModels() {
         return this.settings.enabledModels;
     }
+    getDefaultTools() {
+        const tools = this.settings.defaultTools;
+        return tools ? [...tools] : undefined;
+    }
     setEnabledModels(patterns) {
         this.globalSettings.enabledModels = patterns;
         this.markModified("enabledModels");

package/dist/core/system-prompt.js

@@ -51,7 +51,7 @@ export function buildSystemPrompt(options) {
         if (activeGuidelines.length > 0) {
             prompt += `\n\nActive tool guidelines:\n${activeGuidelines.map((guideline) => `- ${guideline}`).join("\n")}`;
         }
-        prompt += `\nCurrent working directory: ${promptCwd}`;
+        prompt += `\nCurrent working directory: ${promptCwd}\n`;
         return prompt;
     }
     // Get absolute paths to documentation and examples
@@ -103,14 +103,8 @@ In addition to the tools above, you may have access to other custom tools depend
 Guidelines:
 ${guidelines}
 
-Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
-- Main documentation: ${readmePath}
-- Additional docs: ${docsPath}
-- Examples: ${examplesPath} (extensions, custom tools, SDK)
-- When reading pi docs or examples, resolve docs/... under Additional docs and examples/... under Examples, not the current working directory
-- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md)
-- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
-- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;
+Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI): main docs ${readmePath}, additional docs ${docsPath}, examples ${examplesPath}.
+When working on pi topics, resolve docs/... and examples/... under those paths (not cwd), read the relevant .md files completely, and follow cross-references before implementing.`;
     if (appendSection) {
         prompt += appendSection;
     }

package/dist/core/system-prompt.test.js

@@ -12,6 +12,12 @@ describe("buildSystemPrompt", () => {
         expect(prompt).toMatch(/Guidelines:/);
         expect(prompt).toContain("Current working directory: /tmp/project");
     });
+    it("keeps the collapsed Pi-docs block without the per-topic filename map", () => {
+        const prompt = buildSystemPrompt({ cwd: "/tmp/project" });
+        expect(prompt).toContain("Pi documentation");
+        expect(prompt).not.toContain("When asked about:");
+        expect(prompt).not.toContain("(docs/extensions.md");
+    });
     it("keeps the default tool snippets, skills, and agents XML read-gated", () => {
         const skill = {
             name: "test-skill",

package/dist/core/tools/bash.js

@@ -7,6 +7,7 @@ import { keyHint } from "../../modes/interactive/components/keybinding-hints.js"
 import { truncateToVisualLines } from "../../modes/interactive/components/visual-truncate.js";
 import { theme } from "../../modes/interactive/theme/theme.js";
 import { waitForChildProcess } from "../../utils/child-process.js";
+import { getExperimentalToolSampling } from "../experimental.js";
 import { getShellConfig, getShellEnv, killProcessTree, trackDetachedChildPid, untrackDetachedChildPid, } from "../../utils/shell.js";
 import { OutputAccumulator } from "./output-accumulator.js";
 import { getTextOutput, invalidArgText, str } from "./render-utils.js";
@@ -232,6 +233,7 @@ export function createBashToolDefinition(cwd, options) {
             ? ["Inspect PI_* environment variables for current model and session details."]
             : undefined,
         parameters: bashSchema,
+        constrainedSampling: getExperimentalToolSampling(),
         async execute(_toolCallId, { command, timeout }, signal, onUpdate, ctx) {
             const resolvedCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
             const spawnContext = resolveSpawnContext(resolvedCommand, cwd, spawnHook, exposeSessionEnvironment, ctx);

package/dist/core/tools/edit.js

@@ -3,6 +3,7 @@ import { constants } from "fs";
 import { access as fsAccess, readFile as fsReadFile, writeFile as fsWriteFile } from "fs/promises";
 import { Type } from "typebox";
 import { renderDiff } from "../../modes/interactive/components/diff.js";
+import { getExperimentalToolSampling } from "../experimental.js";
 import { applyEditsToNormalizedContent, computeEditsDiff, detectLineEnding, generateDiffString, generateUnifiedPatch, normalizeToLF, restoreLineEndings, stripBom, } from "./edit-diff.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { resolveToCwd } from "./path-utils.js";
@@ -169,6 +170,7 @@ export function createEditToolDefinition(cwd, options) {
             "Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions.",
         ],
         parameters: editSchema,
+        constrainedSampling: getExperimentalToolSampling(),
         renderShell: "self",
         prepareArguments: prepareEditArguments,
         async execute(_toolCallId, input, signal, _onUpdate, _ctx) {

package/dist/core/tools/find.js

@@ -154,7 +154,7 @@ export function createFindToolDefinition(cwd, options) {
                             return;
                         }
                         // Default implementation uses fd.
-                        const fdPath = await ensureTool("fd", true);
+                        const fdPath = await ensureTool("fd");
                         if (signal?.aborted) {
                             settle(() => reject(new Error("Operation aborted")));
                             return;

package/dist/core/tools/grep.js

@@ -92,7 +92,7 @@ export function createGrepToolDefinition(cwd, options) {
                 };
                 (async () => {
                     try {
-                        const rgPath = await ensureTool("rg", true);
+                        const rgPath = await ensureTool("rg");
                         if (!rgPath) {
                             settle(() => reject(new Error("ripgrep (rg) is not available and could not be downloaded")));
                             return;

package/dist/core/tools/index.d.ts

@@ -5,6 +5,7 @@ export { createFindTool, createFindToolDefinition, type FindOperations, type Fin
 export { createGrepTool, createGrepToolDefinition, type GrepOperations, type GrepToolDetails, type GrepToolInput, type GrepToolOptions, } from "./grep.ts";
 export { createLsTool, createLsToolDefinition, type LsOperations, type LsToolDetails, type LsToolInput, type LsToolOptions, } from "./ls.ts";
 export { createReadTool, createReadToolDefinition, type ReadOperations, type ReadToolDetails, type ReadToolInput, type ReadToolOptions, } from "./read.ts";
+export { stripSchemaDescriptions, stripToolParameterDescriptions, } from "./schema-prune.ts";
 export { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, type TruncationOptions, type TruncationResult, truncateHead, truncateLine, truncateTail, } from "./truncate.ts";
 export { createWriteTool, createWriteToolDefinition, type WriteOperations, type WriteToolInput, type WriteToolOptions, } from "./write.ts";
 import type { AgentTool } from "@earendil-works/pi-agent-core";