@oh-my-pi/pi-coding-agent 16.0.11 → 16.1.0

package/dist/types/config/settings-schema.d.ts

@@ -819,6 +819,16 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Show per-turn token usage on assistant messages";
         };
     };
+    readonly "display.cacheMissMarker": {
+        readonly type: "boolean";
+        readonly default: true;
+        readonly ui: {
+            readonly tab: "appearance";
+            readonly group: "Display";
+            readonly label: "Cache Miss Marker";
+            readonly description: "Show a divider above an assistant turn whose request lost (missed) the prompt cache";
+        };
+    };
     readonly showHardwareCursor: {
         readonly type: "boolean";
         readonly default: true;
@@ -871,14 +881,14 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Apply loop guard to assistant prose messages in addition to thinking logs";
         };
     };
-    readonly repeatToolDescriptions: {
+    readonly inlineToolDescriptors: {
         readonly type: "boolean";
-        readonly default: false;
+        readonly default: true;
         readonly ui: {
             readonly tab: "model";
             readonly group: "Prompt";
-            readonly label: "Repeat Tool Descriptions";
-            readonly description: "Render full tool descriptions in the system prompt instead of a tool name list";
+            readonly label: "Inline Tool Descriptors";
+            readonly description: "Render full tool descriptors in the system prompt and strip top-level/nested descriptions from provider tool schemas so descriptor text is sent once";
         };
     };
     readonly includeModelInPrompt: {

package/dist/types/modes/components/__tests__/skill-message.test.d.ts

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

package/dist/types/modes/components/assistant-message.d.ts

@@ -1,6 +1,7 @@
 import type { AssistantMessage, ImageContent } from "@oh-my-pi/pi-ai";
 import { Container, type ImageBudget } from "@oh-my-pi/pi-tui";
 import type { AssistantThinkingRenderer } from "../../extensibility/extensions/types";
+import { type CacheInvalidation } from "./cache-invalidation-marker";
 /**
  * Component that renders a complete assistant message
  */
@@ -11,6 +12,13 @@ export declare class AssistantMessageComponent extends Container {
     private readonly thinkingRenderers;
     private readonly imageBudget?;
     constructor(message?: AssistantMessage, hideThinkingBlock?: boolean, onImageUpdate?: (() => void) | undefined, thinkingRenderers?: readonly AssistantThinkingRenderer[], imageBudget?: ImageBudget | undefined);
+    /**
+     * Show or clear the slim cache-invalidation divider above this turn. Set at
+     * `message_end` (live) or during rebuild, once the turn's usage is known and
+     * compared against the previous turn's cache footprint. Bumps the transcript
+     * block version so the change repaints even after content finalized.
+     */
+    setCacheInvalidation(info: CacheInvalidation | undefined): void;
     invalidate(): void;
     setHideThinkingBlock(hide: boolean): void;
     dispose(): void;

package/dist/types/modes/components/cache-invalidation-marker.d.ts

@@ -0,0 +1,34 @@
+import type { Usage } from "@oh-my-pi/pi-ai";
+import type { Component } from "@oh-my-pi/pi-tui";
+/** A prompt-cache invalidation detected from a turn's usage. */
+export interface CacheInvalidation {
+    /** Prompt tokens the cold turn had to (re)process instead of reading from cache. */
+    reprocessedTokens: number;
+}
+/**
+ * Decide whether `current` turn lost the prompt cache that `prev` established.
+ *
+ * The provider reports a warm prefix as `cacheRead`; a model/thinking/tool/
+ * system-prompt change (or a history rewrite) breaks the prefix, so the next
+ * request reads nothing from cache and re-pays for the whole prompt. We detect
+ * that as: the previous turn cached a meaningful prefix, yet this turn's
+ * `cacheRead` collapsed to zero while it still reprocessed a non-trivial prompt.
+ * Returns `undefined` (no marker) for the first turn, tiny contexts, and turns
+ * that reused any cache.
+ */
+export declare function detectCacheInvalidation(prev: Usage | undefined, current: Usage): CacheInvalidation | undefined;
+/**
+ * Slim left-aligned divider rendered above an assistant turn whose request lost
+ * the prompt cache. Mirrors the compaction divider's banner styling but spans
+ * only a short rule plus label (not the full width) and carries no expandable
+ * detail:
+ *
+ *   ────────── ⊘ cache miss · 50.9k tokens
+ */
+export declare class CacheInvalidationMarkerComponent implements Component {
+    #private;
+    private readonly info;
+    constructor(info: CacheInvalidation);
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

package/dist/types/modes/components/compaction-summary-message.d.ts

@@ -1,5 +1,5 @@
 import { type Component } from "@oh-my-pi/pi-tui";
-import type { CompactionSummaryMessage, CustomMessage } from "../../session/messages";
+import type { BranchSummaryMessage, CompactionSummaryMessage, CustomMessage } from "../../session/messages";
 /**
  * Compaction point in the transcript, rendered as a slim horizontal divider:
  *
@@ -31,3 +31,16 @@ export declare class HandoffSummaryMessageComponent implements Component {
     render(width: number): readonly string[];
 }
 export declare function createHandoffSummaryMessageComponent(message: CustomMessage<unknown>, expanded: boolean): HandoffSummaryMessageComponent | undefined;
+/**
+ * A branch summary collapses a side branch back into the main line. Render it
+ * with the same slim divider as `/compact` and handoff rather than a `[branch]`
+ * box, so every history-collapse point reads as one consistent banner.
+ */
+export declare class BranchSummaryMessageComponent implements Component {
+    #private;
+    private readonly message;
+    constructor(message: BranchSummaryMessage);
+    setExpanded(expanded: boolean): void;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

package/dist/types/modes/components/index.d.ts

@@ -1,7 +1,6 @@
 export * from "./assistant-message";
 export * from "./bash-execution";
 export * from "./bordered-loader";
-export * from "./branch-summary-message";
 export * from "./compaction-summary-message";
 export * from "./countdown-timer";
 export * from "./custom-editor";

package/dist/types/modes/components/message-frame.d.ts

@@ -29,14 +29,16 @@ export interface RebuildFrameOptions<M extends FramedMessage> {
     message: M;
     box: Box;
     expanded: boolean;
+    /** Icon glyph shown before the customType in the default header (e.g. a hook/extension icon). */
+    icon?: string;
     /** Collapse the markdown body to this many lines when `expanded` is false. Omit to never collapse. */
     collapseAfterLines?: number;
     customRenderer?: FramedRenderer<M>;
 }
 /**
- * Attempt the custom renderer; on failure or undefined return, populate
- * `box` with the default `[customType]` label + markdown body and return
- * undefined. When the custom renderer succeeds, return its Component so the
- * caller can mount it and skip the default box.
+ * Attempt the custom renderer; on failure or undefined return, populate `box`
+ * with the default outlined card — an `icon customType` header + markdown body —
+ * and return undefined. When the custom renderer succeeds, return its Component
+ * so the caller can mount it and skip the default box.
  */
 export declare function renderFramedMessage<M extends FramedMessage>(opts: RebuildFrameOptions<M>): Component | undefined;

package/dist/types/modes/interactive-mode.d.ts

@@ -1,6 +1,6 @@
 import { type Agent, type AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { CompactionOutcome } from "@oh-my-pi/pi-agent-core/compaction";
-import type { AssistantMessage, ImageContent, Message, UsageReport } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage, ImageContent, Message, Usage, UsageReport } from "@oh-my-pi/pi-ai";
 import type { Component, EditorTheme } from "@oh-my-pi/pi-tui";
 import { Container, Loader, Spacer, Text, TUI } from "@oh-my-pi/pi-tui";
 import type { CollabGuestLink } from "../collab/guest";
@@ -119,6 +119,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
     isPythonMode: boolean;
     streamingComponent: AssistantMessageComponent | undefined;
     streamingMessage: AssistantMessage | undefined;
+    lastAssistantUsage: Usage | undefined;
     loadingAnimation: Loader | undefined;
     autoCompactionLoader: Loader | undefined;
     retryLoader: Loader | undefined;

package/dist/types/modes/theme/theme.d.ts

@@ -6,7 +6,7 @@ export type SymbolPreset = "unicode" | "nerd" | "ascii";
 /**
  * All available symbol keys organized by category.
  */
-export type SymbolKey = "status.success" | "status.error" | "status.warning" | "status.info" | "status.pending" | "status.disabled" | "status.enabled" | "status.running" | "status.shadowed" | "status.aborted" | "status.done" | "nav.cursor" | "nav.selected" | "nav.expand" | "nav.collapse" | "nav.back" | "tree.branch" | "tree.last" | "tree.vertical" | "tree.horizontal" | "tree.hook" | "boxRound.topLeft" | "boxRound.topRight" | "boxRound.bottomLeft" | "boxRound.bottomRight" | "boxRound.horizontal" | "boxRound.vertical" | "boxSharp.topLeft" | "boxSharp.topRight" | "boxSharp.bottomLeft" | "boxSharp.bottomRight" | "boxSharp.horizontal" | "boxSharp.vertical" | "boxSharp.cross" | "boxSharp.teeDown" | "boxSharp.teeUp" | "boxSharp.teeRight" | "boxSharp.teeLeft" | "sep.powerline" | "sep.powerlineThin" | "sep.powerlineLeft" | "sep.powerlineRight" | "sep.powerlineThinLeft" | "sep.powerlineThinRight" | "sep.block" | "sep.space" | "sep.asciiLeft" | "sep.asciiRight" | "sep.dot" | "sep.slash" | "sep.pipe" | "icon.model" | "icon.plan" | "icon.goal" | "icon.pause" | "icon.loop" | "icon.folder" | "icon.search" | "icon.scratchFolder" | "icon.file" | "icon.git" | "icon.branch" | "icon.pr" | "icon.tokens" | "icon.context" | "icon.cost" | "icon.time" | "icon.pi" | "icon.ghost" | "icon.agents" | "icon.job" | "icon.cache" | "icon.input" | "icon.output" | "icon.host" | "icon.session" | "icon.package" | "icon.warning" | "icon.rewind" | "icon.auto" | "icon.fast" | "icon.extensionSkill" | "icon.extensionTool" | "icon.extensionSlashCommand" | "icon.extensionMcp" | "icon.extensionRule" | "icon.extensionHook" | "icon.extensionPrompt" | "icon.extensionContextFile" | "icon.extensionInstruction" | "icon.mic" | "icon.camera" | "thinking.minimal" | "thinking.low" | "thinking.medium" | "thinking.high" | "thinking.xhigh" | "thinking.autoPending" | "checkbox.checked" | "checkbox.unchecked" | "radio.selected" | "radio.unselected" | "format.bullet" | "format.dash" | "format.bracketLeft" | "format.bracketRight" | "md.quoteBorder" | "md.hrChar" | "md.bullet" | "md.colorSwatch" | "lang.default" | "lang.typescript" | "lang.javascript" | "lang.python" | "lang.rust" | "lang.go" | "lang.java" | "lang.c" | "lang.cpp" | "lang.csharp" | "lang.ruby" | "lang.php" | "lang.swift" | "lang.kotlin" | "lang.shell" | "lang.html" | "lang.css" | "lang.json" | "lang.yaml" | "lang.markdown" | "lang.sql" | "lang.docker" | "lang.lua" | "lang.text" | "lang.env" | "lang.toml" | "lang.xml" | "lang.ini" | "lang.conf" | "lang.log" | "lang.csv" | "lang.tsv" | "lang.image" | "lang.pdf" | "lang.archive" | "lang.binary" | "tab.appearance" | "tab.model" | "tab.interaction" | "tab.context" | "tab.files" | "tab.shell" | "tab.tools" | "tab.memory" | "tab.tasks" | "tab.providers" | "tool.write" | "tool.edit" | "tool.bash" | "tool.ssh" | "tool.lsp" | "tool.gh" | "tool.webSearch" | "tool.exa" | "tool.browser" | "tool.eval" | "tool.debug" | "tool.mcp" | "tool.job" | "tool.task" | "tool.todo" | "tool.memory" | "tool.ask" | "tool.resolve" | "tool.review" | "tool.inspectImage" | "tool.goal" | "tool.irc";
+export type SymbolKey = "status.success" | "status.error" | "status.warning" | "status.info" | "status.pending" | "status.disabled" | "status.enabled" | "status.running" | "status.shadowed" | "status.aborted" | "status.done" | "nav.cursor" | "nav.selected" | "nav.expand" | "nav.collapse" | "nav.back" | "tree.branch" | "tree.last" | "tree.vertical" | "tree.horizontal" | "tree.hook" | "boxRound.topLeft" | "boxRound.topRight" | "boxRound.bottomLeft" | "boxRound.bottomRight" | "boxRound.horizontal" | "boxRound.vertical" | "boxSharp.topLeft" | "boxSharp.topRight" | "boxSharp.bottomLeft" | "boxSharp.bottomRight" | "boxSharp.horizontal" | "boxSharp.vertical" | "boxSharp.cross" | "boxSharp.teeDown" | "boxSharp.teeUp" | "boxSharp.teeRight" | "boxSharp.teeLeft" | "sep.powerline" | "sep.powerlineThin" | "sep.powerlineLeft" | "sep.powerlineRight" | "sep.powerlineThinLeft" | "sep.powerlineThinRight" | "sep.block" | "sep.space" | "sep.asciiLeft" | "sep.asciiRight" | "sep.dot" | "sep.slash" | "sep.pipe" | "icon.model" | "icon.plan" | "icon.goal" | "icon.pause" | "icon.loop" | "icon.folder" | "icon.search" | "icon.scratchFolder" | "icon.file" | "icon.git" | "icon.branch" | "icon.pr" | "icon.tokens" | "icon.context" | "icon.cost" | "icon.time" | "icon.pi" | "icon.ghost" | "icon.agents" | "icon.job" | "icon.cache" | "icon.cacheMiss" | "icon.input" | "icon.output" | "icon.host" | "icon.session" | "icon.package" | "icon.warning" | "icon.rewind" | "icon.auto" | "icon.fast" | "icon.extensionSkill" | "icon.extensionTool" | "icon.extensionSlashCommand" | "icon.extensionMcp" | "icon.extensionRule" | "icon.extensionHook" | "icon.extensionPrompt" | "icon.extensionContextFile" | "icon.extensionInstruction" | "icon.mic" | "icon.camera" | "thinking.minimal" | "thinking.low" | "thinking.medium" | "thinking.high" | "thinking.xhigh" | "thinking.autoPending" | "checkbox.checked" | "checkbox.unchecked" | "radio.selected" | "radio.unselected" | "format.bullet" | "format.dash" | "format.bracketLeft" | "format.bracketRight" | "md.quoteBorder" | "md.hrChar" | "md.bullet" | "md.colorSwatch" | "lang.default" | "lang.typescript" | "lang.javascript" | "lang.python" | "lang.rust" | "lang.go" | "lang.java" | "lang.c" | "lang.cpp" | "lang.csharp" | "lang.ruby" | "lang.php" | "lang.swift" | "lang.kotlin" | "lang.shell" | "lang.html" | "lang.css" | "lang.json" | "lang.yaml" | "lang.markdown" | "lang.sql" | "lang.docker" | "lang.lua" | "lang.text" | "lang.env" | "lang.toml" | "lang.xml" | "lang.ini" | "lang.conf" | "lang.log" | "lang.csv" | "lang.tsv" | "lang.image" | "lang.pdf" | "lang.archive" | "lang.binary" | "tab.appearance" | "tab.model" | "tab.interaction" | "tab.context" | "tab.files" | "tab.shell" | "tab.tools" | "tab.memory" | "tab.tasks" | "tab.providers" | "tool.write" | "tool.edit" | "tool.bash" | "tool.ssh" | "tool.lsp" | "tool.gh" | "tool.webSearch" | "tool.exa" | "tool.browser" | "tool.eval" | "tool.debug" | "tool.mcp" | "tool.job" | "tool.task" | "tool.todo" | "tool.memory" | "tool.ask" | "tool.resolve" | "tool.review" | "tool.inspectImage" | "tool.goal" | "tool.irc";
 export type SpinnerType = "status" | "activity";
 export type ThemeColor = "accent" | "border" | "borderAccent" | "borderMuted" | "success" | "error" | "warning" | "muted" | "dim" | "text" | "thinkingText" | "userMessageText" | "customMessageText" | "customMessageLabel" | "toolTitle" | "toolOutput" | "mdHeading" | "mdLink" | "mdLinkUrl" | "mdCode" | "mdCodeBlock" | "mdCodeBlockBorder" | "mdQuote" | "mdQuoteBorder" | "mdHr" | "mdListBullet" | "toolDiffAdded" | "toolDiffRemoved" | "toolDiffContext" | "syntaxComment" | "syntaxKeyword" | "syntaxFunction" | "syntaxVariable" | "syntaxString" | "syntaxNumber" | "syntaxType" | "syntaxOperator" | "syntaxPunctuation" | "thinkingOff" | "thinkingMinimal" | "thinkingLow" | "thinkingMedium" | "thinkingHigh" | "thinkingXhigh" | "bashMode" | "pythonMode" | "statusLineSep" | "statusLineModel" | "statusLinePath" | "statusLineGitClean" | "statusLineGitDirty" | "statusLineContext" | "statusLineSpend" | "statusLineStaged" | "statusLineDirty" | "statusLineUntracked" | "statusLineOutput" | "statusLineCost" | "statusLineSubagents";
 /** Check if a string is a valid ThemeColor value */
@@ -123,6 +123,11 @@ export declare class Theme {
         bottomRight: string;
         horizontal: string;
         vertical: string;
+        cross: string;
+        teeDown: string;
+        teeUp: string;
+        teeRight: string;
+        teeLeft: string;
     };
     get boxSharp(): {
         topLeft: string;
@@ -173,6 +178,7 @@ export declare class Theme {
         agents: string;
         job: string;
         cache: string;
+        cacheMiss: string;
         input: string;
         output: string;
         host: string;

package/dist/types/modes/types.d.ts

@@ -1,6 +1,6 @@
 import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import type { CompactionOutcome } from "@oh-my-pi/pi-agent-core/compaction";
-import type { AssistantMessage, ImageContent, Message, UsageReport } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage, ImageContent, Message, Usage, UsageReport } from "@oh-my-pi/pi-ai";
 import type { Component, Container, EditorTheme, Loader, Spacer, Text, TUI } from "@oh-my-pi/pi-tui";
 import type { CollabGuestLink } from "../collab/guest";
 import type { CollabHost } from "../collab/host";
@@ -140,6 +140,12 @@ export interface InteractiveModeContext {
     isPythonMode: boolean;
     streamingComponent: AssistantMessageComponent | undefined;
     streamingMessage: AssistantMessage | undefined;
+    /**
+     * Usage of the most recently rendered assistant turn, used to detect a
+     * prompt-cache invalidation on the next turn (cache footprint collapse).
+     * Reseeded by `renderSessionContext` on every rebuild/session switch.
+     */
+    lastAssistantUsage: Usage | undefined;
     loadingAnimation: Loader | undefined;
     autoCompactionLoader: Loader | undefined;
     retryLoader: Loader | undefined;

package/dist/types/sdk.d.ts

@@ -288,7 +288,7 @@ export interface BuildSystemPromptOptions {
     }>;
     cwd?: string;
     appendPrompt?: string;
-    repeatToolDescriptions?: boolean;
+    inlineToolDescriptors?: boolean;
 }
 /**
  * Build the default provider-facing system prompt blocks.

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

@@ -13,7 +13,7 @@
  * Modes use this class and add their own I/O layer on top.
  */
 import type { InMemorySnapshotStore } from "@oh-my-pi/hashline";
-import { Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import { Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, ThinkingLevel, type ToolChoiceDirective } from "@oh-my-pi/pi-agent-core";
 import { type CompactionResult, type ShakeConfig } from "@oh-my-pi/pi-agent-core/compaction";
 import type { AssistantMessage, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ResetCreditAccountStatus, ResetCreditRedeemOutcome, ResetCreditTarget, ServiceTier, SimpleStreamOptions, TextContent, ToolChoice, UsageReport } from "@oh-my-pi/pi-ai";
 import { Effort } from "@oh-my-pi/pi-ai";
@@ -237,6 +237,12 @@ export interface AgentSessionConfig {
     advisorReadOnlyTools?: AgentTool[];
     /** Preloaded watchdog prompt content for the advisor. */
     advisorWatchdogPrompt?: string;
+    /**
+     * Strip tool descriptions from provider-bound tool specs on side requests
+     * (handoff). Must match the session-start value used to build the system
+     * prompt so inline descriptors are not also sent through provider schemas.
+     */
+    pruneToolDescriptions?: boolean;
     /**
      * Disconnect this session's OWNED MCP manager on dispose. Provided only when
      * the session created the manager (top-level sessions); subagents reuse a
@@ -380,6 +386,19 @@ export declare class AgentSession {
     getAgentId(): string | undefined;
     /** Advance the tool-choice queue and return the next directive for the upcoming LLM call. */
     nextToolChoice(): ToolChoice | undefined;
+    /**
+     * The per-turn tool-choice directive for the agent loop's `getToolChoice`. Priority:
+     *   1. a HARD forced choice from the queue (genuine forces: user-force, eager-todo, …) —
+     *      consuming, unchanged from `nextToolChoice`;
+     *   2. else, when a non-forcing preview is pending, a {@link SoftToolRequirement} — a
+     *      PEEK (advances/pops nothing), so the agent-loop injects the reminder once per head
+     *      and escalates to a forced `resolve` only if the model declines. A compliant turn
+     *      pays ZERO tool_choice change (no prompt-cache messages-cache invalidation);
+     *   3. else undefined.
+     */
+    nextToolChoiceDirective(): ToolChoiceDirective | undefined;
+    /** Peek the head non-forcing pending preview invoker, for the `resolve` tool's dispatch. */
+    peekPendingInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
     /**
      * Force the next model call to target a specific active tool, then terminate
      * the agent loop. Pushes a two-step sequence [forced, "none"] so the model

package/dist/types/session/session-context.d.ts

@@ -17,6 +17,13 @@ export interface SessionContext {
     mode: string;
     /** Mode-specific data from the last mode_change entry */
     modeData?: Record<string, unknown>;
+    /**
+     * Array parallel to messages, indicating which assistant turns should
+     * have their prompt-cache misses suppressed/explained (because a model,
+     * compaction, or plan-mode transition directly preceded them).
+     * Only populated in transcript mode.
+     */
+    cacheMissExplainedAt?: boolean[];
 }
 /** Lists session model strings to try when restoring, in fallback order. */
 export declare function getRestorableSessionModels(models: Readonly<Record<string, string>>, lastModelChangeRole: string | undefined): string[];

package/dist/types/session/session-dump-format.d.ts

@@ -21,6 +21,7 @@ export interface FormatSessionDumpTextOptions {
     model?: Model | null;
     thinkingLevel?: ThinkingLevel | string | null;
     tools?: readonly SessionDumpToolInfo[];
+    inlineToolDescriptors?: boolean;
 }
 /**
  * Format messages and session metadata as markdown/plain text (same as

package/dist/types/session/tool-choice-queue.d.ts

@@ -67,6 +67,20 @@ export declare class ToolChoiceQueue {
     get hasInFlight(): boolean;
     /** Return the in-flight directive's onInvoked handler and mark it when called. */
     peekInFlightInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    /** Register (or replace by exact id) a non-forcing pending preview invoker. */
+    registerPendingInvoker(id: string, sourceToolName: string, onInvoked: (input: unknown) => Promise<unknown> | unknown): void;
+    /** Drop the pending invoker with this id (e.g. after it resolves). */
+    removePendingInvoker(id: string): void;
+    /** True when at least one non-forcing pending preview is registered. */
+    get hasPendingInvoker(): boolean;
+    /** The head (most-recently registered) pending invoker's handler, for resolve dispatch. */
+    peekPendingInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    /** The head pending preview's stable id + source tool, for building the agent-level
+     *  SoftToolRequirement (the id drives reminder re-injection when the head changes). */
+    peekPendingHead(): {
+        id: string;
+        sourceToolName: string;
+    } | undefined;
     /** Remove all directives with the given label. Rejects in-flight if it matches. */
     removeByLabel(label: string): void;
     /** Empty the queue and reject any in-flight yield. */

package/dist/types/system-prompt.d.ts

@@ -54,11 +54,11 @@ export interface BuildSystemPromptOptions {
     toolNames?: string[];
     /** Text to append to system prompt. */
     appendSystemPrompt?: string;
-    /** Repeat full tool descriptions in system prompt. Default: false */
-    repeatToolDescriptions?: boolean;
+    /** Inline full tool descriptors in the system prompt. Default: true */
+    inlineToolDescriptors?: boolean;
     /**
      * Whether provider-native tool calling is active (no owned/in-band syntax).
-     * When true and `repeatToolDescriptions` is false, the inventory renders as a
+     * When true and `inlineToolDescriptors` is false, the inventory renders as a
      * compact tool-name list; otherwise it renders full `# Tool:` sections. Default: true
      */
     nativeTools?: boolean;

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

@@ -272,6 +272,10 @@ export interface ToolSession {
     }): void;
     /** Peek the currently in-flight tool-choice queue directive's invocation handler. Used by the `resolve` tool to dispatch to the pending action. */
     peekQueueInvoker?(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    /** Peek the most-recently registered non-forcing pending preview invoker. The `resolve`
+     *  tool dispatches to it so a staged preview resolves WITHOUT forcing tool_choice — the
+     *  agent-loop's SoftToolRequirement lifecycle owns reminder injection and escalation. */
+    peekPendingInvoker?(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
     /** Peek the long-lived "standing" resolve handler registered by a mode (e.g. plan mode).
      *  Consulted by the `resolve` tool as a fallback when no queue invoker is in flight,
      *  letting modes accept `resolve` invocations without forcing the tool choice every turn. */

package/dist/types/tools/resolve.d.ts

@@ -1,4 +1,4 @@
-import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, CustomMessage } from "@oh-my-pi/pi-agent-core";
 import type { Component } from "@oh-my-pi/pi-tui";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
@@ -18,10 +18,13 @@ export interface ResolveToolDetails {
     sourceResultDetails?: unknown;
 }
 /**
- * Queue a resolve-protocol handler on the tool-choice queue. Forces the next
- * LLM call to invoke the hidden `resolve` tool, wraps the caller's apply/reject
- * callbacks into an onInvoked closure that matches the resolve schema, and
- * steers a preview reminder so the model understands why.
+ * Register a non-forcing resolve-protocol handler for a staged preview. Wraps the
+ * caller's apply/reject into an onInvoked closure (matching the resolve schema) and
+ * stores it on the tool-choice queue's pending-invoker registry under a UNIQUE id.
+ * The `resolve` tool dispatches to it; the agent-loop's SoftToolRequirement
+ * lifecycle injects the preview reminder and escalates to a forced `resolve` only
+ * if the model declines — so a compliant turn pays ZERO tool_choice change (no
+ * prompt-cache messages-cache invalidation).
  *
  * This is the canonical entry point for any tool that wants preview/apply
  * semantics. No session-level abstraction is needed: callers pass their
@@ -33,6 +36,13 @@ export declare function queueResolveHandler(session: ToolSession, options: {
     apply(reason: string, extra?: Record<string, unknown>): Promise<AgentToolResult<unknown>>;
     reject?(reason: string, extra?: Record<string, unknown>): Promise<AgentToolResult<unknown> | undefined>;
 }): void;
+/**
+ * The canonical preview reminder. The resolve mechanism owns the wording; the
+ * agent-loop delivers it via the session's `SoftToolRequirement.reminder` (injected
+ * once per pending-preview head) instead of a host-side steer, so it lands as a
+ * stable mid-history append and never churns the cached prefix.
+ */
+export declare function buildResolveReminderMessage(sourceToolName: string): CustomMessage;
 /**
  * Shared invocation runner used by both queued (in-flight) handlers and
  * standing handlers (e.g. plan-mode approval). Discriminates on action,

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "16.0.11",
+	"version": "16.1.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -48,17 +48,17 @@
 		"@agentclientprotocol/sdk": "0.25.0",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "16.0.11",
-		"@oh-my-pi/omp-stats": "16.0.11",
-		"@oh-my-pi/pi-agent-core": "16.0.11",
-		"@oh-my-pi/pi-ai": "16.0.11",
-		"@oh-my-pi/pi-catalog": "16.0.11",
-		"@oh-my-pi/pi-mnemopi": "16.0.11",
-		"@oh-my-pi/pi-natives": "16.0.11",
-		"@oh-my-pi/pi-tui": "16.0.11",
-		"@oh-my-pi/pi-utils": "16.0.11",
-		"@oh-my-pi/pi-wire": "16.0.11",
-		"@oh-my-pi/snapcompact": "16.0.11",
+		"@oh-my-pi/hashline": "16.1.0",
+		"@oh-my-pi/omp-stats": "16.1.0",
+		"@oh-my-pi/pi-agent-core": "16.1.0",
+		"@oh-my-pi/pi-ai": "16.1.0",
+		"@oh-my-pi/pi-catalog": "16.1.0",
+		"@oh-my-pi/pi-mnemopi": "16.1.0",
+		"@oh-my-pi/pi-natives": "16.1.0",
+		"@oh-my-pi/pi-tui": "16.1.0",
+		"@oh-my-pi/pi-utils": "16.1.0",
+		"@oh-my-pi/pi-wire": "16.1.0",
+		"@oh-my-pi/snapcompact": "16.1.0",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/context-async-hooks": "^2.7.1",
 		"@opentelemetry/exporter-trace-otlp-proto": "^0.218.0",

package/src/config/settings-schema.ts

@@ -849,6 +849,17 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	"display.cacheMissMarker": {
+		type: "boolean",
+		default: true,
+		ui: {
+			tab: "appearance",
+			group: "Display",
+			label: "Cache Miss Marker",
+			description: "Show a divider above an assistant turn whose request lost (missed) the prompt cache",
+		},
+	},
+
 	showHardwareCursor: {
 		type: "boolean",
 		default: true, // will be computed based on platform if undefined
@@ -914,14 +925,15 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
-	repeatToolDescriptions: {
+	inlineToolDescriptors: {
 		type: "boolean",
-		default: false,
+		default: true,
 		ui: {
 			tab: "model",
 			group: "Prompt",
-			label: "Repeat Tool Descriptions",
-			description: "Render full tool descriptions in the system prompt instead of a tool name list",
+			label: "Inline Tool Descriptors",
+			description:
+				"Render full tool descriptors in the system prompt and strip top-level/nested descriptions from provider tool schemas so descriptor text is sent once",
 		},
 	},
 

package/src/debug/log-viewer.ts

@@ -866,21 +866,21 @@ export class DebugLogViewerComponent implements Component {
 	}
 
 	#frameTop(innerWidth: number): string {
-		return `${theme.boxSharp.topLeft}${theme.boxSharp.horizontal.repeat(innerWidth)}${theme.boxSharp.topRight}`;
+		return `${theme.boxRound.topLeft}${theme.boxRound.horizontal.repeat(innerWidth)}${theme.boxRound.topRight}`;
 	}
 
 	#frameSeparator(innerWidth: number): string {
-		return `${theme.boxSharp.teeRight}${theme.boxSharp.horizontal.repeat(innerWidth)}${theme.boxSharp.teeLeft}`;
+		return `${theme.boxRound.teeRight}${theme.boxRound.horizontal.repeat(innerWidth)}${theme.boxRound.teeLeft}`;
 	}
 
 	#frameBottom(innerWidth: number): string {
-		return `${theme.boxSharp.bottomLeft}${theme.boxSharp.horizontal.repeat(innerWidth)}${theme.boxSharp.bottomRight}`;
+		return `${theme.boxRound.bottomLeft}${theme.boxRound.horizontal.repeat(innerWidth)}${theme.boxRound.bottomRight}`;
 	}
 
 	#frameLine(content: string, innerWidth: number): string {
 		const truncated = truncateToWidth(content, innerWidth);
 		const remaining = Math.max(0, innerWidth - visibleWidth(truncated));
-		return `${theme.boxSharp.vertical}${truncated}${padding(remaining)}${theme.boxSharp.vertical}`;
+		return `${theme.boxRound.vertical}${truncated}${padding(remaining)}${theme.boxRound.vertical}`;
 	}
 
 	#copySelected() {

package/src/debug/raw-sse.ts

@@ -273,20 +273,20 @@ export class RawSseViewerComponent implements Component {
 	}
 
 	#frameTop(innerWidth: number): string {
-		return `${theme.boxSharp.topLeft}${theme.boxSharp.horizontal.repeat(innerWidth)}${theme.boxSharp.topRight}`;
+		return `${theme.boxRound.topLeft}${theme.boxRound.horizontal.repeat(innerWidth)}${theme.boxRound.topRight}`;
 	}
 
 	#frameSeparator(innerWidth: number): string {
-		return `${theme.boxSharp.teeRight}${theme.boxSharp.horizontal.repeat(innerWidth)}${theme.boxSharp.teeLeft}`;
+		return `${theme.boxRound.teeRight}${theme.boxRound.horizontal.repeat(innerWidth)}${theme.boxRound.teeLeft}`;
 	}
 
 	#frameBottom(innerWidth: number): string {
-		return `${theme.boxSharp.bottomLeft}${theme.boxSharp.horizontal.repeat(innerWidth)}${theme.boxSharp.bottomRight}`;
+		return `${theme.boxRound.bottomLeft}${theme.boxRound.horizontal.repeat(innerWidth)}${theme.boxRound.bottomRight}`;
 	}
 
 	#frameLine(content: string, innerWidth: number): string {
 		const truncated = truncateToWidth(content, innerWidth);
 		const remaining = Math.max(0, innerWidth - visibleWidth(truncated));
-		return `${theme.boxSharp.vertical}${truncated}${padding(remaining)}${theme.boxSharp.vertical}`;
+		return `${theme.boxRound.vertical}${truncated}${padding(remaining)}${theme.boxRound.vertical}`;
 	}
 }

package/src/edit/renderer.ts

@@ -275,8 +275,8 @@ function formatEditDescription(
 }
 
 function editHeaderLabelBudget(width: number, uiTheme: Theme): number {
-	const leftGlyphs = `${uiTheme.boxSharp.topLeft}${uiTheme.boxSharp.horizontal.repeat(3)}`;
-	return Math.max(0, width - visibleWidth(leftGlyphs) - visibleWidth(uiTheme.boxSharp.topRight) - 2);
+	const leftGlyphs = `${uiTheme.boxRound.topLeft}${uiTheme.boxRound.horizontal.repeat(3)}`;
+	return Math.max(0, width - visibleWidth(leftGlyphs) - visibleWidth(uiTheme.boxRound.topRight) - 2);
 }
 
 function renderEditHeader(