@zhijiewang/openharness 2.20.0 → 2.22.0

package/README.md

@@ -241,6 +241,7 @@ Over 80 commands are registered. The most-used ones are grouped below; see `/hel
 | `/memory` | View and search memories |
 | `/doctor` | Run diagnostic health checks |
 | `/hooks` | List loaded hooks grouped by event |
+| `/reload-plugins` | Hot-reload plugins, skills, hooks, and MCP server connections without restarting the session |
 
 **Settings:**
 | Command | Description |
@@ -298,7 +299,7 @@ hooks:
     command: "scripts/cleanup.sh"
 ```
 
-**Event types** (17 total):
+**Event types** (23 total):
 
 | Event | When it fires | Can block? |
 |-------|---------------|------------|
@@ -307,10 +308,13 @@ hooks:
 | `turnStart` | Top-level agent turn begins (after user prompt accepted) | — |
 | `turnStop` | Top-level agent turn ends (mirrors Claude Code's `Stop`) | — |
 | `userPromptSubmit` | Before user prompt reaches the LLM | yes — `decision: deny` |
+| `userPromptExpansion` | Slash command produces an expanded prompt (audit trail) | — |
 | `preToolUse` | Before each tool call | yes — exit code 1 / `decision: deny` |
 | `postToolUse` | After successful tool execution | — |
 | `postToolUseFailure` | After tool throws or returns `isError: true` | — |
+| `postToolBatch` | Once after a turn's full set of tool calls all resolve, before the next model call | — |
 | `permissionRequest` | When a tool needs approval (between `preToolUse` and the prompt) | yes — `decision: allow\|deny\|ask` |
+| `permissionDenied` | When a tool call is denied (hook / user / headless / policy) | — |
 | `fileChanged` | After a tool modifies a file | — |
 | `cwdChanged` | After working directory changes | — |
 | `subagentStart` | A sub-agent is spawned | — |
@@ -319,6 +323,9 @@ hooks:
 | `postCompact` | After conversation compaction | — |
 | `configChange` | `.oh/config.yaml` is modified during the session | — |
 | `notification` | A notification is dispatched | — |
+| `taskCreated` | `TaskCreate` persists a new task | — |
+| `taskCompleted` | `TaskUpdate` transitions a task to `completed` | — |
+| `instructionsLoaded` | `loadRulesAsPrompt` rebuilt the system prompt with rules in scope | — |
 
 Live introspection: run `/hooks` in-session to see exactly which hooks are loaded, grouped by event.
 
@@ -390,6 +397,15 @@ mcpServers:
 
 MCP tools appear alongside built-in tools. `/status` shows connected servers.
 
+**MCP server prompts as slash commands** — servers that expose `prompts/list` (e.g., GitHub, Sentry, Linear) get their prompts surfaced as `/<server>:<prompt>` slash commands automatically. Arguments use a `key=value` syntax with quoting:
+
+```
+/github:summarize-pr repo=acme/widget pr=42
+/sentry:triage-issue issue=ABC-123 severity="high priority"
+```
+
+Required arguments declared by the prompt template surface a usage error if missing (no model call). Run `/reload-plugins` to re-discover prompts after editing your MCP config.
+
 ### Remote MCP servers (HTTP / SSE)
 
 ```yaml
@@ -535,6 +551,10 @@ oh run "add error handling to api.ts" --json    # JSON output
 # Pipe stdin
 cat error.log | oh run "what's wrong here?"
 git diff | oh run "review these changes"
+
+# Hard cap on session cost — agent halts at the threshold with reason: "budget_exceeded"
+oh run "review the diff" --model claude-sonnet-4-6 --max-budget-usd 0.50
+oh session --model gpt-4o --max-budget-usd 5
 ```
 
 ### Structured output with `--json-schema`

package/README.zh-CN.md

@@ -241,6 +241,7 @@ OH 注册了 80+ 个斜杠命令；下表只列出最常用的一部分。在会
 | `/memory` | 查看并搜索记忆 |
 | `/doctor` | 运行诊断健康检查 |
 | `/hooks` | 按事件列出已加载的钩子 |
+| `/reload-plugins` | 不重启会话即可热重载插件、技能、钩子和 MCP 服务器连接 |
 
 **设置：**
 | 命令 | 描述 |
@@ -298,7 +299,7 @@ hooks:
     command: "scripts/cleanup.sh"
 ```
 
-**事件类型**（共 17 个）：
+**事件类型**（共 23 个）：
 
 | 事件 | 触发时机 | 是否可阻止 |
 |-------|---------------|------------|
@@ -307,10 +308,13 @@ hooks:
 | `turnStart` | 顶层代理回合开始（用户提示词被接受后） | — |
 | `turnStop` | 顶层代理回合结束（对应 Claude Code 的 `Stop`） | — |
 | `userPromptSubmit` | 用户提示词到达 LLM 之前 | 是 —— `decision: deny` |
+| `userPromptExpansion` | 斜杠命令展开成模型提示词时（用于审计追踪） | — |
 | `preToolUse` | 工具调用之前 | 是 —— 退出码 1 / `decision: deny` |
 | `postToolUse` | 工具成功执行之后 | — |
 | `postToolUseFailure` | 工具抛错或返回 `isError: true` | — |
+| `postToolBatch` | 一个回合内全部工具调用都完成后、下一次模型调用之前 | — |
 | `permissionRequest` | 工具需要授权时（`preToolUse` 与询问之间） | 是 —— `decision: allow\|deny\|ask` |
+| `permissionDenied` | 工具调用被拒绝时（钩子 / 用户 / 无头 / 策略） | — |
 | `fileChanged` | 工具修改文件之后 | — |
 | `cwdChanged` | 工作目录变更之后 | — |
 | `subagentStart` | 子代理被派生 | — |
@@ -319,6 +323,9 @@ hooks:
 | `postCompact` | 对话压缩之后 | — |
 | `configChange` | 会话过程中 `.oh/config.yaml` 被修改 | — |
 | `notification` | 通知被派发 | — |
+| `taskCreated` | `TaskCreate` 持久化新任务后 | — |
+| `taskCompleted` | `TaskUpdate` 将任务状态切换为 `completed` 时 | — |
+| `instructionsLoaded` | `loadRulesAsPrompt` 重新构建系统提示并加载规则之后 | — |
 
 实时查看：在会话中运行 `/hooks` 可以按事件分组查看当前已加载的钩子。
 
@@ -390,6 +397,15 @@ mcpServers:
 
 MCP 工具会与内置工具并列出现。`/status` 会显示已连接的服务器。
 
+**MCP 服务器提示词作为斜杠命令** —— 实现了 `prompts/list` 的服务器（如 GitHub、Sentry、Linear）会自动把它们的提示词暴露为 `/<server>:<prompt>` 斜杠命令。参数采用 `key=value` 语法，支持加引号：
+
+```
+/github:summarize-pr repo=acme/widget pr=42
+/sentry:triage-issue issue=ABC-123 severity="high priority"
+```
+
+提示词模板声明的 required 参数缺失时会直接报用法错误（不会调用模型）。修改 MCP 配置后运行 `/reload-plugins` 即可重新发现提示词。
+
 ### 远程 MCP 服务器（HTTP / SSE）
 
 ```yaml
@@ -535,6 +551,10 @@ oh run "add error handling to api.ts" --json    # JSON 输出
 # 通过 stdin 输入
 cat error.log | oh run "what's wrong here?"
 git diff | oh run "review these changes"
+
+# 会话总成本硬上限 —— 达到阈值时代理会以 reason: "budget_exceeded" 终止
+oh run "review the diff" --model claude-sonnet-4-6 --max-budget-usd 0.50
+oh session --model gpt-4o --max-budget-usd 5
 ```
 
 ### 使用 `--json-schema` 约束结构化输出

package/dist/commands/ai.js

@@ -232,6 +232,16 @@ export function registerAICommands(register) {
             prependToPrompt: `Summarize this conversation concisely. Highlight the main topics discussed, decisions made, and any pending action items. Be brief but thorough.`,
         };
     });
+    register("recap", "One-sentence recap of the current session (lighter than /summarize)", (_args, ctx) => {
+        if (ctx.messages.length === 0) {
+            return { output: "No messages to recap.", handled: true };
+        }
+        return {
+            output: `[recap] ${ctx.messages.length} messages`,
+            handled: false,
+            prependToPrompt: `In ONE sentence (max ~25 words), recap what this session has accomplished so far. No preamble, no bullet list, no markdown — just the sentence. Skip topics still in progress; lead with what's done.`,
+        };
+    });
     register("explain", "Explain a file or concept", (args) => {
         const topic = args.trim();
         if (!topic) {

package/dist/commands/session.d.ts

@@ -1,6 +1,23 @@
 /**
- * Session commands — /clear, /compact, /export, /history, /browse, /resume, /fork, /pin, /unpin
+ * Session commands — /clear, /compact, /copy, /export, /history, /browse, /resume, /fork, /pin, /unpin
  */
 import type { CommandHandler } from "./types.js";
+/**
+ * Copy text to the system clipboard. Picks a platform-specific external tool
+ * — `clip.exe` (Windows / WSL), `pbcopy` (macOS), then `wl-copy` then
+ * `xclip -selection clipboard` (Linux). The first one that exits 0 wins.
+ *
+ * Pure helper exported for tests; everything is synchronous so the slash
+ * command response can include success/failure inline.
+ *
+ * @internal
+ */
+export declare function copyToClipboard(text: string): {
+    ok: true;
+    tool: string;
+} | {
+    ok: false;
+    reason: string;
+};
 export declare function registerSessionCommands(register: (name: string, description: string, handler: CommandHandler) => void): void;
 //# sourceMappingURL=session.d.ts.map

package/dist/commands/session.js

@@ -1,12 +1,53 @@
 /**
- * Session commands — /clear, /compact, /export, /history, /browse, /resume, /fork, /pin, /unpin
+ * Session commands — /clear, /compact, /copy, /export, /history, /browse, /resume, /fork, /pin, /unpin
  */
+import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
+import { homedir, platform } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { getContextWindow } from "../harness/cost.js";
 import { createSession, listSessions, loadSession, saveSession } from "../harness/session.js";
 import { compressMessages } from "../query/index.js";
+/**
+ * Copy text to the system clipboard. Picks a platform-specific external tool
+ * — `clip.exe` (Windows / WSL), `pbcopy` (macOS), then `wl-copy` then
+ * `xclip -selection clipboard` (Linux). The first one that exits 0 wins.
+ *
+ * Pure helper exported for tests; everything is synchronous so the slash
+ * command response can include success/failure inline.
+ *
+ * @internal
+ */
+export function copyToClipboard(text) {
+    const candidates = platform() === "win32"
+        ? [{ cmd: "clip", args: [] }]
+        : platform() === "darwin"
+            ? [{ cmd: "pbcopy", args: [] }]
+            : [
+                { cmd: "wl-copy", args: [] },
+                { cmd: "xclip", args: ["-selection", "clipboard"] },
+                { cmd: "xsel", args: ["--clipboard", "--input"] },
+                // WSL / generic-Linux-with-clip.exe-on-PATH fallback
+                { cmd: "clip.exe", args: [] },
+            ];
+    for (const { cmd, args } of candidates) {
+        try {
+            const result = spawnSync(cmd, args, { input: text, encoding: "utf8", shell: false });
+            if (!result.error && result.status === 0) {
+                return { ok: true, tool: cmd };
+            }
+        }
+        catch {
+            /* try the next candidate */
+        }
+    }
+    return {
+        ok: false,
+        reason: platform() === "linux"
+            ? "no clipboard tool found — install one of: wl-copy, xclip, xsel"
+            : `no working clipboard tool found for ${platform()}`,
+    };
+}
 function formatMessagesAsMarkdown(messages) {
     const blocks = [];
     for (const m of messages) {
@@ -216,6 +257,45 @@ export function registerSessionCommands(register) {
             compactedMessages: kept,
         };
     });
+    register("copy", "Copy the Nth-last assistant response to the clipboard (default: most recent)", (args, ctx) => {
+        const raw = args.trim();
+        const n = raw ? parseInt(raw, 10) : 1;
+        if (raw && (Number.isNaN(n) || n < 1)) {
+            return {
+                output: `Usage: /copy [n]\n\nCopies the Nth-last assistant response (default: 1 = most recent).`,
+                handled: true,
+            };
+        }
+        // Walk messages newest-to-oldest, keeping only assistant messages with text.
+        // /export already filters out tool-result messages from rendering — same rule
+        // applies here: we want the model's reply text, not its tool plumbing.
+        const assistantMessages = ctx.messages
+            .filter((m) => m.role === "assistant" && typeof m.content === "string" && m.content.trim().length > 0)
+            .reverse();
+        if (assistantMessages.length === 0) {
+            return { output: "No assistant responses to copy yet.", handled: true };
+        }
+        if (n > assistantMessages.length) {
+            return {
+                output: `Only ${assistantMessages.length} assistant response(s) available; can't copy #${n}.`,
+                handled: true,
+            };
+        }
+        const target = assistantMessages[n - 1];
+        const text = target.content;
+        const result = copyToClipboard(text);
+        if (!result.ok) {
+            return {
+                output: `Could not copy to clipboard: ${result.reason}\n\nResponse text (${text.length} chars):\n${text}`,
+                handled: true,
+            };
+        }
+        const preview = text.length > 80 ? `${text.slice(0, 80)}…` : text;
+        return {
+            output: `Copied assistant response #${n} (${text.length} chars) via ${result.tool}: ${preview}`,
+            handled: true,
+        };
+    });
     register("search", "Search current conversation", (args, ctx) => {
         const term = args.trim().toLowerCase();
         if (!term) {

package/dist/commands/settings.d.ts

@@ -1,5 +1,5 @@
 /**
- * Settings commands — /theme, /companion, /fast, /keys, /effort, /sandbox, /permissions, /allowed-tools
+ * Settings commands — /theme, /companion, /fast, /keys, /keybindings, /effort, /sandbox, /permissions, /allowed-tools
  */
 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,8 +1,47 @@
 /**
- * Settings commands — /theme, /companion, /fast, /keys, /effort, /sandbox, /permissions, /allowed-tools
+ * Settings commands — /theme, /companion, /fast, /keys, /keybindings, /effort, /sandbox, /permissions, /allowed-tools
  */
+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 { readOhConfig } from "../harness/config.js";
 import { loadKeybindings } from "../harness/keybindings.js";
+const KEYBINDINGS_TEMPLATE = `[
+  { "key": "ctrl+d", "action": "/diff" },
+  { "key": "ctrl+l", "action": "/clear" },
+  { "key": "ctrl+u", "action": "/undo" },
+  { "key": "ctrl+s", "action": "/status" },
+  { "key": "ctrl+k ctrl+c", "action": "/cost" },
+  { "key": "ctrl+k ctrl+f", "action": "/fast" },
+  { "key": "ctrl+k ctrl+l", "action": "/log" }
+]
+`;
+/**
+ * Open a file in the user's editor — `$VISUAL` → `$EDITOR` → `notepad`
+ * (Windows) → `vi` (POSIX). The child uses `stdio: "ignore"` + `detached: true`
+ * + `unref()` so it is fully decoupled from the REPL and from `node --test`
+ * (which would otherwise hang waiting for the inherited stdio handle to
+ * close). The trade-off: terminal editors like `vi` / `vim` are not usable
+ * here — they need a TTY. That's fine for `/keybindings`, which targets a
+ * GUI-editor flow; an interactive in-REPL edit would be its own command.
+ */
+function openInEditor(filePath) {
+    const editor = process.env.VISUAL || process.env.EDITOR || (platform() === "win32" ? "notepad" : "vi");
+    if (process.env.OH_NO_OPEN_EDITOR === "1") {
+        // Test / CI escape hatch — pretend the editor launched without actually
+        // spawning anything. Used so suite runs don't pop a notepad window.
+        return { command: editor, spawned: true };
+    }
+    try {
+        const child = spawn(editor, [filePath], { stdio: "ignore", shell: true, detached: true });
+        child.unref();
+        return { command: editor, spawned: true };
+    }
+    catch {
+        return { command: editor, spawned: false };
+    }
+}
 export function registerSettingsCommands(register) {
     register("theme", "Switch theme (dark/light)", (args) => {
         const theme = args.trim().toLowerCase();
@@ -52,6 +91,37 @@ export function registerSettingsCommands(register) {
         shortcuts.push("", "  Session:", "    /vim              Toggle Vim mode", "    /browse           Interactive session browser", "    /theme dark|light Switch theme");
         return { output: shortcuts.join("\n"), handled: true };
     });
+    register("keybindings", "Open ~/.oh/keybindings.json in $EDITOR (creates a starter file if missing)", () => {
+        const path = join(homedir(), ".oh", "keybindings.json");
+        let createdNew = false;
+        if (!existsSync(path)) {
+            try {
+                mkdirSync(dirname(path), { recursive: true });
+                writeFileSync(path, KEYBINDINGS_TEMPLATE);
+                createdNew = true;
+            }
+            catch (err) {
+                return {
+                    output: `Could not create ${path}: ${err instanceof Error ? err.message : String(err)}`,
+                    handled: true,
+                };
+            }
+        }
+        const { command, spawned } = openInEditor(path);
+        if (!spawned) {
+            return {
+                output: `Could not launch ${command}. File path: ${path}\nSet $EDITOR or open it manually.`,
+                handled: true,
+            };
+        }
+        const lines = [
+            createdNew ? `Created starter file at ${path}` : `Opening ${path}`,
+            `Editor: ${command}`,
+            "",
+            "Edits take effect on the next session start. Reload now with /reload-plugins.",
+        ];
+        return { output: lines.join("\n"), handled: true };
+    });
     register("effort", "Set reasoning effort level (low/medium/high/max)", (args) => {
         const level = args.trim().toLowerCase();
         const valid = ["low", "medium", "high", "max"];

package/dist/harness/api-key-helper.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Run the configured `apiKeyHelper` script and return its trimmed stdout as
+ * the API key (audit B8). Mirrors Claude Code's `apiKeyHelper`.
+ *
+ * Invocation:
+ *   - shell: true (so `helper-script.sh` and pipelines work without an explicit shell)
+ *   - 5s timeout (helper should be fast — it's invoked at credential-fetch time)
+ *   - OH_PROVIDER env var set so a single helper can dispatch by provider
+ *   - stderr captured and surfaced on failure
+ *
+ * Failure modes — all return undefined (caller falls through to legacy config):
+ *   - non-zero exit code
+ *   - timeout
+ *   - empty stdout
+ *   - spawn error (helper not found, permission denied, etc.)
+ *
+ * Failures are logged via `debug("config", ...)` so users can opt into
+ * visibility with `--debug config` without polluting normal output.
+ */
+export interface RunApiKeyHelperOptions {
+    /** Provider name passed to the helper as `OH_PROVIDER`. */
+    provider: string;
+    /** Spawn timeout in ms. Defaults to 5_000. */
+    timeoutMs?: number;
+}
+/**
+ * Execute `command` via the user's shell with `OH_PROVIDER` set, return the
+ * trimmed stdout on success, undefined on any failure. Pure side-effect-only —
+ * no caching here; resolveApiKey owns lifetime.
+ */
+export declare function runApiKeyHelper(command: string, opts: RunApiKeyHelperOptions): string | undefined;
+//# sourceMappingURL=api-key-helper.d.ts.map

package/dist/harness/api-key-helper.js

@@ -0,0 +1,70 @@
+/**
+ * Run the configured `apiKeyHelper` script and return its trimmed stdout as
+ * the API key (audit B8). Mirrors Claude Code's `apiKeyHelper`.
+ *
+ * Invocation:
+ *   - shell: true (so `helper-script.sh` and pipelines work without an explicit shell)
+ *   - 5s timeout (helper should be fast — it's invoked at credential-fetch time)
+ *   - OH_PROVIDER env var set so a single helper can dispatch by provider
+ *   - stderr captured and surfaced on failure
+ *
+ * Failure modes — all return undefined (caller falls through to legacy config):
+ *   - non-zero exit code
+ *   - timeout
+ *   - empty stdout
+ *   - spawn error (helper not found, permission denied, etc.)
+ *
+ * Failures are logged via `debug("config", ...)` so users can opt into
+ * visibility with `--debug config` without polluting normal output.
+ */
+import { spawnSync } from "node:child_process";
+import { debug } from "../utils/debug.js";
+/**
+ * Execute `command` via the user's shell with `OH_PROVIDER` set, return the
+ * trimmed stdout on success, undefined on any failure. Pure side-effect-only —
+ * no caching here; resolveApiKey owns lifetime.
+ */
+export function runApiKeyHelper(command, opts) {
+    const timeout = opts.timeoutMs ?? 5_000;
+    try {
+        const result = spawnSync(command, {
+            shell: true,
+            timeout,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, OH_PROVIDER: opts.provider },
+            encoding: "utf8",
+        });
+        if (result.error) {
+            debug("config", "apiKeyHelper spawn failed", { provider: opts.provider, err: result.error.message });
+            return undefined;
+        }
+        if (result.signal === "SIGTERM") {
+            debug("config", "apiKeyHelper timed out", { provider: opts.provider, timeoutMs: timeout });
+            return undefined;
+        }
+        if (result.status !== 0) {
+            const stderr = (result.stderr ?? "").toString().trim().slice(0, 500);
+            debug("config", "apiKeyHelper non-zero exit", {
+                provider: opts.provider,
+                exit: result.status,
+                stderr,
+            });
+            return undefined;
+        }
+        const out = (result.stdout ?? "").toString().trim();
+        if (!out) {
+            debug("config", "apiKeyHelper produced empty stdout", { provider: opts.provider });
+            return undefined;
+        }
+        debug("config", "apiKeyHelper resolved", { provider: opts.provider, length: out.length });
+        return out;
+    }
+    catch (err) {
+        debug("config", "apiKeyHelper threw", {
+            provider: opts.provider,
+            err: err instanceof Error ? err.message : String(err),
+        });
+        return undefined;
+    }
+}
+//# sourceMappingURL=api-key-helper.js.map

package/dist/harness/config.d.ts

@@ -76,6 +76,23 @@ export type HooksConfig = {
     taskCreated?: HookDef[];
     /** Fires when a TaskUpdate tool call transitions a task to status "completed". */
     taskCompleted?: HookDef[];
+    /** Fires after EnterWorktreeTool successfully creates an isolated git worktree. */
+    worktreeCreate?: HookDef[];
+    /** Fires after ExitWorktreeTool successfully removes a git worktree. */
+    worktreeRemove?: HookDef[];
+    /**
+     * Fires when an MCP server issues an `elicitation/create` request — before
+     * any decision is made. Hook can return `permissionDecision: "allow"` to
+     * accept (sends `{action: "accept", content: {}}` to the server) or `"deny"`
+     * to decline. No decision falls through to the interactive handler (REPL)
+     * or, if absent, to a fail-safe `decline`.
+     */
+    elicitation?: HookDef[];
+    /**
+     * Fires after the elicitation response has been decided — symmetric to
+     * `elicitation`. Useful for audit trails that want the request/response pair.
+     */
+    elicitationResult?: HookDef[];
     /** Fires once per system-prompt build after CLAUDE.md / global-rules / project RULES.md / user profile have been concatenated. Useful for audit trails. */
     instructionsLoaded?: HookDef[];
 };
@@ -111,6 +128,27 @@ export type OhConfig = {
     baseUrl?: string;
     mcpServers?: McpServerConfig[];
     hooks?: HooksConfig;
+    /**
+     * Global kill switch for the hook system. When `true`, every `emitHook` /
+     * `emitHookAsync` / `emitHookWithOutcome` call short-circuits as if no
+     * hooks were configured — useful for one-off CI runs where the configured
+     * hooks would interfere. Configured hooks remain in `.oh/config.yaml` and
+     * are visible via `/hooks` so the off-state is auditable. Mirrors
+     * Claude Code's `disableAllHooks` setting.
+     */
+    disableAllHooks?: boolean;
+    /**
+     * Script invoked at credential-fetch time to produce an API key on stdout.
+     * Avoids storing keys in plaintext config or the encrypted store. Inserted
+     * between the encrypted-store and legacy-config steps in `resolveApiKey`.
+     * Mirrors Claude Code's `apiKeyHelper`.
+     *
+     * The configured command runs through the user's shell with a 5s timeout;
+     * stderr is captured and surfaced on failure. The provider name is passed
+     * via the `OH_PROVIDER` env var so a single helper can dispatch by provider
+     * (`if [ "$OH_PROVIDER" = "anthropic" ]; then ... fi`).
+     */
+    apiKeyHelper?: string;
     toolPermissions?: ToolPermissionRule[];
     statusLineFormat?: string;
     /** Verification loops — auto-run lint/typecheck after file edits */

package/dist/harness/credentials.d.ts

@@ -15,10 +15,12 @@ export declare function deleteCredential(key: string): void;
 /** List credential keys (not values) */
 export declare function listCredentials(): string[];
 /**
- * Get API key for a provider, checking:
- * 1. Environment variable (highest priority)
- * 2. Encrypted credential store
- * 3. Config file (legacy plaintext, with migration prompt)
+ * Get API key for a provider, checking in priority order:
+ *   1. Environment variable
+ *   2. Encrypted credential store
+ *   3. `apiKeyHelper` config script (audit B8) — runs the configured command
+ *      with `OH_PROVIDER` set; trimmed stdout is the key. Failures fall through.
+ *   4. Config file (legacy plaintext, with migration into the encrypted store)
  */
 export declare function resolveApiKey(provider: string, configApiKey?: string): string | undefined;
 //# sourceMappingURL=credentials.d.ts.map

package/dist/harness/credentials.js

@@ -10,6 +10,8 @@ import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname, userInfo } from "node:os";
 import { join } from "node:path";
+import { runApiKeyHelper } from "./api-key-helper.js";
+import { readOhConfig } from "./config.js";
 const CRED_DIR = join(homedir(), ".oh");
 const CRED_PATH = join(CRED_DIR, "credentials.enc");
 const ALGORITHM = "aes-256-gcm";
@@ -74,10 +76,12 @@ export function listCredentials() {
     return Object.keys(loadStore());
 }
 /**
- * Get API key for a provider, checking:
- * 1. Environment variable (highest priority)
- * 2. Encrypted credential store
- * 3. Config file (legacy plaintext, with migration prompt)
+ * Get API key for a provider, checking in priority order:
+ *   1. Environment variable
+ *   2. Encrypted credential store
+ *   3. `apiKeyHelper` config script (audit B8) — runs the configured command
+ *      with `OH_PROVIDER` set; trimmed stdout is the key. Failures fall through.
+ *   4. Config file (legacy plaintext, with migration into the encrypted store)
  */
 export function resolveApiKey(provider, configApiKey) {
     // Environment variable names by provider
@@ -93,6 +97,13 @@ export function resolveApiKey(provider, configApiKey) {
     const stored = getCredential(`${provider}-api-key`);
     if (stored)
         return stored;
+    // apiKeyHelper script — let users plug in 1Password / pass / vault / etc.
+    const cfg = readOhConfig();
+    if (cfg?.apiKeyHelper) {
+        const fromHelper = runApiKeyHelper(cfg.apiKeyHelper, { provider });
+        if (fromHelper)
+            return fromHelper;
+    }
     // Legacy config (migrate on use)
     if (configApiKey) {
         // Auto-migrate to encrypted store

package/dist/harness/hooks.d.ts

@@ -10,7 +10,7 @@
  * - prompt: LLM yes/no check via provider.complete()
  */
 import type { HookDef, HooksConfig } from "./config.js";
-export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse" | "postToolUseFailure" | "postToolBatch" | "userPromptSubmit" | "userPromptExpansion" | "permissionRequest" | "permissionDenied" | "fileChanged" | "cwdChanged" | "subagentStart" | "subagentStop" | "preCompact" | "postCompact" | "configChange" | "notification" | "turnStart" | "turnStop" | "taskCreated" | "taskCompleted" | "instructionsLoaded";
+export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse" | "postToolUseFailure" | "postToolBatch" | "userPromptSubmit" | "userPromptExpansion" | "permissionRequest" | "permissionDenied" | "fileChanged" | "cwdChanged" | "subagentStart" | "subagentStop" | "preCompact" | "postCompact" | "configChange" | "notification" | "turnStart" | "turnStop" | "taskCreated" | "taskCompleted" | "worktreeCreate" | "worktreeRemove" | "elicitation" | "elicitationResult" | "instructionsLoaded";
 export type HookContext = {
     toolName?: string;
     toolArgs?: string;
@@ -60,6 +60,22 @@ export type HookContext = {
     taskSubject?: string;
     /** For taskCompleted: the previous status before completion (usually "in_progress") */
     taskPreviousStatus?: string;
+    /** For worktreeCreate/worktreeRemove: absolute path to the worktree directory */
+    worktreePath?: string;
+    /** For worktreeCreate/worktreeRemove: the parent repo directory the worktree was forked from */
+    worktreeParent?: string;
+    /** For worktreeRemove: whether `force: true` was passed to skip the dirty-state check */
+    worktreeForced?: string;
+    /** For elicitation/elicitationResult: the MCP server that issued the elicitation request */
+    elicitationServer?: string;
+    /** For elicitation/elicitationResult: human-readable message the server wants to show (capped at 500 chars) */
+    elicitationMessage?: string;
+    /** For elicitation: JSON-stringified `requestedSchema` from the server (capped at 2000 chars) */
+    elicitationSchema?: string;
+    /** For elicitationResult: the final action ("accept" | "decline" | "cancel") */
+    elicitationAction?: string;
+    /** For elicitationResult: JSON-stringified content payload returned to the server (when action="accept") */
+    elicitationContent?: string;
     /** For instructionsLoaded: count of rules concatenated (as a string for env-var parity) */
     rulesCount?: string;
     /** For instructionsLoaded: total character length of the loaded rules */
@@ -68,6 +84,11 @@ export type HookContext = {
 export declare function getHooks(): HooksConfig | null;
 /** Clear hook cache (call after config changes) */
 export declare function invalidateHookCache(): void;
+/**
+ * Whether the configured `disableAllHooks` kill switch is set.
+ * Cached so the per-emit cost is a single boolean read.
+ */
+export declare function areHooksEnabled(): boolean;
 /**
  * Evaluate a hook matcher against the current tool name.
  *