@zhijiewang/openharness 2.22.1 → 2.24.0

package/README.md

@@ -42,6 +42,8 @@ AI coding agent in your terminal. Works with any LLM -- free local models or clo
 - [Cybergotchi](#cybergotchi)
 - [MCP Servers](#mcp-servers)
 - [Providers](#providers)
+- [Auth](#auth)
+- [Update](#update)
 - [FAQ](#faq)
 - [Install](#install)
 - [Development](#development)
@@ -162,6 +164,7 @@ Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XX
 | **Web** | | |
 | WebFetch | medium | Fetch URL content (SSRF-protected) |
 | WebSearch | medium | Search the web |
+| ExaSearch | medium | Neural web search via Exa (requires `EXA_API_KEY`) |
 | RemoteTrigger | high | HTTP requests to webhooks/APIs |
 | **Tasks** | | |
 | TaskCreate | low | Create structured tasks |
@@ -216,6 +219,7 @@ Over 80 commands are registered. The most-used ones are grouped below; see `/hel
 | `/clear` | Clear conversation history |
 | `/compact` | Compress conversation to free context |
 | `/export` | Export conversation to markdown |
+| `/copy [n]` | Copy the Nth-last assistant response to the system clipboard |
 | `/history [n]` | List recent sessions; `/history search <term>` to search |
 | `/browse` | Interactive session browser with preview |
 | `/resume <id>` | Resume a saved session |
@@ -249,12 +253,16 @@ Over 80 commands are registered. The most-used ones are grouped below; see `/hel
 | `/theme dark\|light` | Switch theme (saved to config) |
 | `/vim` | Toggle Vim mode |
 | `/companion off\|on` | Toggle companion visibility |
+| `/keys` | Show keyboard shortcuts |
+| `/keybindings` | Open `~/.oh/keybindings.json` in `$EDITOR` (creates a starter file if missing) |
 
 **AI:**
 | Command | Description |
 |---------|-------------|
 | `/plan <task>` | Enter plan mode |
 | `/review` | Review recent code changes |
+| `/summarize` | Summarize the current conversation |
+| `/recap` | One-sentence recap of the session (lighter than `/summarize`) |
 
 **Pet:**
 | Command | Description |
@@ -299,7 +307,7 @@ hooks:
     command: "scripts/cleanup.sh"
 ```
 
-**Event types** (23 total):
+**Event types** (27 total — matches Claude Code's stable surface):
 
 | Event | When it fires | Can block? |
 |-------|---------------|------------|
@@ -325,8 +333,14 @@ hooks:
 | `notification` | A notification is dispatched | — |
 | `taskCreated` | `TaskCreate` persists a new task | — |
 | `taskCompleted` | `TaskUpdate` transitions a task to `completed` | — |
+| `worktreeCreate` | `EnterWorktreeTool` creates an isolated git worktree | — |
+| `worktreeRemove` | `ExitWorktreeTool` removes a git worktree | — |
+| `elicitation` | An MCP server requests user input via `elicitation/create` | yes — `decision: allow\|deny` |
+| `elicitationResult` | After the elicitation response has been decided (audit trail) | — |
 | `instructionsLoaded` | `loadRulesAsPrompt` rebuilt the system prompt with rules in scope | — |
 
+Set `disableAllHooks: true` in `.oh/config.yaml` to globally disable hook execution while keeping definitions on disk for auditability.
+
 Live introspection: run `/hooks` in-session to see exactly which hooks are loaded, grouped by event.
 
 **Environment variables** available to hook scripts:
@@ -557,6 +571,23 @@ oh run "review the diff" --model claude-sonnet-4-6 --max-budget-usd 0.50
 oh session --model gpt-4o --max-budget-usd 5
 ```
 
+### CLI flags for CI / SDK use
+
+| Flag | Effect |
+|------|--------|
+| `--bare` | Skip optional startup work (project detection, plugins, memory, skills, MCP). System prompt is just the tool-use baseline. Faster startup on repos with many CLAUDE.md / RULES.md files. |
+| `--debug [categories]` | Enable categorized debug logs. `--debug` alone enables all; `--debug mcp,hooks` filters. Falls back to `OH_DEBUG` env var. |
+| `--debug-file <path>` | Append debug lines to a file instead of stderr. Falls back to `OH_DEBUG_FILE`. |
+| `--mcp-config <path>` | Load MCP servers from an external JSON file (in addition to `.oh/config.yaml`). |
+| `--strict-mcp-config` | With `--mcp-config`, ignore `.oh/config.yaml` MCP servers entirely. |
+| `--system-prompt-file <path>` / `--append-system-prompt-file <path>` | File-path variants of `--system-prompt` / `--append-system-prompt`. |
+| `--no-session-persistence` | Skip writing the session record to `~/.oh/sessions/` for ephemeral CI runs. |
+| `--fallback-model <model>` | Fallback used when the primary fails with a retriable error. REPLACES `.oh/config.yaml` `fallbackProviders` for this run. |
+| `--permission-prompt-tool <mcp_tool>` | Delegate tool-permission decisions to a configured MCP tool (e.g. `mcp__myperm__check`). |
+| `--init` / `--init-only` | Run the interactive setup wizard before / instead of the command. |
+
+All flags work on both `oh run` and `oh session`. See `oh run --help` and `oh session --help` for the full surface.
+
 ### Structured output with `--json-schema`
 
 Constrain the model's output to a JSON Schema. Useful for CI scripts that
@@ -650,6 +681,35 @@ oh --model llamacpp/my-model
 oh models                    # list available models
 ```
 
+## Auth
+
+Provider-agnostic credential management. Local LLMs (Ollama / llama.cpp / LM Studio) need no auth — configure them via `oh init`.
+
+```bash
+oh auth login [provider] [--key <value>]   # store API key for a provider
+oh auth logout [provider]                   # clear stored API key
+oh auth status                              # show stored providers + env-var overrides
+```
+
+`[provider]` defaults to your configured default. `--key` supplies the value inline; otherwise OH prompts (TTY) or reads from stdin (piped).
+
+### Script-based key resolution (`apiKeyHelper`)
+
+Avoid storing keys in plaintext / the encrypted store by plugging in a helper script (1Password, `pass`, vault, cloud secret manager). The configured command runs at credential-fetch time with `OH_PROVIDER` set, and its trimmed stdout becomes the key.
+
+```yaml
+# .oh/config.yaml
+apiKeyHelper: 'op read "op://Personal/Anthropic/key"'
+```
+
+Resolution priority: env var → encrypted store → `apiKeyHelper` → legacy plaintext config.
+
+## Update
+
+```bash
+oh update                    # detects how OH was installed (npm-global / npx / local clone) and prints the right upgrade command
+```
+
 ## Configuration Hierarchy
 
 Config is loaded in layers (later overrides earlier):

package/README.zh-CN.md

@@ -42,6 +42,8 @@
 - [电子宠物 Cybergotchi](#电子宠物-cybergotchi)
 - [MCP 服务器](#mcp-服务器)
 - [模型提供商](#模型提供商)
+- [鉴权（Auth）](#鉴权auth)
+- [自动更新（Update）](#自动更新update)
 - [常见问题](#常见问题)
 - [安装](#安装)
 - [开发](#开发)
@@ -162,6 +164,7 @@ statusLineFormat: '{model} │ {tokens} │ {cost} │ {ctx}'
 | **Web** | | |
 | WebFetch | 中 | 获取 URL 内容（防 SSRF） |
 | WebSearch | 中 | 网络搜索 |
+| ExaSearch | 中 | 通过 Exa 进行神经网络搜索（需要 `EXA_API_KEY`） |
 | RemoteTrigger | 高 | 向 webhook/API 发送 HTTP 请求 |
 | **任务** | | |
 | TaskCreate | 低 | 创建结构化任务 |
@@ -216,6 +219,7 @@ OH 注册了 80+ 个斜杠命令；下表只列出最常用的一部分。在会
 | `/clear` | 清空对话历史 |
 | `/compact` | 压缩对话以释放上下文 |
 | `/export` | 将对话导出为 markdown |
+| `/copy [n]` | 复制倒数第 N 条助手回复到系统剪贴板 |
 | `/history [n]` | 列出最近的会话；`/history search <term>` 搜索 |
 | `/browse` | 带预览的交互式会话浏览器 |
 | `/resume <id>` | 恢复已保存的会话 |
@@ -249,12 +253,16 @@ OH 注册了 80+ 个斜杠命令；下表只列出最常用的一部分。在会
 | `/theme dark\|light` | 切换主题（自动保存到配置） |
 | `/vim` | 切换 Vim 模式 |
 | `/companion off\|on` | 切换电子宠物可见性 |
+| `/keys` | 显示键盘快捷键 |
+| `/keybindings` | 在 `$EDITOR` 中打开 `~/.oh/keybindings.json`（首次运行会创建初始文件） |
 
 **AI：**
 | 命令 | 描述 |
 |---------|-------------|
 | `/plan <task>` | 进入规划模式 |
 | `/review` | 审查最近的代码变更 |
+| `/summarize` | 总结当前对话 |
+| `/recap` | 一句话回顾本次会话（比 `/summarize` 更轻量） |
 
 **宠物：**
 | 命令 | 描述 |
@@ -299,7 +307,7 @@ hooks:
     command: "scripts/cleanup.sh"
 ```
 
-**事件类型**（共 23 个）：
+**事件类型**（共 27 个 —— 与 Claude Code 稳定版一致）：
 
 | 事件 | 触发时机 | 是否可阻止 |
 |-------|---------------|------------|
@@ -325,8 +333,14 @@ hooks:
 | `notification` | 通知被派发 | — |
 | `taskCreated` | `TaskCreate` 持久化新任务后 | — |
 | `taskCompleted` | `TaskUpdate` 将任务状态切换为 `completed` 时 | — |
+| `worktreeCreate` | `EnterWorktreeTool` 创建隔离的 git worktree 时 | — |
+| `worktreeRemove` | `ExitWorktreeTool` 移除 git worktree 时 | — |
+| `elicitation` | MCP 服务器通过 `elicitation/create` 请求用户输入 | 是 —— `decision: allow\|deny` |
+| `elicitationResult` | elicitation 响应决定之后（用于审计追踪） | — |
 | `instructionsLoaded` | `loadRulesAsPrompt` 重新构建系统提示并加载规则之后 | — |
 
+在 `.oh/config.yaml` 中设置 `disableAllHooks: true` 可全局禁用钩子执行，同时保留磁盘上的定义以便审计。
+
 实时查看：在会话中运行 `/hooks` 可以按事件分组查看当前已加载的钩子。
 
 **环境变量**（钩子脚本可用）：
@@ -557,6 +571,23 @@ oh run "review the diff" --model claude-sonnet-4-6 --max-budget-usd 0.50
 oh session --model gpt-4o --max-budget-usd 5
 ```
 
+### CI / SDK 常用 CLI 标志
+
+| 标志 | 作用 |
+|------|------|
+| `--bare` | 跳过启动时的可选工作（项目检测、插件、记忆、技能、MCP）。系统提示仅保留工具使用基线，对包含大量 CLAUDE.md / RULES.md 的仓库启动更快。 |
+| `--debug [类别]` | 启用分类调试日志。`--debug` 启用全部；`--debug mcp,hooks` 仅启用指定类别。也读取 `OH_DEBUG` 环境变量。 |
+| `--debug-file <path>` | 把调试日志追加到文件而非 stderr。也读取 `OH_DEBUG_FILE`。 |
+| `--mcp-config <path>` | 从外部 JSON 文件加载 MCP 服务器（叠加在 `.oh/config.yaml` 之上）。 |
+| `--strict-mcp-config` | 配合 `--mcp-config`，完全忽略 `.oh/config.yaml` 中的 MCP 服务器。 |
+| `--system-prompt-file <path>` / `--append-system-prompt-file <path>` | `--system-prompt` / `--append-system-prompt` 的文件路径变体。 |
+| `--no-session-persistence` | 跳过会话写入 `~/.oh/sessions/`，适合一次性 CI 运行。 |
+| `--fallback-model <model>` | 主模型遇到可重试错误时使用的回退模型。本次运行内会替代 `.oh/config.yaml` 的 `fallbackProviders`。 |
+| `--permission-prompt-tool <mcp_tool>` | 把工具授权决策委托给指定的 MCP 工具（例如 `mcp__myperm__check`）。 |
+| `--init` / `--init-only` | 在执行命令前 / 替代执行命令运行交互式安装向导。 |
+
+所有标志在 `oh run` 与 `oh session` 上都可用。完整列表见 `oh run --help` 与 `oh session --help`。
+
 ### 使用 `--json-schema` 约束结构化输出
 
 按 JSON Schema 约束模型输出。适用于需要以编程方式解析模型输出、避免正则启发式的 CI 脚本：
@@ -649,6 +680,35 @@ oh --model llamacpp/my-model
 oh models                    # 列出可用模型
 ```
 
+## 鉴权（Auth）
+
+提供商无关的凭据管理。本地 LLM（Ollama / llama.cpp / LM Studio）无需鉴权 —— 通过 `oh init` 配置即可。
+
+```bash
+oh auth login [provider] [--key <value>]   # 存储某个提供商的 API key
+oh auth logout [provider]                   # 清除已存储的 API key
+oh auth status                              # 显示已存储的提供商及环境变量覆盖情况
+```
+
+`[provider]` 默认使用配置好的默认提供商。`--key` 可直接传入；否则 OH 会在 TTY 下交互询问，在管道输入下读到 EOF。
+
+### 脚本化 key 解析（`apiKeyHelper`）
+
+通过插入辅助脚本（1Password、`pass`、vault、云端密钥管理器等）避免把 key 写入纯文本或加密存储。配置好的命令在取 key 时执行，环境变量带 `OH_PROVIDER`，去掉首尾空白的 stdout 即为 key。
+
+```yaml
+# .oh/config.yaml
+apiKeyHelper: 'op read "op://Personal/Anthropic/key"'
+```
+
+解析优先级：环境变量 → 加密存储 → `apiKeyHelper` → 旧版纯文本配置。
+
+## 自动更新（Update）
+
+```bash
+oh update                    # 检测安装方式（npm 全局 / npx / 本地克隆），打印对应的升级命令
+```
+
 ## 配置层级
 
 配置按层加载（后者覆盖前者）：

package/dist/commands/index.d.ts

@@ -14,6 +14,12 @@
  */
 export type { CommandContext, CommandHandler, CommandResult } from "./types.js";
 import type { CommandContext, CommandResult } from "./types.js";
+/**
+ * Slash command categories shown in the autocomplete picker (audit U-A3).
+ * Names are user-facing — keep them short. Order here is the grouping
+ * order in the picker: most-frequently-used first.
+ */
+export type CommandCategory = "Session" | "Git" | "Info" | "Settings" | "AI" | "Skills" | "MCP" | "Other";
 /**
  * Check if input is a slash command. If so, execute it.
  */
@@ -25,6 +31,7 @@ export declare function getCommandNames(): string[];
 export declare function getCommandEntries(): Array<{
     name: string;
     description: string;
+    category: CommandCategory;
 }>;
 /**
  * Register MCP-server prompts as `/server:prompt` slash commands. Called from

package/dist/commands/index.js

@@ -18,18 +18,25 @@ import { registerInfoCommands } from "./info.js";
 import { registerSessionCommands } from "./session.js";
 import { registerSettingsCommands } from "./settings.js";
 import { registerSkillCommands } from "./skills.js";
-// ── Command Registry ──
 const commands = new Map();
-function register(name, description, handler) {
-    commands.set(name, { description, handler });
+/**
+ * Adapter: each `registerXxx(register)` call is wrapped with a category-bound
+ * register so per-domain command files don't need a 4th argument. Adding a
+ * new category is a one-line change here, not a sweep across the command
+ * files.
+ */
+function registerFor(category) {
+    return (name, description, handler) => {
+        commands.set(name, { description, handler, category });
+    };
 }
-// Register all command groups
-registerSessionCommands(register);
-registerGitCommands(register);
-registerInfoCommands(register, () => commands);
-registerSettingsCommands(register);
-registerAICommands(register);
-registerSkillCommands(register);
+// Register all command groups — category derived from the source file split.
+registerSessionCommands(registerFor("Session"));
+registerGitCommands(registerFor("Git"));
+registerInfoCommands(registerFor("Info"), () => commands);
+registerSettingsCommands(registerFor("Settings"));
+registerAICommands(registerFor("AI"));
+registerSkillCommands(registerFor("Skills"));
 // ── Command Parser ──
 /**
  * Check if input is a slash command. If so, execute it.
@@ -65,7 +72,7 @@ export function getCommandNames() {
     return [...commands.keys()];
 }
 export function getCommandEntries() {
-    return [...commands.entries()].map(([name, { description }]) => ({ name, description }));
+    return [...commands.entries()].map(([name, { description, category }]) => ({ name, description, category }));
 }
 let mcpPromptKeys = [];
 export function registerMcpPromptCommands(prompts) {
@@ -79,6 +86,7 @@ export function registerMcpPromptCommands(prompts) {
         const usageBits = [...required.map((n) => `${n}=<value>`), ...optional.map((n) => `[${n}=<value>]`)].join(" ");
         commands.set(key, {
             description: handle.description,
+            category: "MCP",
             handler: async (args) => {
                 const parsed = parseMcpPromptArgs(args);
                 const missing = required.filter((n) => !(n in parsed));

package/dist/commands/session.js

@@ -181,10 +181,13 @@ export function registerSessionCommands(register) {
     register("browse", "Open interactive session browser", () => {
         return { output: "__OPEN_SESSION_BROWSER__", handled: true };
     });
-    register("resume", "Resume a saved session by ID", (args) => {
+    register("resume", "Resume a saved session — opens a picker if no ID given", (args) => {
         const id = args.trim();
+        // Audit U-A6: with no id, open the interactive session browser instead
+        // of erroring with a usage hint. Mirrors Claude Code's `/resume`
+        // picker. The browser already supports Enter-to-resume.
         if (!id)
-            return { output: "Usage: /resume <session-id>", handled: true };
+            return { output: "__OPEN_SESSION_BROWSER__", handled: true };
         const sessionDir = join(homedir(), ".oh", "sessions");
         try {
             loadSession(id, sessionDir);

package/dist/commands/settings.d.ts

@@ -1,5 +1,5 @@
 /**
- * Settings commands — /theme, /companion, /fast, /keys, /keybindings, /effort, /sandbox, /permissions, /allowed-tools
+ * Settings commands — /theme, /companion, /fast, /keys, /keybindings, /effort, /sandbox, /permissions, /allowed-tools, /trust
  */
 import type { CommandHandler } from "./types.js";
 export declare function registerSettingsCommands(register: (name: string, description: string, handler: CommandHandler) => void): void;

package/dist/commands/settings.js

@@ -1,12 +1,14 @@
 /**
- * Settings commands — /theme, /companion, /fast, /keys, /keybindings, /effort, /sandbox, /permissions, /allowed-tools
+ * Settings commands — /theme, /companion, /fast, /keys, /keybindings, /effort, /sandbox, /permissions, /allowed-tools, /trust
  */
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
+import { readApprovalLog } from "../harness/approvals.js";
 import { readOhConfig } from "../harness/config.js";
 import { loadKeybindings } from "../harness/keybindings.js";
+import { isTrusted, listTrusted, trust } from "../harness/trust.js";
 const KEYBINDINGS_TEMPLATE = `[
   { "key": "ctrl+d", "action": "/diff" },
   { "key": "ctrl+l", "action": "/clear" },
@@ -137,17 +139,37 @@ export function registerSettingsCommands(register) {
         const { sandboxStatus } = require("../harness/sandbox.js");
         return { output: `${sandboxStatus()}\n\nConfigure in .oh/config.yaml under sandbox:`, handled: true };
     });
-    register("permissions", "View or change permission mode", (args, ctx) => {
-        const mode = args.trim().toLowerCase();
-        if (!mode) {
+    register("permissions", "View or change permission mode (or 'log' for approval history)", (args, ctx) => {
+        const trimmed = args.trim();
+        if (!trimmed) {
             return {
-                output: `Current permission mode: ${ctx.permissionMode}\n\nAvailable modes:\n  ask            Prompt for medium/high risk (default)\n  trust          Auto-approve everything\n  deny           Only low-risk read-only\n  acceptEdits    Auto-approve file edits\n  plan           Read-only mode\n  auto           Auto-approve, block dangerous bash\n  bypassPermissions  CI/CD only`,
+                output: `Current permission mode: ${ctx.permissionMode}\n\nAvailable modes:\n  ask            Prompt for medium/high risk (default)\n  trust          Auto-approve everything\n  deny           Only low-risk read-only\n  acceptEdits    Auto-approve file edits\n  plan           Read-only mode\n  auto           Auto-approve, block dangerous bash\n  bypassPermissions  CI/CD only\n\nApproval history:\n  /permissions log [n]   Show last n approval decisions (default 50)`,
                 handled: true,
             };
         }
+        // Audit U-B5: /permissions log [n] — show approval history from
+        // ~/.oh/approvals.log. Subcommand check happens before the mode-name
+        // validation so "log" doesn't collide with the mode list.
+        const [head, ...tail] = trimmed.split(/\s+/);
+        if (head?.toLowerCase() === "log") {
+            const n = Math.max(1, Math.min(500, Number.parseInt(tail[0] ?? "50", 10) || 50));
+            const records = readApprovalLog(n);
+            if (records.length === 0) {
+                return { output: "No approval decisions logged yet.", handled: true };
+            }
+            const lines = records.map((r) => {
+                const time = r.ts.slice(11, 19); // HH:MM:SS from ISO
+                const date = r.ts.slice(0, 10);
+                const decision = r.decision === "allow" ? "✓" : r.decision === "always" ? "★" : "✗";
+                const reason = r.reason ? ` (${r.reason})` : "";
+                return `${date} ${time}  ${decision} ${r.decision.padEnd(7)} ${r.tool.padEnd(14)} ${r.source}${reason}`;
+            });
+            return { output: `Last ${records.length} approval decisions:\n${lines.join("\n")}`, handled: true };
+        }
+        const mode = trimmed.toLowerCase();
         const valid = ["ask", "trust", "deny", "acceptedits", "plan", "auto", "bypasspermissions"];
         if (!valid.includes(mode)) {
-            return { output: `Unknown mode: ${mode}. Valid: ${valid.join(", ")}`, handled: true };
+            return { output: `Unknown mode: ${mode}. Valid: ${valid.join(", ")} | log`, handled: true };
         }
         return {
             output: `Permission mode set to: ${mode}\n(Note: takes effect for new tool calls in this session)`,
@@ -174,6 +196,25 @@ export function registerSettingsCommands(register) {
     register("vim", "Toggle Vim mode", () => {
         return { output: "__TOGGLE_VIM__", handled: true };
     });
+    register("trust", "Trust this workspace for shell hooks / status-line scripts (or list / add a path)", (args) => {
+        const arg = args.trim();
+        if (arg === "list") {
+            const trusted = listTrusted();
+            if (trusted.length === 0) {
+                return { output: "No trusted workspaces yet.\nRun `/trust` to add the current directory.", handled: true };
+            }
+            return { output: `Trusted workspaces:\n${trusted.map((d) => `  ${d}`).join("\n")}`, handled: true };
+        }
+        const target = arg || process.cwd();
+        if (isTrusted(target)) {
+            return { output: `Already trusted: ${target}`, handled: true };
+        }
+        trust(target);
+        return {
+            output: `Trusted: ${target}\nShell hooks and status-line scripts will now execute in this directory.`,
+            handled: true,
+        };
+    });
     register("login", "Set API key for current provider", (args, ctx) => {
         const key = args.trim();
         if (!key) {

package/dist/harness/approvals.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Approval log (audit U-B5).
+ *
+ * Append-only JSONL at `~/.oh/approvals.log` recording every permission
+ * resolution OH makes during a session — the source (user / hook / rule /
+ * permission-prompt-tool / headless / policy), the tool name, the decision
+ * (allow / deny / always), a redacted args preview, and a timestamp.
+ *
+ * Rotated to a `.1` sibling once the file exceeds ~2 MiB so the log doesn't
+ * grow unbounded. The slash command `/permissions log` reads the tail.
+ *
+ * Mirrors Claude Code's session approval log. Genuinely new — no prior art
+ * in OH (grep-verified during the audit refresh).
+ */
+export type ApprovalSource = "user" | "hook" | "rule" | "permission-prompt-tool" | "policy" | "headless";
+export type ApprovalDecision = "allow" | "deny" | "always";
+export interface ApprovalRecord {
+    ts: string;
+    tool: string;
+    decision: ApprovalDecision;
+    source: ApprovalSource;
+    /** Tool args as JSON, truncated to ~500 chars to keep the log compact. */
+    argsPreview?: string;
+    /** Optional human-readable reason (hook reason, headless reason, etc.). */
+    reason?: string;
+    cwd?: string;
+}
+/**
+ * Override the log file path for tests, or `null` to silence the writer.
+ * Calling without arguments resets to the real `~/.oh/approvals.log`.
+ */
+export declare function setApprovalLogPathForTests(path: string | null | undefined): void;
+/**
+ * Append a single approval decision to the log. Errors are swallowed: a
+ * disk-full or permission error must not block the agent loop.
+ */
+export declare function recordApproval(rec: Omit<ApprovalRecord, "ts">): void;
+/**
+ * Read the most recent `n` records from the log. Skips malformed lines.
+ * Used by the `/permissions log` slash command.
+ */
+export declare function readApprovalLog(n?: number): ApprovalRecord[];
+/** Truncate an args string to roughly N chars without breaking JSON brackets. */
+export declare function previewArgs(argsJson: string, max?: number): string;
+//# sourceMappingURL=approvals.d.ts.map

package/dist/harness/approvals.js

@@ -0,0 +1,100 @@
+/**
+ * Approval log (audit U-B5).
+ *
+ * Append-only JSONL at `~/.oh/approvals.log` recording every permission
+ * resolution OH makes during a session — the source (user / hook / rule /
+ * permission-prompt-tool / headless / policy), the tool name, the decision
+ * (allow / deny / always), a redacted args preview, and a timestamp.
+ *
+ * Rotated to a `.1` sibling once the file exceeds ~2 MiB so the log doesn't
+ * grow unbounded. The slash command `/permissions log` reads the tail.
+ *
+ * Mirrors Claude Code's session approval log. Genuinely new — no prior art
+ * in OH (grep-verified during the audit refresh).
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const LOG_FILE = join(homedir(), ".oh", "approvals.log");
+const ROTATE_BYTES = 2 * 1024 * 1024;
+/** Test seam — flip to `null` to disable logging in test runs. */
+let _logFileOverride;
+/**
+ * Override the log file path for tests, or `null` to silence the writer.
+ * Calling without arguments resets to the real `~/.oh/approvals.log`.
+ */
+export function setApprovalLogPathForTests(path) {
+    _logFileOverride = path;
+}
+function logPath() {
+    if (_logFileOverride === null)
+        return null;
+    return _logFileOverride ?? LOG_FILE;
+}
+function rotateIfNeeded(file) {
+    try {
+        const st = statSync(file);
+        if (st.size >= ROTATE_BYTES) {
+            renameSync(file, `${file}.1`);
+        }
+    }
+    catch {
+        /* file does not exist yet — no rotate needed */
+    }
+}
+/**
+ * Append a single approval decision to the log. Errors are swallowed: a
+ * disk-full or permission error must not block the agent loop.
+ */
+export function recordApproval(rec) {
+    const file = logPath();
+    if (!file)
+        return;
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        rotateIfNeeded(file);
+        const line = `${JSON.stringify({ ts: new Date().toISOString(), ...rec })}\n`;
+        appendFileSync(file, line, "utf8");
+    }
+    catch {
+        /* logging must not throw into caller */
+    }
+}
+/**
+ * Read the most recent `n` records from the log. Skips malformed lines.
+ * Used by the `/permissions log` slash command.
+ */
+export function readApprovalLog(n = 50) {
+    const file = logPath();
+    if (!file || !existsSync(file))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const lines = raw.split("\n").filter((l) => l.length > 0);
+    const tail = lines.slice(Math.max(0, lines.length - n));
+    const out = [];
+    for (const line of tail) {
+        try {
+            const obj = JSON.parse(line);
+            if (obj && typeof obj.tool === "string" && typeof obj.decision === "string") {
+                out.push(obj);
+            }
+        }
+        catch {
+            /* skip malformed line */
+        }
+    }
+    return out;
+}
+/** Truncate an args string to roughly N chars without breaking JSON brackets. */
+export function previewArgs(argsJson, max = 500) {
+    if (argsJson.length <= max)
+        return argsJson;
+    return `${argsJson.slice(0, max)}…`;
+}
+//# sourceMappingURL=approvals.js.map

package/dist/harness/config.d.ts

@@ -151,6 +151,27 @@ export type OhConfig = {
     apiKeyHelper?: string;
     toolPermissions?: ToolPermissionRule[];
     statusLineFormat?: string;
+    /**
+     * JSON-envelope status line script (audit U-B1). When set, OH spawns
+     * `command` through the user's shell on each refresh, pipes a JSON
+     * envelope `{ model, tokens, cost, ctx, sessionId, cwd, gitBranch }` to
+     * stdin, and uses the trimmed stdout as the status line. Mirrors Claude
+     * Code's `statusLine` config. Gated through the workspace-trust system —
+     * scripts only run in trusted dirs.
+     *
+     * Output is cached for `refreshMs` (default 1000) so the script doesn't
+     * re-spawn on every keypress. Multi-line output is truncated to the
+     * first line.
+     *
+     * Coexists with `statusLineFormat` — when both are set, the script wins.
+     */
+    statusLine?: {
+        command: string;
+        /** Cache window in ms. Default: 1000. Min: 100. */
+        refreshMs?: number;
+        /** Spawn timeout in ms. Default: 2000. */
+        timeoutMs?: number;
+    };
     /** Verification loops — auto-run lint/typecheck after file edits */
     verification?: {
         enabled?: boolean;
@@ -223,5 +244,18 @@ export declare function readOhConfig(root?: string, sources?: readonly SettingSo
  * Unknown names are silently dropped.
  */
 export declare function parseSettingSources(raw: string | undefined): SettingSource[] | undefined;
+/**
+ * Persist a single tool-allow rule (audit U-A2). Used by the "[A]lways"
+ * keypress in the permission prompt — the user has just approved a tool
+ * call and wants future calls to that tool to skip the prompt.
+ *
+ * No-ops when no project config exists (user is running on auto-detected
+ * settings; we don't auto-create `.oh/config.yaml` just to add a rule).
+ * De-dupes against an exact-tool rule with no pattern.
+ *
+ * Returns `true` if a rule was written, `false` if already present or
+ * skipped because no config exists.
+ */
+export declare function appendToolPermission(toolName: string, action?: "allow" | "deny", root?: string): boolean;
 export declare function writeOhConfig(cfg: OhConfig, root?: string): void;
 //# sourceMappingURL=config.d.ts.map

package/dist/harness/config.js

@@ -101,6 +101,30 @@ export function parseSettingSources(raw) {
         .filter((s) => valid.has(s));
     return out.length > 0 ? out : undefined;
 }
+/**
+ * Persist a single tool-allow rule (audit U-A2). Used by the "[A]lways"
+ * keypress in the permission prompt — the user has just approved a tool
+ * call and wants future calls to that tool to skip the prompt.
+ *
+ * No-ops when no project config exists (user is running on auto-detected
+ * settings; we don't auto-create `.oh/config.yaml` just to add a rule).
+ * De-dupes against an exact-tool rule with no pattern.
+ *
+ * Returns `true` if a rule was written, `false` if already present or
+ * skipped because no config exists.
+ */
+export function appendToolPermission(toolName, action = "allow", root) {
+    const cfg = readOhConfig(root);
+    if (!cfg)
+        return false;
+    const existing = cfg.toolPermissions ?? [];
+    if (existing.some((r) => r.tool === toolName && !r.pattern && r.action === action)) {
+        return false;
+    }
+    cfg.toolPermissions = [...existing, { tool: toolName, action }];
+    writeOhConfig(cfg, root);
+    return true;
+}
 export function writeOhConfig(cfg, root) {
     invalidateConfigCache();
     // Emit configChange hook (lazy import to avoid circular dependency)