@zhijiewang/openharness 2.22.1 → 2.23.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)
@@ -216,6 +218,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 +252,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 +306,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 +332,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 +570,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 +680,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)
 - [常见问题](#常见问题)
 - [安装](#安装)
 - [开发](#开发)
@@ -216,6 +218,7 @@ OH 注册了 80+ 个斜杠命令；下表只列出最常用的一部分。在会
 | `/clear` | 清空对话历史 |
 | `/compact` | 压缩对话以释放上下文 |
 | `/export` | 将对话导出为 markdown |
+| `/copy [n]` | 复制倒数第 N 条助手回复到系统剪贴板 |
 | `/history [n]` | 列出最近的会话；`/history search <term>` 搜索 |
 | `/browse` | 带预览的交互式会话浏览器 |
 | `/resume <id>` | 恢复已保存的会话 |
@@ -249,12 +252,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 +306,7 @@ hooks:
     command: "scripts/cleanup.sh"
 ```
 
-**事件类型**（共 23 个）：
+**事件类型**（共 27 个 —— 与 Claude Code 稳定版一致）：
 
 | 事件 | 触发时机 | 是否可阻止 |
 |-------|---------------|------------|
@@ -325,8 +332,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 +570,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 +679,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,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 { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
@@ -7,6 +7,7 @@ import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 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" },
@@ -174,6 +175,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/config.d.ts

@@ -223,5 +223,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)

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/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/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;

package/dist/renderer/index.js

@@ -62,6 +62,7 @@ export class TerminalRenderer {
             questionPrompt: null,
             autocomplete: [],
             autocompleteDescriptions: [],
+            autocompleteCategories: [],
             autocompleteIndex: -1,
             manualScroll: 0,
             codeBlocksExpanded: false,
@@ -195,9 +196,10 @@ export class TerminalRenderer {
         this.state.bannerLines = lines;
         this.scheduleRender();
     }
-    setAutocomplete(suggestions, index, descriptions) {
+    setAutocomplete(suggestions, index, descriptions, categories) {
         this.state.autocomplete = suggestions;
         this.state.autocompleteDescriptions = descriptions ?? [];
+        this.state.autocompleteCategories = categories ?? [];
         this.state.autocompleteIndex = index;
         this.scheduleRender();
     }
@@ -366,20 +368,44 @@ export class TerminalRenderer {
         this.animationCallback = handler;
     }
     // ── Input routing ──
-    /** 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.
+     */
     handlePermissionKey(key) {
         if (!this.permissionResolve)
             return false;
         const k = key.char.toLowerCase();
-        if (k === "y" || k === "n") {
+        if (k === "y" || k === "n" || k === "a") {
             const resolve = this.permissionResolve;
+            const toolName = this.state.permissionBox?.toolName;
             this.permissionResolve = null;
             this.permissionPrompt = null;
             this.state.permissionBox = null;
             this.state.permissionDiffVisible = false;
             this.state.permissionDiffInfo = null;
+            // Persist before resolving — any error in the write should not block
+            // the resolution. The persist call itself is no-op when no .oh/config.yaml
+            // exists (we don't auto-create on first interaction).
+            if (k === "a" && toolName) {
+                try {
+                    // Lazy import to avoid pulling config into the renderer bundle
+                    // for callers that don't trip the permission path.
+                    const { appendToolPermission } = require("../harness/config.js");
+                    appendToolPermission(toolName);
+                }
+                catch {
+                    /* persistence failure must not block the agent */
+                }
+            }
             this.scheduleRender();
-            resolve(k === "y");
+            resolve(k === "y" || k === "a");
         }
         else if (k === "d" && this.state.permissionDiffInfo) {
             this.state.permissionDiffVisible = !this.state.permissionDiffVisible;
@@ -626,6 +652,8 @@ export class TerminalRenderer {
         if (this.state.statusLine)
             rows += 1;
         rows += this.state.autocomplete.length;
+        // Audit U-A3: one row per distinct category header.
+        rows += new Set((this.state.autocompleteCategories ?? []).filter((c) => c && c.length > 0)).size;
         if (this.state.permissionBox) {
             rows += 3;
             if (this.state.permissionDiffVisible && this.state.permissionDiffInfo)

package/dist/renderer/input.js

@@ -84,6 +84,13 @@ export function parseKey(data, offset) {
             return { event: key("", "pageup", seq.slice(0, 4)), consumed: 4 };
         if (seq.startsWith("\x1b[6~"))
             return { event: key("", "pagedown", seq.slice(0, 4)), consumed: 4 };
+        // Shift+Tab (xterm "backtab"): ESC [ Z. Used as a quick-toggle for
+        // permission mode (mirrors Claude Code's Shift+Tab cycler).
+        if (seq.startsWith("\x1b[Z"))
+            return {
+                event: { char: "", name: "tab", ctrl: false, meta: false, shift: true, sequence: seq.slice(0, 3) },
+                consumed: 3,
+            };
         // Shift+Arrow: ESC [ 1 ; 2 A/B/C/D
         if (seq.startsWith("\x1b[1;2A"))
             return {

package/dist/renderer/layout-sections.js

@@ -280,6 +280,13 @@ export function renderPermissionBoxSection(state, grid, nextRow, h, opts) {
         kc += 1;
         grid.writeText(nextRow, kc, "o", S_DIM);
         kc += 1;
+        grid.writeText(nextRow, kc, "  ", S_DIM);
+        kc += 2;
+        // Audit U-A2: "always allow this tool" — persists toolPermissions rule.
+        grid.writeText(nextRow, kc, "A", S_KEY_GREEN);
+        kc += 1;
+        grid.writeText(nextRow, kc, "lways", S_DIM);
+        kc += 5;
         if (state.permissionDiffInfo) {
             grid.writeText(nextRow, kc, "  ", S_DIM);
             kc += 2;
@@ -300,10 +307,12 @@ export function renderPermissionBoxSection(state, grid, nextRow, h, opts) {
         grid.writeText(nextRow, 1, "Y", S_KEY_GREEN);
         grid.writeText(nextRow, 2, "es  ", S_DIM);
         grid.writeText(nextRow, 6, "N", S_KEY_RED);
-        grid.writeText(nextRow, 7, "o", S_DIM);
+        grid.writeText(nextRow, 7, "o  ", S_DIM);
+        grid.writeText(nextRow, 10, "A", S_KEY_GREEN);
+        grid.writeText(nextRow, 11, "lways", S_DIM);
         if (state.permissionDiffInfo) {
-            grid.writeText(nextRow, 10, "D", S_KEY_CYAN);
-            grid.writeText(nextRow, 11, "iff", S_DIM);
+            grid.writeText(nextRow, 18, "D", S_KEY_CYAN);
+            grid.writeText(nextRow, 19, "iff", S_DIM);
         }
         nextRow++;
         if (state.permissionDiffVisible && state.permissionDiffInfo && nextRow + 3 < h) {
@@ -375,7 +384,20 @@ export function renderAutocompleteSection(state, grid, nextRow, limit, promptWid
     if (state.autocomplete.length === 0)
         return nextRow;
     const w = grid.width;
+    let lastCategory = "";
     for (let ai = 0; ai < state.autocomplete.length; ai++) {
+        if (nextRow >= limit)
+            break;
+        // Category header — draw whenever the category changes between entries.
+        // First-entry header is drawn when the category is non-empty (audit U-A3).
+        const cat = state.autocompleteCategories?.[ai] ?? "";
+        if (cat && cat !== lastCategory) {
+            if (nextRow >= limit)
+                break;
+            grid.writeText(nextRow, promptWidth, `── ${cat} ──`, S_DIM);
+            nextRow++;
+            lastCategory = cat;
+        }
         if (nextRow >= limit)
             break;
         const cmd = state.autocomplete[ai];

package/dist/renderer/layout.d.ts

@@ -57,6 +57,14 @@ export type LayoutState = {
     } | null;
     autocomplete: string[];
     autocompleteDescriptions: string[];
+    /**
+     * Optional category label per autocomplete entry (audit U-A3). When two
+     * adjacent entries differ in category, the renderer draws a header line
+     * before the second. Empty / missing category strings render flat (the
+     * pre-A3 behavior). Optional so older test fixtures + non-REPL callers
+     * don't need to thread an empty array.
+     */
+    autocompleteCategories?: string[];
     autocompleteIndex: number;
     manualScroll: number;
     codeBlocksExpanded: boolean;

package/dist/renderer/layout.js

@@ -28,7 +28,11 @@ export function rasterize(state, grid) {
     const questionHeight = state.questionPrompt ? 4 + (state.questionPrompt.options?.length ?? 0) : 0;
     const statusLineHeight = state.statusLine ? 1 : 0;
     const contextWarningHeight = state.contextWarning ? 1 : 0;
-    const autocompleteHeight = state.autocomplete.length;
+    // Autocomplete height — each entry is one row, plus one extra row per
+    // distinct category (audit U-A3 header lines). Distinct-category count
+    // is bounded by entry count so this stays cheap.
+    const distinctCategories = new Set((state.autocompleteCategories ?? []).filter((c) => c && c.length > 0));
+    const autocompleteHeight = state.autocomplete.length + distinctCategories.size;
     const inputLineCount = Math.min(5, (state.inputText.match(/\n/g)?.length ?? 0) + 1);
     const rawFooterHeight = Math.max(2 + inputLineCount + statusLineHeight + autocompleteHeight, companionHeight + 1) +
         permissionHeight +

package/dist/repl.js

@@ -105,6 +105,9 @@ export async function startREPL(config) {
     let fastMode = s().fastMode;
     let acSuggestions = s().acSuggestions;
     let acDescriptions = s().acDescriptions;
+    // Audit U-A3: parallel category array for the picker. Local-only — no
+    // need to round-trip through `store` since no other consumer reads it.
+    let acCategories = [];
     let acIndex = s().acIndex;
     let acTokenStart = s().acTokenStart;
     let acIsPath = s().acIsPath;
@@ -128,13 +131,16 @@ export async function startREPL(config) {
     function updateAutocomplete() {
         acIsPath = false;
         if (inputText.startsWith("/") && inputText.length > 1 && !inputText.includes(" ")) {
-            // Slash command autocomplete
+            // Slash command autocomplete — entries arrive in registration order
+            // (Session → Git → Info → Settings → AI → Skills → MCP), so categories
+            // are naturally contiguous after a startsWith filter (audit U-A3).
             const prefix = inputText.slice(1).toLowerCase();
             const entries = getCommandEntries()
                 .filter((e) => e.name.startsWith(prefix))
-                .slice(0, 5);
+                .slice(0, 8);
             acSuggestions = entries.map((e) => e.name);
             acDescriptions = entries.map((e) => e.description);
+            acCategories = entries.map((e) => e.category);
             acTokenStart = 0;
             acIndex = -1;
         }
@@ -176,26 +182,30 @@ export async function startREPL(config) {
                             return "";
                         }
                     });
+                    acCategories = [];
                     acIsPath = acSuggestions.length > 0;
                 }
                 catch {
                     acSuggestions = [];
                     acDescriptions = [];
+                    acCategories = [];
                 }
                 acIndex = -1;
             }
             else {
                 acSuggestions = [];
                 acDescriptions = [];
+                acCategories = [];
                 acIndex = -1;
             }
         }
         else {
             acSuggestions = [];
             acDescriptions = [];
+            acCategories = [];
             acIndex = -1;
         }
-        renderer.setAutocomplete(acSuggestions, acIndex, acDescriptions);
+        renderer.setAutocomplete(acSuggestions, acIndex, acDescriptions, acCategories);
     }
     // Companion
     let companionVisible = true;
@@ -516,6 +526,14 @@ export async function startREPL(config) {
         }
         if (key.name === "pageup" || key.name === "pagedown" || key.name === "mouse")
             return;
+        // Shift+Tab: cycle permission mode (audit U-A1). Mirrors Claude Code's
+        // quick-toggle. Cycles ask → acceptEdits → plan → trust → ask. The
+        // session-level mode is mutated on `config` so all downstream callers
+        // (`query()`, `cronExecutor`, status line) read the new value.
+        if (key.name === "tab" && key.shift) {
+            cyclePermissionMode();
+            return;
+        }
         // Tab: autocomplete slash commands or file paths, or cycle tool call expansion
         if (key.name === "tab" && !loading) {
             if (acSuggestions.length > 0) {
@@ -533,7 +551,7 @@ export async function startREPL(config) {
                 }
                 renderer.setInputText(inputText);
                 renderer.setInputCursor(inputCursor);
-                renderer.setAutocomplete(acSuggestions, acIndex, acDescriptions);
+                renderer.setAutocomplete(acSuggestions, acIndex, acDescriptions, acCategories);
                 return;
             }
             renderer.cycleToolCallExpansion();
@@ -621,6 +639,26 @@ export async function startREPL(config) {
             acIsPath,
         });
     });
+    /**
+     * Cycle the session permission mode (audit U-A1, Shift+Tab). The cycle
+     * intentionally covers the four interactive modes a user is likely to
+     * toggle between — `ask`, `acceptEdits`, `plan`, `trust`. The other modes
+     * (`deny`, `auto`, `bypassPermissions`) stay reachable via `/permissions
+     * <mode>` but aren't on the quick-cycle path because they're either
+     * destructive (`bypassPermissions`) or seldom-used.
+     *
+     * Mutates `config.permissionMode` directly so every existing read site
+     * (the `query()` call sites, `cronExecutor`, status hints) sees the new
+     * value without extra plumbing.
+     */
+    function cyclePermissionMode() {
+        const cycle = ["ask", "acceptEdits", "plan", "trust"];
+        const idx = cycle.indexOf(config.permissionMode);
+        const next = cycle[(idx === -1 ? 0 : idx + 1) % cycle.length];
+        config.permissionMode = next;
+        messages.push(createInfoMessage(`Permission mode → ${next}`));
+        syncRenderer();
+    }
     function navigateHistory(dir) {
         if (dir < 0 && historyIndex < inputHistory.length - 1) {
             historyIndex++;
@@ -1063,5 +1101,39 @@ export async function startREPL(config) {
     renderer.start();
     // Banner is already printed to stdout by main.tsx (visible in terminal scrollback)
     syncRenderer();
+    // Workspace-trust prompt (audit U-A4). Fires once per session when:
+    //   - the cwd isn't already on the trust list, AND
+    //   - `.oh/config.yaml` defines at least one shell-executing hook
+    //     (command/http) — `prompt` hooks don't trip the gate.
+    // Untrusted cwd silently skips command/http hooks via the gate in
+    // `harness/hooks.ts`. The prompt is non-blocking: we fire-and-forget
+    // the askQuestion so the REPL stays responsive while the question is
+    // displayed.
+    void (async () => {
+        try {
+            const { isTrusted, trust } = await import("./harness/trust.js");
+            if (isTrusted(process.cwd()))
+                return;
+            const cfgWithHooks = readOhConfig();
+            const hooks = cfgWithHooks?.hooks;
+            if (!hooks)
+                return;
+            const hasShellHook = Object.values(hooks).some((defs) => Array.isArray(defs) && defs.some((d) => d.command || d.http));
+            if (!hasShellHook)
+                return;
+            const answer = await renderer.askQuestion(`Trust this workspace? Shell hooks are configured in ${process.cwd()}. (yes/no)`);
+            if (answer.toLowerCase().startsWith("y")) {
+                trust(process.cwd());
+                messages.push(createInfoMessage(`Trusted ${process.cwd()} — shell hooks will now execute.`));
+            }
+            else {
+                messages.push(createInfoMessage(`Workspace not trusted — shell hooks are silently skipped. Run /trust to grant.`));
+            }
+            syncRenderer();
+        }
+        catch {
+            /* trust prompt is best-effort; never block the REPL */
+        }
+    })();
 }
 //# sourceMappingURL=repl.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.22.1",
+  "version": "2.23.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {