@cruxy/cli 0.13.0 → 0.16.0

package/dist/hooks/trust.d.ts

@@ -0,0 +1,46 @@
+import type { HookDefinition, HookTrust } from "./types.js";
+/**
+ * The project-hook trust model (C.19). Trust is recorded in the GLOBAL dir
+ * (`~/.cruxy/trust.json`) — in the user's home, NEVER inside a repo — so cloning
+ * a repo carries zero trust and an attacker cannot ship a pre-trusted marker.
+ *
+ * Trust is bound to a {@link fingerprintHooks fingerprint} of the exact project
+ * hook commands seen at trust time. It is re-checked on every run: if the
+ * project's hooks change (a command / event / blocking edit), the fingerprint no
+ * longer matches and trust is stale → the user is re-prompted. This is what
+ * defeats trust-then-swap.
+ */
+/** ~/.cruxy/trust.json */
+export declare function trustPath(): string;
+/**
+ * A stable content fingerprint of a repo's PROJECT hook definitions. Canonical
+ * by construction so a benign reformat of `hooks.json` (reindent, reordered
+ * keys, extra whitespace inside a command) does NOT change it, while any real
+ * change to a command, event, or blocking flag DOES:
+ * - only the meaning-bearing fields are hashed (name, event, command, blocking);
+ * - the command string is whitespace-normalized (trim + collapse runs);
+ * - specs are sorted by name and serialized with a fixed key order.
+ */
+export declare function fingerprintHooks(hooks: readonly HookDefinition[]): string;
+/** The persisted trust seam — a file-backed store in production, injectable for
+ * tests. `get`/`record` are synchronous (the record is tiny). */
+export interface TrustStore {
+    /** The recorded decision for a repo root, or undefined if never trusted. */
+    get(root: string): HookTrust | undefined;
+    /** Persist a trust decision (overwrites any prior one for the same root). */
+    record(trust: HookTrust): void;
+}
+/**
+ * Is this repo's current project-hook set trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — a changed hook set is
+ * treated as untrusted (stale), forcing a fresh decision.
+ */
+export declare function isTrusted(store: TrustStore, root: string, currentFingerprint: string): boolean;
+/**
+ * The real store, persisting to `~/.cruxy/trust.json` as `{ [root]: HookTrust }`.
+ * Reads are lazy + cached; a corrupt file is treated as "no trust recorded"
+ * (fail-closed — a broken trust file must never grant trust).
+ */
+export declare function fileTrustStore(file?: string): TrustStore;
+/** An in-memory store for tests (and any ephemeral run). */
+export declare function memoryTrustStore(seed?: HookTrust[]): TrustStore;

package/dist/hooks/trust.js

