@lucascouts/claude-agent-acp-plus 0.3.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/%40lucascouts%2Fclaude-agent-acp-plus)](https://www.npmjs.com/package/@lucascouts/claude-agent-acp-plus)
 
-> A **fork** of [claude-agent-acp](https://github.com/agentclientprotocol/claude-agent-acp) that ports features from the Claude Code VS Code extension to ACP clients (like Zed), for a friendlier experience. Currently based on upstream v0.57.0.
+> A **fork** of [claude-agent-acp](https://github.com/agentclientprotocol/claude-agent-acp) that ports features from the Claude Code VS Code extension to ACP clients (like Zed), for a friendlier experience. Currently based on upstream v0.58.1. Requires Node.js >= 24.
 
 Use [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview#branding-guidelines) from [ACP-compatible](https://agentclientprotocol.com) clients!
 

package/dist/acp-agent.d.ts

@@ -1,5 +1,5 @@
-import { AuthenticateRequest, CancelNotification, ClientCapabilities, CompleteElicitationNotification, CreateElicitationRequest, CreateElicitationResponse, ForkSessionRequest, ForkSessionResponse, InitializeRequest, InitializeResponse, ListSessionsRequest, ListSessionsResponse, LoadSessionRequest, LoadSessionResponse, LogoutRequest, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, ReadTextFileRequest, ReadTextFileResponse, RequestPermissionRequest, RequestPermissionResponse, ResumeSessionRequest, ResumeSessionResponse, SessionConfigOption, SessionModeState, SessionNotification, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest, SetSessionModeResponse, CloseSessionRequest, CloseSessionResponse, DeleteSessionRequest, DeleteSessionResponse, WriteTextFileRequest, WriteTextFileResponse } from "@agentclientprotocol/sdk";
-import { AgentInfo, CanUseTool, FastModeState, ModelInfo, Options, PermissionMode, PermissionUpdate, Query, SDKMessageOrigin, SDKPartialAssistantMessage, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import { AuthenticateRequest, CancelNotification, ClientCapabilities, CompleteElicitationNotification, CreateElicitationRequest, CreateElicitationResponse, DisableProviderRequest, DisableProviderResponse, ForkSessionRequest, ForkSessionResponse, InitializeRequest, InitializeResponse, ListProvidersRequest, ListProvidersResponse, LlmProtocol, ListSessionsRequest, ListSessionsResponse, LoadSessionRequest, LoadSessionResponse, LogoutRequest, NewSessionRequest, NewSessionResponse, PromptRequest, PromptResponse, ReadTextFileRequest, ReadTextFileResponse, SetProviderRequest, SetProviderResponse, RequestPermissionRequest, RequestPermissionResponse, ResumeSessionRequest, ResumeSessionResponse, SessionConfigOption, SessionModeState, SessionNotification, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, SetSessionModeRequest, SetSessionModeResponse, CloseSessionRequest, CloseSessionResponse, DeleteSessionRequest, DeleteSessionResponse, WriteTextFileRequest, WriteTextFileResponse } from "@agentclientprotocol/sdk";
+import { AgentInfo, CanUseTool, FastModeDisabledReason, FastModeState, ModelInfo, Options, PermissionMode, PermissionUpdate, Query, SDKMessageOrigin, SDKPartialAssistantMessage, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
 import { ContentBlockParam } from "@anthropic-ai/sdk/resources";
 import { BetaContentBlock, BetaRawContentBlockDelta } from "@anthropic-ai/sdk/resources/beta.mjs";
 import { SettingsManager } from "./settings.js";
@@ -19,6 +19,34 @@ type AccumulatedUsage = {
     cachedReadTokens: number;
     cachedWriteTokens: number;
 };
+/** Request-level steering options. `promptRequired` is opt-in so existing Hosts
+ *  keep the established idle fallback behavior. */
+type SteerMeta = {
+    [key: string]: unknown;
+    steering?: {
+        idleBehavior?: "promptRequired";
+    };
+};
+/** Params of a {@link STEER_METHOD} request. Shaped like the relevant subset of
+ *  a `PromptRequest` so the same `promptToClaude` conversion applies. Delivery
+ *  priority is deliberately NOT exposed here — it's an internal detail the agent
+ *  chooses (see {@link STEER_PRIORITY}). */
+export type SteerRequest = {
+    sessionId: string;
+    prompt: PromptRequest["prompt"];
+    _meta?: SteerMeta | null;
+};
+/** Result of a {@link STEER_METHOD} request. The legacy `startedNewTurn` result
+ *  remains the default idle behavior; `promptRequired` is returned only when the
+ *  Host explicitly opts into the host-owned fallback in request `_meta`. */
+export type SteerResponse = {
+    outcome: "injected";
+} | {
+    outcome: "startedNewTurn";
+} | {
+    outcome: "promptRequired";
+    reason: "noRunningTurn";
+};
 /** Internal model-selection state. Mirrors the shape the ACP SDK exposed as
  *  `SessionModelState` before model selection moved entirely into
  *  `SessionConfigOption` (category "model"). Retained internally to track the
@@ -47,6 +75,77 @@ type Turn = {
     /** Set once the deferred has been resolved/rejected, so the consumer never
      *  settles a turn twice (idle + handoff + stream-end can all race). */
     settled: boolean;
+    /** Set when a `command_lifecycle` "started" frame arrives for this turn's
+     *  uuid (msg_lifecycle_v1 CLIs): the SDK dispatched the command into a turn.
+     *  Read by cancel() to seed the orphan's state — a started orphan's turn may
+     *  still emit a result, an undispatched one may be dropped without one. */
+    commandStarted?: boolean;
+    /** Set when a terminal `command_lifecycle` frame arrives for this turn's
+     *  uuid while the turn is still queued (msg_lifecycle_v1 CLIs). The command
+     *  is already finished SDK-side, so a later cancel() must not seed an
+     *  orphan entry for it — no terminal frame will ever come to drain it.
+     *  "completed"/"discarded" leave nothing outstanding; "cancelled" after a
+     *  dispatch means the dead turn's result may still arrive (seeded as a
+     *  zombie) unless it already passed (`commandResultSeen`), and without a
+     *  dispatch means dropped (nothing coming). */
+    commandFinished?: "completed" | "discarded" | "cancelled";
+    /** Set when a user-turn result arrives while this command is known
+     *  dispatched (`commandStarted`) with no terminal frame yet. Turns run
+     *  sequentially and frames arrive in stream order, so the turn this command
+     *  was dispatched into IS the turn that emitted that result — including
+     *  when the command was FOLDED into another turn (their shared result).
+     *  Read by cancel() and the force-cancel wedge path so neither seeds an
+     *  orphan entry for a result that has already passed: such an entry could
+     *  never be drained by its result and would swallow an unrelated later
+     *  echo-less one instead. */
+    commandResultSeen?: boolean;
+    /** Task ids of the background subagents launched while this turn was the
+     *  active one — including during its held-open drain window, so an agent
+     *  chain (a followup that launches another subagent) extends the hold.
+     *  A turn only waits on its OWN spawned subagents: a long-running agent
+     *  from an earlier turn must not stall every later prompt's settlement.
+     *  Known residual: task_started carries no lineage, so a spawn made by a
+     *  PREVIOUS turn's followup chain while a later turn happens to be held
+     *  is attributed to the holder — extending that hold behind a foreign
+     *  chain. Bounded: the hold still ends at drain, hand-off, or cancel. */
+    spawnedTaskIds?: Set<string>;
+    /** Set instead of settling when the turn's terminal result arrives while
+     *  subagents it spawned are still live (`spawnedTaskIds` ∩
+     *  `session.liveBackgroundTasks`). The turn is held open — its
+     *  `session/prompt` stays pending — so the subagents' streamed output,
+     *  their permission requests (which would otherwise block on an RPC a
+     *  client that stops consuming at the prompt response never answers —
+     *  issue #866), and the model's task-notification followup summary all
+     *  land inside the turn.
+     *
+     *  The CLI does NOT hold its trailing idle for background agents (observed
+     *  on 2.1.206: `idle` follows the result immediately while the subagent
+     *  still runs), so the hold spans multiple idle cycles: user result →
+     *  idle → (subagent works) → task_notification → followup turn → idle.
+     *  The stored outcome (the result's stop reason and usage snapshot) is
+     *  what the turn settles with once its spawned subagents have settled —
+     *  at the followup's terminal result (the summary has streamed by then),
+     *  or at an idle with none of its subagents left (no followup came). A
+     *  cancel or the next turn's echo hand-off settles it earlier, so a
+     *  long-running subagent never holds the prompt hostage.
+     *
+     *  Accepted residuals. (1) A subagent that ends WITHOUT waking the model —
+     *  its task_notification lost or skipped (only the terminal task_updated
+     *  patch is guaranteed per transition) — leaves no followup result and no
+     *  further idle, so the held turn parks until `session/cancel` or the next
+     *  prompt (either settles it: the echo hand-off or ensureActiveTurn's
+     *  held-turn hand-off). Settling at the prune sites instead would preempt
+     *  the followup summary in the normal ordering (prunes precede the
+     *  notification), and a grace timer was judged not worth the machinery —
+     *  the same rescue contract as the adapter's other wedge classes (issue
+     *  #825's out-of-scope notes). (2) Drained-ness is judged by live-task
+     *  membership only: with parallel subagents, a notification that prunes
+     *  the last task during an earlier task's still-streaming followup lets
+     *  that followup's result settle the turn before the LAST task's summary
+     *  streams — degrading to post-turn delivery for it, never worse than the
+     *  pre-hold behavior (pending wakes are not countable: notifications can
+     *  batch into one followup). */
+    deferredSettle?: PromptResponse;
     resolve: (response: PromptResponse) => void;
     reject: (error: unknown) => void;
 };
@@ -70,8 +169,40 @@ type Session = {
      *  the interrupt dropped (absent from `still_queued`) are uncounted as soon
      *  as the receipt arrives (see cancel()). Reset to 0 on every activation as
      *  a backstop against a dropped queued input this can't see (older CLIs, a
-     *  receipt lost to a failed control round-trip). */
+     *  receipt lost to a failed control round-trip). Only used when the CLI does
+     *  NOT emit lifecycle frames (see `orphanCommands` for the msg_lifecycle_v1
+     *  lane); a count can't express command coalescing — N queued commands can
+     *  fold into ONE turn emitting one result, leaving a stale skip of N-1. */
     pendingOrphanResults?: number;
+    /** msg_lifecycle_v1 lane of the orphan accounting (see
+     *  `pendingOrphanResults` for the count lane): the uuids of cancelled queued
+     *  turns whose SDK-side command may still produce an unaccounted result,
+     *  keyed to what we know of its fate. "pending" = not seen dispatched; if
+     *  the SDK drops it (interrupt, `cancelled` before "started") no result
+     *  ever comes. "started" = dispatched into a turn whose result is still
+     *  coming; exactly one terminal lifecycle frame will follow. "zombie" = its
+     *  turn was aborted/failed after dispatch with no result seen since
+     *  (`cancelled` after "started"); no more lifecycle frames come, but the
+     *  dead turn's error result may still arrive. Entries are removed the
+     *  moment their result is covered: EVERY user-turn result covers ALL
+     *  started and zombie entries at once (turns run sequentially and frames
+     *  arrive in stream order, so at any result the started entries were
+     *  dispatched into — possibly folded into — the emitting turn, and any
+     *  zombie's late result has already passed or never existed), whether that
+     *  result was attributed to the active turn or skipped echo-less (see
+     *  recordResultForOrphanCommands / ensureActiveTurn). A command's own
+     *  terminal frame also drains its entry ("completed" is emitted after any
+     *  result its turn produced; a bare `cancelled` deletes a pending entry —
+     *  dropped without running — and zombifies a started one). An echo-less
+     *  result is an orphan's iff this map is non-empty (FIFO: orphan turns run
+     *  before any live turn's). Cleared on every activation, same self-heal as
+     *  the count (covers a lost frame, which can leak an entry — each state
+     *  bounds the damage to one wrong skip). */
+    orphanCommands?: Map<string, "pending" | "started" | "zombie">;
+    /** True once a `system`/init advertised the msg_lifecycle_v1 capability, so
+     *  cancel() routes orphan accounting to `orphanCommands` (exact, per-uuid)
+     *  instead of `pendingOrphanResults` (count, coalescing-blind). */
+    msgLifecycleV1?: boolean;
     /** The long-lived consumer task. Lazily started on the first `prompt()` and
      *  kept alive for the session so between-turn/background messages are still
      *  drained and forwarded. */
@@ -104,6 +235,13 @@ type Session = {
      *  user's intent so it persists across model switches; the Fast mode config
      *  option is only surfaced while the selected model supports it. */
     fastModeEnabled: boolean;
+    /** Why the SDK currently can't serve Fast mode, when the reason is one worth
+     *  telling the user about (see {@link FAST_MODE_UNAVAILABLE_EXPLANATIONS} —
+     *  routine states like the SDK's own opt-in requirement normalize to
+     *  `undefined`). Refreshed from every `fast_mode_disabled_reason` the SDK
+     *  reports on `system`/init and user-turn `result`s; surfaced in the Fast mode
+     *  option's description so a toggle that snaps back off explains itself. */
+    fastModeDisabledReason?: FastModeDisabledReason;
     /** Tri-state Thinking intent (story 006): `true`/`false` once the client has
      *  set the Thinking config option, `undefined` while untouched — i.e. the
      *  env-driven `MAX_THINKING_TOKENS` behavior stays in charge (R1.6). Mirrors
@@ -148,12 +286,37 @@ type Session = {
      *  cancel. */
     forceCancelTimer?: ReturnType<typeof setTimeout>;
     emitRawSDKMessages: boolean | SDKMessageFilter[];
-    /** Context window size of the last top-level assistant model, carried across
+    /** Whether nested subagent text/thinking is forwarded to the ACP client.
+     *  Enabled by either the ACP capability or the pre-existing SDK option. */
+    forwardSubagentText: boolean;
+    /** Context window size of the session's current 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. */
+     *  before the turn's first result message arrives. Seeded synchronously at
+     *  session creation and on model switches from the per-model cache or the
+     *  text heuristic (DEFAULT_CONTEXT_WINDOW when both miss; on session/load the
+     *  resumed session's own `getContextUsage` report wins, see
+     *  `readResumedLiveModel`), then confirmed — and the cache populated — by each
+     *  result's modelUsage. No extra `getContextUsage` IPC is on these paths: on a
+     *  fresh session it stalls until the first turn runs (see the seeding call
+     *  sites and `contextWindowCache`). */
     contextWindowSize: number;
+    /** Whether `contextWindowSize` came from an authoritative source (the
+     *  cross-session cache, a resumed session's `getContextUsage` report, or a
+     *  `result.modelUsage`) rather than the text heuristic / default. Guards the
+     *  mid-stream `message_start` heuristic upgrade: an authoritative window that
+     *  happens to equal DEFAULT_CONTEXT_WINDOW must not be mistaken for "unseeded"
+     *  and clobbered by a "1m" text match. */
+    contextWindowAuthoritative: boolean;
+    /** Stable identifier of the LLM backend this session's query was created
+     *  against, derived from the routing-relevant vars of the exact `env` handed
+     *  to the SDK at query creation (see {@link providerCacheKeyFor}). The context
+     *  window is a property of (model id, backend) — the same resolved model id
+     *  can name different windows behind different base URLs, routing headers, or
+     *  credentials — so this scopes the module-global `contextWindowCache` per
+     *  backend. Captured from the query's own env (not re-resolved later) because
+     *  the process-wide provider config can change while a session is being
+     *  created, while the query stays baked to the env it was created with. */
+    providerCacheKey: string;
     /** Accumulated task list for the session, keyed by task ID. Task IDs are
      *  per-session, so this state must not be shared across sessions. */
     taskState: TaskState;
@@ -177,6 +340,113 @@ type Session = {
      *  tool_use block streams; this set makes the two paths converge regardless of
      *  order. Pruned at `tool_result` time alongside `toolUseCache`. */
     emittedToolCalls: Set<string>;
+    /** Registry of live background tasks, keyed by task id: populated at
+     *  `task_started`, pruned when the task settles (a `task_notification` or
+     *  a terminal `task_updated` patch), and reconciled against
+     *  `background_tasks_changed`'s replace-semantics payload so a lost
+     *  bookend can't leak an entry. One structure for both of its concerns so
+     *  a future terminal path can't prune one and not the other:
+     *
+     *  `parentToolUseId` — the tool_use id of the Agent/Task call that spawned
+     *  the task. For subagent tasks the SDK keys its registry by agent id, so
+     *  `task_started.task_id` IS the `agentID` that `canUseTool` later
+     *  receives. Lets the permission flow attribute a subagent's
+     *  eagerly-emitted `tool_call` (and the permission request itself) to its
+     *  parent tool call via `_meta.claudeCode.parentToolUseId`, matching the
+     *  streamed subagent path. Best-effort: a `canUseTool` that races ahead of
+     *  the consumer processing `task_started` omits the attribution from the
+     *  eager tool_call, and the streamed tool_use chunk's refining
+     *  `tool_call_update` — which carries the message-level
+     *  `parent_tool_use_id` — restores it for merging clients; that recovery
+     *  is what makes best-effort acceptable here.
+     *
+     *  `isSubagent` — whether the task is a Task/Agent-tool subagent
+     *  (`task_started` carried a `subagent_type`). Read by
+     *  `turnAwaitingSubagents` (with `spawnedTaskIds`) to decide whether a
+     *  turn's settlement is deferred (see `Turn.deferredSettle`), so the
+     *  subagents' post-result output and permission requests stay inside the
+     *  turn (issues #864/#866). Deliberately false for non-subagent background
+     *  tasks (e.g. a `run_in_background` dev server): those can outlive every
+     *  turn, and the model's contract with them is a wake-on-exit
+     *  notification, not a turn-scoped drain — a hold must NEVER wait on a
+     *  shell.
+     *
+     *  `endedPerLevel` — a `background_tasks_changed` payload did not include
+     *  this subagent entry. The level's universe is BACKGROUND tasks only, so
+     *  a live sync (foreground) subagent is legitimately absent — its entry is
+     *  kept for permission attribution — but a hold must stop waiting on the
+     *  id: an absent id can equally be a leaked async entry whose settle
+     *  bookends were lost, and waiting on it would park the hold forever.
+     *  Non-subagent entries are simply deleted instead (shells are always in
+     *  the level's universe). */
+    liveBackgroundTasks: Map<string, {
+        parentToolUseId?: string;
+        isSubagent: boolean;
+        /** Absent-from-level lifecycle, one field so the illegal
+         *  armed-but-not-ended state is unrepresentable: undefined = live per
+         *  the level signal; "ended" = a level omitted the task (holds stop
+         *  waiting on it; attribution is kept); "sweep-armed" = a turn
+         *  activation saw it ended — the NEXT activation deletes it. The
+         *  one-activation grace exists for the absent-mark race (a level
+         *  payload built before a live async agent's registration): a
+         *  corrective inclusive level resets the field to undefined — one
+         *  assignment, disarming any in-flight sweep — if it arrives within a
+         *  full turn, keeping the agent's attribution; eager deletion would
+         *  be irreversible, since levels never ADD entries. A re-mark
+         *  preserves an in-flight arm (`??=`), keeping a continuously absent
+         *  entry on its two-activation clock. */
+        endedPerLevel?: "ended" | "sweep-armed";
+    }>;
+    /** Whether any top-level assistant text reached the client since the last
+     *  stretch boundary. Set as a side effect of sending in the consumer's
+     *  `sendUpdate`, never at an emission site; read at the terminal `result`
+     *  to tell a turn whose answer was already delivered from one that only
+     *  ever carried it on `result` (issue #453). Session-level (not
+     *  consumer-scoped) so cancel()'s inline settle can clear it.
+     *
+     *  The CURRENT boundary set — a new clear site must be added here: the
+     *  result case's `finally` (user-turn results), settleActive's wasHeld
+     *  clear (every held-turn settle lane: drain settle, both hand-offs,
+     *  stream-done), failActive, the force-cancel backstop, the idle
+     *  cancelled-settle, the autonomous-result close (only with no turn
+     *  active OR queued — see its queued-turn guard), and cancel()'s inline
+     *  mirror.
+     *
+     *  Deliberately NOT reset on turn activation: activation can fire
+     *  mid-message (see the echo hand-off), so a flag cleared there would
+     *  forget text that already streamed and the result text would be emitted
+     *  a second time. Neither the consolidated `assistant` message nor a
+     *  `stream_event` carries `origin`, so an autonomous cycle's prose is
+     *  indistinguishable from a user turn's here and sets the flag too; the
+     *  autonomous-result close normally ends that stretch so a replayed
+     *  prompt behind it still delivers, and only in the racing window (a
+     *  turn already active or queued when the autonomous result lands) does
+     *  the replayed turn stay silent rather than risk a duplicate. */
+    emittedAssistantText: boolean;
+    /** The most recent `session_state_changed` state the consumer processed.
+     *  Read by cancel() to decide whether the interrupt will produce a
+     *  trailing idle worth pre-counting: interrupting a RUNNING cycle yields
+     *  one; interrupting an already-idle session (the common held-turn shape)
+     *  yields none, and a pre-counted debt that never drains would mask one
+     *  future issue-#825 detection. */
+    lastSessionState?: "idle" | "running" | "requires_action";
+    /** How many trailing `session_state_changed: idle` messages are already
+     *  accounted for: every result is followed by one (user-turn results that
+     *  terminate a turn — settle, reject, or orphan skip — and autonomous
+     *  cycles alike), as is a cancelled turn settled by the next turn's echo
+     *  hand-off or by cancel()'s inline settle of a held turn whose interrupt
+     *  pre-empts a running cycle — the reason this lives on the Session:
+     *  cancel() must be able to record the debt. The idle handler absorbs
+     *  owed idles; an idle that arrives when NONE is owed while the active
+     *  turn is still unsettled means the SDK ended the turn without ever
+     *  emitting its result, so the turn will never settle on its own (issue
+     *  #825). Stream-level debt, deliberately NOT reset per turn: a lagged
+     *  idle can arrive after the next turn has already activated (issue
+     *  #773), and the debt is what attributes it to the turn that owed it.
+     *  Over-counting (an idle the SDK never emits) is benign: the counter
+     *  just absorbs one future idle, and detection degrades to the status quo
+     *  rather than misfiring. */
+    owedTrailingIdles: number;
     /** Maps the ACP `messageId` we expose to clients (see `messageIdForGrouping`)
      *  to the SDK message uuid that the Agent SDK's rewind/resume APIs key on
      *  (`Query.rewindFiles` takes a user-message uuid; `resumeSessionAt` takes an
@@ -251,13 +521,34 @@ type GatewayAuthMeta = {
 type GatewayAuthRequest = AuthenticateRequest & {
     _meta?: GatewayAuthMeta;
 };
+/**
+ * Resolved, non-secret + secret routing config for the `main` provider. This is
+ * the shared shape produced by both `providers/set` and the legacy gateway auth
+ * path, and consumed by {@link createEnvForProvider}. `null` means the provider
+ * is unconfigured (no client-managed routing in effect).
+ */
+type ProviderConfig = {
+    apiType: LlmProtocol;
+    baseUrl: string;
+    headers: Record<string, string>;
+    /** Present only for `apiType === "vertex"`. */
+    vertex?: {
+        projectId: string;
+        region: string;
+    };
+};
 /**
  * Extra metadata that the agent provides for each tool_call / tool_update update.
  */
 export type ToolUpdateMeta = {
     claudeCode?: {
         toolName: string;
+        title?: string;
         toolResponse?: unknown;
+        parentToolUseId?: string;
+        nonExecutionKind?: string;
+        userFeedback?: string;
+        subagent?: true;
     };
     terminal_info?: {
         terminal_id: string;
@@ -280,6 +571,25 @@ export type ToolUseCache = {
         input: unknown;
     };
 };
+type StreamedToolInput = {
+    id: string;
+    name: string;
+    partialJson: string;
+    /** Offset into `partialJson` the scanner has consumed; each delta only scans
+     *  the newly appended fragment, so total scan work stays linear. */
+    scannedTo: number;
+    inString: boolean;
+    escaped: boolean;
+    objectDepth: number;
+    arrayDepth: number;
+    /** Offset of the most recent comma at the top level of the input object
+     *  (-1 before the first). Everything before it is a complete field. */
+    lastTopLevelComma: number;
+    /** The comma offset the last emitted refinement was sliced at (-1 before the
+     *  first), so a field boundary only triggers one recovery attempt. */
+    emittedThroughComma: number;
+};
+export type StreamedToolInputCache = Map<string, Map<number, StreamedToolInput>>;
 export declare function claudeCliPath(): Promise<string>;
 /**
  * Return user-message content with local-command marker tags removed, or
@@ -289,6 +599,23 @@ export declare function claudeCliPath(): Promise<string>;
  */
 export declare function stripLocalCommandMetadata(content: unknown): unknown | null;
 export declare function isLocalCommandMetadata(content: unknown): boolean;
+/**
+ * True for the synthetic assistant message the CLI injects into the transcript
+ * when a turn fails authentication (e.g. "Not logged in · Please run /login",
+ * "Session expired. Please run /login to sign in again."). The `/login`
+ * instruction is Claude Code TUI-specific and meaningless to ACP clients
+ * (issue #863). The live prompt loop suppresses the text and fails the turn
+ * with `authRequired` so the client can run its own auth flow; replay must
+ * skip it too — both for parity with what the client saw live and because the
+ * message stays in the transcript forever, so it would resurface on every
+ * session/load even after the user has logged back in.
+ *
+ * Takes the API message (`message.message`), which replay only knows as
+ * `unknown`. The persisted record's structured `error: "authentication_failed"`
+ * marker is stripped by `getSessionMessages`, so the synthetic model + text is
+ * all both paths have to match on.
+ */
+export declare function isSyntheticLoginMessage(apiMessage: unknown): boolean;
 export declare function resolvePermissionMode(defaultMode?: unknown, logger?: Logger): PermissionMode;
 /**
  * Builds the label for the "Always Allow" permission option so the user can see
@@ -326,6 +653,10 @@ export declare class ClaudeAcpAgent {
     clientCapabilities?: ClientCapabilities;
     logger: Logger;
     gatewayAuthRequest?: GatewayAuthRequest;
+    /** Client-managed LLM routing set via `providers/set`. Process-scoped and
+     *  never persisted to disk (see the Configurable LLM Providers RFD). When
+     *  set, it takes precedence over {@link gatewayAuthRequest}. */
+    providerConfig?: ProviderConfig;
     /** Grace period before a `session/cancel` forces a wedged prompt loop to
      *  return "cancelled". See {@link DEFAULT_FORCE_CANCEL_GRACE_MS}. Mutable so
      *  tests can shrink it. */
@@ -344,8 +675,60 @@ export declare class ClaudeAcpAgent {
      *  the title is best-effort and another turn will retry. */
     private maybeUpdateSessionTitle;
     authenticate(_params: AuthenticateRequest): Promise<void>;
+    /**
+     * `providers/list` — returns the single client-configurable custom gateway
+     * provider (`main`). `current` carries only non-secret routing (never headers,
+     * which may hold secrets); only `apiType`/`baseUrl` are surfaced for UI
+     * display, and is `null` when the provider is not configured/disabled. The
+     * provider is optional (`required: false`): while disabled/unconfigured the
+     * agent falls back to its own default routing (normal Claude login).
+     */
+    unstable_listProviders(_params: ListProvidersRequest): Promise<ListProvidersResponse>;
+    /**
+     * `providers/set` — replace the full configuration for the `main` provider.
+     * Rejects unknown IDs, unsupported protocols, and empty/invalid base URLs with
+     * `invalid_params`. Config is process-scoped and applies to sessions created or
+     * loaded after this call.
+     */
+    unstable_setProvider(params: SetProviderRequest): Promise<SetProviderResponse>;
+    /**
+     * `providers/disable` — disabling the `main` provider clears any client-managed
+     * routing (both a `providers/set` config and the legacy gateway auth request),
+     * so the agent reverts to its own default routing and `providers/list` reports
+     * `current: null`. Disabling any other (unknown) ID is treated as a successful
+     * no-op per the RFD's idempotency rule.
+     */
+    unstable_disableProvider(params: DisableProviderRequest): Promise<DisableProviderResponse>;
+    /**
+     * Resolve the effective client-managed routing config. `providers/set` takes
+     * precedence; otherwise fall back to the legacy gateway auth request. Returns
+     * `null` when neither is configured.
+     */
+    resolveProviderConfig(): ProviderConfig | null;
     logout(_params: LogoutRequest): Promise<void>;
     prompt(params: PromptRequest): Promise<PromptResponse>;
+    /** Steer the session per the ACP steering wire protocol: inject a follow-up
+     *  message into the turn that is currently running. If that turn already
+     *  settled, the established default starts a new detached turn; Hosts may opt
+     *  into the host-owned `promptRequired` fallback through request `_meta`.
+     *
+     *  When a turn is in flight this injects (returns `injected`): unlike
+     *  `prompt()`, it does NOT create a Turn or enqueue on `turnQueue`; it pushes
+     *  an `SDKUserMessage` onto the same streaming input, which the SDK routes
+     *  into the in-flight turn. The injected message's echo carries a uuid that
+     *  matches no queued turn, so the consumer drops it as an unrelated replay
+     *  without promoting/settling anything. It is delivered at {@link
+     *  STEER_PRIORITY} (`now`) so it pre-empts the current generation (interrupting
+     *  a single-shot response, or slotting in between a multi-step turn's tool
+     *  calls). The steered message's own output streams via `session/update`, not
+     *  this response.
+     *
+     *  When the session is idle, the opt-in path returns `promptRequired` WITHOUT
+     *  calling `prompt()`, pushing SDK input, or mutating `turnQueue`: the content
+     *  stays Host-owned so the Host can submit it through a standard
+     *  `session/prompt`. Without the opt-in, the existing detached `prompt()` and
+     *  `startedNewTurn` result are preserved for compatibility. */
+    steer(params: SteerRequest): Promise<SteerResponse>;
     /** Lazily start the per-session consumer that drains the SDK query stream for
      *  the session's whole life. Idempotent: only the first `prompt()` starts it. */
     private ensureConsumer;
@@ -355,6 +738,22 @@ export declare class ClaudeAcpAgent {
      *  Turn's deferred when that turn ends. Replaces the per-prompt message loop;
      *  `params` only carries the (session-invariant) `sessionId`. */
     private runConsumer;
+    /** Route one orphaned command into the session's orphan-accounting lane:
+     *  the per-uuid map on msg_lifecycle_v1 CLIs (drained by the command's own
+     *  terminal lifecycle frame and the echo-less-result skip), the plain count
+     *  elsewhere (the count lane can't express per-command states, so `state`
+     *  only matters on the map lane). Both orphan-producing paths — cancel()'s
+     *  queued-turn sweep and the consumer's force-cancel wedge path — must seed
+     *  through here so the lane split stays a single mechanism.
+     *
+     *  Known window: `msgLifecycleV1` is only learnable from the stream's first
+     *  `system`/init (the control-channel initialize carries no capabilities),
+     *  so a cancel that beats that drain seeds the COUNT lane on a
+     *  lifecycle-capable CLI — where command coalescing can leave the count
+     *  stale by N-1 (the pre-map bug, confined to this sub-second window and
+     *  still healed by the next activation's reset). Structural until the SDK
+     *  exposes capabilities before the stream starts. */
+    private trackOrphanCommand;
     cancel(params: CancelNotification): Promise<void>;
     /** Mark a session's SDK query stream as permanently ended and release the
      *  resources tied to it: drop the consumer handle, dispose the settings
@@ -403,7 +802,12 @@ export declare class ClaudeAcpAgent {
      *  instead of emitting a duplicate (see `emittedToolCalls`). Built via the same
      *  `toolCallNotification` helper as the streamed path so the two are identical.
      *  Tools the stream renders as a plan (TodoWrite) or suppresses (Task*) are
-     *  skipped so a permission prompt for them never surfaces a stray tool_call. */
+     *  emitted too: a permission request referencing a tool call the client has
+     *  never seen can trip strict clients (issue #851), so the reference must
+     *  always resolve. Since the streamed path never completes those calls, they
+     *  are resolved at tool_result time instead (see `toAcpNotifications`).
+     *  `parentToolUseId` attributes a subagent's tool call to the Agent/Task call
+     *  that spawned it, matching the streamed path's `_meta`. */
     private ensureToolCallEmitted;
     canUseTool(sessionId: string): CanUseTool;
     /**
@@ -438,10 +842,11 @@ export declare class ClaudeAcpAgent {
      *  user-driven model change takes, then notifies the client. */
     private syncModelAfterRefusalFallback;
     /** Replace the Fast mode option in `session.configOptions` so it reflects
-     *  `enabled`. A no-op when the option isn't present, so callers must confirm
-     *  the current model surfaces it first. Rebuilds through the single-parameter
-     *  {@link createFastModeConfigOption} — the one source of the option's shape —
-     *  so the shape can't drift from what `buildConfigOptions` first emitted. */
+     *  `enabled` (and the session's current disabled reason). A no-op when the
+     *  option isn't present, so callers must confirm the current model surfaces
+     *  it first. Rebuilds through {@link createFastModeConfigOption} — the one
+     *  source of the option's shape — so the shape can't drift from what
+     *  `buildConfigOptions` first emitted. */
     private refreshFastModeOption;
     /** Toggle Fast mode for a session: push the SDK flag, record the user's
      *  intent, and refresh the Fast mode config option in place. Only reached
@@ -502,7 +907,14 @@ export declare class ClaudeAcpAgent {
      *     here).
      *   - `cooldown`: a transient suspension of an already-enabled fast mode.
      *     Leave the toggle as-is rather than flapping it — and never let a stray
-     *     cooldown spuriously enable a toggle the user has off. */
+     *     cooldown spuriously enable a toggle the user has off.
+     *
+     *  `reason` is the SDK's `fast_mode_disabled_reason`, reported alongside the
+     *  state. Only explainable reasons are retained (see
+     *  {@link normalizeFastModeDisabledReason}), so the comparison below tracks
+     *  exactly what the user can see: a routine `sdk_opt_in_required` report on
+     *  every turn's result can't churn the option, while a real blocker updates
+     *  the description even when the toggle's own value is unchanged. */
     private syncFastModeState;
     private getOrCreateSession;
     /**
@@ -539,13 +951,31 @@ export declare const FAST_MODE_OFF = "off";
  *  docs) keeps the toggle on so it reflects the user's intent — only an
  *  explicit `off` clears it. */
 export declare function fastModeStateEnabled(state: FastModeState): boolean;
+/** Normalize an SDK-reported `fast_mode_disabled_reason` to the one we retain:
+ *  a reason we have an explanation for, else `undefined`. Keeping only
+ *  explainable reasons means state comparisons (see `syncFastModeState`) track
+ *  exactly what the user can see, so routine reports like
+ *  `sdk_opt_in_required` never churn the config option. */
+export declare function normalizeFastModeDisabledReason(reason: FastModeDisabledReason | undefined): FastModeDisabledReason | undefined;
 /** Build the Fast mode config option as a two-value on/off `select`. Emitted
- *  for EVERY Client — the boolean option shape is gone (story 006, R2.1). Only
- *  the emitted SHAPE is fixed to a select; boolean VALUES are still honored on
- *  set (see {@link resolveFastModeEnabled}). This factory is the single source
- *  of the option's shape, re-rendered by `refreshFastModeOption` /
- *  `syncFastModeState` so the shape can never desync. */
-export declare function createFastModeConfigOption(enabled: boolean): SessionConfigOption;
+ *  for EVERY Client — the boolean option shape is gone (story 006, R2.1;
+ *  retained through the v0.64.0 sync by story 008 R3.4). Only the emitted SHAPE
+ *  is fixed to a select; boolean VALUES are still honored on set (see
+ *  {@link resolveFastModeEnabled}). This factory is the single source of the
+ *  option's shape, re-rendered by `refreshFastModeOption` / `syncFastModeState`
+ *  so the shape can never desync.
+ *
+ *  `disabledReason` (the SDK's `fast_mode_disabled_reason`, upstream v0.64.0) is
+ *  folded into the description while the toggle reads off, so a user whose
+ *  account or provider can't serve Fast mode sees why instead of a switch that
+ *  silently refuses to stay on. Ignored while enabled: a reason reported
+ *  alongside an `on`/`cooldown` state isn't blocking anything right now.
+ *
+ *  Upstream's second parameter (`useBooleanOption`) is deliberately absent: the
+ *  shape is unconditionally a select, so there is no branch to select. What
+ *  guards that is behavioural, not structural — `tests/fast-mode-select-only.
+ *  test.ts` proves no argument combination can yield the boolean shape. */
+export declare function createFastModeConfigOption(enabled: boolean, disabledReason?: FastModeDisabledReason): SessionConfigOption;
 /** Resolve the requested Fast mode value from a `session/set_config_option`
  *  request. Accepts the select's "on"/"off" strings or a native boolean,
  *  kept for backward compatibility (R2.3). */
@@ -557,6 +987,9 @@ export declare function resolveFastModeEnabled(params: {
 export type FastModeOptionState = {
     supported: boolean;
     enabled: boolean;
+    /** Latest explainable `fast_mode_disabled_reason`, folded into the option's
+     *  description while the toggle reads off. */
+    disabledReason?: FastModeDisabledReason;
 };
 export declare function buildConfigOptions(modes: SessionModeState, models: SessionModelState, modelInfos: ModelInfo[], currentEffortLevel?: string, agents?: AgentInfo[], currentAgent?: string, fastMode?: FastModeOptionState, 
 /** Display state for the Thinking toggle: the session's tri-state intent
@@ -632,6 +1065,8 @@ export declare function toAcpNotifications(content: string | ContentBlockParam[]
     taskState?: TaskState;
     emittedToolCalls?: Set<string>;
     messageId?: string;
+    toolUseResult?: unknown;
+    toolResultMeta?: unknown;
 }): SessionNotification[];
 export declare function streamEventToAcpNotifications(message: SDKPartialAssistantMessage, sessionId: string, toolUseCache: ToolUseCache, client: AcpClient, logger: Logger, options?: {
     clientCapabilities?: ClientCapabilities;
@@ -639,6 +1074,7 @@ export declare function streamEventToAcpNotifications(message: SDKPartialAssista
     taskState?: TaskState;
     emittedToolCalls?: Set<string>;
     messageId?: string;
+    streamedToolInputs?: StreamedToolInputCache;
 }): SessionNotification[];
 /** Run a `session/prompt` while honoring `$/cancel_request` for it. ACP clients
  *  normally stop a turn with the `session/cancel` notification, but `signal`