@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/config/schema.d.ts

@@ -78,6 +78,27 @@ export declare const DEFAULT_TRANSCRIPT_WINDOW = 1000;
 export declare const MIN_TRANSCRIPT_WINDOW = 50;
 export declare const MAX_TRANSCRIPT_WINDOW = 20000;
 export declare function clampTranscriptWindow(v: unknown, fallback: number): number;
+/**
+ * Bounds for a hand-supplied context window.
+ *
+ * The floor is roughly the smallest window any current model ships with; the
+ * ceiling is well above the largest, and both exist to keep a typo (a missing
+ * or an extra zero) from producing a gauge that is permanently red or
+ * permanently flat.
+ */
+export declare const MIN_CONTEXT_WINDOW = 8000;
+export declare const MAX_CONTEXT_WINDOW = 5000000;
+/**
+ * THE single gate for every `contextWindow` read AND write.
+ *
+ * TRI-STATE, AND `null` MUST PASS STRAIGHT THROUGH (RV-12). `null` means AUTO -
+ * take the model table's number, or the 128k placeholder. Clamping it into
+ * `[8000, ...]` yields 8000, which removes "auto" from the config permanently
+ * and presents to the user as an 8k denominator with a permanently red bar and
+ * no visible source. `maxTokens` above is the existing tri-state precedent and
+ * this deliberately copies its shape rather than inventing a second convention.
+ */
+export declare function clampContextWindow(v: unknown, fallback: number | null): number | null;
 /**
  * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
  *
@@ -599,6 +620,48 @@ export declare const DEFAULT_COMPACTION_CONFIG: CompactionConfig;
  * gives `warnThreshold` a range of `[0.4, 0.45]`.
  */
 export declare function clampCompactionConfig(raw: unknown): CompactionConfig;
+export interface BashConfig {
+    /**
+     * Register `bash_output` / `bash_kill`, honour `background`, splice the prompt
+     * block, render the chip. Default TRUE.
+     *
+     * READ ONCE AT CONSTRUCTION, the `team.enabled` / `todo.enabled` /
+     * `fast.enabled` rule.
+     *
+     * IT GOVERNS *SERVICES*, NEVER *INTERRUPTIBILITY* (I-2 / D-9). `Esc`/`Esc`,
+     * the foreground child registry and `forceStop()` are unconditional, because
+     * "bash always settles" and "Esc twice always works" are promised
+     * unconditionally — a user who turned background services off has not asked
+     * for a less interruptible agent.
+     */
+    background: boolean;
+    /**
+     * Let the classifier decide when the model did not say. Default TRUE.
+     *
+     * RESOLVES TO `false` WITHOUT AN INTERACTIVE VIEW (D-15 / P1-8), and that is
+     * decided at the tool layer rather than here: the value on disk is the user's
+     * preference, and headless has no card, no `/bg` and no user to keep a service
+     * alive, so the rescue would be a surprise instead. An explicit
+     * `background: true` is still honoured there — that one the model asked for.
+     */
+    autoBackground: boolean;
+    /** How long a background launch may block the turn before returning. */
+    startupSettleMs: number;
+    /** How long a service may stay `starting` before it is called `running`. */
+    readyTimeoutMs: number;
+}
+export declare const DEFAULT_BASH_CONFIG: BashConfig;
+/**
+ * THE single gate for every bash-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those record: hardening only the read path leaves a bad value
+ * on disk that reverts to the default on every launch, which presents to the
+ * user as "my setting won't stick".
+ *
+ * CLAMPED, NEVER REJECTED — the discipline every other key in this file follows.
+ * A garbage `startupSettleMs` resolves to 4000 and throws nothing.
+ */
+export declare function clampBashConfig(raw: unknown): BashConfig;
 /**
  * Parse `0.9`, `90%` or `90` into a ratio, or `null` when it is neither.
  *
@@ -650,6 +713,18 @@ export interface PersistedConfig {
      * `null`), which left the user no way to express "let the model decide".
      */
     maxTokens: number | null;
