@lucascouts/claude-agent-acp-plus 0.26.0 → 0.28.0

package/dist/ultracode.d.ts

@@ -1,100 +1,166 @@
 /**
- * The "Ultracode" entry of the Effort picker.
+ * Ultracode — an independent, session-scoped boolean option.
  *
- * **Ultracode is not a sixth effort level, and reading it as one produces the
- * wrong control.** Claude Code's VS Code extension models it as a boolean that
- * turns on two things at once — `xhigh` effort *and* standing dynamic-workflow
- * orchestration — and its own tooltip says so: `"Ultracode - xhigh +
- * workflows"`. Its five real levels are `low` `medium` `high` `xhigh` `max`;
- * Ultracode is drawn as one extra notch past the last of them, styled
- * differently, and selecting any ordinary level clears it.
+ * **What it is.** The SDK's `Settings.ultracode` is *"standing
+ * dynamic-workflow orchestration at any effort level"*, session-scoped and
+ * applied through `apply_flag_settings`. It is not an effort level and it does
+ * not imply one: the CLI (`/effort ultracode on|off`, "any effort level, this
+ * session only") and the VS Code extension (a switch in the effort popover)
+ * both model it as a toggle beside effort. An earlier version of this module
+ * followed an older extension tooltip ("xhigh + workflows") and drew it as a
+ * notch in the effort select that forced `xhigh`; that silently raised the
+ * effort of a session started with `ultracode: true`, cleared it on any effort
+ * pick, and lost it on a model switch (PARITY-REPORT §21.2).
  *
- * ACP has no compound control to carry that, so the adapter projects it the way
- * the extension's UI reads rather than the way its state is stored: one more
- * entry in the `effort` select. The compound stays here, in one module, instead
- * of being spread across the three places `acp-agent.ts` applies effort.
+ * **The wire contract** (`applyFlagSettings`, unchanged SDK 0.3.285..0.3.299):
+ * - `ultracode: true|false` turns it on or off and leaves effort alone;
+ * - an `effortLevel` change sent WITHOUT the key turns it off;
+ * - `null` resets it to off.
+ * Hence the two payload rules below: the toggle sends `{ultracode:true}` or
+ * `{ultracode:null}`, and every effort change re-sends `ultracode:true` while
+ * the intent is on — and never `null`.
  *
- * The SDK carries both halves and names the channel: `Settings.ultracode` is
- * *"xhigh effort plus standing dynamic-workflow orchestration. Session-scoped —
- * typically provided via --settings or the apply_flag_settings control
- * request"*. `apply_flag_settings` is already how the effort option is applied,
- * so no new transport is involved.
+ * **Intent is not availability.** The CLI keeps the request and computes "in
+ * effect = requested and available", where available means workflows are
+ * enabled and the model supports `xhigh`. The adapter mirrors that: the
+ * session holds the intent, the option is shown only while available, and a
+ * model switch never drops the intent. The CLI reports both through the
+ * `get_settings` control request (`applied.{ultracode, ultracodeRequested,
+ * ultracodeAvailable}`), which the SDK runtime exposes as `Query.getSettings()`
+ * but `sdk.d.ts` does not declare — {@link readUltracodeState} wraps it.
  *
  * Kept self-contained — no import from `acp-agent.ts` — for the reason
- * `thinking-option.ts` and `rewind-command.ts` state: that file is ~9,900 lines
- * and moves upstream almost daily, so every coupling to it is paid again at
- * each sync.
+ * `thinking-option.ts` and `rewind-command.ts` state: that file is ~10,000
+ * lines and moves upstream almost daily, so every coupling to it is paid again
+ * at each sync.
  */
+import type { SessionConfigOption, SetSessionConfigOptionRequest } from "@agentclientprotocol/sdk";
 import type { EffortLevel, Settings } from "@anthropic-ai/claude-agent-sdk";
-/** Value of the synthetic "Ultracode" entry in the effort picker. It is a
- *  reserved sentinel: no `EffortLevel` is spelled this way, so it cannot
- *  collide with a level the SDK reports in `supportedEffortLevels`. */
-export declare const ULTRACODE_OPTION_VALUE = "ultracode";
-/** Display name of that entry, matching the extension's own label. */
+/** Config option id. */
+export declare const ULTRACODE_CONFIG_ID = "ultracode";
+/** Display name, matching the CLI's and the extension's label. */
 export declare const ULTRACODE_OPTION_NAME = "Ultracode";
-/** The effort level Ultracode implies. Not configurable: the extension hardcodes
- *  `xhigh` in `enableUltracode()`, and the SDK's own description of the setting
- *  names the same level. A different level here would silently mean something
- *  else than it does in the reference client. */
+/** Select-fallback values for clients without boolean config options. The
+ *  same spelling Fast mode uses, so one client-side mapping serves both. */
+export declare const ULTRACODE_ON = "on";
+export declare const ULTRACODE_OFF = "off";
+/** The effort level the model must support for Ultracode to be available.
+ *  Availability only: Ultracode never SETS this level. */
 export declare const ULTRACODE_EFFORT_LEVEL: EffortLevel;
-/** Display state for the Ultracode entry, resolved by the caller. Mirrors the
- *  shape `FastModeOptionState` uses for the same job — availability and current
- *  value are two different questions, and folding them into one boolean loses
- *  the case where the entry should render but not be selected. */
+/** The value the old effort-select notch carried. Accepted for one release
+ *  from clients that still send it (see {@link isLegacyUltracodeEffort}). */
+export declare const LEGACY_ULTRACODE_EFFORT_VALUE = "ultracode";
+/** Display state for the option, resolved by the caller. Mirrors
+ *  `FastModeOptionState`: availability and value are different questions. */
 export interface UltracodeOptionState {
-    /** Whether the entry should appear at all. */
+    /** Whether the option is shown at all. */
     available: boolean;
-    /** Whether it is the currently selected effort. */
-    enabled: boolean;
+    /** The session's intent — shown as the option's value. */
+    requested: boolean;
+    /** Whether the client opted into boolean config options. */
+    useBooleanOption: boolean;
 }
 /**
- * Whether the Ultracode entry may be offered, under the same two conditions the
- * extension checks in its own `ultracodeAvailable`:
+ * The fallback availability check, used until (or instead of) the CLI's own
+ * `applied.ultracodeAvailable`:
  *
- * 1. workflows are not disabled — Ultracode *is* the workflow half, so offering
- *    it where `disableWorkflows` is set would advertise something that cannot
- *    happen;
- * 2. the current model supports `xhigh` — Ultracode has no meaning on a model
- *    that cannot reach the level it implies.
+ * 1. workflows are not disabled — Ultracode *is* workflow orchestration;
+ * 2. the current model supports `xhigh`.
  *
- * Both are read rather than assumed: an unknown settings shape leaves
- * `disableWorkflows` undefined, which is *not* `true`, so the gate opens — the
- * same direction the extension's `=== !0` comparison takes.
+ * Partial by nature: the CLI also checks managed settings, org policy,
+ * `enableWorkflows` and `CLAUDE_CODE_DISABLE_WORKFLOWS`. An absent
+ * `disableWorkflows` opens the gate, the same direction the extension's
+ * `=== !0` comparison takes.
  */
 export declare function isUltracodeAvailable(supportedEffortLevels: readonly string[], settings: Pick<Settings, "disableWorkflows"> | undefined): boolean;
