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

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

@@ -1,3 +1,4 @@
 export * from "./advise-tool";
 export * from "./runtime";
+export * from "./transcript-recorder";
 export * from "./watchdog";

package/dist/types/advisor/transcript-recorder.d.ts

@@ -0,0 +1,52 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+/**
+ * Reserved transcript stem for advisor session files. Chosen so it cannot
+ * collide with a task subagent's `<id>.jsonl` (task ids are reserved against
+ * this exact stem in {@link AgentOutputManager}).
+ */
+export declare const ADVISOR_TRANSCRIPT_STEM = "__advisor";
+export declare const ADVISOR_TRANSCRIPT_FILENAME = "__advisor.jsonl";
+/**
+ * Append-only persister for an advisor agent's transcript.
+ *
+ * The advisor is a passive reviewer with its own model usage, so — like a task
+ * subagent — its turns are written to a JSONL inside the owning session's
+ * artifacts dir (`<session>/__advisor.jsonl`, `<session>/<SubId>/__advisor.jsonl`
+ * for subagent advisors). That single file gives the advisor model proper usage
+ * attribution in `omp stats` (the stats parser scans the session dir
+ * recursively) and a read-only transcript in the Agent Hub, without making the
+ * advisor a registered, messageable peer.
+ *
+ * The target is derived from the *session file* (`getSessionFile()`), never
+ * `getArtifactsDir()` — subagents adopt the parent's artifact manager, so the
+ * artifacts dir points at the parent root and every subagent advisor would
+ * collide. The file path is resolved synchronously when a message finalizes and
+ * captured for the queued write, so a `/new`, resume, or session switch in
+ * flight can never misattribute an old advisor turn into the new session's file.
+ * On such a switch the previous writer is closed and the new file opened on the
+ * next recorded turn. The recorder never truncates: the advisor's in-memory
+ * context resets/compacts independently, but every billed turn is appended here.
+ */
+export declare class AdvisorTranscriptRecorder {
+    #private;
+    private readonly resolveSessionFile;
+    private readonly resolveCwd;
+    /**
+     * @param after Optional barrier the queue starts behind — used on the advisor
+     *   on→off→on toggle so a fresh recorder's first `open` waits for the prior
+     *   recorder's `close` and the two never hold the same `__advisor.jsonl` at once.
+     */
+    constructor(resolveSessionFile: () => string | undefined, resolveCwd: () => string, after?: Promise<unknown>);
+    /**
+     * Persist one finalized advisor message. Assistant turns carry the usage the
+     * stats parser reads; tool results round out the Hub transcript; user deltas
+     * (the advisor's "session update" prompts) are persisted but flagged
+     * `synthetic`/agent-attributed so they never inflate user-message metrics.
+     * Non-conversational message kinds are skipped.
+     */
+    record(message: AgentMessage): void;
+    /** Flush pending writes (best-effort). */
+    flush(): Promise<void>;
+    /** Flush and close the writer, releasing the session file. */
+    close(): Promise<void>;
+}

package/dist/types/commit/agentic/agent.d.ts

@@ -1,4 +1,4 @@
-import { type ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Api, Model } from "@oh-my-pi/pi-ai";
 import type { ModelRegistry } from "../../config/model-registry";
 import type { Settings } from "../../config/settings";

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

@@ -775,10 +775,6 @@ export declare const SETTINGS_SCHEMA: {
             readonly description: "Remove the 1-character horizontal padding from the left and right of the terminal output";
         };
     };
