@lucascouts/claude-agent-tui 0.5.2 → 0.7.0

package/NOTICE

@@ -10,5 +10,5 @@ This product is a derivative work of:
 
 The engine was rewritten to drive the Claude Code subscription TUI over a
 pseudo-terminal (PTY) instead of calling the Claude Agent SDK. See
-.fork-provenance.json (fork point: v0.39.0) and CHANGELOG.md for the scope
+.fork-provenance.json (fork point: v0.53.0) and CHANGELOG.md for the scope
 of modifications.

package/README.md

@@ -4,7 +4,7 @@
 
 An [ACP](https://agentclientprotocol.com)-compatible agent that drives the **Claude Code subscription TUI** over a PTY, so your Claude Code threads render natively in [Zed](https://zed.dev) and other ACP clients.
 
-> **Fork** of [`@agentclientprotocol/claude-agent-acp`](https://github.com/agentclientprotocol/claude-agent-acp) v0.39.0. Where the upstream adapter calls the Claude Agent **SDK**, this fork spawns the `claude` **subscription CLI** in a pseudo-terminal and translates its JSONL transcript into ACP `session/update` notifications. See [`.fork-provenance.json`](.fork-provenance.json) for the exact fork point.
+> **Fork** of [`@agentclientprotocol/claude-agent-acp`](https://github.com/agentclientprotocol/claude-agent-acp) v0.53.0. Where the upstream adapter calls the Claude Agent **SDK**, this fork spawns the `claude` **subscription CLI** in a pseudo-terminal and translates its JSONL transcript into ACP `session/update` notifications. See [`.fork-provenance.json`](.fork-provenance.json) for the exact fork point.
 
 ## Why this exists
 

package/dist/acp-agent.d.ts

@@ -1,4 +1,4 @@
-import { Agent, AgentSideConnection, AuthenticateRequest, CancelNotification, ClientCapabilities, ForkSessionRequest, ForkSessionResponse, InitializeRequest, InitializeResponse, ListSessionsRequest, ListSessionsResponse, LoadSessionRequest, LoadSessionResponse, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, ReadTextFileRequest, ReadTextFileResponse, ResumeSessionRequest, ResumeSessionResponse, SessionConfigOption, SessionModeState, SessionNotification, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest, SetSessionModeResponse, CloseSessionRequest, CloseSessionResponse, DeleteSessionRequest, DeleteSessionResponse, TerminalHandle, TerminalOutputResponse, WriteTextFileRequest, WriteTextFileResponse } from "@agentclientprotocol/sdk";
+import { Agent, AgentSideConnection, AuthenticateRequest, CancelNotification, ClientCapabilities, ForkSessionRequest, ForkSessionResponse, InitializeRequest, InitializeResponse, ListSessionsRequest, ListSessionsResponse, LoadSessionRequest, LoadSessionResponse, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, ReadTextFileRequest, ReadTextFileResponse, ResumeSessionRequest, ResumeSessionResponse, SessionConfigOption, SessionModeState, SessionNotification, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest, SetSessionModeResponse, CloseSessionRequest, CloseSessionResponse, DeleteSessionRequest, DeleteSessionResponse, LogoutRequest, LogoutResponse, TerminalHandle, TerminalOutputResponse, WriteTextFileRequest, WriteTextFileResponse, AvailableCommand } from "@agentclientprotocol/sdk";
 import { ModelInfo, Options, PermissionMode, PermissionUpdate, SDKMessageOrigin, SDKPartialAssistantMessage } from "@anthropic-ai/claude-agent-sdk";
 import { ContentBlockParam } from "@anthropic-ai/sdk/resources";
 import { BetaContentBlock, BetaRawContentBlockDelta } from "@anthropic-ai/sdk/resources/beta.mjs";
@@ -15,6 +15,7 @@ import type { ListSubagents, GetSubagentMessages } from "./subagent-source.js";
 import { type SidechainToolUse } from "./subagent-gate.js";
 import type { SubagentWatcher } from "./subagent-watcher.js";
 import type { DetectorSchedule, EndOfTurnDetector } from "./end-of-turn.js";
+import { type AgentCatalogEntry } from "./agent-catalog.js";
 import type { SessionGate, SessionGateOptions } from "./permissions/gate-wiring.js";
 export declare const CLAUDE_CONFIG_DIR: string;
 /**
@@ -30,6 +31,7 @@ type AccumulatedUsage = {
     cachedReadTokens: number;
     cachedWriteTokens: number;
 };
+export declare const DEFAULT_CONTEXT_WINDOW = 200000;
 type Session = {
     /** The live PTY handle (story 013/014) running the subscription `claude` TUI for this session. */
     pty: IPty;
@@ -49,6 +51,13 @@ type Session = {
      * was surfaced in an earlier pump). Per-session — sub-agent row uuids are session-scoped.
      */
     emittedNested: Set<string>;
+    /**
+     * Story 056 (#812) — the last session title pushed to the client via `session_info_update` at the
+     * story-024 turn boundary. Used to DEDUP: `emitSessionTitleUpdate` skips the push when the freshly
+     * sanitized `getSessionInfo().summary` equals this. Undefined until the first non-empty title is
+     * pushed; per-session (titles are session-scoped).
+     */
+    lastEmittedTitle?: string;
     /** Story 054 — per-session dedup Set of sidechain inner tool_use ids already fed to the gate
      *  correlator (R3 exactly-once). Lazy-init on the gated pump path; absent on a no-gate session. */
     registeredSidechain?: Set<string>;
@@ -59,19 +68,54 @@ type Session = {
     engine?: SessionEngine;
     cancelled: boolean;
     cwd: string;
-    /** Serialized snapshot of session-defining params (cwd, mcpServers) used to
+    /**
+     * Story 057 (R1.3) — the RESOLVED additional-directory list for this session (the request's
+     * `additionalDirectories`, else `_meta.additionalRoots`, else `[]`), stored so sub-task 2.3's
+     * {@link respawnSession} can re-thread the SAME `--add-dir` scope into the in-place re-spawn. This
+     * is the RAW list (per-dir sanitization is the engine's job); absent on pre-057 / replay records.
+     */
+    additionalDirectories?: string[];
+    /**
+     * Story 057 (R2.3/R2.4, sub-task 2.3) — the CURRENT MCP scratch path ({@link writeMcpScratch})
+     * threaded into this session's spawn as `--mcp-config "<file>"`. Retained so {@link teardownSession}
+     * can REMOVE it (R2.3, no orphan/secret leak) and {@link respawnSession} can REGENERATE it (R2.4:
+     * write-new-then-remove-old, swapping this to the new path). Absent when the session declared no
+     * MCP servers (and on replay-only records, which spawn nothing).
+     */
+    mcpConfigFile?: string;
+    /**
+     * Story 057 (R2.4, sub-task 2.3) — the RAW ACP `mcpServers` array the client declared at create
+     * time, retained so {@link respawnSession} can RE-translate ({@link translateMcpServers}) and
+     * regenerate the scratch for the re-spawned `claude`. (The translation output is not stored —
+     * re-translating from the source keeps the regenerated scratch faithful to the original request.)
+     * Absent/empty when no MCP servers were declared.
+     */
+    mcpServers?: NewSessionRequest["mcpServers"];
+    /** Serialized snapshot of session-defining params (cwd, mcpServers, additionalDirectories) used to
      *  detect when loadSession/resumeSession is called with changed values. */
     sessionFingerprint: string;
     settingsManager: SettingsManager;
     accumulatedUsage: AccumulatedUsage;
     modes: SessionModeState;
     modelInfos: ModelInfo[];
+    /**
+     * Story 056 (R3.2) — the main-thread agent personas discovered for this session's cwd at
+     * create time ({@link discoverAgents}, glob-only). Stored so the model-change reconcile in
+     * {@link setSessionConfigOption} can REBUILD the `agent` configOption without re-globbing the
+     * disk. The CURRENT agent is NOT held here — it lives in the `agent` configOption's
+     * `currentValue` (mirroring `currentEffort`); `[]`/absent means no personas were discovered and
+     * the `agent` option is omitted entirely (upstream #794 `agents.length > 0` gate).
+     */
+    agents?: AgentCatalogEntry[];
     configOptions: SessionConfigOption[];
-    /** Context window size of the last top-level assistant model, carried across
-     *  prompts so mid-stream usage_update notifications report a correct `size`
-     *  before the turn's first result message arrives. Defaults to
-     *  DEFAULT_CONTEXT_WINDOW, refreshed from each result's modelUsage, and
-     *  invalidated when the user switches the session's model. */
+    /** Context window size for the session, carried across prompts so mid-stream
+     *  usage_update notifications report a correct `size` before the turn's first
+     *  result message arrives. Seeded by `inferContextWindowFromModel` (the static
+     *  `MODEL_CONTEXT_WINDOWS` curation) and re-resolved when the user switches the
+     *  session's model. NOTE (story 068): there is NO `result.modelUsage` refresh —
+     *  the JSONL `usage` block carries only token counts, never a window; the window
+     *  comes from static curation (the Models API `max_input_tokens` is the real
+     *  authority, which this PTY/JSONL fork does not call). */
     contextWindowSize: number;
     /** Accumulated task list for the session, keyed by task ID. Task IDs are
      *  per-session, so this state must not be shared across sessions. */
@@ -111,6 +155,19 @@ type Session = {
      * nothing is queued.
      */
     pendingModelInjection?: string;
+    /**
+     * Story 056 v4 — an effort change (`/effort <level>`) requested WHILE a turn is in flight is deferred
+     * here (last-write-wins) and flushed as a side-channel PTY write once the turn settles (mirrors
+     * {@link pendingModelInjection}). Undefined when nothing is queued.
+     */
+    pendingEffortInjection?: string;
+    /**
+     * Story 060 (R2.1/R2.2) — true WHILE the "ultracode" effort-selector sentinel is selected for this
+     * session. The LIVE activation it drives is a keyword prefix on the OUTGOING prompt (the binary's
+     * documented per-turn Workflow opt-in) — Option A, no re-spawn. Cleared when a real effort level (or
+     * `default`) is re-selected. The declarative spawn-time complement is {@link applyUltracodeSettings}.
+     */
+    ultracodeActive?: boolean;
     /**
      * Story 046 (R3.8) — true WHILE an in-place re-spawn (R3.4 dontAsk/bypass switch) is between the old
      * PTY teardown and the new PTY being ready. Selector changes arriving in this window are rejected
@@ -148,6 +205,13 @@ type Session = {
      * sourced fresh inside `emitLinearizedWithNested`; the main chain is whatever the last pump saw.
      */
     lastMessages?: SessionMessage[];
+    /**
+     * Story 058 (R2.1/R2.2) — the temp image files materialized for the in-flight turn (pushed by
+     * {@link promptToClaude}'s sink when the prompt is assembled, BEFORE it is sent), unlinked at turn
+     * settle (prompt()'s catch + finally, covering resolve AND cancel) via {@link cleanupMaterializedImages}
+     * and again on teardown as an idempotent backstop. Undefined when the turn materialized no image.
+     */
+    turnTempImagePaths?: string[];
 };
 /** What {@link StartEngine} returns: the authoritative session id (engine-spawn-generated for a
  *  fresh session, the resumed id otherwise), the live PTY, the started watcher, the owning engine,
@@ -226,6 +290,14 @@ export interface StartEngineArgs {
      * <level>` (non-"default" only). Threaded to BOTH the fresh and resume spawn paths.
      */
     effortLevel?: string;
+    /**
+     * Story 056 (R3.2): the seeded/re-spawn main-thread agent persona, forwarded to the spawn as
+     * `--agent "<name>"` (non-"default" only — the spawn layer drops the literal "default" sentinel,
+     * exactly like `--effort`/`--permission-mode`). Threaded to BOTH the fresh ({@link
+     * createSessionEngine}) and resume ({@link spawnResumePty}) paths so the agent-selecting re-spawn
+     * carries it. The persona name is allowlist-safe at the catalog boundary ({@link discoverAgents}).
+     */
+    agent?: string;
     /**
      * Story 046 (R3.4 LIVE FIX): this resume is an IN-PLACE re-spawn ({@link respawnSession} for a
      * dontAsk/bypass mode or an effort change), NOT a fork/resume of an already-lived session. An
@@ -237,6 +309,28 @@ export interface StartEngineArgs {
      * absent) keeps its blocking 2000ms watchdog (R2.1, resume-discovery-unchanged.test.ts).
      */
     inPlaceRespawn?: boolean;
+    /**
+     * Story 057 (R1.3/R3.1): the RESOLVED additional-directory list (session `additionalDirectories`,
+     * else `_meta.additionalRoots`), forwarded to BOTH the fresh ({@link createSessionEngine}) and
+     * resume ({@link spawnResumePty}) spawn paths so a re-spawn re-threads it. Each safe entry becomes
+     * one `--add-dir "<dir>"` on the interactive TUI argv; sanitization (per-dir drop of unsafe paths)
+     * is the ENGINE's job ({@link buildAddDirFlags}/`isSafeDir`, sub-task 1.1), so the list threaded
+     * here is RAW. ALWAYS-ON (no `FORK_*` opt-in gate, R3.1). Interactive-only — never on a `-p`/
+     * `stream-json` invocation (the fork has no headless path).
+     */
+    additionalDirectories?: string[];
+    /**
+     * Story 057 (R2.2/R2.3, sub-task 2.3): the fork-controlled uuid-namespaced MCP scratch path
+     * ({@link writeMcpScratch}), forwarded to BOTH the fresh ({@link createSessionEngine}) and resume
+     * ({@link spawnResumePty}) spawn paths and emitted as `--mcp-config "<file>"` (never `--strict` —
+     * R2.2 MERGE: claude folds these servers IN alongside any project/user `.mcp.json` rather than
+     * replacing them). Written BEFORE the spawn — claude reads it at startup, exactly like
+     * {@link settingsFile}, so it gates the first MCP use. ALWAYS-ON (no `FORK_*` gate); present only
+     * when the session declared ≥1 MCP server. The scratch may carry MCP auth headers/env (0600 +
+     * never logged, R2.3); the caller removes it on teardown ({@link removeMcpScratch}) and regenerates
+     * it on re-spawn ({@link respawnSession}, R2.4).
+     */
+    mcpConfigFile?: string;
 }
 /** The createSession injection seam: spawn the PTY engine + JSONL watcher + locate the transcript. */
 export type StartEngine = (args: StartEngineArgs) => Promise<StartedEngine> | StartedEngine;
@@ -318,6 +412,32 @@ export interface AgentDeps {
      * cannot be overridden. Tests inject short windows here; production passes nothing.
      */
     gateOptions?: Omit<SessionGateOptions, "client" | "onWarn">;
+    /**
+     * Story 056 (R3.2) — override the main-thread agent-persona discovery `createSession` seeds the
+     * `agent` configOption from (default: the glob-only {@link discoverAgents}). Injected by the unit
+     * tests with an in-memory fake so the surface is exercised hermetically, never touching the real
+     * `~/.claude/agents`. Production passes nothing → the real disk glob.
+     */
+    discoverAgents?: (cwd: string) => AgentCatalogEntry[];
+    /**
+     * Story 063 (R1/R1.1) — override the offline command discovery `sendAvailableCommandsUpdate` sources
+     * the `available_commands_update` set from (default: the disk-only {@link discoverCommands}, keyed on
+     * the session cwd). Injected by the wiring test with an in-memory fake so the surface is exercised
+     * hermetically, never touching the real `~/.claude`. Production passes nothing → the real disk scan.
+     */
+    discoverCommands?: (cwd: string) => AvailableCommand[];
+    /**
+     * Story 056 (#812) — override the SDK session-metadata reader the end-of-turn `session_info_update`
+     * push sources the title from (default: the pure {@link getSessionInfo} from the agent SDK, which
+     * resolves the session's `summary` from its JSONL — custom title, auto-summary, or first prompt).
+     * Injected by the unit tests with an in-memory fake so the push is exercised hermetically, never
+     * touching the real `~/.claude` transcript tree. Production passes nothing → the real SDK reader.
+     */
+    getSessionInfo?: (sessionId: string, options?: {
+        dir?: string;
+    }) => Promise<{
+        summary: string;
+    } | undefined>;
 }
 /**
  * Production default for the {@link StartEngine} seam. Spawns the subscription `claude` TUI under a
@@ -451,6 +571,14 @@ export declare class ClaudeAcpAgent implements Agent {
         [key: string]: BackgroundTerminal;
     };
     clientCapabilities?: ClientCapabilities;
+    /**
+     * Story 065 (R1/R3) — did the client advertise `clientCapabilities.elicitation.form`
+     * at initialize? Presence-based (a present `form` may legitimately be an empty `{}`,
+     * so this is derived with `!= null`, NOT property truthiness). The 065 gate (task 3.1)
+     * reads this to decide relay-via-elicitation (R1) vs the story-064 deny fallback (R3).
+     * Defaults `false` so a client that never advertised elicitation falls back safely.
+     */
+    clientSupportsElicitationForm: boolean;
     logger: Logger;
     gatewayAuthRequest?: GatewayAuthRequest;
     engine: Engine;
@@ -476,6 +604,13 @@ export declare class ClaudeAcpAgent implements Agent {
     private readonly gateEnabled;
     /** Story 034 — gate tuning knobs forwarded to setupSessionGate; see {@link AgentDeps.gateOptions}. */
     private readonly gateOptions?;
+    /** Story 056 (R3.2) — main-thread agent-persona discovery seam; see {@link AgentDeps.discoverAgents}. */
+    private readonly discoverAgents;
+    /** Story 063 (R1/R1.1) — offline `available_commands` discovery seam; see {@link AgentDeps.discoverCommands}. */
+    private readonly discoverCommands;
+    /** Story 056 (#812) — SDK session-metadata reader for the end-of-turn title push; see
+     *  {@link AgentDeps.getSessionInfo}. */
+    private readonly getSessionInfo;
     /** Live PTY-engine registry shared with the per-session engines (story 014 cleanup map). */
     private readonly engines;
     constructor(client: AgentSideConnection, logger?: Logger, engine?: Engine, deps?: AgentDeps);
@@ -486,7 +621,27 @@ export declare class ClaudeAcpAgent implements Agent {
     loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse>;
     listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse>;
     authenticate(_params: AuthenticateRequest): Promise<void>;
+    /**
+     * ACP `logout` (acp-sdk 1.0.0, acp.d.ts:1646). Under the PTY engine the bridge
+     * authenticates lazily and only tracks an in-memory `gatewayAuthRequest`; the
+     * interactive `claude` TUI owns the on-disk credential lifecycle. So `logout`
+     * here drops the in-memory auth intent and re-offers a clean handshake on the
+     * next `initialize()` (authMethods are recomputed there, unconditioned by this
+     * field). It does NOT read/write/delete `~/.claude` (billing seam — story 062
+     * R2) and never bridges `/logout` to the PTY (R3). Idempotent with no prior
+     * authenticate() (R4); active sessions are untouched (R6).
+     */
+    logout(_params: LogoutRequest): Promise<LogoutResponse | void>;
     prompt(params: PromptRequest): Promise<PromptResponse>;
+    /**
+     * Story 056 (#812) — push the sanitized session title to the client via `session_info_update`,
+     * fired (fire-and-forget) by the story-024 end-of-turn boundary ONLY (never on cancel/watchdog,
+     * via {@link TurnResolverOptions.onTurnResolved}). DEDUPED against {@link Session.lastEmittedTitle}
+     * so an unchanged title is not re-emitted, and silent when `getSessionInfo` finds no transcript /
+     * the title is empty. Every error is swallowed and logged — this MUST NEVER reject the turn (it is
+     * never awaited in `prompt()`), and a slow/never-resolving reader cannot delay the PromptResponse.
+     */
+    private emitSessionTitleUpdate;
     cancel(params: CancelNotification): Promise<void>;
     /** Cleanly tear down a session: cancel in-flight work, dispose resources,
      *  and remove it from the session map. */
@@ -494,7 +649,7 @@ export declare class ClaudeAcpAgent implements Agent {
     /** Tear down all active sessions. Called when the ACP connection closes. */
     dispose(): Promise<void>;
     closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse>;
-    unstable_deleteSession(params: DeleteSessionRequest): Promise<DeleteSessionResponse>;
+    deleteSession(params: DeleteSessionRequest): Promise<DeleteSessionResponse>;
     setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse>;
     setSessionConfigOption(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
     /**
@@ -559,19 +714,60 @@ export declare class ClaudeAcpAgent implements Agent {
      * Order is load-bearing for R3.7: re-spawn FIRST, and swap in + tear down the old PTY ONLY once the new
      * one is live — so a failed re-spawn leaves the prior PTY/currentValue intact (never
      * torn-down-without-replacement). Re-spawn runs only while idle, so the old PTY has no pending turn to
-     * double-resolve. The `respawning` latch defers concurrent selector changes (R3.8).
+     * double-resolve. The `respawning` latch defers concurrent selector changes (R3.8). Re-spawning for
+     * ONE selector preserves the OTHER two (mode / effort / agent — Story 056 added agent) by reading
+     * their current values, so the resume argv always carries all three flags.
      */
     private respawnSession;
     /** Story 046 — the session's current effort configOption value (undefined when no effort option). */
     private currentEffort;
+    /** Story 056 — the session's current agent configOption value (undefined when no agent option). */
+    private currentAgent;
     /**
-     * Story 046 (R2.2, design §7) — apply a reasoning-effort change. Probe B verdict: effort has no live
-     * mid-session mechanism (`--effort` is a spawn flag), so a change re-spawns in place with the flag
-     * (mirroring the dontAsk/bypass mode path), idle-guarded, with the R3.7 failure path and R3.8 latch.
-     * A no-op change applies nothing. Throwing here leaves the caller's applyConfigOptionValue unrun, so
-     * the prior currentValue is left unchanged on failure (R3.7).
+     * Story 060 (R2/R3.2) — apply an effort-selector choice, special-casing the `ultracode` sentinel.
+     *
+     * Selecting `ultracode` (Option A — keyword + scratch, NO re-spawn): activate the session flag (which
+     * makes {@link prompt} prefix the OUTGOING prompt with the `ultracode` keyword — the binary's per-turn
+     * Workflow opt-in, the effective live mechanism), write the scratch ultracode keys via
+     * {@link applyUltracodeSettings} (the declarative spawn-time complement), and set the effort to xhigh
+     * through the SAME live `/effort` inject as every other level — NEVER `/effort ultracode` (R1.2). The
+     * `already` guard suppresses a redundant `/effort xhigh` re-inject when ultracode is re-selected while
+     * already active.
+     *
+     * Selecting a real level (or `default`) DEACTIVATES ultracode: clear the flag, remove the scratch keys,
+     * then apply that level through {@link applyEffortChange} (whose own no-op guard handles a same-level
+     * pick). `applyConfigOptionValue` (the caller, after this returns) commits the selector's currentValue,
+     * which for `ultracode` correctly stays `"ultracode"` (the {@link buildConfigOptions} `includes` guard
+     * keeps it valid across rebuilds).
+     */
+    private applyEffortSelection;
+    /**
+     * Story 046 (R2.2) + Story 056 v4 — apply a reasoning-effort change LIVE via `/effort <level>`.
+     * SUPERSEDES the 046 Probe-B re-spawn: `claude` 2.1.195 DOES have a live `/effort <level>` local TUI
+     * command (LIVE-VERIFIED — "Set effort level to high…", applied inline, NO "Switch?" dialog unlike
+     * /model). So effort now mirrors {@link applyModelSwitch}: a side-channel write, no re-spawn, no turn —
+     * which means it ALSO works BEFORE the first interaction (the re-spawn's --resume idle-guard was why
+     * effort silently failed pre-first-prompt). Mid-turn it defers (pendingEffortInjection) and flushes
+     * when the turn settles. A no-op change applies nothing; effort stays preserved across mode/agent
+     * re-spawns (currentEffort → --effort flag), so the spawn-flag path remains as the seed/preserve route.
      */
     private applyEffortChange;
+    /**
+     * Side-channel `/effort <level>` write — synchronous, resolves immediately (never a turn). Unlike
+     * `/model`, `/effort` applies INLINE with no blocking "Switch?" dialog (LIVE-VERIFIED 2.1.195), so
+     * sendPrompt's own submit `\r` is sufficient and NO confirm Enter is scheduled.
+     */
+    private injectEffortCommand;
+    /**
+     * Story 056 (R3.3/R3.4) — apply a main-thread agent-persona change. Like effort, the persona has no
+     * live mid-session mechanism (`--agent "<name>"` is a spawn flag), so a change re-spawns in place
+     * carrying the flag (mirroring {@link applyEffortChange}), idle-guarded, with the R3.7 failure path
+     * and the R3.8 latch. A no-op change (same persona, with the "default" sentinel as the no-persona
+     * baseline) applies nothing. Throwing here leaves the caller's applyConfigOptionValue unrun, so the
+     * prior currentValue is left unchanged on failure (R3.7). Optimistic-on-apply, like effort: there is
+     * no transcript drift event for the agent persona, so it is NOT reconciled afterward (R4.3).
+     */
+    private applyAgentChange;
     /**
      * Story 046 (R4.1/R4.2/R4.3, design §8) — reconcile the `mode` configOption from the latest
      * permission-mode event in the exactly-once `messages` slice. Emits current_mode_update EXACTLY ONCE
@@ -694,13 +890,23 @@ export declare const EMBEDDED_RESOURCE_INLINE_THRESHOLD = 2048;
  *                     anything below the threshold — or large but path-less — is
  *                     inlined directly so the context is not lost.
  *
- * `resource` (blob) / `image` / `audio` blocks are SILENT no-ops here (R4.1): they
- * emit no PTY bytes and are NOT logged — they are expected-but-unsupported media in
- * v1, not errors. An UNKNOWN block `type` (the `default` branch) and any block whose
- * mapping THROWS are treated as malformed: skipped, recorded via the `logger`, and the
- * remaining valid blocks still map — one bad block never aborts the whole prompt (R1.3).
+ *   - image → materialize the base64 to a uuid-named temp file (extension from mimeType)
+ *             and emit `@<temp-path>` (Story 058 / R1.1). Once at least one image is
+ *             materialized, a single Read-inducing directive is appended after the loop so
+ *             the TUI's Read tool fires and vision-encodes it (R1.2). Each temp path is
+ *             pushed into `materializedSink` (when provided) so the caller can clean it up.
+ *
+ * `resource` (blob) / `audio` blocks are SILENT no-ops here (R4.1): they emit no PTY bytes
+ * and are NOT logged — they are expected-but-unsupported media in v1, not errors. An UNKNOWN
+ * block `type` (the `default` branch) and any block whose mapping THROWS are treated as
+ * malformed: skipped, recorded via the `logger`, and the remaining valid blocks still map —
+ * one bad block never aborts the whole prompt (R1.3). A `materializeImage` failure is caught
+ * by that same per-block isolation, so a broken image is skipped, never aborting the prompt.
+ *
+ * `materializedSink`, when passed, receives every materialized temp path (in order) so the
+ * caller owns their lifecycle (cleanup is a later task). The return type stays `string`.
  */
-export declare function promptToClaude(prompt: PromptRequest, logger?: Logger): string;
+export declare function promptToClaude(prompt: PromptRequest, logger?: Logger, materializedSink?: string[]): string;
 /**
  * Convert an SDKAssistantMessage (Claude) to a SessionNotification (ACP).
  * Only handles text, image, and thinking chunks for now.
@@ -721,5 +927,27 @@ export declare function runAcp(deps?: AgentDeps): {
     connection: AgentSideConnection;
     agent: ClaudeAcpAgent;
 };
+/** Resolve a model alias's context window (the usage_update `size` denominator).
+ *  NOTE (story 068): there is NO `result.modelUsage` window to refresh from — the
+ *  JSONL `usage` carries only token counts; the window comes from static curation
+ *  (the Models API `max_input_tokens` is the real authority, which this fork does
+ *  not call), as detailed below.
+ *
+ *  Story 068 (R1, R1.1, R1.2): consults the static {@link MODEL_CONTEXT_WINDOWS}
+ *  alias→window map FIRST (an exact catalog-`value` hit — `opus`=1M, `sonnet`=200K,
+ *  `sonnet[1m]`=1M, `haiku`=200K, `default`/`opusplan`=200K conservative). This
+ *  fixes `opus` having wrongly reported 200K. An alias absent from the map then
+ *  falls back to the legacy `\b1m\b` inference: Anthropic 1M-context variants
+ *  encode "1m" as a distinct token in the SDK model ID (e.g., "claude-opus-4-6-1m"),
+ *  which `\b1m\b` catches without also matching "10m" or embedded substrings.
+ *  `null` (fully unknown) is intentional — the two call sites apply
+ *  `?? DEFAULT_CONTEXT_WINDOW`. */
+export declare function inferContextWindowFromModel(model: string): number | null;
+/** Story 069 (R1) — AUTHORITATIVE context window from a turn's REAL model ID (the JSONL `model`
+ *  field), used by the pump to refine the alias seed once the model is known. Exact-ID lookup first
+ *  (MODEL_ID_CONTEXT_WINDOWS), then a family+version heuristic for dated snapshots / future variants
+ *  (Opus is NOT uniform: 4.6 and earlier = 200K, 4.7+ = 1M; Sonnet 4.x = 200K but Sonnet 5+ = 1M;
+ *  haiku = 200K; fable = 1M — story 071), then a
+ *  `\b1m\b` suffix, then null (R1.3: a missing / non-string id never refines). */
+export declare function inferContextWindowFromModelId(id: string): number | null;
 export {};
-//# sourceMappingURL=acp-agent.d.ts.map