-/** Whether a picker value denotes Ultracode rather than a plain effort level. */
-export declare function isUltracodeValue(value: string | undefined): boolean;
+/** Build the option: a native boolean for clients that opted in, an on/off
+ *  select otherwise (the ACP boolean-config-option RFD makes that a MUST). */
+export declare function createUltracodeConfigOption(requested: boolean, useBooleanOption: boolean): SessionConfigOption;
+/** The option for a resolved state, or `undefined` while unavailable. */
+export declare function ultracodeConfigOption(state: UltracodeOptionState | undefined): SessionConfigOption | undefined;
 /**
- * The `apply_flag_settings` payload for an effort selection, Ultracode included.
+ * Put the option where it belongs in an existing list — right after `effort`
+ * (after `model` when the model has no effort option), before `fast` — or
+ * remove it when `next` is undefined. Used when a background readback changes
+ * availability without a full rebuild.
+ */
+export declare function placeUltracodeOption(options: SessionConfigOption[], next: SessionConfigOption | undefined): SessionConfigOption[];
+/** Resolve the requested value from `session/set_config_option`: a native
+ *  boolean, or the on/off select-fallback strings. */
+export declare function resolveUltracodeRequested(params: SetSessionConfigOptionRequest): boolean;
+/** The toggle's payload. Off is an explicit `null`: `undefined` is dropped by
+ *  JSON transport, and the SDK only clears a flag on `null`. */
+export declare function ultracodeTogglePayload(requested: boolean): {
+    ultracode: true | null;
+};
+/**
+ * The `apply_flag_settings` payload for an effort change — a user pick, the
+ * model-switch fallback, the initial effort, or a recreate's replay.
  *
- * **The `null` is the load-bearing part.** The SDK shallow-merges flag settings
- * and only clears a key when an explicit `null` arrives — `undefined` is dropped
- * by JSON transport and leaves the previous value standing. So every selection
- * has to say something about `ultracode`, not just the one that turns it on:
- * without the clear, picking `High` after Ultracode would lower the effort and
- * leave workflow orchestration running, which is a state no picker entry names.
- * The same reasoning applies to `effortLevel` — this function absorbed the older
- * `toSdkEffortLevel` helper for exactly that reason: both keys are decided in
- * one place, so neither can be forgotten on a path the other takes.
+ * An `effortLevel` change sent without `ultracode` turns Ultracode off, so the
+ * key rides along whenever the intent is on. It is never sent as `null` here:
+ * an effort change is not a request to turn Ultracode off.
  *
- * @param value the picker value — `"default"`, an `EffortLevel`, or the
- *   Ultracode sentinel. `undefined` means the option is absent for this model.
+ * @param value the effort select's value — `"default"`, an `EffortLevel`, or
+ *   `undefined` when the model has no effort option.
  */
