@oh-my-pi/pi-coding-agent 17.0.9 → 17.1.0

package/dist/types/mcp/smithery-auth.d.ts

@@ -2,7 +2,7 @@ type SmitheryCliAuthSession = {
     sessionId: string;
     authUrl: string;
 };
-type SmitheryCliPollResponse = {
+export type SmitheryCliPollResponse = {
     status: "pending" | "success" | "error";
     apiKey?: string;
     message?: string;

package/dist/types/mcp/smithery-auth.test.d.ts

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

package/dist/types/memory-backend/tool-names.d.ts

@@ -0,0 +1,2 @@
+/** Built-in tools whose availability depends on the selected memory backend. */
+export declare const MEMORY_BACKEND_TOOL_NAMES: readonly ["retain", "recall", "reflect", "memory_edit", "learn"];

package/dist/types/modes/components/login-dialog.d.ts

@@ -15,8 +15,8 @@ export declare class LoginDialogComponent extends Container {
      * is offered as an additional local shortcut so narrow local terminals still
      * have a truncation-safe copy target (viewport clipping on a long authorize
      * URL silently drops trailing OAuth query parameters — e.g.
-     * `code_challenge_method=S256`). The OSC 8 hyperlink carries the full URL
-     * for terminals that support click-through.
+     * `code_challenge_method=S256`). Every physical URL row carries its own OSC 8
+     * link to the full URL, so clicking any wrapped fragment opens the same target.
      */
     showAuth(url: string, instructions?: string, launchUrl?: string): void;
     /**

package/dist/types/modes/components/plan-review-overlay.d.ts

@@ -18,6 +18,28 @@
  */
 import { type Component } from "@oh-my-pi/pi-tui";
 import type { HookSelectorSlider } from "./hook-selector.js";
+/** Serializable annotations retained by the plan-review owner between overlays. */
+export interface PlanReviewAnnotationState {
+    annotations: Array<{
+        section: {
+            index: number;
+            title: string;
+            /** Heading ancestry from the document root, when emitted by this overlay. */
+            path?: string[];
+            /** Hash of the section source, used to reject ambiguous moved headings. */
+            contentHash?: string;
+        };
+        target: {
+            kind: "section";
+        } | {
+            kind: "line";
+            row: number;
+            context: string;
+            contextTruncated?: boolean;
+        };
+        note: string;
+    }>;
+}
 export interface PlanReviewOverlayCallbacks {
     /** Invoked with the chosen option label (never a disabled one). */
     onPick: (label: string) => void;
@@ -33,6 +55,8 @@ export interface PlanReviewOverlayCallbacks {
     onPlanEdited?: (content: string) => void;
     /** Invoked with the Refine feedback markdown whenever annotations change. */
     onFeedbackChange?: (feedback: string) => void;
+    /** Invoked with a serializable annotation snapshot whenever annotations change. */
+    onAnnotationStateChange?: (state: PlanReviewAnnotationState) => void;
 }
 export interface PlanReviewOverlayOptions {
     /** Prompt rendered above the options (e.g. "Plan mode - next step"). */
@@ -48,6 +72,8 @@ export interface PlanReviewOverlayOptions {
     slider?: HookSelectorSlider;
     /** Display label for the external-editor key, surfaced in the footer help. */
     externalEditorLabel?: string;
+    /** Serializable annotations restored into this overlay instance. */
+    annotationState?: PlanReviewAnnotationState;
 }
 export declare class PlanReviewOverlay implements Component {
     #private;

package/dist/types/modes/components/settings-defs.d.ts

@@ -45,7 +45,13 @@ export interface TextInputSettingDef extends BaseSettingDef {
 export interface ProviderLimitsSettingDef extends BaseSettingDef {
     type: "providerLimits";
 }
-export type SettingDef = BooleanSettingDef | EnumSettingDef | SubmenuSettingDef | TextInputSettingDef | ProviderLimitsSettingDef;
+/** Array-of-enum setting edited as a toggle list; `ordered` lists render positions and support reordering. */
+export interface MultiSelectSettingDef extends BaseSettingDef {
+    type: "multiselect";
+    options: OptionList;
+    ordered: boolean;
+}
+export type SettingDef = BooleanSettingDef | EnumSettingDef | SubmenuSettingDef | TextInputSettingDef | ProviderLimitsSettingDef | MultiSelectSettingDef;
 /** Get all setting definitions with UI */
 export declare function getAllSettingDefs(): SettingDef[];
 /**

package/dist/types/modes/components/status-line/component.jj-cache.test.d.ts

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

package/dist/types/modes/components/tool-execution.d.ts

@@ -92,7 +92,15 @@ export declare class ToolExecutionComponent extends Container implements NativeS
      * immutable native scrollback before the result replaces them.
      */
     getNativeScrollbackLiveRegionStart(): number | undefined;
-    /** Keeps the in-flight `vibe_wait` TV wall out of immutable native scrollback. */
+    /**
+     * Keeps in-flight TV-wall frames out of immutable native scrollback: the
+     * `vibe_wait` wall and displaceable snapshots (`hub` waiting polls, `todo`
+     * lists). Their frames replace each other rather than append, and their
+     * rows mutate every spinner tick — an unpinned commit records a per-tick
+     * frozen snapshot AND force-seals the block (see TranscriptContainer's
+     * committed-snapshot seal), so the next poll stacks a new frame instead of
+     * displacing this one.
+     */
     isNativeScrollbackLiveRegionPinned(): boolean;
     /**
      * Whether this block has reached a terminal state for transcript freezing.

package/dist/types/modes/controllers/command-controller.d.ts

@@ -60,4 +60,4 @@ export declare function renderProviderSection(details: ProviderDetails, uiTheme:
  * Example output: `Quota: 7d window · 67% used · resets in 3.2d`
  */
 export declare function formatCompactQuota(provider: string, reports: UsageReport[], nowMs: number, activeAccount?: OAuthAccountIdentity): string | null;
-export declare function renderUsageReports(reports: UsageReport[], uiTheme: typeof theme, nowMs: number, availableWidth: number, resolveActiveAccount?: (provider: string) => OAuthAccountIdentity | undefined): string;
+export declare function renderUsageReports(reports: UsageReport[], uiTheme: typeof theme, nowMs: number, availableWidth: number, resolveActiveAccount?: (provider: string) => OAuthAccountIdentity | undefined, usageModelSelectors?: readonly string[]): string;

package/dist/types/modes/controllers/event-controller.d.ts

@@ -24,5 +24,10 @@ export declare class EventController {
      * Drops the candidate when it is no longer a displaceable todo.
      */
     inheritDisplaceableTodo(component: ToolExecutionComponent | null | undefined): void;
-    sendCompletionNotification(): void;
+    sendErrorNotification(event: Extract<AgentSessionEvent, {
+        type: "agent_end";
+    }>): void;
+    sendCompletionNotification(event: Extract<AgentSessionEvent, {
+        type: "agent_end";
+    }>): void;
 }

package/dist/types/modes/controllers/live-command-controller.d.ts

@@ -0,0 +1,14 @@
+import type { InteractiveModeContext } from "../types.js";
+/** Owns the editor-replacing visualizer and realtime session lifecycle for `/live`. */
+export declare class LiveCommandController {
+    #private;
+    constructor(ctx: InteractiveModeContext);
+    /** Whether a live session is connected, connecting, or closing. */
+    get active(): boolean;
+    /** Start live mode, or stop the currently active session. */
+    handleCommand(): Promise<void>;
+    /** Stop the active live session and restore the editor. */
+    stop(): Promise<void>;
+    /** Release UI resources during synchronous InteractiveMode teardown. */
+    dispose(): void;
+}

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

@@ -27,6 +27,7 @@ import type { EvalExecutionComponent } from "./components/eval-execution.js";
 import type { HookEditorComponent } from "./components/hook-editor.js";
 import type { HookInputComponent } from "./components/hook-input.js";
 import type { HookSelectorComponent, HookSelectorSlider } from "./components/hook-selector.js";
+import { type PlanReviewAnnotationState } from "./components/plan-review-overlay.js";
 import { StatusLineComponent } from "./components/status-line/index.js";
 import type { ToolExecutionHandle } from "./components/tool-execution.js";
 import { TranscriptContainer } from "./components/transcript-container.js";
@@ -247,6 +248,8 @@ export declare class InteractiveMode implements InteractiveModeContext {
         onExternalEditor?: () => void;
         onPlanEdited?: (content: string) => void;
         onFeedbackChange?: (feedback: string) => void;
+        annotationState?: PlanReviewAnnotationState;
+        onAnnotationStateChange?: (state: PlanReviewAnnotationState) => void;
         initialIndex?: number;
     }, extra?: {
         slider?: HookSelectorSlider;
@@ -340,6 +343,8 @@ export declare class InteractiveMode implements InteractiveModeContext {
     handleRenameCommand(title: string): Promise<void>;
     handleMemoryCommand(text: string): Promise<void>;
     handleSTTToggle(): Promise<void>;
+    /** Start or stop the Codex-backed realtime voice surface. */
+    handleLiveCommand(): Promise<void>;
     showDebugSelector(): Promise<void>;
     showAgentHub(options?: {
         requireContent?: boolean;

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

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
 import type { Effort } from "@oh-my-pi/pi-ai";
 import type { EditorTheme, MarkdownTheme, SelectListTheme, SettingsListTheme, SymbolTheme } from "@oh-my-pi/pi-tui";
-export { getLanguageFromPath } from "../../utils/lang-from-path.js";
+export { getLanguageFromPath, isMarkdownPath } from "../../utils/lang-from-path.js";
 export type SymbolPreset = "unicode" | "nerd" | "ascii";
 /**
  * All available symbol keys organized by category.

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

@@ -61,7 +61,7 @@ export type SubmittedUserInput = {
     cancelled: boolean;
     started: boolean;
 };
-export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned";
+export type TodoStatus = "pending" | "in_progress" | "completed" | "abandoned" | "blocked";
 export type TodoItem = {
     content: string;
     status: TodoStatus;
@@ -334,6 +334,8 @@ export interface InteractiveModeContext {
     handleRenameCommand(title: string): Promise<void>;
     handleMemoryCommand(text: string): Promise<void>;
     handleSTTToggle(): Promise<void>;
+    /** Start or stop the Codex-backed realtime voice session. */
+    handleLiveCommand(): Promise<void>;
     executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<CompactionOutcome>;
     openInBrowser(urlOrPath: string): void;
     refreshSlashCommandState(cwd?: string): Promise<void>;

package/dist/types/modes/utils/context-usage.d.ts

@@ -22,16 +22,26 @@ export interface ContextBreakdown {
     /** Estimated snapcompact wire savings; set when requested and a snapcompact.* setting is enabled. */
     snapcompact?: SnapcompactSavingsEstimate;
 }
+/** Stable inputs used to cache non-message token estimates. */
+export interface NonMessageTokenSource {
+    readonly systemPrompt?: string[];
+    readonly agent?: {
+        readonly state?: {
+            readonly tools?: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>;
+        };
+    };
+    readonly skills?: readonly Skill[];
+}
 export declare function estimateSkillsTokens(skills: readonly Skill[]): number;
 export declare function estimateToolSchemaTokens(tools: ReadonlyArray<Pick<Tool, "name" | "description" | "parameters">>): number;
-export declare function computeNonMessageTokens(session: AgentSession): number;
+export declare function computeNonMessageTokens(session: NonMessageTokenSource): number;
 /**
  * Shared helper for the four non-message token totals used by
  * `computeContextBreakdown` (/context panel). Keep this category split stable:
  * the status-line fast path intentionally uses the equivalent collapsed total
  * in `computeNonMessageTokens`.
  */
-export declare function computeNonMessageBreakdown(session: AgentSession): {
+export declare function computeNonMessageBreakdown(session: NonMessageTokenSource): {
     skillsTokens: number;
     toolsTokens: number;
     systemContextTokens: number;

package/dist/types/plan-mode/plan-files.d.ts

@@ -0,0 +1,10 @@
+import { type LocalProtocolOptions } from "../internal-urls/index.js";
+/** Reads a plan from a local URL or cwd-relative filesystem path. */
+export declare function readPlanFile(planFilePath: string, options: {
+    localProtocolOptions: LocalProtocolOptions;
+    cwd: string;
+}): Promise<string | null>;
+/** Lists session-local plan files from newest to oldest. */
+export declare function listPlanFiles(options: {
+    localProtocolOptions: LocalProtocolOptions;
+}): Promise<string[]>;

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

@@ -14,10 +14,14 @@
  * - ensureLive during an in-flight park either cancels the park (session still
  *   live) or waits for detach+park and then revives.
  * - Concurrent ensureLive/park operations coalesce per id.
+ *
+ * Every adoption, park, and revival is bound to the exact {@link AgentRef} it
+ * started from, so stale async work (a late finalizer, a cancelled initializer,
+ * a superseded revive) can never clobber a newer same-id ref.
  */
 import type { AgentSession } from "../session/agent-session.js";
-import { type AgentRef, AgentRegistry } from "./agent-registry.js";
-export type AgentReviver = () => Promise<AgentSession>;
+import { type AgentRef, type AgentRefExpectation, AgentRegistry } from "./agent-registry.js";
+export type AgentReviver = (expected: AgentRef) => Promise<AgentSession>;
 /**
  * Builds a reviver for a `parked` ref restored from disk (Agent Hub scan,
  * collab mirror, resumed process) that carries a sessionFile but no in-memory
@@ -48,10 +52,12 @@ export declare class AgentLifecycleManager {
     /**
      * Take ownership of a finished subagent. Caller has already set registry
      * status to "idle". Arms the TTL timer (idleTtlMs <= 0 adopts without one).
+     * When `expected` is given, the adoption is refused if the id no longer
+     * resolves to that ref (or that ref's session).
      */
-    adopt(id: string, opts: AdoptOptions): void;
-    /** True if the id is adopted (parked or live). */
-    has(id: string): boolean;
+    adopt(id: string, opts: AdoptOptions, expected?: AgentRefExpectation): void;
+    /** True if the id is adopted (parked or live) — and, when `expected` is given, still bound to that ref. */
+    has(id: string, expected?: AgentRefExpectation): boolean;
     /**
      * True when this manager owns `registry` — i.e. its adopt/park/revive state
      * describes that registry's refs. Lets a caller holding a specific registry
@@ -62,9 +68,10 @@ export declare class AgentLifecycleManager {
     /**
      * True while {@link park} is disposing this agent's session (lets dispose
      * hooks distinguish park from teardown). False once the park is cancelled
-     * by ensureLive or after detach+dispose completes.
+     * by ensureLive or after detach+dispose completes. When `expected` is
+     * given, only a park bound to that ref (or its session) counts.
      */
-    isParking(id: string): boolean;
+    isParking(id: string, expected?: AgentRefExpectation): boolean;
     /**
      * Dispose the live session, detach it from the registry, and mark the
      * agent `parked`. No-op unless the id is adopted and live.
@@ -84,8 +91,13 @@ export declare class AgentLifecycleManager {
      * cancelled (session still live) or awaited to completion before revive.
      */
     ensureLive(id: string): Promise<AgentSession>;
-    /** Hard removal: dispose if live, unregister from registry, drop timers. */
-    release(id: string): Promise<void>;
+    /**
+     * Hard removal: dispose if live, unregister from registry, drop timers.
+     * When `expected` is given, only a ref matching it is released; a stale
+     * release can never take down a newer same-id ref. Returns true when a
+     * matching ref was released.
+     */
+    release(id: string, expected?: AgentRefExpectation): Promise<boolean>;
     /** Teardown everything (process exit / main session dispose). */
     dispose(): Promise<void>;
 }

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

@@ -39,6 +39,7 @@ export interface AgentRef {
     /** Short gist of what the agent is currently doing (latest intent or tool), for the work-aware roster. Display-only. */
     activity?: string;
 }
+export type AgentRefExpectation = AgentRef | AgentSession;
 export type RegistryEvent = {
     type: "registered";
     ref: AgentRef;
@@ -65,7 +66,13 @@ export declare class AgentRegistry {
     /** Reset the global registry. Test-only. */
     static resetGlobalForTests(): void;
     register(input: RegisterInput): AgentRef;
-    setStatus(id: string, status: AgentStatus): void;
+    /**
+     * Register a new id only when it is absent, or reuse the exact ref a parked
+     * revival was authorized to revive. A missing expected ref is a failed CAS:
+     * callers must never claim an id after its prior generation disappeared.
+     */
+    registerIfAvailable(input: RegisterInput, expected: AgentRef | null): AgentRef | undefined;
+    setStatus(id: string, status: AgentStatus, expected?: AgentRefExpectation): boolean;
     /**
      * Record a short activity gist for the work-aware roster. Display-only and
      * read on demand (`irc list`, peer roster), so it emits no event — keeping
@@ -81,9 +88,9 @@ export declare class AgentRegistry {
      * every caller is safe without sanitizing at its own call site.
      */
     setActivity(id: string, activity: string): void;
-    attachSession(id: string, session: AgentSession, sessionFile?: string | null): void;
-    detachSession(id: string): void;
-    unregister(id: string): void;
+    attachSession(id: string, session: AgentSession, sessionFile?: string | null, expected?: AgentRefExpectation): boolean;
+    detachSession(id: string, expected?: AgentRefExpectation): boolean;
+    unregister(id: string, expected?: AgentRefExpectation): boolean;
     get(id: string): AgentRef | undefined;
     list(): AgentRef[];
     /**

package/dist/types/sdk.d.ts

@@ -16,7 +16,7 @@ import type { HindsightSessionState } from "./hindsight/state.js";
 import { type LocalProtocolOptions } from "./internal-urls/index.js";
 import { MCPManager, type MCPToolsLoadResult } from "./mcp/index.js";
 import type { MnemopiSessionState } from "./mnemopi/state.js";
-import { AgentRegistry } from "./registry/agent-registry.js";
+import { type AgentRef, AgentRegistry } from "./registry/agent-registry.js";
 import { AgentSession, type PlanYolo, type Prewalk } from "./session/agent-session.js";
 import type { AuthStorage } from "./session/auth-storage.js";
 import { SessionManager } from "./session/session-manager.js";
@@ -29,6 +29,8 @@ import { type WorkspaceTree } from "./workspace-tree.js";
 export interface CreateAgentSessionOptions {
     /** Working directory for project-local discovery. Default: getProjectDir() */
     cwd?: string;
+    /** Additional workspace directories beyond cwd (multi-root), absolute or cwd-relative. */
+    additionalDirectories?: string[];
     /** Global config directory. Default: ~/.omp/agent */
     agentDir?: string;
     /** Spawns to allow. Default: "*" */
@@ -180,6 +182,13 @@ export interface CreateAgentSessionOptions {
     agentDisplayName?: string;
     /** Optional shared agent registry for IRC routing. Default: AgentRegistry.global(). */
     agentRegistry?: AgentRegistry;
+    /**
+     * Registry generation authorized for this creation. `null` requires the id
+     * to be absent; an AgentRef allows a parked revival to reuse only that ref.
+     * Undefined preserves legacy unconditional registration for external SDK callers.
+     * @internal
+     */
+    expectedAgentRef?: AgentRef | null;
     /** Parent task ID prefix for nested artifact naming (e.g., "Extensions") */
     parentTaskPrefix?: string;
     /**
@@ -205,6 +214,11 @@ export interface CreateAgentSessionOptions {
     settingsManager?: Settings | Promise<Settings>;
     /** Whether UI is available (enables interactive tools like ask). Default: false */
     hasUI?: boolean;
+    /**
+     * Defer `confirm` reserve-policy fallback until AgentSession prompt-time UI is configured.
+     * ACP uses this while capabilities are negotiated without enabling UI-only tools.
+     */
+    deferUsageReserveConfirmation?: boolean;
     /**
      * Opt-in OpenTelemetry instrumentation forwarded to the underlying Agent.
      * Passing `{}` enables the loop's GenAI-semantic-convention spans. See

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

@@ -1,5 +1,18 @@
-import type { SecretEntry } from "./obfuscator.js";
-export { deobfuscateSessionContext, deobfuscateToolArguments, obfuscateMessages, obfuscateProviderContext, type SecretEntry, SecretObfuscator, } from "./obfuscator.js";
+import { type SecretEntry } from "./obfuscator.js";
+/**
+ * Per-install secret key for the placeholder digest. Persisted under the agent
+ * config directory and never sent to a provider, so model-visible placeholders
+ * cannot be reversed by dictionary-hashing candidate secrets. Stable across
+ * sessions so persisted transcripts deobfuscate consistently. Defaults to
+ * `getAgentDir()` — the same directory `createAgentSession()` passes as
+ * `agentDir` — so a caller relying on the default reads/writes the identical
+ * key file live sessions use, per `~/.omp/agent/secret-placeholder.key` in
+ * docs/secrets.md.
+ */
+export declare function getSecretPlaceholderKey(keyDir?: string): Promise<string>;
+/** Return an existing placeholder key for redaction without creating a new key file. */
+export declare function getExistingSecretPlaceholderKey(keyDir?: string): Promise<string | undefined>;
+export { deobfuscateSessionContext, deobfuscateToolArguments, obfuscateMessages, obfuscateProviderContext, type SecretEntry, SecretObfuscator, secretEntriesNeedPlaceholderKey, secretEntryNeedsPlaceholderKey, } from "./obfuscator.js";
 /**
  * Load secrets from project-local and global secrets.yml files.
  * Project-local entries override global entries with matching content.

package/dist/types/secrets/obfuscator.d.ts

@@ -7,6 +7,7 @@ export interface SecretEntry {
     mode?: "obfuscate" | "replace";
     replacement?: string;
     flags?: string;
+    friendlyName?: string;
 }
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue | undefined;
@@ -14,14 +15,105 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
 export type JsonRecord = {
     [key: string]: JsonValue | undefined;
 };
+/**
+ * Whether a default (no custom `replacement`) replace-mode regex can never
+ * safely redact a 1-2 char match: `findNonMatchingReplacement`'s bounded
+ * search — the same search `#generateRegexReplacement` runs at match time —
+ * finds no candidate the regex fails to re-match. This holds independent of
+ * any actual per-install key: the search already exhausts every character in
+ * `REPLACEMENT_CHARS` (the alphabet `buildKeyedReplacementRun` draws its
+ * fallback marker from) plus punctuation and whitespace, so if none of those
+ * escape the regex, no key-derived marker drawn from the same alphabet can
+ * either — the marker is guaranteed to re-match too, making every such match
+ * unresolvable: the fallback could only ever emit the raw matched text
+ * unchanged. Probed with a value (`"\0".repeat(length)`) the bounded search
+ * never treats as a real candidate, so the result depends only on the
+ * regex's own matching behavior, not on this specific probe.
+ */
+export declare function regexHasUnresolvableShortMatchFallback(regex: RegExp): boolean;
+export declare const MIN_OBFUSCATE_SECRET_LEN = 8;
+/** Normalize a friendly name into the model-visible placeholder prefix. */
+export declare function sanitizeSecretFriendlyName(name: string): string | undefined;
+/**
+ * Whether an entry needs the persisted placeholder key: either because it can
+ * produce a reversible (keyed) obfuscate-mode placeholder, or because a default
+ * (no custom `replacement`) replace-mode regex can reach
+ * `#generateRegexReplacement`'s key-derived idempotent fallback marker (see
+ * `#generateReplacement`) when every same-length candidate re-matches a
+ * pathological match-everything config (e.g. `[\s\S]{8}`). That fallback depends
+ * on the persisted per-install key — not just length — to stay a fixed point
+ * across a process restart; without a persisted key, a fresh install falls back
+ * to a process-random key (`defaultPlaceholderKey()`), so the fallback marker
+ * would churn across restarts even though the algorithm itself is stable. A
+ * regex WITH a custom `replacement` never reaches that fallback (it always emits
+ * the literal configured string), and a plain replace secret's replacement is
+ * pure content-hash (`#generateSecretReplacement`), so neither needs the key.
+ * Short plain obfuscate entries are toned down (never placeheld), so they must
+ * NOT force key creation: otherwise a `secret-placeholder.key` file is written
+ * and persisted for a config that ends up with no active secrets, leaving the
+ * key readable via a tool and reusable for later placeholders.
+ */
+export declare function secretEntryNeedsPlaceholderKey(entry: SecretEntry): boolean;
+/**
+ * Whether a SET of entries needs the persisted placeholder key. `obfuscate()`
+ * applies plain replace-mode mappings before the plain-obfuscate pass, so a plain
+ * obfuscate entry only emits a reversible (keyed) placeholder when its content can
+ * still appear AFTER the replace phase. When no obfuscate entry can ever produce a
+ * placeholder, the persisted key must NOT be required/created — otherwise an
+ * effectively replace-only secret set still writes `secret-placeholder.key` and
+ * fails startup when the agent config dir is unwritable.
+ *
+ * The decision models the replace phase as the obfuscator actually runs it:
+ * replace mappings are content-keyed (later duplicate wins) and applied in
+ * descending content-length order; for a fresh probe (no prior placeholders) that
+ * phase is plain sequential substring replacement. A plain obfuscate entry needs
+ * the key when its content survives that simulated phase (direct typing) OR when
+ * any effective replacement can form the content via tiling — a substring,
+ * wholesale superstring, or prefix/suffix border that joins with surrounding
+ * passthrough bytes (see `replacementCanFormContent`). This covers direct
+ * shadowing (`SECRET -> safe`), reintroduction, duplicate ordering, transitive
+ * chains, and context-joined fragments uniformly. Default (omitted) replacements
+ * are deterministic, length-preserving, and distinct, so a same-content shadow
+ * with no other interacting replacement stays key-free.
+ * Replacement outputs are themselves rewritten by every later (shorter-content)
+ * replacement before the plain-obfuscate pass sees them, so a fragment that a
+ * subsequent replacement erases (`AA -> SEC` then `S -> X` turns every `SEC` into
+ * `XEC`) no longer forces the key. Surrounding bytes stay modeled as arbitrary
+ * passthrough, so testing the surviving fragment only drops false positives and
+ * never under-approximates a real key need.
+ */
+export declare function secretEntriesNeedPlaceholderKey(entries: SecretEntry[]): boolean;
+export declare function stripPendingSecretPlaceholderSuffix(text: string): string;
 export declare class SecretObfuscator {
     #private;
-    constructor(entries: SecretEntry[]);
+    constructor(entries: SecretEntry[], key?: string);
     hasSecrets(): boolean;
+    /** Whether stored-session restoration can resolve keyed or legacy placeholders. */
+    hasStoredSecrets(): boolean;
     /** Obfuscate all secrets in text. Bidirectional placeholders for obfuscate mode, one-way for replace. */
-    obfuscate(text: string): string;
-    /** Deobfuscate obfuscate-mode placeholders back to original secrets. Replace-mode is NOT reversed. */
+    obfuscate(text: string, sharedRegexSecretValues?: ReadonlySet<string>): string;
+    /**
+     * Deobfuscate keyed placeholders back to original secrets for LIVE paths
+     * (provider output, tool-call arguments). Replace-mode is NOT reversed, and
+     * legacy index-derived aliases are intentionally ignored so a prompt-injected
+     * model cannot synthesize one to recover a secret.
+     */
     deobfuscate(text: string): string;
+    /**
+     * Deobfuscate stored session content for replay/display. Identical to
+     * {@link deobfuscate} but additionally honors legacy index-derived aliases so
+     * sessions persisted before keyed placeholders still resume correctly. Use
+     * only for trusted on-disk session content, never for live model output.
+     */
+    deobfuscateStored(text: string): string;
+    /** Deep-walk an object, deobfuscating string values for LIVE paths (keyed placeholders only). */
+    deobfuscateObject<T>(obj: T): T;
+    /** Deep-walk stored session content, deobfuscating string values incl. legacy aliases. */
+    deobfuscateStoredObject<T>(obj: T): T;
+    /** Deep-walk an object, obfuscating all string values. */
+    obfuscateObject<T>(obj: T): T;
+    collectRegexSecretValuesForObfuscation(text: string): Set<string>;
+    stripUnsafeFriendlyPlaceholderPrefixes(text: string, sharedRegexSecretValues: ReadonlySet<string>): string;
 }
 /**
  * Restore secret placeholders for local display. Only message kinds the model
@@ -30,30 +122,36 @@ export declare class SecretObfuscator {
  * tool-result messages are persisted with their literal text, so a literal
  * `#ABCD#` the operator typed must survive untouched; those roles are never
  * walked.
+ *
+ * Legacy index-derived aliases (`#XXXX#`) are unkeyed and trivially guessable,
+ * so a prompt-injected model can plant one in any record it influences. Every
+ * agent-feeding path (resume, history rewrite, branch switch) therefore restores
+ * keyed placeholders ONLY (`allowLegacyAliases` false), leaving legacy tokens
+ * inert; display-only transcripts that are never re-obfuscated opt in via
+ * `allowLegacyAliases`.
  */
-export declare function deobfuscateSessionContext(sessionContext: SessionContext, obfuscator: SecretObfuscator | undefined): SessionContext;
-export declare function deobfuscateAgentMessages(obfuscator: SecretObfuscator, messages: AgentMessage[]): AgentMessage[];
+export declare function deobfuscateSessionContext(sessionContext: SessionContext, obfuscator: SecretObfuscator | undefined, allowLegacyAliases?: boolean): SessionContext;
+export declare function deobfuscateAgentMessages(obfuscator: SecretObfuscator, messages: AgentMessage[], allowLegacyAliases?: boolean): AgentMessage[];
 /**
  * Restore placeholders in assistant content: visible text and tool-call
  * arguments/intent/rawBlock. Thinking and signatures are opaque
  * provider-replay/hidden-reasoning data and pass through byte-identical.
  */
-export declare function deobfuscateAssistantContent(obfuscator: SecretObfuscator, content: AssistantMessage["content"]): AssistantMessage["content"];
+export declare function deobfuscateAssistantContent(obfuscator: SecretObfuscator, content: AssistantMessage["content"], allowLegacyAliases?: boolean): AssistantMessage["content"];
 /**
  * Restore placeholders inside a tool call's arguments. Arguments are arbitrary
  * model-authored JSON, so tool-call arguments are the ONLY place a recursive
  * JSON walk runs.
  */
-export declare function deobfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>): Record<string, unknown>;
+export declare function deobfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>, allowLegacyAliases?: boolean): Record<string, unknown>;
 /** Redact secrets inside a tool call's arguments (same JSON-walk exception as {@link deobfuscateToolArguments}). */
-export declare function obfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>): Record<string, unknown>;
-/**
- * Redact secrets from outbound messages. Opt-in by origin: only user messages,
- * tool results, and user-authored developer messages (e.g. `@file` mentions)
- * can carry operator secrets. System prompts, tool schemas, and assistant
- * output are author-controlled or model-generated and pass through untouched.
- * Within a targeted message only `text` blocks are rewritten — inline image
- * bytes are never walked.
+export declare function obfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>, sharedRegexSecretValues?: ReadonlySet<string>): Record<string, unknown>;
+/**
+ * Redact secrets from outbound messages. User messages, tool results, and
+ * user-authored developer messages (e.g. `@file` mentions) are obfuscated.
+ * Assistant replay content is re-obfuscated too, because session restoration
+ * expands keyed placeholders locally before the next provider request. Inline
+ * image bytes are never walked.
  */
 export declare function obfuscateMessages(obfuscator: SecretObfuscator, messages: Message[]): Message[];
 /**

package/dist/types/session/acp-permission-gate.d.ts

@@ -0,0 +1,19 @@
+import type { ClientBridgePermissionOption } from "./client-bridge.js";
+/** Tools that require user permission before execution when an ACP client is connected. */
+export declare const PERMISSION_REQUIRED_TOOLS: Record<string, true>;
+/** Permission options presented to the client on each gated tool call. */
+export declare const PERMISSION_OPTIONS: ClientBridgePermissionOption[];
+/** Permission options indexed by their wire identifiers; unknown IDs miss and fail closed. */
+export declare const PERMISSION_OPTIONS_BY_ID: Map<string, ClientBridgePermissionOption>;
+/** Describes the permission prompt required for a destructive tool call. */
+export declare function getPermissionIntent(toolName: string, args: unknown): {
+    toolName: string;
+    title: string;
+    paths?: string[];
+    cacheKey: string;
+} | undefined;
+/** Converts tool path arguments into absolute ACP editor locations. */
+export declare function extractPermissionLocations(args: unknown, cwd: string, explicitPaths?: string[]): {
+    path: string;
+    line?: number;
+}[];