@@ -0,0 +1,106 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { TRUST_FILE_NAME } from "../constants.js";
+/**
+ * The project-hook trust model (C.19). Trust is recorded in the GLOBAL dir
+ * (`~/.cruxy/trust.json`) — in the user's home, NEVER inside a repo — so cloning
+ * a repo carries zero trust and an attacker cannot ship a pre-trusted marker.
+ *
+ * Trust is bound to a {@link fingerprintHooks fingerprint} of the exact project
+ * hook commands seen at trust time. It is re-checked on every run: if the
+ * project's hooks change (a command / event / blocking edit), the fingerprint no
+ * longer matches and trust is stale → the user is re-prompted. This is what
+ * defeats trust-then-swap.
+ */
+/** ~/.cruxy/trust.json */
+export function trustPath() {
+    return path.join(globalDir(), TRUST_FILE_NAME);
+}
+/**
+ * A stable content fingerprint of a repo's PROJECT hook definitions. Canonical
+ * by construction so a benign reformat of `hooks.json` (reindent, reordered
+ * keys, extra whitespace inside a command) does NOT change it, while any real
+ * change to a command, event, or blocking flag DOES:
+ * - only the meaning-bearing fields are hashed (name, event, command, blocking);
+ * - the command string is whitespace-normalized (trim + collapse runs);
+ * - specs are sorted by name and serialized with a fixed key order.
+ */
+export function fingerprintHooks(hooks) {
+    const canonical = hooks
+        .map((h) => ({
+        name: h.name,
+        event: h.event,
+        command: h.command.trim().replace(/\s+/g, " "),
+        blocking: h.blocking,
+    }))
+        .sort((a, b) => a.name.localeCompare(b.name))
+        // Fixed key order — JSON of an object literal preserves insertion order.
+        .map((h) => [h.name, h.event, h.command, h.blocking]);
+    return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+/**
+ * Is this repo's current project-hook set trusted? True only when a decision
+ * exists AND its fingerprint matches the current one — a changed hook set is
+ * treated as untrusted (stale), forcing a fresh decision.
+ */
+export function isTrusted(store, root, currentFingerprint) {
+    const record = store.get(path.resolve(root));
+    return record !== undefined && record.fingerprint === currentFingerprint;
+}
+// ── file-backed store ─────────────────────────────────────────────────────────
+/**
+ * The real store, persisting to `~/.cruxy/trust.json` as `{ [root]: HookTrust }`.
+ * Reads are lazy + cached; a corrupt file is treated as "no trust recorded"
+ * (fail-closed — a broken trust file must never grant trust).
+ */
+export function fileTrustStore(file = trustPath()) {
+    let cache = null;
+    const load = () => {
+        if (cache)
+            return cache;
+        try {
+            const raw = JSON.parse(readFileSync(file, "utf8"));
+            cache =
+                raw && typeof raw === "object"
+                    ? raw
+                    : {};
+        }
+        catch {
+            // Missing or corrupt → no trust (fail-closed).
+            cache = {};
+        }
+        return cache;
+    };
+    return {
+        get(root) {
+            return load()[path.resolve(root)];
+        },
+        record(trust) {
+            const store = load();
+            store[path.resolve(trust.root)] = {
+                ...trust,
+                root: path.resolve(trust.root),
+            };
+            mkdirSync(path.dirname(file), { recursive: true });
+            // 0600: trust records name local paths; keep them owner-only.
+            writeFileSync(file, JSON.stringify(store, null, 2), { mode: 0o600 });
+            if (existsSync(file))
+                cache = store;
+        },
+    };
+}
+/** An in-memory store for tests (and any ephemeral run). */
+export function memoryTrustStore(seed = []) {
+    const store = new Map();
+    for (const t of seed)
+        store.set(path.resolve(t.root), t);
+    return {
+        get: (root) => store.get(path.resolve(root)),
+        record: (trust) => void store.set(path.resolve(trust.root), {
+            ...trust,
+            root: path.resolve(trust.root),
+        }),
+    };
+}

package/dist/hooks/types.d.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+/**
+ * Types for hooks + custom slash commands (C.19). Everything here is **data**:
+ * hook and command definitions are validated (fail-loud, malformed excluded) and
+ * NEVER eval'd — a hook's `command` string only ever reaches execution through
+ * the shared U.3-gated + C.16-sandboxed shell path (see `runner.ts`), exactly
+ * like an agent-run command.
+ */
+/**
+ * The core hook lifecycle events. Deliberately a small, closed set for this
+ * build; the enum is the extension point for future events (out of scope).
+ * - `before-run` / `after-run` — around a whole user turn (the agent loop).
+ * - `before-tool` / `after-tool` — around each tool call.
+ * - `on-file-change` — after a file-mutating tool (write/edit/patch) succeeds.
+ */
+export declare const HOOK_EVENTS: readonly ["before-run", "after-run", "before-tool", "after-tool", "on-file-change"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+/** `before-*` events default to blocking (fail-closed pre-checks); everything
+ * that fires *after* an action defaults to advisory. Overridable per hook. */
+export declare function defaultBlocking(event: HookEvent): boolean;
+/** Where a hook / command was discovered. `project` is the supply-chain-risky
+ * source (another author); `user` is your own `~/.cruxy`. */
+export type HookSource = "project" | "user";
+/** Precedence: a project definition overrides a user one of the same name. */
+export declare const HOOK_SOURCE_PRECEDENCE: readonly HookSource[];
+/** Strict schema for one hook definition in a `hooks.json`. Unknown keys are a
+ * loud error (`.strict()`); `blocking` is optional (resolved from the event). */
+export declare const HookSpecSchema: z.ZodObject<{
+    name: z.ZodString;
+    event: z.ZodEnum<["before-run", "after-run", "before-tool", "after-tool", "on-file-change"]>;
+    command: z.ZodString;
+    blocking: z.ZodOptional<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    name: string;
+    command: string;
+    event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+    blocking?: boolean | undefined;
+}, {
+    name: string;
+    command: string;
+    event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+    blocking?: boolean | undefined;
+}>;
+export type HookSpec = z.infer<typeof HookSpecSchema>;
+/** The whole `hooks.json` file shape. */
+export declare const HooksFileSchema: z.ZodObject<{
+    hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        event: z.ZodEnum<["before-run", "after-run", "before-tool", "after-tool", "on-file-change"]>;
+        command: z.ZodString;
+        blocking: z.ZodOptional<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }, {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    hooks: {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }[];
+}, {
+    hooks?: {
+        name: string;
+        command: string;
+        event: "before-run" | "after-run" | "before-tool" | "after-tool" | "on-file-change";
+        blocking?: boolean | undefined;
+    }[] | undefined;
+}>;
+/** A validated hook, tagged with its source and with `blocking` resolved. */
+export interface HookDefinition {
+    name: string;
+    event: HookEvent;
+    command: string;
+    /** Resolved (event default applied) — the value the runner acts on. */
+    blocking: boolean;
+    source: HookSource;
+}
+/**
+ * A custom slash command. `prompt` (the safe default) expands a text template
+ * fed to the agent; `shell` binds a command that runs through the SAME gate +
+ * sandbox as everything else. Never arbitrary code by default.
+ */
+export type SlashKind = "prompt" | "shell";
+/** Strict frontmatter for a `commands/<name>.md`. The command NAME comes from
+ * the filename; the markdown BODY is the prompt template (kind `prompt`). */
+export declare const SlashFrontmatterSchema: z.ZodObject<{
+    kind: z.ZodDefault<z.ZodEnum<["prompt", "shell"]>>;
+    description: z.ZodString;
+    /** Required (and only meaningful) when `kind: "shell"`. */
+    command: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    kind: "shell" | "prompt";
+    description: string;
+    command?: string | undefined;
+}, {
+    description: string;
+    command?: string | undefined;
+    kind?: "shell" | "prompt" | undefined;
+}>;
+export type SlashFrontmatter = z.infer<typeof SlashFrontmatterSchema>;
+/** A validated custom slash command, tagged with source. */
+export interface SlashCommandSpec {
+    name: string;
+    kind: SlashKind;
+    description: string;
+    /** Prompt template (kind `prompt`); `{{args}}` is substituted at expansion. */
+    template?: string;
+    /** Shell command (kind `shell`) — gated + sandboxed when run. */
+    command?: string;
+    source: HookSource;
+}
+/** A malformed hook / command, excluded from the catalog and surfaced loudly
+ * (never eval'd, never silently dropped). */
+export interface HookConfigError {
+    source: HookSource;
+    /** Absolute path of the offending file. */
+    file: string;
+    /** The would-be name (filename / spec name), for display. */
+    name: string;
+    message: string;
+}
+/** The resolved hook catalog: valid definitions (deduped by precedence) + the
+ * malformed ones that were excluded. */
+export interface HookCatalog {
+    hooks: HookDefinition[];
+    commands: SlashCommandSpec[];
+    errors: HookConfigError[];
+}
+/** One repo's recorded trust decision (persisted in `~/.cruxy/trust.json`). The
+ * `fingerprint` binds trust to the exact hook commands seen at trust time. */
+export interface HookTrust {
+    /** Absolute project root. */
+    root: string;
+    /** sha256 of the canonicalized project hook specs (see `trust.ts`). */
+    fingerprint: string;
+    /** ISO timestamp the decision was recorded. */
+    at: string;
+}

package/dist/hooks/types.js

@@ -0,0 +1,61 @@
+import { z } from "zod";
+/**
+ * Types for hooks + custom slash commands (C.19). Everything here is **data**:
+ * hook and command definitions are validated (fail-loud, malformed excluded) and
+ * NEVER eval'd — a hook's `command` string only ever reaches execution through
+ * the shared U.3-gated + C.16-sandboxed shell path (see `runner.ts`), exactly
+ * like an agent-run command.
+ */
+// ── lifecycle events ──────────────────────────────────────────────────────────
+/**
+ * The core hook lifecycle events. Deliberately a small, closed set for this
+ * build; the enum is the extension point for future events (out of scope).
+ * - `before-run` / `after-run` — around a whole user turn (the agent loop).
+ * - `before-tool` / `after-tool` — around each tool call.
+ * - `on-file-change` — after a file-mutating tool (write/edit/patch) succeeds.
+ */
+export const HOOK_EVENTS = [
+    "before-run",
+    "after-run",
+    "before-tool",
+    "after-tool",
+    "on-file-change",
+];
+/** `before-*` events default to blocking (fail-closed pre-checks); everything
+ * that fires *after* an action defaults to advisory. Overridable per hook. */
+export function defaultBlocking(event) {
+    return event === "before-run" || event === "before-tool";
+}
+/** Precedence: a project definition overrides a user one of the same name. */
+export const HOOK_SOURCE_PRECEDENCE = [
+    "project",
+    "user",
+];
+// ── hook specs ────────────────────────────────────────────────────────────────
+/** Strict schema for one hook definition in a `hooks.json`. Unknown keys are a
+ * loud error (`.strict()`); `blocking` is optional (resolved from the event). */
+export const HookSpecSchema = z
+    .object({
+    name: z
+        .string()
+        .min(1)
+        .regex(/^[a-z0-9][a-z0-9-]*$/, "hook name must be kebab-case (lowercase letters, digits, hyphens)"),
+    event: z.enum(HOOK_EVENTS),
+    command: z.string().min(1, "hook command must be a non-empty string"),
+    blocking: z.boolean().optional(),
+})
+    .strict();
+/** The whole `hooks.json` file shape. */
+export const HooksFileSchema = z
+    .object({ hooks: z.array(HookSpecSchema).default([]) })
+    .strict();
+/** Strict frontmatter for a `commands/<name>.md`. The command NAME comes from
+ * the filename; the markdown BODY is the prompt template (kind `prompt`). */
+export const SlashFrontmatterSchema = z
+    .object({
+    kind: z.enum(["prompt", "shell"]).default("prompt"),
+    description: z.string().min(1),
+    /** Required (and only meaningful) when `kind: "shell"`. */
+    command: z.string().min(1).optional(),
+})
+    .strict();

package/dist/onboarding/steps.js

@@ -17,7 +17,7 @@ const c = (io) => themeForColor(io.color);
  */
 export async function acquireKeyStep(io, deps, provider) {
     const col = c(io);
-    io.write(`\nYou'll need a Cruxy API key. Create one at ${col.accent(CREATE_KEY_URL)}\n`);
+    io.write(`\nYou'll need a cruxy API key. Create one at ${col.accent(CREATE_KEY_URL)}\n`);
     for (let attempt = 1; attempt <= MAX_KEY_ATTEMPTS; attempt++) {
         io.write(col.strong("Paste your API key: "));
         const key = (await io.readSecret()).trim();
@@ -93,7 +93,10 @@ export async function firstWinStep(io, deps) {
     io.write(`\nRun a quick demo now — let cruxy summarize this repo? ${col.muted("[Y/n]")} `);
     const key = (await io.readKey()).toLowerCase();
     io.write("\n");
-    if (key === "n")
+    // Decline on an explicit `n`, and treat Ctrl-C / EOF / escape (readKey → "")
+    // as a clean cancel rather than "proceed": a cancel must never launch a task.
+    // Enter (readKey → "\n") keeps the `[Y/n]` default and runs the demo.
+    if (key === "n" || key === "")
         return { status: "skipped" };
     await deps.runTask(FIRST_WIN_PROMPT);
     return { status: "ok" };

package/dist/render/capabilities.d.ts

@@ -1,4 +1,11 @@
 import type { RenderCapabilities, RenderStream } from "./types.js";
+/**
+ * Reduced-motion (U.11) — the ecosystem `NO_MOTION` signal, the explicit cruxy
+ * knob `CRUXY_REDUCED_MOTION`, and `CRUXY_NO_SPINNER` kept as an alias flowing
+ * through this one axis. A screen reader implies it (no live region to animate).
+ * The single source of the spinner gate.
+ */
+export declare function detectReducedMotion(env?: NodeJS.ProcessEnv): boolean;
 /**
  * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
  * given its inputs (stream + env are injectable), so every row of the
@@ -6,7 +13,8 @@ import type { RenderCapabilities, RenderStream } from "./types.js";
  *
  * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
  * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
- * Cursor control and color are independent axes — a NO_COLOR terminal still
- * supports in-place status updates; a dumb terminal supports neither.
+ * The axes are independent (U.1/U.11): a NO_COLOR terminal still supports
+ * in-place status updates; a dumb terminal supports neither; reduced motion and
+ * screen-reader mode compose orthogonally with color and unicode.
  */
 export declare function detectCapabilities(stream?: RenderStream, env?: NodeJS.ProcessEnv): RenderCapabilities;

package/dist/render/capabilities.js

@@ -1,5 +1,21 @@
 import { shouldUseColor } from "../errors/index.js";
-import { detectUnicode } from "../theme/index.js";
+import { detectScreenReader, detectUnicode } from "../theme/index.js";
+/** Set-and-non-empty (the NO_COLOR convention): any non-empty value counts. */
+function isSet(value) {
+    return value !== undefined && value !== "";
+}
+/**
+ * Reduced-motion (U.11) — the ecosystem `NO_MOTION` signal, the explicit cruxy
+ * knob `CRUXY_REDUCED_MOTION`, and `CRUXY_NO_SPINNER` kept as an alias flowing
+ * through this one axis. A screen reader implies it (no live region to animate).
+ * The single source of the spinner gate.
+ */
+export function detectReducedMotion(env = process.env) {
+    return (isSet(env.NO_MOTION) ||
+        isSet(env.CRUXY_REDUCED_MOTION) ||
+        isSet(env.CRUXY_NO_SPINNER) ||
+        detectScreenReader(env));
+}
 /**
  * Probe the environment once and reduce it to {@link RenderCapabilities}. Pure
  * given its inputs (stream + env are injectable), so every row of the
@@ -7,20 +23,24 @@ import { detectUnicode } from "../theme/index.js";
  *
  * Color reuses {@link shouldUseColor} (NO_COLOR / FORCE_COLOR / TTY) with one
  * refinement: `TERM=dumb` terminals get no color even though they are TTYs.
- * Cursor control and color are independent axes — a NO_COLOR terminal still
- * supports in-place status updates; a dumb terminal supports neither.
+ * The axes are independent (U.1/U.11): a NO_COLOR terminal still supports
+ * in-place status updates; a dumb terminal supports neither; reduced motion and
+ * screen-reader mode compose orthogonally with color and unicode.
  */
 export function detectCapabilities(stream = process.stdout, env = process.env) {
     const tty = Boolean(stream.isTTY);
     const dumb = env.TERM === "dumb";
     const cursor = tty && !dumb;
+    const reducedMotion = detectReducedMotion(env);
     return {
         tty,
         color: shouldUseColor(stream, env) && !dumb,
         cursor,
-        // Same set-and-non-empty convention as NO_COLOR: any value disables.
-        spinner: cursor &&
-            !(env.CRUXY_NO_SPINNER !== undefined && env.CRUXY_NO_SPINNER !== ""),
+        // Motion is the single gate now: CRUXY_NO_SPINNER flows through it (alias),
+        // as do NO_MOTION / CRUXY_REDUCED_MOTION and an implied screen reader.
+        spinner: cursor && !reducedMotion,
+        reducedMotion,
+        screenReader: detectScreenReader(env),
         // Unicode glyph safety (U.1) — independent of color. dumb / CRUXY_ASCII →
         // ASCII glyphs; everything else (incl. pipes) keeps unicode.
         unicode: detectUnicode(env),

package/dist/render/index.d.ts

@@ -1,15 +1,19 @@
 import type { RenderStream, StreamRenderer } from "./types.js";
 export type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, StreamRenderer, TokenUsage, ToolLifecycleEvent, } from "./types.js";
-export { detectCapabilities } from "./capabilities.js";
+export { detectCapabilities, detectReducedMotion } from "./capabilities.js";
 export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, type HighlightCarry, type LineHighlighter, type StreamHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";
+export { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 export { TtyRenderer } from "./tty-renderer.js";
 /**
- * Build the renderer for the detected environment: the managed-live-region
- * {@link TtyRenderer} when cursor control is safe, otherwise the append-only
- * {@link PlainRenderer} (pipes, CI, `TERM=dumb`). Everything downstream talks
- * to the {@link StreamRenderer} interface and never re-probes the terminal.
+ * Build the renderer for the detected environment (U.11 adds the first branch):
+ * - `screenReader` → the linear, worded {@link ScreenReaderRenderer}, regardless
+ *   of cursor support (a screen-reader TTY must not get the live region);
+ * - else cursor-safe → the managed-live-region {@link TtyRenderer} (static, no
+ *   timer, when `reducedMotion`);
+ * - else → the append-only {@link PlainRenderer} (pipes, CI, `TERM=dumb`).
+ * Everything downstream talks to {@link StreamRenderer} and never re-probes.
  */
 export declare function createRenderer(out?: RenderStream, err?: RenderStream, env?: NodeJS.ProcessEnv): StreamRenderer;

package/dist/render/index.js

@@ -1,20 +1,27 @@
 import { detectCapabilities } from "./capabilities.js";
 import { PlainRenderer } from "./plain-renderer.js";
+import { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 import { TtyRenderer } from "./tty-renderer.js";
-export { detectCapabilities } from "./capabilities.js";
+export { detectCapabilities, detectReducedMotion } from "./capabilities.js";
 export { composeStatusLine, describePhase, ELAPSED_AFTER_MS, formatElapsed, formatTokens, phaseIdentity, } from "./state.js";
 export { renderActionPreview, PREVIEW_MAX_LINES } from "./diff.js";
 export { createStreamHighlighter, defaultLineHighlighter, } from "./highlight.js";
 export { PlainRenderer } from "./plain-renderer.js";
+export { ScreenReaderRenderer } from "./screen-reader-renderer.js";
 export { TtyRenderer } from "./tty-renderer.js";
 /**
- * Build the renderer for the detected environment: the managed-live-region
- * {@link TtyRenderer} when cursor control is safe, otherwise the append-only
- * {@link PlainRenderer} (pipes, CI, `TERM=dumb`). Everything downstream talks
- * to the {@link StreamRenderer} interface and never re-probes the terminal.
+ * Build the renderer for the detected environment (U.11 adds the first branch):
+ * - `screenReader` → the linear, worded {@link ScreenReaderRenderer}, regardless
+ *   of cursor support (a screen-reader TTY must not get the live region);
+ * - else cursor-safe → the managed-live-region {@link TtyRenderer} (static, no
+ *   timer, when `reducedMotion`);
+ * - else → the append-only {@link PlainRenderer} (pipes, CI, `TERM=dumb`).
+ * Everything downstream talks to {@link StreamRenderer} and never re-probes.
  */
 export function createRenderer(out = process.stdout, err = process.stderr, env = process.env) {
     const caps = detectCapabilities(out, env);
+    if (caps.screenReader)
+        return new ScreenReaderRenderer(caps, out, err);
     return caps.cursor
         ? new TtyRenderer(caps, out)
         : new PlainRenderer(caps, out, err);

package/dist/render/plain-renderer.d.ts

@@ -1,6 +1,6 @@
 import type { ActionPreview } from "../tools/types.js";
 import { type Theme } from "../theme/index.js";
-import type { RenderCapabilities, RenderStream, StreamRenderer, ToolLifecycleEvent } from "./types.js";
+import type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, StreamRenderer, ToolLifecycleEvent } from "./types.js";
 /**
  * The append-only renderer for pipes, CI, and cursor-less terminals. Emits no
  * cursor-control sequences ever, and no color unless the capabilities say so
@@ -30,8 +30,8 @@ export declare class PlainRenderer implements StreamRenderer {
     note(text: string): void;
     preview(preview: ActionPreview): void;
     status(): void;
-    setPhase(): void;
-    progress(): void;
+    setPhase(phase: RenderPhase | null): void;
+    progress(state: ProgressState | null): void;
     toolLifecycle(event: ToolLifecycleEvent): void;
     promptResolved(): void;
     endTurn(): void;

package/dist/render/plain-renderer.js

@@ -59,12 +59,20 @@ export class PlainRenderer {
     status() {
         // Append-only medium: transient state is dropped by design.
     }
-    setPhase() {
+    // setPhase / progress declare their StreamRenderer params because the
+    // ScreenReaderRenderer subclass overrides them to announce (the override must
+    // be signature-compatible). In the plain medium they are no-ops: there is no
+    // live region to update, so the guard simply returns.
+    setPhase(phase) {
         // Phases are live-region state; there is no live region here (U.4).
+        if (phase !== null)
+            return;
     }
-    progress() {
+    progress(state) {
         // The committed plan trail (C.31, via PromptIO) is the record in this
         // medium; a live [i/n] prefix would just duplicate it line by line.
+        if (state !== null)
+            return;
     }
     toolLifecycle(event) {
         if (event.event === "start") {

package/dist/render/screen-reader-renderer.d.ts

@@ -0,0 +1,45 @@
+import { PlainRenderer } from "./plain-renderer.js";
+import type { ProgressState, RenderCapabilities, RenderPhase, RenderStream, ToolLifecycleEvent } from "./types.js";
+/**
+ * The screen-reader renderer (U.11): {@link PlainRenderer}'s linear,
+ * append-only, zero-cursor-control output — plus two things a screen reader
+ * needs that the plain path drops.
+ *
+ * 1. **Worded status.** Its theme resolves the {@link SCREEN_READER_GLYPHS}
+ *    table (via `caps.screenReader`), so every inherited code path that writes
+ *    `theme.glyph.success` prints `done` instead of `✓`, `failed` for `✗`, etc.
+ *    Nothing here special-cases it — the glyph table does the work.
+ *
+ * 2. **Announced state.** A screen reader cannot see an in-place live region, so
+ *    each state change is emitted as its own committed line (never a redraw):
+ *    a phase becomes `working: read_file src/x.ts`, a tool run brackets as
+ *    `working: …` → `done …`, and plan progress announces `step 2 of 5: title`.
+ *    Announcements are deduped by phase *identity* so token-count updates within
+ *    the same activity don't repeat a line.
+ *
+ * Everything else — text streaming, `endSegment`, `note`, `preview` — is
+ * inherited unchanged. This is the whole of screen-reader mode: no parallel
+ * path, no behavior change to the plain or TTY renderers.
+ */
+export declare class ScreenReaderRenderer extends PlainRenderer {
+    /** Identity of the last phase announced, so we speak each activity once. */
+    private lastPhaseId;
+    /** Text of the last progress line announced, to avoid repeats. */
+    private lastProgress;
+    constructor(caps: RenderCapabilities, out: RenderStream, err: RenderStream);
+    /**
+     * Announce a phase transition as a committed line. `null`, `awaiting-approval`
+     * (the prompt block is its own announcement), and `calling-tool` (announced by
+     * {@link toolLifecycle}) are silent; repeats of the same activity are deduped.
+     */
+    setPhase(phase: RenderPhase | null): void;
+    /** Announce plan-step progress as `step i of n: title`, deduped. */
+    progress(state: ProgressState | null): void;
+    /**
+     * Bracket a tool call with two committed lines — `working: label` on start,
+     * `done/failed label` on end — so a screen-reader user hears both that a call
+     * began (crucial for long ones) and how it resolved. The end note + honest
+     * duration is the inherited plain behavior; only the start line is added.
+     */
+    toolLifecycle(event: ToolLifecycleEvent): void;
+}