-export declare function ultracodeFlagSettings(value: string | undefined): {
+export declare function effortFlagSettings(value: string | undefined, ultracodeRequested: boolean): {
     effortLevel: EffortLevel | null;
-    ultracode: boolean | null;
+    ultracode?: true;
 };
+/** Whether an effort value is the retired Ultracode notch. Clients that saved
+ *  it get `{effortLevel:'xhigh', ultracode:true}` for one release. */
+export declare function isLegacyUltracodeEffort(value: unknown): boolean;
+/** What the CLI reported. Each field is absent when the CLI did not say. */
+export interface UltracodeReadback {
+    requested?: boolean;
+    available?: boolean;
+}
 /**
- * The picker value to display, given the persisted effort level and whether the
- * Ultracode flag is on.
+ * Read `applied.{ultracodeRequested, ultracodeAvailable}` through the SDK's
+ * untyped `Query.getSettings()`.
+ *
+ * Structural, never trusting: an SDK without the method, a rejected request,
+ * or a response without `applied` all resolve to `undefined`, and the caller
+ * keeps the heuristic. Never rejects.
  *
- * The flag wins over the level, and only when it is *available*: a session that
- * carries `ultracode: true` from settings while the current model cannot reach
- * `xhigh` must not show an entry the picker is not rendering. The extension
- * reaches the same state through `adoptAppliedEffort`, which reads
- * `applied.ultracode` first and falls back to inferring it from `xhigh`; we do
- * not infer, because `xhigh` alone is a legitimate selection that is not
- * Ultracode, and guessing would silently turn workflows on in the label.
+ * **Call it in the background, never inline.** Control requests are
+ * serialized and queue ahead of interrupt and close (upstream #1216), and on a
+ * fresh session the CLI does not service them until the first turn.
+ */
+export declare function readUltracodeState(query: unknown, onError?: (error: unknown) => void): Promise<UltracodeReadback | undefined>;
+/**
+ * The slice of a session these helpers read and write. Structural, so this
+ * module does not import the `Session` type from `acp-agent.ts`.
+ */
+export interface UltracodeSession {
+    query: {
+        applyFlagSettings(settings: Record<string, unknown>): Promise<void>;
+    };
+    configOptions: SessionConfigOption[];
+    /** The intent: what the user (or settings, or the CLI's readback) asked for. */
+    ultracodeRequested: boolean;
+    /** Whether the option is shown: the CLI's `applied.ultracodeAvailable` when
+     *  read, else {@link isUltracodeAvailable}'s heuristic. */
+    ultracodeAvailable: boolean;
+}
+/** Rebuild the option in place from the session's state. */
+export declare function refreshUltracodeOption(session: UltracodeSession, useBooleanOption: boolean): void;
+/** Toggle the intent. Applies first, then records — a rejected control
+ *  request leaves the session and its option untouched, as Fast mode does. */
+export declare function applyUltracodeToggle(session: UltracodeSession, requested: boolean, useBooleanOption: boolean): Promise<void>;
+/**
+ * The one-release migration for clients that still send the retired notch:
+ * `effort = "ultracode"` becomes `{effortLevel:'xhigh', ultracode:true}`.
+ * Returns `false`, sending nothing, when this model's effort select does not
+ * offer `xhigh` — the caller then rejects the value like any other.
+ */
+export declare function applyLegacyUltracodeEffort(session: UltracodeSession, useBooleanOption: boolean): Promise<boolean>;
+/**
+ * Fold a CLI readback into the session. Availability is always taken; the
+ * intent only when `seedIntent` (session start — a model switch keeps the
+ * intent it has). Returns whether the option the client sees changed, i.e.
+ * whether a `config_option_update` is owed.
  */
-export declare function effortOptionValue(effortLevel: string | undefined, ultracode: UltracodeOptionState | undefined): string | undefined;
+export declare function applyUltracodeReadback(session: UltracodeSession, readback: UltracodeReadback, seedIntent: boolean, useBooleanOption: boolean): boolean;
 //# sourceMappingURL=ultracode.d.ts.map

package/dist/ultracode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ultracode.d.ts","sourceRoot":"","sources":["../src/ultracode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAE5E;;uEAEuE;AACvE,eAAO,MAAM,sBAAsB,cAAc,CAAC;AAElD,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,cAAc,CAAC;AAEjD;;;iDAGiD;AACjD,eAAO,MAAM,sBAAsB,EAAE,WAAqB,CAAC;AAE3D;;;kEAGkE;AAClE,MAAM,WAAW,oBAAoB;IACnC,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAC;IACnB,mDAAmD;IACnD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,qBAAqB,EAAE,SAAS,MAAM,EAAE,EACxC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,kBAAkB,CAAC,GAAG,SAAS,GACvD,OAAO,CAGT;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEnE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG;IAChE,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3B,CAQA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,SAAS,EAAE,oBAAoB,GAAG,SAAS,GAC1C,MAAM,GAAG,SAAS,CAGpB"}
+{"version":3,"file":"ultracode.d.ts","sourceRoot":"","sources":["../src/ultracode.ts"],"names":[],"mappings":"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"}

package/dist/ultracode.js

@@ -1,103 +1,236 @@
 /**
- * The "Ultracode" entry of the Effort picker.
+ * Ultracode — an independent, session-scoped boolean option.
  *
- * **Ultracode is not a sixth effort level, and reading it as one produces the
- * wrong control.** Claude Code's VS Code extension models it as a boolean that
- * turns on two things at once — `xhigh` effort *and* standing dynamic-workflow
- * orchestration — and its own tooltip says so: `"Ultracode - xhigh +
- * workflows"`. Its five real levels are `low` `medium` `high` `xhigh` `max`;
- * Ultracode is drawn as one extra notch past the last of them, styled
- * differently, and selecting any ordinary level clears it.
+ * **What it is.** The SDK's `Settings.ultracode` is *"standing
+ * dynamic-workflow orchestration at any effort level"*, session-scoped and
+ * applied through `apply_flag_settings`. It is not an effort level and it does
+ * not imply one: the CLI (`/effort ultracode on|off`, "any effort level, this
+ * session only") and the VS Code extension (a switch in the effort popover)
+ * both model it as a toggle beside effort. An earlier version of this module
+ * followed an older extension tooltip ("xhigh + workflows") and drew it as a
+ * notch in the effort select that forced `xhigh`; that silently raised the
+ * effort of a session started with `ultracode: true`, cleared it on any effort
+ * pick, and lost it on a model switch (PARITY-REPORT §21.2).
  *
- * ACP has no compound control to carry that, so the adapter projects it the way
- * the extension's UI reads rather than the way its state is stored: one more
- * entry in the `effort` select. The compound stays here, in one module, instead
- * of being spread across the three places `acp-agent.ts` applies effort.
+ * **The wire contract** (`applyFlagSettings`, unchanged SDK 0.3.285..0.3.299):
+ * - `ultracode: true|false` turns it on or off and leaves effort alone;
+ * - an `effortLevel` change sent WITHOUT the key turns it off;
+ * - `null` resets it to off.
+ * Hence the two payload rules below: the toggle sends `{ultracode:true}` or
+ * `{ultracode:null}`, and every effort change re-sends `ultracode:true` while
+ * the intent is on — and never `null`.
  *
- * The SDK carries both halves and names the channel: `Settings.ultracode` is
- * *"xhigh effort plus standing dynamic-workflow orchestration. Session-scoped —
- * typically provided via --settings or the apply_flag_settings control
- * request"*. `apply_flag_settings` is already how the effort option is applied,
- * so no new transport is involved.
+ * **Intent is not availability.** The CLI keeps the request and computes "in
+ * effect = requested and available", where available means workflows are
+ * enabled and the model supports `xhigh`. The adapter mirrors that: the
+ * session holds the intent, the option is shown only while available, and a
+ * model switch never drops the intent. The CLI reports both through the
+ * `get_settings` control request (`applied.{ultracode, ultracodeRequested,
+ * ultracodeAvailable}`), which the SDK runtime exposes as `Query.getSettings()`
+ * but `sdk.d.ts` does not declare — {@link readUltracodeState} wraps it.
  *
  * Kept self-contained — no import from `acp-agent.ts` — for the reason
- * `thinking-option.ts` and `rewind-command.ts` state: that file is ~9,900 lines
- * and moves upstream almost daily, so every coupling to it is paid again at
- * each sync.
+ * `thinking-option.ts` and `rewind-command.ts` state: that file is ~10,000
+ * lines and moves upstream almost daily, so every coupling to it is paid again
+ * at each sync.
  */
-/** Value of the synthetic "Ultracode" entry in the effort picker. It is a
- *  reserved sentinel: no `EffortLevel` is spelled this way, so it cannot
- *  collide with a level the SDK reports in `supportedEffortLevels`. */
-export const ULTRACODE_OPTION_VALUE = "ultracode";
-/** Display name of that entry, matching the extension's own label. */
+/** Config option id. */
+export const ULTRACODE_CONFIG_ID = "ultracode";
+/** Display name, matching the CLI's and the extension's label. */
 export const ULTRACODE_OPTION_NAME = "Ultracode";
-/** The effort level Ultracode implies. Not configurable: the extension hardcodes
- *  `xhigh` in `enableUltracode()`, and the SDK's own description of the setting
- *  names the same level. A different level here would silently mean something
- *  else than it does in the reference client. */
+const ULTRACODE_DESCRIPTION = "Run dynamic workflows on every task";
+/** Select-fallback values for clients without boolean config options. The
+ *  same spelling Fast mode uses, so one client-side mapping serves both. */
+export const ULTRACODE_ON = "on";
+export const ULTRACODE_OFF = "off";
+/** The effort level the model must support for Ultracode to be available.
+ *  Availability only: Ultracode never SETS this level. */
 export const ULTRACODE_EFFORT_LEVEL = "xhigh";
+/** The value the old effort-select notch carried. Accepted for one release
+ *  from clients that still send it (see {@link isLegacyUltracodeEffort}). */
+export const LEGACY_ULTRACODE_EFFORT_VALUE = "ultracode";
 /**
- * Whether the Ultracode entry may be offered, under the same two conditions the
- * extension checks in its own `ultracodeAvailable`:
+ * The fallback availability check, used until (or instead of) the CLI's own
+ * `applied.ultracodeAvailable`:
  *
- * 1. workflows are not disabled — Ultracode *is* the workflow half, so offering
- *    it where `disableWorkflows` is set would advertise something that cannot
- *    happen;
- * 2. the current model supports `xhigh` — Ultracode has no meaning on a model
- *    that cannot reach the level it implies.
+ * 1. workflows are not disabled — Ultracode *is* workflow orchestration;
+ * 2. the current model supports `xhigh`.
  *
- * Both are read rather than assumed: an unknown settings shape leaves
- * `disableWorkflows` undefined, which is *not* `true`, so the gate opens — the
- * same direction the extension's `=== !0` comparison takes.
+ * Partial by nature: the CLI also checks managed settings, org policy,
+ * `enableWorkflows` and `CLAUDE_CODE_DISABLE_WORKFLOWS`. An absent
+ * `disableWorkflows` opens the gate, the same direction the extension's
+ * `=== !0` comparison takes.
  */
 export function isUltracodeAvailable(supportedEffortLevels, settings) {
     if (settings?.disableWorkflows === true)
         return false;
     return supportedEffortLevels.includes(ULTRACODE_EFFORT_LEVEL);
 }
-/** Whether a picker value denotes Ultracode rather than a plain effort level. */
-export function isUltracodeValue(value) {
-    return value === ULTRACODE_OPTION_VALUE;
+/** Build the option: a native boolean for clients that opted in, an on/off
+ *  select otherwise (the ACP boolean-config-option RFD makes that a MUST). */
+export function createUltracodeConfigOption(requested, useBooleanOption) {
+    const base = {
+        id: ULTRACODE_CONFIG_ID,
+        name: ULTRACODE_OPTION_NAME,
+        description: ULTRACODE_DESCRIPTION,
+        category: "model_config",
+    };
+    if (useBooleanOption) {
+        return { ...base, type: "boolean", currentValue: requested };
+    }
+    return {
+        ...base,
+        type: "select",
+        currentValue: requested ? ULTRACODE_ON : ULTRACODE_OFF,
+        options: [
+            { value: ULTRACODE_ON, name: "On" },
+            { value: ULTRACODE_OFF, name: "Off" },
+        ],
+    };
+}
+/** The option for a resolved state, or `undefined` while unavailable. */
+export function ultracodeConfigOption(state) {
+    if (!state?.available)
+        return undefined;
+    return createUltracodeConfigOption(state.requested, state.useBooleanOption);
+}
+/**
+ * Put the option where it belongs in an existing list — right after `effort`
+ * (after `model` when the model has no effort option), before `fast` — or
+ * remove it when `next` is undefined. Used when a background readback changes
+ * availability without a full rebuild.
+ */
+export function placeUltracodeOption(options, next) {
+    const rest = options.filter((o) => o.id !== ULTRACODE_CONFIG_ID);
+    if (!next)
+        return rest;
+    let anchor = rest.findIndex((o) => o.id === "effort");
+    if (anchor < 0)
+        anchor = rest.findIndex((o) => o.id === "model");
+    const at = anchor < 0 ? rest.length : anchor + 1;
+    return [...rest.slice(0, at), next, ...rest.slice(at)];
+}
+/** Resolve the requested value from `session/set_config_option`: a native
+ *  boolean, or the on/off select-fallback strings. */
+export function resolveUltracodeRequested(params) {
+    const value = params.value;
+    if (typeof value === "boolean")
+        return value;
+    if (value === ULTRACODE_ON)
+        return true;
+    if (value === ULTRACODE_OFF)
+        return false;
+    throw new Error(`Invalid value for config option ${ULTRACODE_CONFIG_ID}: ${String(value)}`);
+}
+/** The toggle's payload. Off is an explicit `null`: `undefined` is dropped by
+ *  JSON transport, and the SDK only clears a flag on `null`. */
+export function ultracodeTogglePayload(requested) {
+    return { ultracode: requested ? true : null };
 }
 /**
- * The `apply_flag_settings` payload for an effort selection, Ultracode included.
+ * The `apply_flag_settings` payload for an effort change — a user pick, the
+ * model-switch fallback, the initial effort, or a recreate's replay.
  *
- * **The `null` is the load-bearing part.** The SDK shallow-merges flag settings
- * and only clears a key when an explicit `null` arrives — `undefined` is dropped
- * by JSON transport and leaves the previous value standing. So every selection
- * has to say something about `ultracode`, not just the one that turns it on:
- * without the clear, picking `High` after Ultracode would lower the effort and
- * leave workflow orchestration running, which is a state no picker entry names.
- * The same reasoning applies to `effortLevel` — this function absorbed the older
- * `toSdkEffortLevel` helper for exactly that reason: both keys are decided in
- * one place, so neither can be forgotten on a path the other takes.
+ * An `effortLevel` change sent without `ultracode` turns Ultracode off, so the
+ * key rides along whenever the intent is on. It is never sent as `null` here:
+ * an effort change is not a request to turn Ultracode off.
  *
- * @param value the picker value — `"default"`, an `EffortLevel`, or the
- *   Ultracode sentinel. `undefined` means the option is absent for this model.
+ * @param value the effort select's value — `"default"`, an `EffortLevel`, or
+ *   `undefined` when the model has no effort option.
  */
-export function ultracodeFlagSettings(value) {
-    if (isUltracodeValue(value)) {
-        return { effortLevel: ULTRACODE_EFFORT_LEVEL, ultracode: true };
-    }
-    return {
-        effortLevel: value === undefined || value === "default" ? null : value,
-        ultracode: null,
-    };
+export function effortFlagSettings(value, ultracodeRequested) {
+    const effortLevel = value === undefined || value === "default" ? null : value;
+    return ultracodeRequested ? { effortLevel, ultracode: true } : { effortLevel };
+}
+/** Whether an effort value is the retired Ultracode notch. Clients that saved
+ *  it get `{effortLevel:'xhigh', ultracode:true}` for one release. */
+export function isLegacyUltracodeEffort(value) {
+    return value === LEGACY_ULTRACODE_EFFORT_VALUE;
 }
 /**
- * The picker value to display, given the persisted effort level and whether the
- * Ultracode flag is on.
+ * Read `applied.{ultracodeRequested, ultracodeAvailable}` through the SDK's
+ * untyped `Query.getSettings()`.
+ *
+ * Structural, never trusting: an SDK without the method, a rejected request,
+ * or a response without `applied` all resolve to `undefined`, and the caller
+ * keeps the heuristic. Never rejects.
  *
- * The flag wins over the level, and only when it is *available*: a session that
- * carries `ultracode: true` from settings while the current model cannot reach
- * `xhigh` must not show an entry the picker is not rendering. The extension
- * reaches the same state through `adoptAppliedEffort`, which reads
- * `applied.ultracode` first and falls back to inferring it from `xhigh`; we do
- * not infer, because `xhigh` alone is a legitimate selection that is not
- * Ultracode, and guessing would silently turn workflows on in the label.
+ * **Call it in the background, never inline.** Control requests are
+ * serialized and queue ahead of interrupt and close (upstream #1216), and on a
+ * fresh session the CLI does not service them until the first turn.
+ */
+export async function readUltracodeState(query, onError) {
+    const getSettings = query?.getSettings;
+    if (typeof getSettings !== "function")
+        return undefined;
+    let response;
+    try {
+        response = await getSettings.call(query);
+    }
+    catch (error) {
+        onError?.(error);
+        return undefined;
+    }
+    const applied = response?.applied;
+    if (typeof applied !== "object" || applied === null)
+        return undefined;
+    const { ultracodeRequested, ultracodeAvailable } = applied;
+    const readback = {};
+    if (typeof ultracodeRequested === "boolean")
+        readback.requested = ultracodeRequested;
+    if (typeof ultracodeAvailable === "boolean")
+        readback.available = ultracodeAvailable;
+    return readback.requested === undefined && readback.available === undefined
+        ? undefined
+        : readback;
+}
+/** Rebuild the option in place from the session's state. */
+export function refreshUltracodeOption(session, useBooleanOption) {
+    session.configOptions = placeUltracodeOption(session.configOptions, ultracodeConfigOption({
+        available: session.ultracodeAvailable,
+        requested: session.ultracodeRequested,
+        useBooleanOption,
+    }));
+}
+/** Toggle the intent. Applies first, then records — a rejected control
+ *  request leaves the session and its option untouched, as Fast mode does. */
+export async function applyUltracodeToggle(session, requested, useBooleanOption) {
+    await session.query.applyFlagSettings(ultracodeTogglePayload(requested));
+    session.ultracodeRequested = requested;
+    refreshUltracodeOption(session, useBooleanOption);
+}
+/**
+ * The one-release migration for clients that still send the retired notch:
+ * `effort = "ultracode"` becomes `{effortLevel:'xhigh', ultracode:true}`.
+ * Returns `false`, sending nothing, when this model's effort select does not
+ * offer `xhigh` — the caller then rejects the value like any other.
  */
-export function effortOptionValue(effortLevel, ultracode) {
-    if (ultracode?.available && ultracode.enabled)
-        return ULTRACODE_OPTION_VALUE;
-    return effortLevel;
+export async function applyLegacyUltracodeEffort(session, useBooleanOption) {
+    const effort = session.configOptions.find((o) => o.id === "effort");
+    const offersXhigh = effort?.type === "select" &&
+        effort.options.some((o) => "value" in o && o.value === ULTRACODE_EFFORT_LEVEL);
+    if (!offersXhigh)
+        return false;
+    await session.query.applyFlagSettings(effortFlagSettings(ULTRACODE_EFFORT_LEVEL, true));
+    session.ultracodeRequested = true;
+    session.configOptions = session.configOptions.map((o) => o.id === "effort" && o.type === "select" ? { ...o, currentValue: ULTRACODE_EFFORT_LEVEL } : o);
+    refreshUltracodeOption(session, useBooleanOption);
+    return true;
+}
+/**
+ * Fold a CLI readback into the session. Availability is always taken; the
+ * intent only when `seedIntent` (session start — a model switch keeps the
+ * intent it has). Returns whether the option the client sees changed, i.e.
+ * whether a `config_option_update` is owed.
+ */
+export function applyUltracodeReadback(session, readback, seedIntent, useBooleanOption) {
+    const before = JSON.stringify(session.configOptions.find((o) => o.id === ULTRACODE_CONFIG_ID));
+    if (readback.available !== undefined)
+        session.ultracodeAvailable = readback.available;
+    if (seedIntent && readback.requested !== undefined) {
+        session.ultracodeRequested = readback.requested;
+    }
+    refreshUltracodeOption(session, useBooleanOption);
+    const after = JSON.stringify(session.configOptions.find((o) => o.id === ULTRACODE_CONFIG_ID));
+    return before !== after;
 }

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Claude Code in Zed and other ACP clients with the VS Code extension's UX — multi-select questions, refusal consent, live quota windows, background tasks, Ultracode effort and session notices. Fork of claude-agent-acp.",
   "main": "dist/lib.js",
   "types": "dist/lib.d.ts",