-    readonly "display.tabWidth": {
-        readonly type: "number";
-        readonly default: 3;
-    };
     readonly "display.shimmer": {
         readonly type: "enum";
         readonly values: readonly ["classic", "kitt", "disabled"];
@@ -823,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;
@@ -875,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/edit/file-snapshot-store.d.ts

@@ -48,7 +48,7 @@ export declare function recordFileSnapshot(session: FileSnapshotStoreOwner, abso
 /**
  * The 1-indexed file lines a hashline-formatted body actually displayed.
  * Single `NN:` rows contribute that line; a collapsed summary `NN-MM:` row
- * (a `{ .. }` brace pair) contributes only its boundary lines `NN` and `MM` —
+ * (a `{ … }` brace pair) contributes only its boundary lines `NN` and `MM` —
  * the elided interior was never shown, so editing inside it must be rejected.
  */
 export declare function parseSeenLinesFromHashlineBody(body: string): number[];

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

@@ -25,6 +25,7 @@ import type * as PiCodingAgent from "../../index";
 import type { MemoryRuntimeContext } from "../../memory-backend";
 import type { CustomEditor } from "../../modes/components/custom-editor";
 import type { Theme } from "../../modes/theme/theme";
+import type { CompactMode } from "../../session/compact-modes";
 import type { CustomMessage } from "../../session/messages";
 import type { ReadonlySessionManager, SessionManager } from "../../session/session-manager";
 import type { BashToolDetails, BashToolInput, FindToolDetails, FindToolInput, ReadToolDetails, ReadToolInput, SearchToolDetails, SearchToolInput, WriteToolInput } from "../../tools";
@@ -171,6 +172,12 @@ export interface ContextUsage {
 export interface CompactOptions {
     onComplete?: (result: CompactionResult) => void;
     onError?: (error: Error) => void;
+    /**
+     * Force a one-off compaction mode for this invocation, overriding the
+     * configured `compaction.strategy` / `remoteEnabled` (the `/compact`
+     * subcommands: `soft` | `remote` | `snapcompact`). Omitted = configured behavior.
+     */
+    mode?: CompactMode;
 }
 /**
  * Context passed to extension event handlers.

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

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

package/dist/types/modes/components/agent-hub.d.ts

@@ -62,6 +62,11 @@ export declare class AgentHubOverlayComponent extends Container {
     dispose(): void;
     render(width: number): readonly string[];
     handleInput(keyData: string): void;
-    /** Open the chat view for an agent id (public for table Enter and tests). */
+    /**
+     * Open the fullscreen transcript viewer for an agent id (public for table Enter
+     * and tests). Mounts {@link AgentTranscriptViewer} as a `fullscreen` overlay so it
+     * owns the alternate screen; the hub table stays mounted underneath and is
+     * restored when the viewer closes. No-op without a real TUI (render-only test stub).
+     */
     openChat(id: string): void;
 }

package/dist/types/modes/components/agent-transcript-viewer.d.ts

@@ -0,0 +1,39 @@
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import { type Component, type TUI } from "@oh-my-pi/pi-tui";
+import type { KeyId } from "../../config/keybindings";
+import type { MessageRenderer } from "../../extensibility/extensions/types";
+import type { AgentLifecycleManager } from "../../registry/agent-lifecycle";
+import type { AgentRegistry } from "../../registry/agent-registry";
+import type { SessionObserverRegistry } from "../session-observer-registry";
+import type { AgentHubRemote } from "./agent-hub";
+export interface AgentTranscriptViewerDeps {
+    agentId: string;
+    registry: AgentRegistry;
+    /** Collab guest: read transcript from the host instead of a local file. */
+    remote?: AgentHubRemote;
+    /** Progress/cost snapshot source for the stats line. */
+    observers?: SessionObserverRegistry;
+    /** Revive+prompt path for messageable local agents. Lazy to avoid touching the global. */
+    lifecycle?: () => AgentLifecycleManager;
+    ui: TUI;
+    getTool?: (name: string) => AgentTool | undefined;
+    getMessageRenderer?: (customType: string) => MessageRenderer | undefined;
+    cwd: string;
+    hideThinkingBlock?: () => boolean;
+    expandKeys: KeyId[];
+    /** Keys that toggle the whole hub closed (app.agents.hub + app.session.observe). */
+    hubKeys: KeyId[];
+    requestRender: () => void;
+    /** Close just this viewer (Esc), returning to the hub table. */
+    onClose: () => void;
+    /** Close this viewer AND the hub (hub-toggle keys). */
+    onHubClose: () => void;
+}
+export declare class AgentTranscriptViewer implements Component {
+    #private;
+    private readonly deps;
+    constructor(deps: AgentTranscriptViewerDeps);
+    dispose(): void;
+    handleInput(data: string): void;
+    render(width: number): readonly string[];
+}

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/chat-transcript-builder.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Builds transcript components from persisted session message entries — the
+ * file/remote-backed counterpart to {@link UiHelpers.addMessageToChat} (which is
+ * bound to the live InteractiveModeContext). Used by the fullscreen transcript
+ * viewer ({@link AgentTranscriptViewer}) to render a parked subagent / advisor /
+ * collab-guest transcript that has no live session.
+ *
+ * Unlike the old incremental hub sync, {@link ChatTranscriptBuilder.rebuild}
+ * always discards prior components and rebuilds the whole transcript from the
+ * supplied entries. Re-rendering a growing transcript is therefore O(n) in the
+ * entry count, but it cannot duplicate or misorder rows the way incremental
+ * component reuse could.
+ */
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import { type TUI } from "@oh-my-pi/pi-tui";
+import type { MessageRenderer } from "../../extensibility/extensions/types";
+import type { SessionMessageEntry } from "../../session/session-entries";
+import { TranscriptContainer } from "./transcript-container";
+export interface ChatTranscriptBuilderDeps {
+    ui: TUI;
+    getTool?: (name: string) => AgentTool | undefined;
+    getMessageRenderer?: (customType: string) => MessageRenderer | undefined;
+    cwd: string;
+    hideThinkingBlock?: () => boolean;
+    requestRender: () => void;
+}
+export declare class ChatTranscriptBuilder {
+    #private;
+    private readonly deps;
+    readonly container: TranscriptContainer;
+    constructor(deps: ChatTranscriptBuilderDeps);
+    /** Whether the transcript currently holds any rendered rows. */
+    get isEmpty(): boolean;
+    /** Discard all components and rebuild the whole transcript from `entries`. */
+    rebuild(entries: SessionMessageEntry[]): void;
+    /** Toggle tool-output expansion across every expandable component. */
+    setExpanded(expanded: boolean): void;
+    get expanded(): boolean;
+    /** Tear down components (sealing pending spinners) and clear build state. */
+    reset(): void;
+    dispose(): void;
+}

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/controllers/command-controller.d.ts

@@ -3,6 +3,7 @@ import { type ProviderDetails, type UsageReport } from "@oh-my-pi/pi-ai";
 import type { CompactOptions } from "../../extensibility/extensions/types";
 import { theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext } from "../../modes/types";
+import type { CompactMode } from "../../session/compact-modes";
 import { type ShakeMode } from "../../session/shake-types";
 export declare class CommandController {
     #private;
@@ -31,14 +32,14 @@ export declare class CommandController {
     handleRenameCommand(title: string): Promise<void>;
     handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;
     handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
-    handleCompactCommand(customInstructions?: string, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
+    handleCompactCommand(customInstructions?: string, mode?: CompactMode, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
     /**
      * TUI handler for `/shake`. `elide` drops heavy structural content and
      * `images` strips image blocks. Rebuilds the chat and reports counts.
      */
     handleShakeCommand(mode: ShakeMode): Promise<void>;
     handleSkillCommand(skillPath: string, args: string): Promise<void>;
-    executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
+    executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>, mode?: CompactMode): Promise<CompactionOutcome>;
     handleHandoffCommand(customInstructions?: string): Promise<void>;
 }
 export declare function renderProviderSection(details: ProviderDetails, uiTheme: Pick<typeof theme, "fg">): string;

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";
@@ -12,6 +12,7 @@ import type { CompactOptions } from "../extensibility/extensions/types";
 import type { MCPManager } from "../mcp";
 import { type PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { AgentSession } from "../session/agent-session";
+import type { CompactMode } from "../session/compact-modes";
 import { HistoryStorage } from "../session/history-storage";
 import type { SessionContext } from "../session/session-context";
 import type { SessionManager } from "../session/session-manager";
@@ -118,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;
@@ -298,7 +300,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
     handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
     handleMCPCommand(text: string): Promise<void>;
     handleSSHCommand(text: string): Promise<void>;
-    handleCompactCommand(customInstructions?: string, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
+    handleCompactCommand(customInstructions?: string, mode?: CompactMode, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
     handleHandoffCommand(customInstructions?: string): Promise<void>;
     handleShakeCommand(mode: ShakeMode): Promise<void>;
     executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<CompactionOutcome>;

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";
@@ -11,6 +11,7 @@ import type { CompactOptions } from "../extensibility/extensions/types";
 import type { MCPManager } from "../mcp";
 import type { PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { AgentSession } from "../session/agent-session";
+import type { CompactMode } from "../session/compact-modes";
 import type { HistoryStorage } from "../session/history-storage";
 import type { SessionContext } from "../session/session-context";
 import type { SessionManager } from "../session/session-manager";
@@ -139,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;
@@ -273,7 +280,7 @@ export interface InteractiveModeContext {
     handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
     handleMCPCommand(text: string): Promise<void>;
     handleSSHCommand(text: string): Promise<void>;
-    handleCompactCommand(customInstructions?: string): Promise<CompactionOutcome>;
+    handleCompactCommand(customInstructions?: string, mode?: CompactMode): Promise<CompactionOutcome>;
     handleHandoffCommand(customInstructions?: string): Promise<void>;
     handleShakeCommand(mode: ShakeMode): Promise<void>;
     handleMoveCommand(targetPath: string): Promise<void>;

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

@@ -18,7 +18,13 @@ export declare const MAIN_AGENT_ID = "Main";
  * - `aborted`: hard-killed, terminal.
  */
 export type AgentStatus = "running" | "idle" | "parked" | "aborted";
-export type AgentKind = "main" | "sub";
+/**
+ * - `main`/`sub`: the user-facing agent tree (driving agent + task subagents).
+ * - `advisor`: a passive review transcript persisted like a subagent for usage
+ *   attribution and Agent Hub observability, but never a peer — hidden from
+ *   agent-facing rosters (`irc`, `history://`) and not messageable/revivable.
+ */
+export type AgentKind = "main" | "sub" | "advisor";
 export interface AgentRef {
     id: string;
     displayName: string;
@@ -81,8 +87,9 @@ export declare class AgentRegistry {
     get(id: string): AgentRef | undefined;
     list(): AgentRef[];
     /**
-     * Returns every alive agent (running | idle) except the caller.
-     * Flat namespace: every agent can see every other agent.
+     * Returns every alive agent (running | idle) except the caller. Advisor refs
+     * are observability-only transcripts, never peers, so they are excluded.
+     * Flat namespace: every other agent is visible.
      */
     listVisibleTo(id: string): AgentRef[];
     onChange(listener: RegistryListener): () => void;

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