@zhijiewang/openharness 2.22.1 → 2.24.0

package/dist/harness/hooks.js

@@ -12,6 +12,7 @@
 import { spawn, spawnSync } from "node:child_process";
 import { debug } from "../utils/debug.js";
 import { readOhConfig } from "./config.js";
+import { isTrusted, trustSystemActive } from "./trust.js";
 let cachedHooks;
 export function getHooks() {
     if (cachedHooks !== undefined)
@@ -403,6 +404,22 @@ async function runPromptHook(promptText, ctx, timeoutMs = 10_000) {
 /** Execute a single hook definition. Returns true if allowed. */
 async function executeHookDef(def, event, ctx) {
     const timeout = def.timeout ?? 10_000;
+    // Workspace-trust gate (audit U-A4). Shell-executing hook types
+    // (`command`, `http`) require the cwd to be on the trust list — a fresh
+    // clone of a hostile repo can't auto-execute on first launch. Allowed by
+    // default for `prompt` hooks (LLM-only, no shell).
+    //
+    // Soft rollout: the gate is only enforced once the user has interacted
+    // with the trust system (i.e., `~/.oh/trusted-dirs.json` exists). Until
+    // then, existing behavior is preserved. The first session in a hooked
+    // workspace fires a startup prompt that creates the file — from that
+    // point on every other dir requires explicit trust.
+    if ((def.command || def.http) && trustSystemActive() && !isTrusted(process.cwd())) {
+        // Allow as if the hook didn't exist. The REPL surfaces a one-time
+        // prompt at session start when hooks are configured but the dir is
+        // untrusted; the user can also grant trust via `/trust`.
+        return true;
+    }
     if (def.command) {
         const env = buildEnv(event, ctx);
         // JSON-mode (Claude Code convention): send `{event, ...ctx}` on stdin,
@@ -439,10 +456,17 @@ export function emitHook(event, ctx = {}) {
         debug("hooks", "fire", { event, count: defs.length, tool: ctx.toolName });
     const env = buildEnv(event, ctx);
     if (event === "preToolUse") {
-        // preToolUse command hooks must be synchronous — they gate tool execution
+        // preToolUse command hooks must be synchronous — they gate tool execution.
+        // Workspace-trust gate (audit U-A4): once the trust system is active
+        // (file exists), shell-executing hooks in untrusted dirs act as absent.
+        // Soft rollout: when no trust file exists at all, treat as legacy mode
+        // and run all hooks normally.
+        const enforceTrust = trustSystemActive() && !isTrusted(process.cwd());
         for (const def of defs) {
             if (!matchesHook(def, ctx))
                 continue;
+            if ((def.command || def.http) && enforceTrust)
+                continue;
             if (def.command) {
                 const input = def.jsonIO ? JSON.stringify({ event, ...ctx }) : undefined;
                 const result = spawnSync(def.command, {

package/dist/harness/status-line-script.d.ts

@@ -0,0 +1,52 @@
+/**
+ * JSON-envelope status line script runner (audit U-B1).
+ *
+ * Mirrors Claude Code's `statusLine` config. The user configures a shell
+ * command in `.oh/config.yaml`:
+ *
+ *   statusLine:
+ *     command: "~/scripts/oh-status.sh"
+ *     refreshMs: 2000
+ *
+ * On each REPL refresh, OH:
+ *   1. Builds a JSON envelope of session state (model, tokens, cost, etc.)
+ *   2. If the cache window hasn't expired AND the envelope hasn't changed,
+ *      returns the cached stdout — no spawn cost on every keypress.
+ *   3. Otherwise spawns the command through the shell, pipes the envelope
+ *      on stdin, captures stdout (timeout: 2s), trims to the first line.
+ *
+ * Caller is responsible for the workspace-trust gate (`isTrusted(cwd)`);
+ * this module just runs the command. Failures (non-zero exit, timeout,
+ * spawn error) return null so the caller can fall back to template /
+ * default rendering.
+ *
+ * Synchronous spawn used so the renderer doesn't need an async path —
+ * keeps the keypress loop hot. Trade-off: a slow script blocks the render
+ * up to `timeoutMs`; the cache makes this rare.
+ */
+export interface StatusLineEnvelope {
+    model: string;
+    tokens: {
+        input: number;
+        output: number;
+    };
+    cost: number;
+    contextPercent: number;
+    sessionId: string;
+    cwd: string;
+    gitBranch?: string;
+}
+export interface StatusLineConfig {
+    command: string;
+    refreshMs?: number;
+    timeoutMs?: number;
+}
+/**
+ * Run the status line script with the given envelope. Returns the trimmed
+ * first line of stdout, or null on failure / empty output. Caches results
+ * for `refreshMs`.
+ */
+export declare function runStatusLineScript(env: StatusLineEnvelope, cfg: StatusLineConfig): string | null;
+/** @internal Test-only reset. */
+export declare function _resetStatusLineCacheForTest(): void;
+//# sourceMappingURL=status-line-script.d.ts.map

package/dist/harness/status-line-script.js

@@ -0,0 +1,88 @@
+/**
+ * JSON-envelope status line script runner (audit U-B1).
+ *
+ * Mirrors Claude Code's `statusLine` config. The user configures a shell
+ * command in `.oh/config.yaml`:
+ *
+ *   statusLine:
+ *     command: "~/scripts/oh-status.sh"
+ *     refreshMs: 2000
+ *
+ * On each REPL refresh, OH:
+ *   1. Builds a JSON envelope of session state (model, tokens, cost, etc.)
+ *   2. If the cache window hasn't expired AND the envelope hasn't changed,
+ *      returns the cached stdout — no spawn cost on every keypress.
+ *   3. Otherwise spawns the command through the shell, pipes the envelope
+ *      on stdin, captures stdout (timeout: 2s), trims to the first line.
+ *
+ * Caller is responsible for the workspace-trust gate (`isTrusted(cwd)`);
+ * this module just runs the command. Failures (non-zero exit, timeout,
+ * spawn error) return null so the caller can fall back to template /
+ * default rendering.
+ *
+ * Synchronous spawn used so the renderer doesn't need an async path —
+ * keeps the keypress loop hot. Trade-off: a slow script blocks the render
+ * up to `timeoutMs`; the cache makes this rare.
+ */
+import { spawnSync } from "node:child_process";
+let cache = null;
+const DEFAULT_REFRESH_MS = 1000;
+const MIN_REFRESH_MS = 100;
+const DEFAULT_TIMEOUT_MS = 2000;
+/**
+ * Stable cache key from the envelope. Excludes timestamps / sessionId-y
+ * things that don't actually change the script's output (the script reads
+ * the envelope it gets — if the input is the same, the output should be
+ * too).
+ */
+function envelopeKey(env) {
+    return JSON.stringify({
+        model: env.model,
+        tokens: env.tokens,
+        cost: env.cost,
+        contextPercent: env.contextPercent,
+        cwd: env.cwd,
+        gitBranch: env.gitBranch,
+    });
+}
+/**
+ * Run the status line script with the given envelope. Returns the trimmed
+ * first line of stdout, or null on failure / empty output. Caches results
+ * for `refreshMs`.
+ */
+export function runStatusLineScript(env, cfg) {
+    const refresh = Math.max(MIN_REFRESH_MS, cfg.refreshMs ?? DEFAULT_REFRESH_MS);
+    const timeout = cfg.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const key = envelopeKey(env);
+    const now = Date.now();
+    if (cache && cache.envelopeKey === key && now - cache.timestamp < refresh) {
+        return cache.output;
+    }
+    try {
+        const result = spawnSync(cfg.command, {
+            shell: true,
+            timeout,
+            stdio: ["pipe", "pipe", "pipe"],
+            input: JSON.stringify(env),
+            encoding: "utf8",
+        });
+        if (result.error || result.status !== 0) {
+            return null;
+        }
+        const out = (result.stdout ?? "").toString().trim();
+        if (!out)
+            return null;
+        // Truncate to first line — multi-line output would corrupt the status row.
+        const firstLine = out.split(/\r?\n/)[0];
+        cache = { envelopeKey: key, output: firstLine, timestamp: now };
+        return firstLine;
+    }
+    catch {
+        return null;
+    }
+}
+/** @internal Test-only reset. */
+export function _resetStatusLineCacheForTest() {
+    cache = null;
+}
+//# sourceMappingURL=status-line-script.js.map

package/dist/harness/trust.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Workspace-trust store (audit U-A4).
+ *
+ * OH lets users configure shell hooks (`.oh/config.yaml` `hooks:`) and
+ * arbitrary status-line scripts (Tier U-B1) that auto-execute as part of
+ * the session loop. That's a footgun for fresh-cloned projects — a hostile
+ * `.oh/config.yaml` could run shell on first launch.
+ *
+ * This module gates user-defined-shell execution on a one-time
+ * "trust this directory" prompt, persisted in `~/.oh/trusted-dirs.json`.
+ * The first time a hook or status-line script tries to run in an untrusted
+ * directory, the REPL pops a question; trusted dirs skip the prompt forever.
+ *
+ * Mirrors Claude Code's workspace-trust model. Per the prior audit's
+ * already-built check, OH had zero `trustedDirectories` matches anywhere —
+ * this is genuinely new.
+ */
+/** Check whether `dir` is trusted. Pure read — never prompts. */
+export declare function isTrusted(dir: string): boolean;
+/**
+ * Whether the user has ever interacted with the trust system. Used by the
+ * hook gate as a soft-rollout switch: before the file exists, we treat all
+ * dirs as trusted (legacy behavior — existing users not affected). Once
+ * the user grants trust to even one workspace, the gate switches on for
+ * every other dir. Mirrors the design pattern of "explicit opt-in once,
+ * enforce always after."
+ *
+ * Bypasses the in-memory cache so it picks up writes from a parallel
+ * process (e.g., `oh trust` run from another shell while a session is up).
+ */
+export declare function trustSystemActive(): boolean;
+/**
+ * Mark `dir` as trusted. Idempotent — a second call is a no-op. Persists
+ * immediately so a process crash before the next prompt doesn't lose the
+ * grant.
+ */
+export declare function trust(dir: string): void;
+/** List currently-trusted dirs. For diagnostics / `oh status`. */
+export declare function listTrusted(): readonly string[];
+/** @internal Test-only reset. */
+export declare function _resetTrustForTest(): void;
+//# sourceMappingURL=trust.d.ts.map

package/dist/harness/trust.js

@@ -0,0 +1,99 @@
+/**
+ * Workspace-trust store (audit U-A4).
+ *
+ * OH lets users configure shell hooks (`.oh/config.yaml` `hooks:`) and
+ * arbitrary status-line scripts (Tier U-B1) that auto-execute as part of
+ * the session loop. That's a footgun for fresh-cloned projects — a hostile
+ * `.oh/config.yaml` could run shell on first launch.
+ *
+ * This module gates user-defined-shell execution on a one-time
+ * "trust this directory" prompt, persisted in `~/.oh/trusted-dirs.json`.
+ * The first time a hook or status-line script tries to run in an untrusted
+ * directory, the REPL pops a question; trusted dirs skip the prompt forever.
+ *
+ * Mirrors Claude Code's workspace-trust model. Per the prior audit's
+ * already-built check, OH had zero `trustedDirectories` matches anywhere —
+ * this is genuinely new.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+const TRUST_FILE = join(homedir(), ".oh", "trusted-dirs.json");
+let cached;
+function loadStore() {
+    if (cached)
+        return cached;
+    if (!existsSync(TRUST_FILE)) {
+        cached = { trusted: [] };
+        return cached;
+    }
+    try {
+        const raw = readFileSync(TRUST_FILE, "utf8");
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed.trusted)) {
+            cached = { trusted: parsed.trusted.filter((p) => typeof p === "string") };
+            return cached;
+        }
+    }
+    catch {
+        /* malformed file — treat as empty so the user can re-grant */
+    }
+    cached = { trusted: [] };
+    return cached;
+}
+function saveStore(store) {
+    cached = store;
+    mkdirSync(dirname(TRUST_FILE), { recursive: true });
+    writeFileSync(TRUST_FILE, JSON.stringify({ trusted: store.trusted }, null, 2));
+}
+/**
+ * Normalize a directory for comparison. Resolves to an absolute path and
+ * lowercases on Windows (which is case-insensitive for paths). Other
+ * platforms keep case so distinct dirs that differ only in case are treated
+ * as distinct.
+ */
+function normalize(dir) {
+    const abs = resolve(dir);
+    return process.platform === "win32" ? abs.toLowerCase() : abs;
+}
+/** Check whether `dir` is trusted. Pure read — never prompts. */
+export function isTrusted(dir) {
+    const store = loadStore();
+    const target = normalize(dir);
+    return store.trusted.some((t) => normalize(t) === target);
+}
+/**
+ * Whether the user has ever interacted with the trust system. Used by the
+ * hook gate as a soft-rollout switch: before the file exists, we treat all
+ * dirs as trusted (legacy behavior — existing users not affected). Once
+ * the user grants trust to even one workspace, the gate switches on for
+ * every other dir. Mirrors the design pattern of "explicit opt-in once,
+ * enforce always after."
+ *
+ * Bypasses the in-memory cache so it picks up writes from a parallel
+ * process (e.g., `oh trust` run from another shell while a session is up).
+ */
+export function trustSystemActive() {
+    return existsSync(TRUST_FILE);
+}
+/**
+ * Mark `dir` as trusted. Idempotent — a second call is a no-op. Persists
+ * immediately so a process crash before the next prompt doesn't lose the
+ * grant.
+ */
+export function trust(dir) {
+    const store = loadStore();
+    const target = normalize(dir);
+    if (store.trusted.some((t) => normalize(t) === target))
+        return;
+    saveStore({ trusted: [...store.trusted, dir] });
+}
+/** List currently-trusted dirs. For diagnostics / `oh status`. */
+export function listTrusted() {
+    return loadStore().trusted;
+}
+/** @internal Test-only reset. */
+export function _resetTrustForTest() {
+    cached = undefined;
+}
+//# sourceMappingURL=trust.js.map

package/dist/query/tools.js

@@ -1,6 +1,7 @@
 /**
  * Tool execution — permission checking, batching, output capping.
  */
+import { previewArgs, recordApproval } from "../harness/approvals.js";
 import { createCheckpoint, getAffectedFiles } from "../harness/checkpoints.js";
 import { emitHook, emitHookWithOutcome } from "../harness/hooks.js";
 import { findToolByName } from "../Tool.js";
@@ -91,6 +92,7 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 permissionMode,
                 permissionAction: "ask",
             });
+            const argsPreview = previewArgs(JSON.stringify(toolCall.arguments));
             const denyAndEmit = (source, reason, output) => {
                 emitHook("permissionDenied", {
                     toolName: tool.name,
@@ -99,10 +101,31 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                     denySource: source,
                     denyReason: reason,
                 });
+                // Audit U-B5: persist denial to ~/.oh/approvals.log so /permissions log
+                // can replay the session's approval history. The cast is safe — the
+                // four call sites below pass exact string literals matching ApprovalSource.
+                recordApproval({
+                    tool: tool.name,
+                    decision: "deny",
+                    source: source,
+                    argsPreview,
+                    reason,
+                    cwd: process.cwd(),
+                });
                 return { output, isError: true };
             };
+            const recordAllow = (source) => {
+                recordApproval({
+                    tool: tool.name,
+                    decision: "allow",
+                    source,
+                    argsPreview,
+                    cwd: process.cwd(),
+                });
+            };
             if (hookOutcome.permissionDecision === "allow") {
                 // Hook granted permission — proceed to execution.
+                recordAllow("hook");
             }
             else if (hookOutcome.permissionDecision === "deny" || !hookOutcome.allowed) {
                 const reason = hookOutcome.reason ? `: ${hookOutcome.reason}` : "";
@@ -118,6 +141,7 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 const promptDecision = await callPermissionPromptTool(permissionPromptTool, tools, context, tool.name, parsed.data);
                 if (promptDecision.behavior === "allow") {
                     // Permission tool granted — proceed.
+                    recordAllow("permission-prompt-tool");
                 }
                 else if (promptDecision.behavior === "deny") {
                     return denyAndEmit("permission-prompt-tool", promptDecision.message ?? "denied", `Permission denied by ${permissionPromptTool}${promptDecision.message ? `: ${promptDecision.message}` : ""}`);
@@ -131,6 +155,7 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                     if (!allowed) {
                         return denyAndEmit("user", "user declined", "Permission denied by user.");
                     }
+                    recordAllow("user");
                 }
                 else {
                     return denyAndEmit("headless", "permission-prompt-tool unavailable and no interactive prompt", `Permission denied: ${permissionPromptTool} did not produce a usable decision and no interactive prompt is available.`);
@@ -144,6 +169,7 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 if (!allowed) {
                     return denyAndEmit("user", "user declined", "Permission denied by user.");
                 }
+                recordAllow("user");
             }
             else {
                 // Headless mode with no hook decision and no interactive prompt:
@@ -161,6 +187,16 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 denySource: "policy",
                 denyReason: perm.reason,
             });
+            // Audit U-B5: a `tool-rule-deny` reason came from an explicit
+            // `toolPermissions` rule the user wrote; everything else is policy.
+            recordApproval({
+                tool: tool.name,
+                decision: "deny",
+                source: perm.reason === "tool-rule-deny" ? "rule" : "policy",
+                argsPreview: previewArgs(JSON.stringify(toolCall.arguments)),
+                reason: perm.reason,
+                cwd: process.cwd(),
+            });
             return { output: `Permission denied: ${perm.reason}`, isError: true };
         }
     }

package/dist/renderer/cells.d.ts

@@ -7,6 +7,7 @@ export type Style = {
     bold: boolean;
     dim: boolean;
     underline: boolean;
+    hyperlink?: string | null;
 };
 export type Cell = {
     char: string;
@@ -32,6 +33,11 @@ export declare class CellGrid {
      * Returns the number of rows consumed.
      */
     writeWrapped(row: number, col: number, text: string, style: Style, wrapWidth: number, maxRow?: number): number;
+    /**
+     * Write text on a single row (no wrapping), tagging http(s):// and file:// runs
+     * with the OSC 8 hyperlink attribute (cyan + underline). Stops at maxCol or grid width.
+     */
+    writeTextWithLinks(row: number, col: number, text: string, baseStyle: Style, maxCol?: number): void;
     clone(): CellGrid;
 }
 //# sourceMappingURL=cells.d.ts.map

package/dist/renderer/cells.js

@@ -1,7 +1,7 @@
 /**
  * Cell grid — 2D array of styled characters for terminal rendering.
  */
-export const EMPTY_STYLE = { fg: null, bg: null, bold: false, dim: false, underline: false };
+export const EMPTY_STYLE = { fg: null, bg: null, bold: false, dim: false, underline: false, hyperlink: null };
 export const EMPTY_CELL = { char: " ", style: { ...EMPTY_STYLE } };
 export function cellsEqual(a, b) {
     return (a.char === b.char &&
@@ -9,7 +9,8 @@ export function cellsEqual(a, b) {
         a.style.bg === b.style.bg &&
         a.style.bold === b.style.bold &&
         a.style.dim === b.style.dim &&
-        a.style.underline === b.style.underline);
+        a.style.underline === b.style.underline &&
+        (a.style.hyperlink ?? null) === (b.style.hyperlink ?? null));
 }
 export class CellGrid {
     width;
@@ -37,6 +38,7 @@ export class CellGrid {
                 cell.style.bold = false;
                 cell.style.dim = false;
                 cell.style.underline = false;
+                cell.style.hyperlink = null;
             }
         }
     }
@@ -51,6 +53,7 @@ export class CellGrid {
         cell.style.bold = s.bold;
         cell.style.dim = s.dim;
         cell.style.underline = s.underline;
+        cell.style.hyperlink = s.hyperlink ?? null;
     }
     /**
      * Write a string into the grid at (row, col). Handles \n for line breaks.
@@ -122,6 +125,49 @@ export class CellGrid {
         }
         return r - row;
     }
+    /**
+     * Write text on a single row (no wrapping), tagging http(s):// and file:// runs
+     * with the OSC 8 hyperlink attribute (cyan + underline). Stops at maxCol or grid width.
+     */
+    writeTextWithLinks(row, col, text, baseStyle, maxCol) {
+        const limit = Math.min(maxCol ?? this.width, this.width);
+        if (row < 0 || row >= this.height)
+            return;
+        const linkRegex = /(https?:\/\/[^\s)\]'"<>]+|file:\/\/[^\s)\]'"<>]+)/g;
+        let cursor = 0;
+        let c = col;
+        while (true) {
+            const m = linkRegex.exec(text);
+            if (m === null)
+                break;
+            const before = text.slice(cursor, m.index);
+            for (let i = 0; i < before.length && c < limit; i++) {
+                this.setCell(row, c, before[i], baseStyle);
+                c++;
+            }
+            if (c >= limit)
+                return;
+            // Strip trailing punctuation that's almost never part of the URL.
+            let url = m[0];
+            while (url.length > 0 && /[.,;:!?]/.test(url[url.length - 1])) {
+                url = url.slice(0, -1);
+            }
+            if (url.length === 0) {
+                cursor = m.index + m[0].length;
+                continue;
+            }
+            const linkStyle = { ...baseStyle, fg: "cyan", underline: true, hyperlink: url };
+            for (let i = 0; i < url.length && c < limit; i++) {
+                this.setCell(row, c, url[i], linkStyle);
+                c++;
+            }
+            cursor = m.index + url.length;
+        }
+        for (let i = cursor; i < text.length && c < limit; i++) {
+            this.setCell(row, c, text[i], baseStyle);
+            c++;
+        }
+    }
     clone() {
         const g = new CellGrid(this.width, this.height);
         for (let r = 0; r < this.height; r++) {

package/dist/renderer/differ.js

@@ -18,6 +18,11 @@ export function styleToSGR(style) {
         codes.push(BG_CODES[style.bg]);
     return `\x1b[${codes.join(";")}m`;
 }
+/** OSC 8 hyperlink open/close sequences (ST = ESC \). */
+function osc8Open(url) {
+    return `\x1b]8;;${url}\x1b\\`;
+}
+const OSC8_CLOSE = "\x1b]8;;\x1b\\";
 /**
  * Compare two grids and return the ANSI string that transforms prev into next.
  * Only emits escape sequences for changed cells.
@@ -25,6 +30,7 @@ export function styleToSGR(style) {
 export function diff(prev, next, rowOffset = 0) {
     const parts = [];
     let lastStyle = null;
+    let lastHyperlink = null;
     let expectedRow = -1;
     let expectedCol = -1;
     for (let r = 0; r < next.height; r++) {
@@ -43,13 +49,24 @@ export function diff(prev, next, rowOffset = 0) {
                 parts.push(sgr);
                 lastStyle = sgr;
             }
+            // Apply OSC 8 hyperlink transitions independently of SGR
+            const nextHyperlink = nextCell.style.hyperlink ?? null;
+            if (nextHyperlink !== lastHyperlink) {
+                if (lastHyperlink !== null)
+                    parts.push(OSC8_CLOSE);
+                if (nextHyperlink !== null)
+                    parts.push(osc8Open(nextHyperlink));
+                lastHyperlink = nextHyperlink;
+            }
             parts.push(nextCell.char);
             expectedRow = r;
             expectedCol = c + 1;
         }
     }
-    // Reset style at end
+    // Close any open hyperlink and reset style at end
     if (parts.length > 0) {
+        if (lastHyperlink !== null)
+            parts.push(OSC8_CLOSE);
         parts.push("\x1b[0m");
     }
     return parts.join("");

package/dist/renderer/index.d.ts

@@ -45,7 +45,7 @@ export declare class TerminalRenderer {
     setCompanion(lines: string[] | null, color: string): void;
     setStatusHints(text: string): void;
     setBannerLines(lines: string[]): void;
-    setAutocomplete(suggestions: string[], index: number, descriptions?: string[]): void;
+    setAutocomplete(suggestions: string[], index: number, descriptions?: string[], categories?: string[]): void;
     setStatusLine(text: string): void;
     setContextWarning(warning: {
         text: string;
@@ -82,7 +82,16 @@ export declare class TerminalRenderer {
     clearLiveArea(): void;
     onKeypress(handler: (key: KeyEvent) => void): void;
     onAnimation(handler: (frame: number) => void): void;
-    /** Handle permission prompt keys (Y/N/D). Returns true if key was consumed. */
+    /**
+     * Handle permission prompt keys (Y/N/A/D).
+     * - Y / N: approve or deny this single call.
+     * - A: approve AND persist a `toolPermissions: { tool, action: "allow" }`
+     *   rule to `.oh/config.yaml` so future calls to this tool skip the prompt
+     *   entirely (audit U-A2). Mirrors Claude Code's "yes, don't ask again".
+     * - D: toggle inline diff (when available).
+     *
+     * Returns true if key was consumed.
+     */
     private handlePermissionKey;
     /** Handle question prompt text input. Returns true if key was consumed. */
     private handleQuestionKey;