+    /**
+     * The context window to measure occupancy against, or `null` for AUTO
+     * (context-usage-gauge-accuracy §3.6).
+     *
+     * `null` MEANS AUTO - the model table's window, or `buildRuntimeModel`'s 128k
+     * placeholder for a model the table has never seen. It exists because that
+     * placeholder is a FABRICATED denominator: on a custom `baseUrl` or an
+     * unlisted model id the gauge is a percentage of a number nobody supplied, and
+     * before this key there was no way to correct it. Setting it also removes the
+     * `?` marker from the absolute pair (I-6).
+     */
+    contextWindow: number | null;
     theme: ThemeName;
     /** Replace spinners with a static glyph for calmer, low-motion output. */
     reducedMotion: boolean;
@@ -702,6 +777,16 @@ export interface PersistedConfig {
      * written at all, so `false` is byte-identical to a pre-feature session.
      */
     mouseSelect: boolean;
+    /**
+     * Recognise pasted text and collapse a large paste into a placeholder
+     * (tui-paste-handling D-10 / section 7.3).
+     *
+     * A PLAIN BOOLEAN and the ONLY user-facing key this feature adds: the collapse
+     * threshold and every size bound are structural and live in `input/limits.ts`
+     * / `ui/composer-limits.ts`. A tunable threshold is a preference nobody has
+     * asked for; a kill switch is what a bug report needs.
+     */
+    paste: boolean;
     /** Idle ms before a paused viewport returns to the newest line; `0` disables. */
     scrollResumeMs: number;
     /** Start every session in PLAN mode (plan-mode §4.4). */
@@ -726,6 +811,8 @@ export interface PersistedConfig {
     update: UpdateConfig;
     /** Context compaction. The NINTH nested object; scalars only (see CompactionConfig). */
     compaction: CompactionConfig;
+    /** Background services. The TENTH nested object; scalars only (see BashConfig). */
+    bash: BashConfig;
 }
 export declare const DEFAULT_CONFIG: PersistedConfig;
 /**
@@ -781,6 +868,17 @@ export interface CliConfig {
     liveToolOutput: boolean;
     /** The resolved cap, or `undefined` for AUTO (per-model ceiling, ≤ 64000). */
     maxTokens?: number;
+    /**
+     * The user's context-window override, or `null` for AUTO.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `showThinking` / `liveToolOutput` / `diffRender` each record above: the
+     * runtime reads `config.*`, where `config` is a `CliConfig`, so a key added to
+     * the persisted shape alone would round-trip through `config set`, appear in
+     * `config list` - and never reach `ContextMeter`. `ARAGON_CONTEXT_WINDOW`
+     * would parse and be discarded, with nothing failing.
+     */
+    contextWindow: number | null;
     theme: ThemeName;
     reducedMotion: boolean;
     /**
@@ -866,6 +964,17 @@ export interface CliConfig {
      * `config list`, and never reach a single one of them.
      */
     mouseSelect: boolean;
+    /**
+     * Whether this session recognises pastes at all.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason
+     * `mouseSelect` above records: `runInteractive` reads `config.paste` -- where
+     * `config` is a `CliConfig` -- to decide the filter's `paste` feature, the
+     * `?2004h` write and the `PasteBridge`. A key added to the persisted shape
+     * alone would round-trip through `config set`, appear in `config list`, and
+     * reach none of them.
+     */
+    paste: boolean;
     /** Idle ms before a paused viewport returns to the newest line; `0` disables. */
     scrollResumeMs: number;
     /**
@@ -959,6 +1068,26 @@ export interface CliConfig {
      * reach either of them.
      */
     compaction: CompactionConfig;
+    /**
+     * Resolved background-service settings (background-service-supervision §5.4).
+     *
+     * `background` here decides whether `bash`'s schema carries a `background`
+     * property, whether `bash_output` / `bash_kill` are REGISTERED and whether
+     * `<background_services>` is spliced — all three at construction, and none of
+     * them undoable, the `team.enabled` / `todo.enabled` / `fast.enabled` rule.
+     * The other three keys are read LIVE.
+     *
+     * IT DOES NOT GATE THE INTERRUPT LADDER (I-2 / D-9). `ProcSupervisor` is
+     * constructed unconditionally, because `Esc`/`Esc` and the foreground registry
+     * are what make G2 and G3 true and those are promised whatever this says.
+     *
+     * IT MUST EXIST HERE AND NOT ONLY IN `PersistedConfig`, for the reason every
+     * section above records: the controller and `bash` read `config.bash`, where
+     * `config` is a `CliConfig`, so a key added to the persisted shape alone would
+     * round-trip through `config set`, appear in `config list` — and never reach
+     * either of them.
+     */
+    bash: BashConfig;
     /**
      * Lifetime submit count driving the composer hint fade (`HINT_FADE_AFTER`).
      *

package/dist/config/schema.js

@@ -115,6 +115,39 @@ export function clampTranscriptWindow(v, fallback) {
     const n = coercePositiveInt(v, fallback);
     return Math.min(MAX_TRANSCRIPT_WINDOW, Math.max(MIN_TRANSCRIPT_WINDOW, n));
 }
+// ---------------------------------------------------------------------------
+// Context window override (context-usage-gauge-accuracy §3.6 / W5)
+// ---------------------------------------------------------------------------
+/**
+ * Bounds for a hand-supplied context window.
+ *
+ * The floor is roughly the smallest window any current model ships with; the
+ * ceiling is well above the largest, and both exist to keep a typo (a missing
+ * or an extra zero) from producing a gauge that is permanently red or
+ * permanently flat.
+ */
+export const MIN_CONTEXT_WINDOW = 8_000;
+export const MAX_CONTEXT_WINDOW = 5_000_000;
+/**
+ * THE single gate for every `contextWindow` read AND write.
+ *
+ * TRI-STATE, AND `null` MUST PASS STRAIGHT THROUGH (RV-12). `null` means AUTO -
+ * take the model table's number, or the 128k placeholder. Clamping it into
+ * `[8000, ...]` yields 8000, which removes "auto" from the config permanently
+ * and presents to the user as an 8k denominator with a permanently red bar and
+ * no visible source. `maxTokens` above is the existing tri-state precedent and
+ * this deliberately copies its shape rather than inventing a second convention.
+ */
+export function clampContextWindow(v, fallback) {
+    if (v === null)
+        return null;
+    if (v === undefined || v === '')
+        return fallback;
+    const n = typeof v === 'number' ? v : Number.parseInt(String(v), 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return fallback;
+    return Math.min(MAX_CONTEXT_WINDOW, Math.max(MIN_CONTEXT_WINDOW, Math.floor(n)));
+}
 /**
  * Entries kept in `ViewState` at all (tui-render-performance L1 / R5).
  *
@@ -777,6 +810,33 @@ export function clampCompactionConfig(raw) {
         archive: bool(src.archive, DEFAULT_COMPACTION_CONFIG.archive),
     };
 }
+export const DEFAULT_BASH_CONFIG = {
+    background: true,
+    autoBackground: true,
+    startupSettleMs: 4000,
+    readyTimeoutMs: 60_000,
+};
+const STARTUP_SETTLE_RANGE = { min: 500, max: 30_000 };
+const READY_TIMEOUT_RANGE = { min: 5_000, max: 600_000 };
+/**
+ * THE single gate for every bash-config read AND write, mirroring
+ * `clampSkillsConfig` / `clampLogConfig` / `clampTeamConfig` / `clampTodoConfig`
+ * for the reason those record: hardening only the read path leaves a bad value
+ * on disk that reverts to the default on every launch, which presents to the
+ * user as "my setting won't stick".
+ *
+ * CLAMPED, NEVER REJECTED — the discipline every other key in this file follows.
+ * A garbage `startupSettleMs` resolves to 4000 and throws nothing.
+ */
+export function clampBashConfig(raw) {
+    const src = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        background: bool(src.background, DEFAULT_BASH_CONFIG.background),
+        autoBackground: bool(src.autoBackground, DEFAULT_BASH_CONFIG.autoBackground),
+        startupSettleMs: clampInt(src.startupSettleMs, DEFAULT_BASH_CONFIG.startupSettleMs, STARTUP_SETTLE_RANGE),
+        readyTimeoutMs: clampInt(src.readyTimeoutMs, DEFAULT_BASH_CONFIG.readyTimeoutMs, READY_TIMEOUT_RANGE),
+    };
+}
 /**
  * Parse `0.9`, `90%` or `90` into a ratio, or `null` when it is neither.
  *
@@ -814,6 +874,9 @@ export const DEFAULT_CONFIG = {
     // The engine owns this number; spelling it here again is how the CLI and the
     // provider adapters end up disagreeing about what "the default" is.
     maxTokens: DEFAULT_MAX_OUTPUT_TOKENS,
+    // AUTO. The model table is right for every listed model, and a default number
+    // here would be the same fabricated denominator this key exists to correct.
+    contextWindow: null,
     theme: 'auto',
     reducedMotion: false,
     fullscreen: true,
@@ -833,6 +896,7 @@ export const DEFAULT_CONFIG = {
     hints: true,
     mouse: true,
     mouseSelect: DEFAULT_MOUSE_SELECT,
+    paste: true,
     scrollResumeMs: DEFAULT_SCROLL_RESUME_MS,
     planModeDefault: false,
     planModeMaxAskRounds: DEFAULT_PLAN_MAX_ASK_ROUNDS,
@@ -865,6 +929,11 @@ export const DEFAULT_CONFIG = {
     // arrive OFF for every existing user, which is the one direction this
     // particular default must never fail in.
     compaction: DEFAULT_COMPACTION_CONFIG,
+    // And one section later again, for the fifth time. `bash.background` is `true`
+    // by default, so a `config.json` predating this feature resolving it to
+    // `undefined` would arrive with background services OFF for every existing
+    // user — the same direction the compaction line above must never fail in.
+    bash: DEFAULT_BASH_CONFIG,
 };
 /**
  * Runtime state that used to be stored in `config.json` by mistake

package/dist/config/store.js

@@ -14,7 +14,7 @@ import { dirname } from 'node:path';
 import process from 'node:process';
 import { getConfigPath, getSessionsDir } from './app-paths.js';
 import { registerSecretsFrom } from '../logging/secret-registry.js';
-import { CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
+import { clampBashConfig, CONFIG_VERSION, DEFAULT_CONFIG, clampCompactionConfig, clampFastConfig, clampLogConfig, clampMaxTokens, clampRetryConfig, clampSkillsConfig, clampTeamConfig, clampTodoConfig, clampContextWindow, clampUpdateConfig, isAutoToken, stripLegacyStateKeys, } from './schema.js';
 /**
  * Normalize `maxTokens` for both directions of the config file.
  *
@@ -31,6 +31,22 @@ function normalizeMaxTokens(v) {
         return null;
     return clampMaxTokens(v) ?? null;
 }
+/**
+ * Normalize `contextWindow` for both directions of the config file.
+ *
+ * THE SAME TRI-STATE DISCIPLINE AS `maxTokens` ABOVE, and for the same reason:
+ * hardening only the read path leaves a bad value on disk that reverts on every
+ * launch and presents as "my setting won't stick". `null` is AUTO and survives
+ * untouched; `auto` / `0` / an empty string mean AUTO too; a number is clamped;
+ * anything else on a hand-edited file becomes AUTO rather than a silent default.
+ */
+function normalizeContextWindow(v) {
+    if (v === undefined)
+        return DEFAULT_CONFIG.contextWindow;
+    if (v === null || isAutoToken(v))
+        return null;
+    return clampContextWindow(v, null);
+}
 // Re-exported so the many existing importers of `store.js` keep working; the
 // definitions live in `app-paths.ts` because they are pure path arithmetic.
 export { getConfigPath, getSessionsDir };
@@ -114,6 +130,11 @@ export function loadPersistedConfig() {
         maxTokens: Object.prototype.hasOwnProperty.call(partial, 'maxTokens')
             ? normalizeMaxTokens(partial.maxTokens)
             : DEFAULT_CONFIG.maxTokens,
+        // Own-property aware for the reason its neighbour records: `null` is AUTO
+        // and a spread cannot tell it from an absent key.
+        contextWindow: Object.prototype.hasOwnProperty.call(partial, 'contextWindow')
+            ? normalizeContextWindow(partial.contextWindow)
+            : DEFAULT_CONFIG.contextWindow,
         apiKeys: { ...DEFAULT_CONFIG.apiKeys, ...(partial.apiKeys ?? {}) },
         // `skills` is the second nested object in this file and needs the same
         // treatment `apiKeys` gets — see the note on updatePersistedConfig below.
@@ -148,6 +169,20 @@ export function loadPersistedConfig() {
             ...DEFAULT_CONFIG.compaction,
             ...(partial.compaction ?? {}),
         }),
+        // `bash` is the tenth. Same one-level rule, same merge — and the READ half
+        // supplies a whole section to every user whose `config.json` predates
+        // background services, which is all of them. Without it
+        // `config.bash.background` reads `undefined`, which is FALSY, so a feature
+        // that is `true` by default would arrive off for every existing user.
+        //
+        // A SIBLING OF `compaction`, NOT A KEY INSIDE ITS ARGUMENT. Nesting it one
+        // level too deep type-checks — `...DEFAULT_CONFIG` above already supplies a
+        // `bash`, so nothing is missing from the return type — and hands
+        // `clampCompactionConfig` a key it drops on the floor. The section then
+        // reaches callers straight off the shallow `...partial` spread: unclamped,
+        // and NOT merged over the defaults, which is verbatim the failure the
+        // paragraph above says this line prevents.
+        bash: clampBashConfig({ ...DEFAULT_CONFIG.bash, ...(partial.bash ?? {}) }),
     };
 }
 /**
@@ -184,6 +219,11 @@ export function updatePersistedConfig(patch) {
         maxTokens: Object.prototype.hasOwnProperty.call(patch, 'maxTokens')
             ? normalizeMaxTokens(patch.maxTokens)
             : current.maxTokens,
+        // The write half of the same gate: without it `config set contextWindow
+        // 99999999` puts a number on disk that the read path silently rewrites.
+        contextWindow: Object.prototype.hasOwnProperty.call(patch, 'contextWindow')
+            ? normalizeContextWindow(patch.contextWindow)
+            : current.contextWindow,
         apiKeys: { ...current.apiKeys, ...(patch.apiKeys ?? {}) },
         skills: clampSkillsConfig({ ...current.skills, ...(patch.skills ?? {}) }),
         // Without this line, changing the log level from the settings screen would
@@ -224,6 +264,12 @@ export function updatePersistedConfig(patch) {
         // OFF finds it back on tomorrow — a feature that spends money on their behalf
         // re-enabling itself because they nudged a threshold.
         compaction: clampCompactionConfig({ ...current.compaction, ...(patch.compaction ?? {}) }),
+        // The tenth section, and the fifth time this file records the same trap.
+        // A patch carrying only `{ bash: { autoBackground: false } }` — turning the
+        // CLASSIFIER off — would, without this line, be spread shallowly over the
+        // top level and write `background` absent, silently unregistering
+        // `bash_output` / `bash_kill` from the next launch onward.
+        bash: clampBashConfig({ ...current.bash, ...(patch.bash ?? {}) }),
     };
     writeConfigFile(merged);
     return merged;

package/dist/exec/events.d.ts

@@ -71,6 +71,43 @@ export interface ExecSystemInitEvent {
     permissionMode: ExecPermissionMode;
     tools: string[];
     resumed: boolean;
+    /**
+     * Capabilities of THIS build that a caller has to know about before using
+     * them. Optional so older consumers are unaffected, and additive so
+     * `EXEC_SCHEMA_VERSION` does not move (see the file header).
+     *
+     * `'interrupt'` means the stdin `{"type":"interrupt"}` frame really does run
+     * the full settle -> persist -> `result` sequence ON EVERY PLATFORM. Builds
+     * before that fix routed it through a self-directed SIGINT, which on Windows
+     * terminates the process outright with exit code 1 - no persistence, no
+     * `result`. A wrapper cannot tell the two apart by observation, and guessing
+     * wrong costs the user their conversation, so this build states it.
+     */
+    capabilities?: string[];
+    /**
+     * Absolute path of the session file THIS run reads and writes; `null` under
+     * `--no-save-session` (web-use-durable-control-and-tier-accountability W2).
+     *
+     * Optional and additive, so `EXEC_SCHEMA_VERSION` does not move (file header).
+     * Stamped by `buildInitEvent`, never set by a caller - the same discipline
+     * `capabilities` follows.
+     *
+     * ## Why a wrapper cannot work this out for itself
+     *
+     * Deriving it host-side means re-implementing `getSessionsDir()`
+     * (`envPaths('aragon-agent')` plus its environment override) in a second
+     * codebase that has no way to notice when this one changes. The failure mode
+     * of a drifted copy is a path that does not exist, which a wrapper reads as
+     * "that conversation is gone" - identical, on screen, to the session really
+     * being gone. The run that is writing the file is the only party that can say
+     * where it is without guessing.
+     *
+     * It is the id THIS RUN writes back under, not the string the caller typed:
+     * `--resume` accepts `<id|path>`, and `resumedSessionId()` decides what the
+     * file is actually called. A wrapper asking "can I reattach later" needs the
+     * latter.
+     */
+    sessionFile?: string | null;
 }
 export interface ExecUserEvent {
     type: 'user';
@@ -84,6 +121,22 @@ export interface ExecUserEvent {
      */
     source: 'caller' | 'todo_continue';
 }
+/** One caller input and its complete automatic follow-through chain. */
+export interface ExecTurnStateEvent {
+    type: 'turn_state';
+    sessionId: string;
+    requestSeq: number;
+    phase: 'started' | 'completed' | 'failed' | 'cancelled';
+}
+/** Semantic source progress; never includes model or tool content. */
+export interface ExecProgressEvent {
+    type: 'execution_progress';
+    sessionId: string;
+    requestSeq: number;
+    progressSeq: number;
+    phase: 'model' | 'thinking' | 'tool_arguments' | 'tool' | 'compaction' | 'retry';
+    retryDelayMs?: number;
+}
 export interface ExecTextDeltaEvent {
     type: 'text_delta';
     sessionId: string;
@@ -157,6 +210,57 @@ export interface ExecFastReviewEvent {
     model: string;
     text: string;
 }
+/**
+ * What the fast tier is ACTUALLY doing, as opposed to what it was configured to
+ * do (web-use-tier-cooperation-and-control-closure W2).
+ *
+ * ONE ADDITIVE EVENT TYPE, AND `EXEC_SCHEMA_VERSION` DOES NOT MOVE — the same
+ * rule `ExecCompactionEvent` states. A consumer that ignores event types it does
+ * not know is unaffected.
+ *
+ * THE PROBLEM IT SOLVES. `fast_review` only fires when a review produced TEXT,
+ * so every other outcome — a review that failed, a tier that switched itself off
+ * after three failures, a budget that ran out, a delegation that did or did not
+ * happen — was invisible to a wrapper. The single most likely and least
+ * self-diagnosable failure ("it runs but not one review card ever arrives") had
+ * no signal at all on this stream.
+ *
+ * IT IS A STATE EVENT, NOT A LOG LINE. It fires on `tier_changed` and on every
+ * `review_end`, which in a session with reviews is a handful per hundred turns.
+ */
+export interface ExecFastTierEvent {
+    type: 'fast_tier';
+    sessionId: string;
+    /** Taken from the runner's own turn counter — `tier_changed` carries none. */
+    turn: number;
+    /** The tier resolved AND the live switch is on. */
+    live: boolean;
+    /**
+     * The CLI switched the fast REVIEWS off by itself after three consecutive
+     * non-transient failures.
+     *
+     * ORTHOGONAL TO `live` AND NOT DERIVABLE FROM IT: the self-disable leaves
+     * `live` at `true`. A consumer reporting "the reviews stopped" MUST read this
+     * field; `live === false && reviews > 0` is a predicate that can never be true.
+     */
+    selfDisabled: boolean;
+    model: string;
+    sameAsMain: boolean;
+    reviews: number;
+    reviewBudget: number;
+    budgetReached: boolean;
+    /** Fast-tier children dispatched — the only evidence delegation is working. */
+    delegated: number;
+    inFlight: boolean;
+    /** Present only on the `review_end` branch. */
+    review?: {
+        index: number;
+        kind: 'ok' | 'advice' | 'empty' | 'failed' | 'dropped';
+        detail?: string;
+        durationMs: number;
+        injected: boolean;
+    };
+}
 /**
  * Context compaction (context-auto-compaction §4.6).
  *
@@ -251,7 +355,7 @@ export interface ExecResultEvent {
     todos: ExecTodoCounts | null;
     error: ExecErrorInfo | null;
 }
-export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecCompactionEvent | ExecRetryEvent | ExecErrorEvent | ExecResultEvent;
+export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTurnStateEvent | ExecProgressEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecFastTierEvent | ExecCompactionEvent | ExecRetryEvent | ExecErrorEvent | ExecResultEvent;
 /** Everything `system/init` needs that the runner cannot derive for itself. */
 export interface ExecInitParams {
     sessionId: string;
@@ -266,7 +370,40 @@ export interface ExecInitParams {
     permissionMode: ExecPermissionMode;
     tools: string[];
     resumed: boolean;
+    /**
+     * Absolute path of the session file this run reads and writes; `null` under
+     * `--no-save-session`. See `ExecSystemInitEvent.sessionFile`.
+     */
+    sessionFile?: string | null;
 }
+/**
+ * What this build announces in `system/init`.
+ *
+ * Stamped by `buildInitEvent`, never by a caller - the same discipline as
+ * `schemaVersion`. A caller that could set it could claim a capability the
+ * binary does not have, which is precisely the mistake the field exists to
+ * prevent.
+ */
+/**
+ * APPEND ONLY, NEVER REORDER. Consumers use `includes()`, but the next one may
+ * not; inserting ahead of `'interrupt'` costs nothing and makes a diff look
+ * bigger than it is.
+ *
+ *  · `'interrupt'`         — `{"type":"interrupt"}` on stdin settles the turn
+ *                            without killing the process.
+ *  · `'fast-policy'`       — this build understands `--fast-delegate` and
+ *                            `--fast-review`. FOR AFTER-THE-FACT DISPLAY ONLY:
+ *                            argv is fixed before `system/init` arrives, so it
+ *                            cannot gate whether the flags are passed.
+ *  · `'fast-tier-events'`  — this build emits `fast_tier`. Its ABSENCE is what
+ *                            lets a wrapper say "this CLI does not report" and
+ *                            not "the fast tier did nothing" — two very
+ *                            different sentences to a user.
+ *  · `'session-file'`      — `system/init` carries `sessionFile`, so a wrapper
+ *                            can check on disk whether a stopped conversation
+ *                            is still resumable instead of guessing the path.
+ */
+export declare const EXEC_CAPABILITIES: readonly string[];
 export declare function buildInitEvent(params: ExecInitParams): ExecSystemInitEvent;
 /** Everything `result` needs. `schemaVersion` is stamped here, never by a caller. */
 export type ExecResultParams = Omit<ExecResultEvent, 'type' | 'schemaVersion'>;

package/dist/exec/events.js

@@ -19,6 +19,41 @@
  * additive change and every wrapper would pin an exact number forever.
  */
 export const EXEC_SCHEMA_VERSION = 1;
+/**
+ * What this build announces in `system/init`.
+ *
+ * Stamped by `buildInitEvent`, never by a caller - the same discipline as
+ * `schemaVersion`. A caller that could set it could claim a capability the
+ * binary does not have, which is precisely the mistake the field exists to
+ * prevent.
+ */
+/**
+ * APPEND ONLY, NEVER REORDER. Consumers use `includes()`, but the next one may
+ * not; inserting ahead of `'interrupt'` costs nothing and makes a diff look
+ * bigger than it is.
+ *
+ *  · `'interrupt'`         — `{"type":"interrupt"}` on stdin settles the turn
+ *                            without killing the process.
+ *  · `'fast-policy'`       — this build understands `--fast-delegate` and
+ *                            `--fast-review`. FOR AFTER-THE-FACT DISPLAY ONLY:
+ *                            argv is fixed before `system/init` arrives, so it
+ *                            cannot gate whether the flags are passed.
+ *  · `'fast-tier-events'`  — this build emits `fast_tier`. Its ABSENCE is what
+ *                            lets a wrapper say "this CLI does not report" and
+ *                            not "the fast tier did nothing" — two very
+ *                            different sentences to a user.
+ *  · `'session-file'`      — `system/init` carries `sessionFile`, so a wrapper
+ *                            can check on disk whether a stopped conversation
+ *                            is still resumable instead of guessing the path.
+ */
+export const EXEC_CAPABILITIES = [
+    'interrupt',
+    'fast-policy',
+    'fast-tier-events',
+    'session-file',
+    'turn-lifecycle',
+    'execution-progress',
+];
 export function buildInitEvent(params) {
     return {
         type: 'system',
@@ -32,6 +67,13 @@ export function buildInitEvent(params) {
         permissionMode: params.permissionMode,
         tools: params.tools,
         resumed: params.resumed,
+        capabilities: [...EXEC_CAPABILITIES],
+        // `?? null` rather than a conditional spread: the field's contract is
+        // three-valued for a CONSUMER (`undefined` = an old build that cannot say,
+        // `null` = this run saves nothing, a string = here it is), and omitting it
+        // when a caller passed nothing would make this build indistinguishable from
+        // one that predates the field.
+        sessionFile: params.sessionFile ?? null,
     };
 }
 export function buildResultEvent(params) {