@lucascouts/claude-agent-tui 0.6.0 → 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";
@@ -31,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;
@@ -107,11 +108,14 @@ type Session = {
      */
     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. */
@@ -415,6 +419,13 @@ export interface AgentDeps {
      * `~/.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
@@ -560,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;
@@ -587,6 +606,8 @@ export declare class ClaudeAcpAgent implements Agent {
     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;
@@ -600,6 +621,17 @@ 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`,
@@ -617,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>;
     /**
@@ -895,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

package/dist/acp-agent.js

@@ -24,12 +24,16 @@ import { guardEvent } from "./billing/entrypoint-guard.js";
 import { usageUpdatesFor } from "./usage.js";
 import { createTurnResolver } from "./end-of-turn.js";
 import { sendPrompt } from "./engine-pty.js";
-import { MODEL_CATALOG, DEFAULT_MODEL_INFO, ULTRACODE_EFFORT, ULTRACODE_EFFORT_LEVEL, ULTRACODE_EFFORT_LABEL, } from "./model-catalog.js";
+import { MODEL_CATALOG, MODEL_CONTEXT_WINDOWS, MODEL_ID_CONTEXT_WINDOWS, modelSelectorDescription, DEFAULT_MODEL_INFO, ULTRACODE_EFFORT, ULTRACODE_EFFORT_LEVEL, ULTRACODE_EFFORT_LABEL, } from "./model-catalog.js";
 // Story 060 (R2.2/R2.3/R3.2) — the declarative spawn-time complement to the live ultracode keyword:
 // toggle the {ultracode,ultracodeKeywordTrigger} keys in the gate's per-session scratch settings file
 // (preserving the hook + every other key). Lives in the gate's settings-writer so it reuses durableWrite.
 import { applyUltracodeSettings } from "./gate/settings-writer.js";
 import { discoverAgents } from "./agent-catalog.js";
+// Story 063 (R1) — OFFLINE disk discovery of the `available_commands` set (custom slash-commands +
+// skills + enabled-plugin surfaces + built-ins), keyed on the session cwd. Populates the
+// `available_commands_update` the session emits at creation in place of the old unconditional `[]`.
+import { discoverCommands } from "./command-catalog.js";
 import { setupSessionGate } from "./permissions/gate-wiring.js";
 // Story 057 / Task 2.3 — MCP scratch-file lifecycle (translate ACP servers → claude `--mcp-config`
 // JSON, durable 0600 write, idempotent teardown removal). Mirrors the gate's settings-scratch
@@ -50,7 +54,7 @@ function sanitizeTitle(text) {
     }
     return sanitized.slice(0, MAX_TITLE_LENGTH - 1) + "…";
 }
-const DEFAULT_CONTEXT_WINDOW = 200000;
+export const DEFAULT_CONTEXT_WINDOW = 200000;
 /**
  * No-op {@link IPty} stub for the Degrau-1 replay-only load path: there is no live `claude` process,
  * but the session record's `pty` field is typed `IPty`. Every method is inert — teardown's `kill()`
@@ -532,6 +536,14 @@ function deriveSubagentLabel(messages, parentId) {
 export class ClaudeAcpAgent {
     constructor(client, logger, engine = createStubEngine(), deps = {}) {
         this.backgroundTerminals = {};
+        /**
+         * 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.
+         */
+        this.clientSupportsElicitationForm = false;
         /** Live PTY-engine registry shared with the per-session engines (story 014 cleanup map). */
         this.engines = new Map();
         this.sessions = {};
@@ -571,12 +583,27 @@ export class ClaudeAcpAgent {
         // Story 056 (R3.2): main-thread agent-persona discovery — defaults to the glob-only
         // discoverAgents; tests inject an in-memory fake so the `agent` surface is hermetic.
         this.discoverAgents = deps.discoverAgents ?? discoverAgents;
+        // Story 063 (R1/R1.1): offline `available_commands` discovery — defaults to the disk-only
+        // discoverCommands; tests inject an in-memory fake so the surface is hermetic (no real ~/.claude read).
+        this.discoverCommands = deps.discoverCommands ?? discoverCommands;
         // Story 056 (#812): end-of-turn session_info_update title source — defaults to the pure SDK
         // getSessionInfo; tests inject an in-memory fake so the push is hermetic (no real ~/.claude read).
         this.getSessionInfo = deps.getSessionInfo ?? getSessionInfo;
     }
     async initialize(request) {
         this.clientCapabilities = request.clientCapabilities;
+        // Story 065 (R1/R3): capability negotiation — a present (non-null) `elicitation.form`
+        // means the client supports form elicitation. Presence-based detection is deliberate: both
+        // `undefined` and `null` are unsupported, and an empty `{}` `form` IS supported (the UNSTABLE
+        // ElicitationFormCapabilities type carries only an optional `_meta`, so a present `form` is
+        // legitimately `{}` — detection MUST be presence-based, not truthiness). Written as explicit
+        // `!== undefined && !== null` (not `!= null`) to satisfy the eqeqeq lint rule.
+        const elicitationForm = request.clientCapabilities?.elicitation?.form;
+        this.clientSupportsElicitationForm = elicitationForm !== undefined && elicitationForm !== null;
+        // Story 065 (Task 6.1 live-probe): make the negotiated capability observable in the Zed logs so
+        // the in-Zed verdict (form rendered vs. gated-dormant behind the 064 deny) is deterministic. Goes
+        // to STDERR via logger.error — NEVER stdout, which carries the ACP ndJson stream.
+        this.logger.error(`[065] clientCapabilities.elicitation.form advertised: ${this.clientSupportsElicitationForm}`);
         // Bypasses standard auth by routing requests through a custom Anthropic-protocol gateway.
         // Only offered when the client advertises `auth._meta.gateway` capability.
         const supportsGatewayAuth = request.clientCapabilities?.auth?._meta?.gateway === true;
@@ -780,6 +807,19 @@ export class ClaudeAcpAgent {
         }
         throw new Error("Method not implemented.");
     }
+    /**
+     * 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).
+     */
+    async logout(_params) {
+        this.gatewayAuthRequest = undefined;
+    }
     async prompt(params) {
         const sessionRecord = this.sessions[params.sessionId];
         if (!sessionRecord) {
@@ -983,6 +1023,8 @@ export class ClaudeAcpAgent {
     }
     /** Tear down all active sessions. Called when the ACP connection closes. */
     async dispose() {
+        // Drop the in-memory auth intent on teardown (story 062 R7) — same clear as logout().
+        this.gatewayAuthRequest = undefined;
         await Promise.all(Object.keys(this.sessions).map((id) => this.teardownSession(id)));
     }
     async closeSession(params) {
@@ -992,7 +1034,7 @@ export class ClaudeAcpAgent {
         await this.teardownSession(params.sessionId);
         return {};
     }
-    async unstable_deleteSession(params) {
+    async deleteSession(params) {
         // Tear down any active in-memory state first so the on-disk file isn't
         // recreated by an outstanding query writing to it.
         if (this.sessions[params.sessionId]) {
@@ -1585,6 +1627,14 @@ export class ClaudeAcpAgent {
         // in pumpUpdates, so the replay-only load never emitted it).
         if (session && !session.usageDisabled) {
             const carrier = turn.message.message ?? {};
+            // Story 069 (R1) — refine the window from the turn's REAL model (the JSONL `model`), authoritatively
+            // correcting the alias seed (e.g. default → claude-opus-4-8[1m] → 1M). A missing / non-string model or
+            // an unknown id leaves the current value unchanged (R1.3 — never overwrite with null).
+            const realModel = carrier.model;
+            if (typeof realModel === "string" && realModel.length > 0) {
+                session.contextWindowSize =
+                    inferContextWindowFromModelId(realModel) ?? session.contextWindowSize;
+            }
             for (const usageUpdate of usageUpdatesFor(carrier, {
                 usageUpdate: this.usageUpdate,
                 contextWindowSize: session.contextWindowSize,
@@ -1914,15 +1964,26 @@ export class ClaudeAcpAgent {
         const session = this.sessions[sessionId];
         if (!session)
             return;
-        // === SEAM(023) Group 1: read-only Degrau-1 shim — emit a static (empty) command set. The SDK
-        // `query.supportedCommands()` is dropped; slash commands are owned by the interactive TUI in
-        // Degrau-1 and are not enumerable over the read-only JSONL path.
-        // Degrau 2 (030/032): PTY-backed control — surface the TUI's real command set. ===
+        // === SEAM(023) Group 1: `available_commands_update`. Historically the SDK
+        // `query.supportedCommands()` was dropped (slash commands are owned by the interactive TUI and are
+        // not enumerable over the read-only JSONL path), so Degrau-1 emitted a static empty set.
+        // Story 063 (R1/R1.1) now POPULATES this set OFFLINE from disk — `discoverCommands(session.cwd)`
+        // scans the cwd/user `.claude/{commands,skills}`, the enabled-plugin surfaces, and the built-in
+        // tier — instead of the unconditional `[]`. Discovery is SYNCHRONOUS but the 4 call-sites invoke
+        // this method fire-and-forget (`setTimeout(0)`), so it never blocks session creation (R4).
+        // Degrau 2 (030/032): PTY-backed control — surface the TUI's real live command set. ===
+        let availableCommands;
+        try {
+            availableCommands = this.discoverCommands(session.cwd);
+        }
+        catch {
+            availableCommands = []; // R4 — discovery must NEVER crash the session; degrade to []
+        }
         await this.client.sessionUpdate({
             sessionId,
             update: {
                 sessionUpdate: "available_commands_update",
-                availableCommands: [],
+                availableCommands,
             },
         });
     }
@@ -2113,6 +2174,11 @@ export class ClaudeAcpAgent {
             gate = await setupSessionGate({
                 ...this.gateOptions,
                 client: this.client,
+                // Story 065 (R1/R3): negotiated in initialize() from clientCapabilities.elicitation.form. When
+                // true the gate drives AskUserQuestion through a real ACP form elicitation; when false it keeps
+                // the story-064 fail-closed deny-guard. this.client (AgentSideConnection) already satisfies the
+                // broadened client type (it has unstable_createElicitation).
+                clientSupportsElicitationForm: this.clientSupportsElicitationForm,
                 onWarn: (m) => this.logger.error(m),
             });
         }
@@ -2326,7 +2392,9 @@ function buildConfigOptions(modes, currentModelId, modelInfos, currentEffortLeve
             options: modelInfos.map((m) => ({
                 value: m.value,
                 name: m.displayName,
-                description: m.description ?? undefined,
+                // Story 072 — prepend the version/context label ("Opus 4.8 with 1M context · <tagline>"),
+                // mirroring the live `/model` picker; bare tagline when no label (e.g. opusplan).
+                description: modelSelectorDescription(m) || undefined,
             })),
         },
     ];
@@ -2955,13 +3023,60 @@ export function runAcp(deps) {
     }, stream);
     return { connection, agent };
 }
-/** Best-effort first guess of a model's context window from its ID, used only
- *  until a `result` message arrives with the authoritative `modelUsage` value.
- *  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 things like "10m" or embedded substrings. */
-function inferContextWindowFromModel(model) {
+/** 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 function inferContextWindowFromModel(model) {
+    const mapped = MODEL_CONTEXT_WINDOWS[model];
+    if (mapped !== undefined)
+        return mapped; // exact alias hit (!== undefined, NOT truthiness)
     if (/\b1m\b/i.test(model))
+        return 1_000_000; // unknown alias that still encodes a 1m token
+    return null; // caller applies ?? DEFAULT_CONTEXT_WINDOW
+}
+/** 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 function inferContextWindowFromModelId(id) {
+    if (typeof id !== "string" || id.length === 0)
+        return null;
+    const exact = MODEL_ID_CONTEXT_WINDOWS[id];
+    if (exact !== undefined)
+        return exact;
+    // An explicit long-context `[1m]`/`-1m` suffix wins over the family heuristic
+    // (`claude-sonnet-…[1m]` = 1M, not 200K; `/model default` resolves to `claude-opus-4-8[1m]`).
+    if (/\b1m\b/i.test(id))
+        return 1_000_000;
+    const opus = id.match(/claude-opus-(\d+)-(\d+)/);
+    if (opus) {
+        const major = Number(opus[1]);
+        const minor = Number(opus[2]);
+        return major > 4 || (major === 4 && minor >= 7) ? 1_000_000 : 200_000;
+    }
+    if (/claude-fable/.test(id))
         return 1_000_000;
+    // Sonnet is NOT uniform across generations (story 071): the subscription CLI serves Sonnet 4.x
+    // at 200K but Sonnet 5+ natively at 1M (Sonnet 5 has no smaller context variant). Version-aware,
+    // like the Opus 4-6 vs 4-7/4-8 split above; dated snapshots (`claude-sonnet-5-<date>`) match too.
+    const sonnet = id.match(/claude-sonnet-(\d+)/);
+    if (sonnet)
+        return Number(sonnet[1]) >= 5 ? 1_000_000 : 200_000;
+    if (/claude-haiku/.test(id))
+        return 200_000;
     return null;
 }

package/dist/agent-catalog.d.ts

@@ -93,4 +93,3 @@ export declare function parseFrontmatter(content: string): Frontmatter;
  */
 export declare function discoverAgents(cwd: string, deps?: DiscoverAgentsDeps): AgentCatalogEntry[];
 export {};
-//# sourceMappingURL=agent-catalog.d.ts.map

package/dist/ansi-mirror.d.ts

@@ -39,4 +39,3 @@ export interface AnsiMirrorOptions {
  * sequence the JSONL tail produces.
  */
 export declare function attachAnsiMirror(p: Pick<IPty, "onData">, opts?: AnsiMirrorOptions): IDisposable | undefined;
-//# sourceMappingURL=ansi-mirror.d.ts.map

package/dist/besteffort.d.ts

@@ -41,4 +41,3 @@ export declare function translateBestEffort(content: string | ContentBlock[], ro
     translate?: TranslateFn;
 }): SessionNotification[];
 export {};
-//# sourceMappingURL=besteffort.d.ts.map

package/dist/billing/entrypoint-guard.d.ts

@@ -94,4 +94,3 @@ export declare function guardEvent(event: WatchedMessage, hooks: GuardHooks): Gu
  *   is the spawn helper's anti-recusa concern, distinct from this billing check — §10).
  */
 export declare function assertCleanBillingEnv(env: Record<string, string | undefined>): void;
-//# sourceMappingURL=entrypoint-guard.d.ts.map

package/dist/claude-path.d.ts

@@ -52,4 +52,3 @@ export interface ResolveOptions {
  * @throws Error naming the PATH lookup attempt if no executable `claude` is found.
  */
 export declare function resolveClaudePath(opts?: ResolveOptions): string;
-//# sourceMappingURL=claude-path.d.ts.map

package/dist/command-catalog.d.ts

@@ -0,0 +1,84 @@
+import type { AvailableCommand } from "@agentclientprotocol/sdk";
+/**
+ * The curated built-in slash-command tier (R9) — the interactive `claude` TUI's own built-ins, which are
+ * baked into the binary and therefore NOT disk-discoverable. This is a CURATED APPROXIMATION (C1), NOT a
+ * live probe: it stands beside the same static-curation idea as `MODEL_CATALOG`. It is the LOWEST-
+ * precedence tier, so any disk command/skill of the same name shadows a built-in (R1/R9). Names are
+ * lowercase (R3) and every entry carries a non-empty `description` (the SDK requires it). The list is
+ * intentionally small and conservative — a documented approximation, not an exhaustive enumeration.
+ */
+export declare const BUILTIN_COMMANDS: readonly AvailableCommand[];
+/**
+ * Injectable seams for {@link discoverCommands} — defaults wire the `node:` stdlib and the built-in
+ * tier. Tests pass fakes so discovery is exercised against an in-memory fs and an isolated (`[]`)
+ * built-in tier, never the real disk or the real `~/.claude` (R5).
+ */
+export interface DiscoverCommandsDeps {
+    /** Resolve the user's home directory (default: `os.homedir`). */
+    homedir?: () => string;
+    /** List the `*.md` filenames in `dir`; MUST return `[]` when `dir` is missing/unreadable. */
+    readdirMd?: (dir: string) => string[];
+    /**
+     * List the IMMEDIATE sub-directory names of `dir` (for the skills tier — R7); MUST return `[]` when
+     * `dir` is missing/unreadable. Default: {@link defaultReaddirDirs}.
+     */
+    readdirDirs?: (dir: string) => string[];
+    /** Read a file's UTF-8 contents (default: `fs.readFileSync(p, "utf8")`). */
+    readFile?: (path: string) => string;
+    /** The built-in command tier (lowest precedence). Default: {@link BUILTIN_COMMANDS}. */
+    builtins?: readonly AvailableCommand[];
+}
+/**
+ * The command-name allowlist (R3). A single un-namespaced segment: LOWERCASE letters/digits/underscore/
+ * hyphen only (no spaces, no uppercase, no shell metacharacters, no path separators). Slash-command
+ * names are conventionally lowercase, so — unlike `agent-catalog.ts`'s {@link SAFE_AGENT_NAME} — this
+ * allowlist excludes uppercase.
+ */
+export declare const SAFE_COMMAND_NAME: RegExp;
+/** True iff `name` is a non-empty string matching {@link SAFE_COMMAND_NAME} (R3). */
+export declare function isSafeCommandName(name: unknown): name is string;
+/** The frontmatter fields we extract — `description` and (hyphenated) `argument-hint`. */
+interface CommandFrontmatter {
+    description?: string;
+    argumentHint?: string;
+}
+/**
+ * Minimal `---`-fenced frontmatter line-parser (NOT a full YAML dep). Reads the leading `---\n … \n---`
+ * block and pulls the `description` and `argument-hint` `key: value` lines; a single pair of surrounding
+ * quotes on a value is stripped. The frontmatter key `argument-hint` (a HYPHEN) is returned as the
+ * camelCase {@link CommandFrontmatter.argumentHint}. A file whose first line is not `---` yields `{}`.
+ * Tiny + pure on purpose, mirroring `agent-catalog.ts`'s `parseFrontmatter` — the command frontmatter we
+ * consume is flat `key: value`.
+ */
+export declare function parseCommandFrontmatter(content: string): CommandFrontmatter;
+/**
+ * Discover the custom slash-commands to advertise via ACP `available_commands` — FULLY OFFLINE (no
+ * subprocess, no network).
+ *
+ * TIERS, highest precedence first:
+ *   1. `<cwd>/.claude/commands/*.md`      (cwd commands — R1.1 precedence)
+ *   2. `<cwd>/.claude/skills/<name>/SKILL.md` (cwd skills — R7)
+ *   3. `~/.claude/commands/*.md`           (user commands)
+ *   4. `~/.claude/skills/<name>/SKILL.md`   (user skills — R7)
+ *   5. `~/.claude/plugins/marketplaces/<m>/{commands,skills}` (ENABLED-plugin tier — R8; a plugin
+ *      surface loses a name collision to any higher tier — R8.1)
+ *   6. {@link DiscoverCommandsDeps.builtins} (the R9 built-in tier — LOWEST; a built-in loses a name
+ *      collision to any disk entry)
+ *
+ * Each command `*.md` file yields `{ name, description, input? }` (R2): `name` = basename sans `.md`,
+ * `description` = frontmatter `description` (else `""`), `input: { hint }` from `argument-hint` (omitted
+ * when absent). Each skill `<name>/SKILL.md` yields `{ name, description }` (no `input`): `name` = the
+ * DIRECTORY name, `description` = the `SKILL.md` frontmatter (R7 / R7.1). Every name is dropped if it
+ * fails the R3 {@link SAFE_COMMAND_NAME} allowlist. Names are deduped FIRST-WINS across the ordered
+ * surfaces — so a cwd command out-ranks a cwd skill (cmd > skill, same scope), any cwd surface
+ * out-ranks any user surface, an enabled-plugin surface out-ranks the built-ins but LOSES to any
+ * cwd/user surface (R8.1) — then the merged set is returned FLAT ALPHABETICAL by `name`.
+ *
+ * Never throws (R3 / R5): a missing/unreadable dir or file yields `[]` for that surface; a skills subdir
+ * without a readable `SKILL.md` is skipped.
+ *
+ * @param cwd  the SESSION cwd (project dir) whose `.claude/{commands,skills}` take precedence.
+ * @param deps injectable fs/home/builtins seams (default: `node:` stdlib + {@link BUILTIN_COMMANDS}).
+ */
+export declare function discoverCommands(cwd: string, deps?: DiscoverCommandsDeps): AvailableCommand[];
+export {};