@zhijiewang/openharness 2.18.0 → 2.20.0

package/README.md

@@ -32,8 +32,8 @@ AI coding agent in your terminal. Works with any LLM -- free local models or clo
 - [Quick Start](#quick-start)
 - [Why OpenHarness?](#why-openharness)
 - [Terminal UI](#terminal-ui)
-- [Tools (37)](#tools-37)
-- [Slash Commands (33)](#slash-commands-33)
+- [Tools (43)](#tools-43)
+- [Slash Commands](#slash-commands)
 - [Permission Modes](#permission-modes)
 - [Hooks](#hooks)
 - [Checkpoints & Rewind](#checkpoints--rewind)
@@ -61,6 +61,8 @@ That's it. OpenHarness auto-detects Ollama and starts chatting. No API key neede
 
 **Python SDK:** there's also an official Python SDK for driving `oh` from Python programs (notebooks, batch scripts, ML pipelines). Install with `pip install openharness-sdk` after the npm install (the PyPI distribution is `openharness-sdk` because the unqualified name is taken), then `from openharness import query`. See [`python/README.md`](python/README.md).
 
+**TypeScript SDK:** drive `oh` from Node.js (VS Code extensions, Electron apps, build scripts) with `@zhijiewang/openharness-sdk` — `npm install @zhijiewang/openharness-sdk`, then `import { query, OpenHarnessClient, tool } from "@zhijiewang/openharness-sdk"`. Mirrors the Python SDK surface (streaming events, stateful sessions, custom tools, permission callback, session resume). See [`packages/sdk/README.md`](packages/sdk/README.md).
+
 ```bash
 oh init                               # interactive setup wizard (provider + cybergotchi)
 oh                                    # auto-detect local model
@@ -142,12 +144,13 @@ statusLineFormat: '{model} │ {tokens} │ {cost} │ {ctx}'
 
 Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XXXX), `{ctx}` (context usage bar). Empty sections are automatically collapsed.
 
-## Tools (37)
+## Tools (43)
 
 | Tool | Risk | Description |
 |------|------|-------------|
 | **Core** | | |
 | Bash | high | Execute shell commands with live streaming output (AST safety analysis) |
+| PowerShell | high | Execute PowerShell commands (Windows-native scripting) |
 | Read | low | Read files with line ranges, PDF support |
 | ImageRead | low | Read images/PDFs for multimodal analysis |
 | Write | medium | Create or overwrite files |
@@ -167,6 +170,7 @@ Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XX
 | TaskGet | low | Get task details |
 | TaskStop | low | Stop a running task |
 | TaskOutput | low | Get task output |
+| TodoWrite | low | Manage session task checklist (Claude Code-compatible) |
 | **Agents** | | |
 | Agent | medium | Spawn a sub-agent (with role specialization) |
 | ParallelAgent | medium | Dispatch multiple agents with DAG dependencies |
@@ -176,9 +180,12 @@ Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XX
 | CronCreate | medium | Schedule recurring tasks |
 | CronDelete | medium | Remove scheduled tasks |
 | CronList | low | List all scheduled tasks |
+| ScheduleWakeup | low | Self-pace the next /loop iteration (cache-aware) |
 | **Planning** | | |
 | EnterPlanMode | low | Enter structured planning mode |
 | ExitPlanMode | low | Exit planning mode |
+| **Pipelines** | | |
+| Pipeline | medium | Run a sequence of tasks with output passed between steps |
 | **Code Intelligence** | | |
 | Diagnostics | low | LSP-based code diagnostics |
 | NotebookEdit | medium | Edit Jupyter notebooks |
@@ -186,6 +193,7 @@ Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XX
 | Memory | low | Save/list/search persistent memories |
 | Skill | low | Invoke a skill from .oh/skills/ |
 | ToolSearch | low | Find tools by description |
+| SessionSearch | low | Search prior sessions for relevant context |
 | **MCP** | | |
 | ListMcpResources | low | List resources from connected MCP servers |
 | ReadMcpResource | low | Read a specific MCP resource by URI |
@@ -194,12 +202,13 @@ Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XX
 | ExitWorktree | medium | Remove a git worktree |
 | **Process** | | |
 | KillProcess | high | Stop processes by PID or name |
+| Monitor | medium | Run a background command and stream each output line back to the agent |
 
 Low-risk read-only tools auto-approve. Medium and high risk tools require confirmation in `ask` mode. Use `--trust` or `--auto` to skip prompts.
 
-## Slash Commands (33)
+## Slash Commands
 
-Type these during a chat session. Aliases: `/q` exit, `/h` help, `/c` commit, `/m` model, `/s` status.
+Over 80 commands are registered. The most-used ones are grouped below; see `/help` in-session for the full list. Aliases: `/q` exit, `/h` help, `/c` commit, `/m` model, `/s` status.
 
 **Session:**
 | Command | Description |
@@ -289,11 +298,29 @@ hooks:
     command: "scripts/cleanup.sh"
 ```
 
-**Event types:**
-- `sessionStart` — fires once when the session begins
-- `preToolUse` — fires before each tool call; **exit code 1 blocks the tool** and returns an error to the model
-- `postToolUse` — fires after each tool call completes
-- `sessionEnd` — fires when the session ends
+**Event types** (17 total):
+
+| Event | When it fires | Can block? |
+|-------|---------------|------------|
+| `sessionStart` | Session begins | — |
+| `sessionEnd` | Session ends | — |
+| `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` |
+| `preToolUse` | Before each tool call | yes — exit code 1 / `decision: deny` |
+| `postToolUse` | After successful tool execution | — |
+| `postToolUseFailure` | After tool throws or returns `isError: true` | — |
+| `permissionRequest` | When a tool needs approval (between `preToolUse` and the prompt) | yes — `decision: allow\|deny\|ask` |
+| `fileChanged` | After a tool modifies a file | — |
+| `cwdChanged` | After working directory changes | — |
+| `subagentStart` | A sub-agent is spawned | — |
+| `subagentStop` | A sub-agent completes | — |
+| `preCompact` | Before conversation compaction | — |
+| `postCompact` | After conversation compaction | — |
+| `configChange` | `.oh/config.yaml` is modified during the session | — |
+| `notification` | A notification is dispatched | — |
+
+Live introspection: run `/hooks` in-session to see exactly which hooks are loaded, grouped by event.
 
 **Environment variables** available to hook scripts:
 
@@ -303,10 +330,16 @@ hooks:
 | `OH_TOOL_NAME` | Name of the tool being called (tool events only) |
 | `OH_TOOL_ARGS` | JSON-encoded tool arguments (tool events only) |
 | `OH_TOOL_OUTPUT` | JSON-encoded tool output (`postToolUse` only) |
+| `OH_TOOL_INPUT_JSON` | Full JSON tool input (tool events only) |
+| `OH_SESSION_ID` / `OH_MODEL` / `OH_PROVIDER` / `OH_PERMISSION_MODE` | Current session context |
+| `OH_COST` / `OH_TOKENS` | Running cost and token totals |
+| `OH_FILE_PATH` | Path that changed (`fileChanged` only) |
+| `OH_NEW_CWD` | New working directory (`cwdChanged` only) |
+| `OH_TURN_NUMBER` / `OH_TURN_REASON` | Turn boundary context (`turnStart` / `turnStop`) |
 
-Use `match` to restrict a hook to a specific tool name (e.g., `match: Bash` only triggers for the Bash tool).
+Use `match` to restrict a hook to a specific tool name (e.g., `match: Bash` only triggers for the Bash tool). Substring, glob (`Cron*`), and `/regex/flags` patterns are all supported.
 
-See [docs/hooks.md](docs/hooks.md) for the full event reference including the new `userPromptSubmit`, `permissionRequest`, and `postToolUseFailure` events.
+Set `jsonIO: true` on a `command` hook to opt into structured JSON I/O — the harness sends `{event, ...context}` on stdin and reads `{decision, reason, hookSpecificOutput}` from stdout. HTTP hooks accept the same response shape. See [docs/hooks.md](docs/hooks.md) for the full reference.
 
 ## Cybergotchi
 

package/README.zh-CN.md

@@ -32,8 +32,8 @@
 - [快速开始](#快速开始)
 - [为什么选择 OpenHarness？](#为什么选择-openharness)
 - [终端界面](#终端界面)
-- [工具（37 个）](#工具37-个)
-- [斜杠命令（33 个）](#斜杠命令33-个)
+- [工具（43 个）](#工具43-个)
+- [斜杠命令](#斜杠命令)
 - [权限模式](#权限模式)
 - [钩子](#钩子)
 - [检查点与回滚](#检查点与回滚)
@@ -61,6 +61,8 @@ oh
 
 **Python SDK：** 我们还提供了官方的 Python SDK，可以在 Python 程序中驱动 `oh`（笔记本、批处理脚本、ML 流水线）。在 npm 安装之后，使用 `pip install openharness-sdk` 安装（PyPI 分发名为 `openharness-sdk`，因为未加后缀的名称已被占用），然后 `from openharness import query`。详见 [`python/README.md`](python/README.md)。
 
+**TypeScript SDK：** 同样有官方的 TypeScript SDK，可以在 Node.js（VS Code 插件、Electron 应用、构建脚本等）中驱动 `oh`：使用 `@zhijiewang/openharness-sdk` —— 通过 `npm install @zhijiewang/openharness-sdk` 安装，然后 `import { query, OpenHarnessClient, tool } from "@zhijiewang/openharness-sdk"`。功能与 Python SDK 对等（流式事件、有状态会话、自定义工具、权限回调、会话恢复）。详见 [`packages/sdk/README.md`](packages/sdk/README.md)。
+
 ```bash
 oh init                               # 交互式安装向导（模型提供商 + 电子宠物）
 oh                                    # 自动检测本地模型
@@ -142,12 +144,13 @@ statusLineFormat: '{model} │ {tokens} │ {cost} │ {ctx}'
 
 可用变量：`{model}`、`{tokens}`（输入↑ 输出↓）、`{cost}`（$X.XXXX）、`{ctx}`（上下文占用条）。空片段会自动折叠。
 
-## 工具（37 个）
+## 工具（43 个）
 
 | 工具 | 风险 | 描述 |
 |------|------|-------------|
 | **核心** | | |
 | Bash | 高 | 执行 shell 命令并实时流式输出（AST 安全分析） |
+| PowerShell | 高 | 执行 PowerShell 命令（Windows 原生脚本） |
 | Read | 低 | 按行范围读取文件，支持 PDF |
 | ImageRead | 低 | 读取图片/PDF 以进行多模态分析 |
 | Write | 中 | 创建或覆盖文件 |
@@ -167,6 +170,7 @@ statusLineFormat: '{model} │ {tokens} │ {cost} │ {ctx}'
 | TaskGet | 低 | 获取任务详情 |
 | TaskStop | 低 | 停止正在运行的任务 |
 | TaskOutput | 低 | 获取任务输出 |
+| TodoWrite | 低 | 管理会话级 todo 列表（兼容 Claude Code） |
 | **代理** | | |
 | Agent | 中 | 派生一个子代理（可指定角色） |
 | ParallelAgent | 中 | 派发多个代理并支持 DAG 依赖 |
@@ -176,9 +180,12 @@ statusLineFormat: '{model} │ {tokens} │ {cost} │ {ctx}'
 | CronCreate | 中 | 创建定时任务 |
 | CronDelete | 中 | 删除定时任务 |
 | CronList | 低 | 列出所有定时任务 |
+| ScheduleWakeup | 低 | 在 /loop 中自适应安排下一次触发（缓存感知） |
 | **规划** | | |
 | EnterPlanMode | 低 | 进入结构化规划模式 |
 | ExitPlanMode | 低 | 退出规划模式 |
+| **流水线** | | |
+| Pipeline | 中 | 顺序执行一连串子任务，把每一步的输出作为下一步的输入 |
 | **代码智能** | | |
 | Diagnostics | 低 | 基于 LSP 的代码诊断 |
 | NotebookEdit | 中 | 编辑 Jupyter notebook |
@@ -186,6 +193,7 @@ statusLineFormat: '{model} │ {tokens} │ {cost} │ {ctx}'
 | Memory | 低 | 保存/列出/搜索持久化记忆 |
 | Skill | 低 | 调用 .oh/skills/ 下的技能 |
 | ToolSearch | 低 | 按描述查找工具 |
+| SessionSearch | 低 | 在历史会话中搜索相关上下文 |
 | **MCP** | | |
 | ListMcpResources | 低 | 列出已连接 MCP 服务器上的资源 |
 | ReadMcpResource | 低 | 按 URI 读取指定的 MCP 资源 |
@@ -194,12 +202,13 @@ statusLineFormat: '{model} │ {tokens} │ {cost} │ {ctx}'
 | ExitWorktree | 中 | 移除一个 git worktree |
 | **进程** | | |
 | KillProcess | 高 | 按 PID 或名称停止进程 |
+| Monitor | 中 | 在后台运行命令，并把每一行输出实时反馈给代理 |
 
 低风险只读工具会自动批准。在 `ask` 模式下，中高风险工具需要确认。使用 `--trust` 或 `--auto` 可跳过提示。
 
-## 斜杠命令（33 个）
+## 斜杠命令
 
-在对话中输入这些命令。别名：`/q` 退出、`/h` 帮助、`/c` 提交、`/m` 模型、`/s` 状态。
+OH 注册了 80+ 个斜杠命令；下表只列出最常用的一部分。在会话中运行 `/help` 可以看到完整列表。别名：`/q` 退出、`/h` 帮助、`/c` 提交、`/m` 模型、`/s` 状态。
 
 **会话：**
 | 命令 | 描述 |
@@ -289,11 +298,29 @@ hooks:
     command: "scripts/cleanup.sh"
 ```
 
-**事件类型：**
-- `sessionStart` —— 会话开始时触发一次
-- `preToolUse` —— 每次工具调用前触发；**退出码 1 会阻止该工具**并向模型返回错误
-- `postToolUse` —— 每次工具调用完成后触发
-- `sessionEnd` —— 会话结束时触发
+**事件类型**（共 17 个）：
+
+| 事件 | 触发时机 | 是否可阻止 |
+|-------|---------------|------------|
+| `sessionStart` | 会话开始 | — |
+| `sessionEnd` | 会话结束 | — |
+| `turnStart` | 顶层代理回合开始（用户提示词被接受后） | — |
+| `turnStop` | 顶层代理回合结束（对应 Claude Code 的 `Stop`） | — |
+| `userPromptSubmit` | 用户提示词到达 LLM 之前 | 是 —— `decision: deny` |
+| `preToolUse` | 工具调用之前 | 是 —— 退出码 1 / `decision: deny` |
+| `postToolUse` | 工具成功执行之后 | — |
+| `postToolUseFailure` | 工具抛错或返回 `isError: true` | — |
+| `permissionRequest` | 工具需要授权时（`preToolUse` 与询问之间） | 是 —— `decision: allow\|deny\|ask` |
+| `fileChanged` | 工具修改文件之后 | — |
+| `cwdChanged` | 工作目录变更之后 | — |
+| `subagentStart` | 子代理被派生 | — |
+| `subagentStop` | 子代理完成 | — |
+| `preCompact` | 对话压缩之前 | — |
+| `postCompact` | 对话压缩之后 | — |
+| `configChange` | 会话过程中 `.oh/config.yaml` 被修改 | — |
+| `notification` | 通知被派发 | — |
+
+实时查看：在会话中运行 `/hooks` 可以按事件分组查看当前已加载的钩子。
 
 **环境变量**（钩子脚本可用）：
 
@@ -303,10 +330,16 @@ hooks:
 | `OH_TOOL_NAME` | 正在调用的工具名（仅工具类事件） |
 | `OH_TOOL_ARGS` | JSON 编码的工具参数（仅工具类事件） |
 | `OH_TOOL_OUTPUT` | JSON 编码的工具输出（仅 `postToolUse`） |
+| `OH_TOOL_INPUT_JSON` | 完整的 JSON 工具输入（仅工具类事件） |
+| `OH_SESSION_ID` / `OH_MODEL` / `OH_PROVIDER` / `OH_PERMISSION_MODE` | 当前会话上下文 |
+| `OH_COST` / `OH_TOKENS` | 累计费用与 token 数 |
+| `OH_FILE_PATH` | 变更的文件路径（仅 `fileChanged`） |
+| `OH_NEW_CWD` | 新的工作目录（仅 `cwdChanged`） |
+| `OH_TURN_NUMBER` / `OH_TURN_REASON` | 回合边界上下文（`turnStart` / `turnStop`） |
 
-使用 `match` 将钩子限定到特定工具名（例如 `match: Bash` 仅对 Bash 工具触发）。
+使用 `match` 将钩子限定到特定工具名（例如 `match: Bash` 仅对 Bash 工具触发）。支持子串、glob（如 `Cron*`）和 `/regex/flags` 三种匹配方式。
 
-完整事件参考（包括新增的 `userPromptSubmit`、`permissionRequest`、`postToolUseFailure` 事件）见 [docs/hooks.md](docs/hooks.md)。
+将 `command` 钩子设置 `jsonIO: true` 即可启用结构化 JSON I/O —— 框架在 stdin 上发送 `{event, ...context}`，并从 stdout 读取 `{decision, reason, hookSpecificOutput}`。HTTP 钩子接受同样的响应格式。完整参考见 [docs/hooks.md](docs/hooks.md)。
 
 ## 电子宠物 Cybergotchi
 

package/dist/commands/index.d.ts

@@ -26,4 +26,27 @@ export declare function getCommandEntries(): Array<{
     name: string;
     description: string;
 }>;
+/**
+ * Register MCP-server prompts as `/server:prompt` slash commands. Called from
+ * main.tsx after `loadMcpTools()` + `loadMcpPrompts()` so the connections are
+ * warm. Each handler invokes the prompt's `render()` and returns the result
+ * as a `prependToPrompt` so the next user prompt carries it as context.
+ *
+ * Argument syntax: `/server:prompt key=value key2=value2 ...`. Quoted values
+ * (`key="value with spaces"`) are supported. Args declared as `required` on
+ * the prompt template that aren't supplied surface as a usage error.
+ *
+ * Re-registering replaces any prior MCP prompt commands — safe to call again
+ * after `/reload-plugins` triggers a re-discover.
+ */
+import type { McpPromptHandle } from "../mcp/loader.js";
+export declare function registerMcpPromptCommands(prompts: readonly McpPromptHandle[]): void;
+/**
+ * Parse `key=value key2="value with spaces"` style args into a map. Bare
+ * tokens (no `=`) are dropped — MCP prompt arguments are always named.
+ * Exposed for tests.
+ *
+ * @internal
+ */
+export declare function parseMcpPromptArgs(raw: string): Record<string, string>;
 //# sourceMappingURL=index.d.ts.map

package/dist/commands/index.js

@@ -67,4 +67,68 @@ export function getCommandNames() {
 export function getCommandEntries() {
     return [...commands.entries()].map(([name, { description }]) => ({ name, description }));
 }
+let mcpPromptKeys = [];
+export function registerMcpPromptCommands(prompts) {
+    for (const key of mcpPromptKeys)
+        commands.delete(key);
+    mcpPromptKeys = [];
+    for (const handle of prompts) {
+        const key = handle.qualifiedName.toLowerCase();
+        const required = (handle.arguments ?? []).filter((a) => a.required).map((a) => a.name);
+        const optional = (handle.arguments ?? []).filter((a) => !a.required).map((a) => a.name);
+        const usageBits = [...required.map((n) => `${n}=<value>`), ...optional.map((n) => `[${n}=<value>]`)].join(" ");
+        commands.set(key, {
+            description: handle.description,
+            handler: async (args) => {
+                const parsed = parseMcpPromptArgs(args);
+                const missing = required.filter((n) => !(n in parsed));
+                if (missing.length > 0) {
+                    return {
+                        output: `/${handle.qualifiedName}: missing required argument(s): ${missing.join(", ")}\nUsage: /${handle.qualifiedName}${usageBits ? ` ${usageBits}` : ""}`,
+                        handled: true,
+                    };
+                }
+                try {
+                    const rendered = await handle.render(parsed);
+                    if (!rendered.trim()) {
+                        return { output: `/${handle.qualifiedName} returned an empty prompt.`, handled: true };
+                    }
+                    return {
+                        output: `[mcp-prompt] ${handle.qualifiedName}`,
+                        handled: false,
+                        prependToPrompt: rendered,
+                    };
+                }
+                catch (err) {
+                    return {
+                        output: `/${handle.qualifiedName} failed: ${err instanceof Error ? err.message : String(err)}`,
+                        handled: true,
+                    };
+                }
+            },
+        });
+        mcpPromptKeys.push(key);
+    }
+}
+/**
+ * Parse `key=value key2="value with spaces"` style args into a map. Bare
+ * tokens (no `=`) are dropped — MCP prompt arguments are always named.
+ * Exposed for tests.
+ *
+ * @internal
+ */
+export function parseMcpPromptArgs(raw) {
+    const out = {};
+    if (!raw.trim())
+        return out;
+    // Match key=value or key="value with spaces" or key='value'
+    const re = /(\w[\w.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+))/g;
+    let m;
+    while ((m = re.exec(raw)) !== null) {
+        const key = m[1];
+        const value = m[2] ?? m[3] ?? m[4] ?? "";
+        out[key] = value;
+    }
+    return out;
+}
 //# sourceMappingURL=index.js.map

package/dist/commands/info.js

@@ -5,12 +5,15 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { gitBranch, isGitRepo, isInMergeOrRebase } from "../git/index.js";
-import { readOhConfig } from "../harness/config.js";
+import { invalidateConfigCache, readOhConfig } from "../harness/config.js";
 import { estimateMessageTokens } from "../harness/context-warning.js";
 import { getContextWindow } from "../harness/cost.js";
-import { getHooks } from "../harness/hooks.js";
+import { getHooks, invalidateHookCache } from "../harness/hooks.js";
+import { discoverPlugins, discoverSkills } from "../harness/plugins.js";
+import { invalidateSandboxCache } from "../harness/sandbox.js";
+import { invalidateVerificationCache } from "../harness/verification.js";
 import { normalizeMcpConfig } from "../mcp/config-normalize.js";
-import { connectedMcpServers } from "../mcp/loader.js";
+import { connectedMcpServers, disconnectMcpClients, loadMcpTools } from "../mcp/loader.js";
 import { getAuthStatus } from "../mcp/oauth.js";
 import { getRouteSelection } from "../providers/router.js";
 import { formatHooksReport } from "./hooks-report.js";
@@ -721,6 +724,46 @@ export function registerInfoCommands(register, getCommandMap) {
         }
         return { output: lines.join("\n"), handled: true };
     });
+    register("reload-plugins", "Hot-reload plugins, skills, hooks, MCP servers and config without restarting the session.", async () => {
+        // Invalidate every cached source — config, hooks, sandbox, verification.
+        // Skills + plugins aren't cached (each discoverSkills/discoverPlugins call
+        // reads fresh) but we still re-run them for the report so the user sees
+        // a count consistent with the new on-disk state.
+        invalidateConfigCache();
+        invalidateHookCache();
+        invalidateSandboxCache();
+        invalidateVerificationCache();
+        // Tear down + reconnect MCP servers (the live connections aren't
+        // cache-driven; they're long-lived sockets that need an explicit
+        // disconnect/reconnect). Failures don't block the reload — partial
+        // success is more useful than nothing.
+        disconnectMcpClients();
+        let mcpTools = 0;
+        let mcpError = null;
+        try {
+            const tools = await loadMcpTools();
+            mcpTools = tools.length;
+        }
+        catch (err) {
+            mcpError = err instanceof Error ? err.message : String(err);
+        }
+        const skillsCount = discoverSkills().length;
+        const pluginsCount = discoverPlugins().length;
+        const hookEvents = Object.keys(getHooks() ?? {}).length;
+        const mcpServers = connectedMcpServers().length;
+        const lines = [
+            "Hot reload complete:",
+            "  - config + hooks + sandbox + verification: caches invalidated",
+            `  - hook events configured:       ${hookEvents}`,
+            `  - MCP servers connected:        ${mcpServers}${mcpError ? ` (error: ${mcpError})` : ""}`,
+            `  - MCP tools loaded:             ${mcpTools}`,
+            `  - skills discovered:            ${skillsCount}`,
+            `  - plugins discovered:           ${pluginsCount}`,
+            "",
+            "Note: in-flight tool registries (held by the agent loop) refresh on the next prompt.",
+        ];
+        return { output: lines.join("\n"), handled: true };
+    });
     register("benchmark", "Run SWE-bench benchmark suite", (args) => {
         const task = args.trim();
         if (!task) {

package/dist/harness/config.d.ts

@@ -66,6 +66,18 @@ export type HooksConfig = {
     turnStart?: HookDef[];
     /** Fires at the end of each top-level agent turn (after the model either completes or errors). Matches Claude Code's Stop hook. */
     turnStop?: HookDef[];
+    /** Fires after a slash command expands into a model prompt (`prependToPrompt`), between expansion and userPromptSubmit. Useful for audit trails. */
+    userPromptExpansion?: HookDef[];
+    /** Fires after a turn's full set of tool calls have all resolved, before the next model call. Sees the batch as a whole; postToolUse fires per-tool. */
+    postToolBatch?: HookDef[];
+    /** Fires when a tool call is denied (auto-mode policy block, hook-driven deny, headless fail-closed, or user "no"). Symmetric to permissionRequest. */
+    permissionDenied?: HookDef[];
+    /** Fires when a TaskCreate tool call has just persisted a new task. */
+    taskCreated?: HookDef[];
+    /** Fires when a TaskUpdate tool call transitions a task to status "completed". */
+    taskCompleted?: 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[];
 };
 export type ToolPermissionRule = {
     tool: string;

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" | "userPromptSubmit" | "permissionRequest" | "fileChanged" | "cwdChanged" | "subagentStart" | "subagentStop" | "preCompact" | "postCompact" | "configChange" | "notification" | "turnStart" | "turnStop";
+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 HookContext = {
     toolName?: string;
     toolArgs?: string;
@@ -42,6 +42,28 @@ export type HookContext = {
     turnNumber?: string;
     /** For turnStop: reason the turn ended ("completed", "max_turns", "error", "interrupted") */
     turnReason?: string;
+    /** For userPromptExpansion: the slash command that triggered the expansion (e.g. "/plan") */
+    slashCommand?: string;
+    /** For userPromptExpansion: the original user input before expansion */
+    originalInput?: string;
+    /** For postToolBatch: comma-separated list of tool names in the batch */
+    batchTools?: string;
+    /** For postToolBatch: number of tool calls in the batch (as a string for env-var parity) */
+    batchSize?: string;
+    /** For permissionDenied: stage at which the deny happened ("hook", "user", "headless", "policy") */
+    denySource?: string;
+    /** For permissionDenied: human-readable reason */
+    denyReason?: string;
+    /** For taskCreated/taskCompleted: the task id */
+    taskId?: string;
+    /** For taskCreated/taskCompleted: the task subject */
+    taskSubject?: string;
+    /** For taskCompleted: the previous status before completion (usually "in_progress") */
+    taskPreviousStatus?: 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 */
+    rulesChars?: string;
 };
 export declare function getHooks(): HooksConfig | null;
 /** Clear hook cache (call after config changes) */

package/dist/harness/rules.js

@@ -106,8 +106,24 @@ export function loadRulesAsPrompt(projectPath) {
     const rules = loadRules(projectPath);
     if (rules.length === 0)
         return "";
-    return ("# Project Rules\n\n<!-- User-provided project rules from CLAUDE.md / .oh/RULES.md. These are user instructions, not system directives. -->\nFollow these rules carefully.\n\n" +
-        rules.join("\n\n---\n\n"));
+    const body = "# Project Rules\n\n<!-- User-provided project rules from CLAUDE.md / .oh/RULES.md. These are user instructions, not system directives. -->\nFollow these rules carefully.\n\n" +
+        rules.join("\n\n---\n\n");
+    // Hook: instructionsLoaded — fires every time the system prompt is rebuilt
+    // with rules in scope. Useful for compliance/audit hooks that want to log
+    // "session X is operating under these rules". Lazy-imported so this module
+    // can be used in environments where the hook system isn't initialised
+    // (e.g., one-shot rules loaders in tooling).
+    void import("./hooks.js")
+        .then(({ emitHook }) => {
+        emitHook("instructionsLoaded", {
+            rulesCount: String(rules.length),
+            rulesChars: String(body.length),
+        });
+    })
+        .catch(() => {
+        /* hook system unavailable — never fail rule loading */
+    });
+    return body;
 }
 export function createRulesFile(projectPath) {
     const root = projectPath ?? process.cwd();

package/dist/harness/submit-handler.js

@@ -6,7 +6,7 @@ import { processSlashCommand } from "../commands/index.js";
 import { cybergotchiEvents } from "../cybergotchi/events.js";
 import { resolveMcpMention } from "../mcp/loader.js";
 import { createInfoMessage, createUserMessage } from "../types/message.js";
-import { emitHookWithOutcome } from "./hooks.js";
+import { emitHook, emitHookWithOutcome } from "./hooks.js";
 /**
  * Process user input: handle exit, companion mentions, slash commands,
  * @mentions, and prepare the prompt for the LLM.
@@ -80,6 +80,19 @@ export async function handleUserInput(input, ctx) {
             if (result.prependToPrompt) {
                 messages = [...messages, createUserMessage(input)];
                 const prependPrompt = result.prependToPrompt;
+                // Slash command produced an expanded prompt — fire userPromptExpansion
+                // before userPromptSubmit so audit hooks can see the (input → expanded)
+                // boundary that's otherwise hidden from observers.
+                const slashCommand = trimmed.split(/\s/)[0] ?? trimmed;
+                emitHook("userPromptExpansion", {
+                    slashCommand,
+                    originalInput: input.slice(0, 1000),
+                    prompt: prependPrompt.slice(0, 1000),
+                    sessionId: ctx.sessionId,
+                    model: ctx.currentModel,
+                    provider: ctx.providerName,
+                    permissionMode: ctx.permissionMode,
+                });
                 const prependOutcome = await emitHookWithOutcome("userPromptSubmit", {
                     prompt: prependPrompt,
                     sessionId: ctx.sessionId,

package/dist/main.js

@@ -23,10 +23,11 @@ import { detectProject, projectContextToPrompt } from "./harness/onboarding.js";
 import { discoverSkills, skillsToPrompt } from "./harness/plugins.js";
 import { createRulesFile, loadRules, loadRulesAsPrompt } from "./harness/rules.js";
 import { listSessions } from "./harness/session.js";
-import { connectedMcpServers, disconnectMcpClients, getMcpInstructions, loadMcpTools } from "./mcp/loader.js";
+import { connectedMcpServers, disconnectMcpClients, getMcpInstructions, loadMcpPrompts, loadMcpTools, } from "./mcp/loader.js";
 import { loadOutputStyle } from "./outputStyles/index.js";
 import { getAllTools } from "./tools.js";
 import { validateAgainstJsonSchema } from "./utils/json-schema.js";
+import { parseMaxBudgetUsd } from "./utils/parse-budget.js";
 const _require = createRequire(import.meta.url);
 const VERSION = _require("../package.json").version;
 const BANNER = `        ___
@@ -74,6 +75,20 @@ You have access to tools for reading, writing, and searching files, running shel
 - When referencing code, include file_path:line_number.
 - Do not restate what the user said. Do not add trailing summaries unless asked.
 - Keep responses short and direct. If you can say it in one sentence, don't use three.`;
+/**
+ * Parse the `--max-budget-usd` CLI argument into a positive USD amount, or
+ * exit 2 with an error message. The pure parser lives in
+ * `src/utils/parse-budget.ts` so it can be unit-tested without spawning the
+ * CLI; this thin wrapper handles the exit-on-failure side effect.
+ */
+function parseMaxBudgetUsdOrExit(raw) {
+    const result = parseMaxBudgetUsd(raw);
+    if (!result.ok) {
+        process.stderr.write(`Error: ${result.message}\n`);
+        process.exit(2);
+    }
+    return result.value;
+}
 function buildSystemPrompt(model) {
     const cfg = readOhConfig();
     // Output-style preface (first — sets personality for everything that follows).
@@ -136,6 +151,7 @@ program
     .option("--disallowed-tools <tools>", "Comma-separated list of disallowed tools")
     .option("--resume <id>", "Resume a saved session (replays its message history before this prompt)")
     .option("--setting-sources <sources>", "Comma-separated list of setting sources to merge (e.g. 'user,project,local'). Mirrors Claude Code's setting_sources.")
+    .option("--max-budget-usd <amount>", "Hard cap on session cost in USD. The agent halts with reason 'budget_exceeded' once totalCost reaches this amount. Mirrors Claude Code's --max-budget-usd.")
     .action(async (promptArg, opts) => {
     // Read from stdin if prompt is "-" or omitted and stdin is not a TTY
     let prompt;
@@ -201,6 +217,7 @@ program
         permissionMode,
         maxTurns: parseInt(opts.maxTurns, 10),
         model,
+        ...(opts.maxBudgetUsd !== undefined ? { maxCost: parseMaxBudgetUsdOrExit(opts.maxBudgetUsd) } : {}),
     };
     const outputFormat = opts.json ? "json" : (opts.outputFormat ?? "text");
     let fullOutput = "";
@@ -210,26 +227,36 @@ program
     // history into the conversation before the new prompt. If the session can't
     // be loaded (missing file, malformed JSON), fail early with a clear error
     // rather than silently starting fresh.
+    //
+    // When --resume is NOT passed, mint a fresh session record so SDK callers
+    // can capture its id from the session_start event and pass it back as
+    // --resume <id> on a later run. Without this, every fresh `oh run` was
+    // a programmatic dead-end for resumption (issue #60).
+    const { createSession, loadSession, saveSession } = await import("./harness/session.js");
     let priorMessages;
     let sessionId;
+    let sessionRecord;
     if (opts.resume) {
-        const { loadSession } = await import("./harness/session.js");
         try {
-            const src = loadSession(opts.resume);
-            priorMessages = src.messages;
-            sessionId = src.id;
+            sessionRecord = loadSession(opts.resume);
+            priorMessages = sessionRecord.messages;
+            sessionId = sessionRecord.id;
         }
         catch {
             process.stderr.write(`Error: could not load session '${opts.resume}'\n`);
             process.exit(1);
         }
     }
+    else {
+        sessionRecord = createSession(provider.name, model);
+        sessionId = sessionRecord.id;
+        saveSession(sessionRecord);
+    }
     if (outputFormat === "stream-json") {
         // Emit a session_start event so SDK callers can capture the id for
-        // later resume (fires once, before turnStart).
-        if (sessionId) {
-            console.log(JSON.stringify({ type: "session_start", sessionId }));
-        }
+        // later resume (fires once, before turnStart). Always emitted now —
+        // fresh runs mint a sessionId above.
+        console.log(JSON.stringify({ type: "session_start", sessionId }));
         setHookDecisionObserver((n) => {
             console.log(JSON.stringify({
                 type: "hook_decision",
@@ -320,6 +347,22 @@ program
     else if (outputFormat === "text") {
         process.stdout.write("\n");
     }
+    // Persist this run's contribution so a later --resume <sessionId> finds
+    // the user/assistant pair. Tool details are intentionally elided —
+    // they're per-tool ephemerals; the assistant's final text is what
+    // matters for context resumption. Mirrors the REPL's save-on-exit pattern
+    // (src/components/REPL.tsx:120) but at one-shot scope.
+    try {
+        const { createUserMessage, createAssistantMessage } = await import("./types/message.js");
+        const newMessages = [...(priorMessages ?? []), createUserMessage(prompt)];
+        if (fullOutput)
+            newMessages.push(createAssistantMessage(fullOutput));
+        sessionRecord.messages = newMessages;
+        saveSession(sessionRecord);
+    }
+    catch {
+        /* persistence is best-effort — never fail the user's run on a save error */
+    }
 });
 // ── `oh session`: long-lived stateful session for the Python SDK ──
 program
@@ -335,6 +378,7 @@ program
     .option("--system-prompt <prompt>", "Override the system prompt")
     .option("--resume <id>", "Resume a saved session (seeds the conversation with its prior message history)")
     .option("--setting-sources <sources>", "Comma-separated list of setting sources to merge (mirrors Claude Code's setting_sources).")
+    .option("--max-budget-usd <amount>", "Hard cap on session cost in USD. Each prompt's cost accumulates; the agent halts with reason 'budget_exceeded' once totalCost reaches this amount.")
     .action(async (opts) => {
     const settingSources = parseSettingSources(opts.settingSources);
     const savedConfig = readOhConfig(undefined, settingSources);
@@ -368,23 +412,32 @@ program
         permissionMode,
         maxTurns: parseInt(opts.maxTurns, 10),
         model,
+        ...(opts.maxBudgetUsd !== undefined ? { maxCost: parseMaxBudgetUsdOrExit(opts.maxBudgetUsd) } : {}),
     };
     // Conversation history, shared across all prompts for this process.
-    // Seeded from a prior session when --resume <id> is passed.
+    // Seeded from a prior session when --resume <id> is passed; otherwise a
+    // fresh session is minted so the SDK can capture the id from the `ready`
+    // event for later resume (issue #60).
     const conversation = [];
+    const { createSession, loadSession, saveSession } = await import("./harness/session.js");
     let sessionId;
+    let sessionRecord;
     if (opts.resume) {
-        const { loadSession } = await import("./harness/session.js");
         try {
-            const src = loadSession(opts.resume);
-            conversation.push(...src.messages);
-            sessionId = src.id;
+            sessionRecord = loadSession(opts.resume);
+            conversation.push(...sessionRecord.messages);
+            sessionId = sessionRecord.id;
         }
         catch {
             console.log(JSON.stringify({ type: "error", message: `could not load session '${opts.resume}'` }));
             return;
         }
     }
+    else {
+        sessionRecord = createSession(provider.name, model);
+        sessionId = sessionRecord.id;
+        saveSession(sessionRecord);
+    }
     let turnCounter = 0;
     // Will be set to the current prompt id before each turn so hook_decision
     // events can be demultiplexed by the client.
@@ -494,6 +547,15 @@ program
         for (const tr of toolResults) {
             conversation.push(createToolResultMessage({ callId: tr.callId, output: tr.output, isError: tr.isError }));
         }
+        // Persist after every completed turn so a later --resume picks up the
+        // history. Best-effort — a save failure shouldn't break the live session.
+        try {
+            sessionRecord.messages = conversation.slice();
+            saveSession(sessionRecord);
+        }
+        catch {
+            /* save errors don't propagate to the client */
+        }
     }
 });
 // ── Default command: just run `openharness` to start chatting ──
@@ -591,6 +653,20 @@ program
     if (mcpNames.length > 0) {
         console.log(`[mcp] Connected: ${mcpNames.join(", ")}`);
     }
+    // Surface MCP-server prompts (`prompts/list`) as `/server:prompt` slash
+    // commands. Errors are swallowed inside loadMcpPrompts — servers that
+    // don't implement the prompts capability return [] without throwing.
+    try {
+        const { registerMcpPromptCommands } = await import("./commands/index.js");
+        const prompts = await loadMcpPrompts();
+        registerMcpPromptCommands(prompts);
+        if (prompts.length > 0) {
+            console.log(`[mcp] Prompts: ${prompts.map((p) => `/${p.qualifiedName}`).join(", ")}`);
+        }
+    }
+    catch {
+        /* prompt registration is best-effort; never block the REPL */
+    }
     const tools = [...getAllTools(), ...mcpTools];
     process.on("exit", () => disconnectMcpClients());
     // Compute working directory and git branch

package/dist/mcp/client.d.ts

@@ -31,6 +31,29 @@ export declare class McpClient {
         description?: string;
     }>>;
     readResource(uri: string): Promise<string>;
+    /**
+     * List the prompts an MCP server exposes. Returns `[]` for servers that
+     * don't implement the `prompts/list` capability — this is a normal case
+     * (most non-prompt-aware MCP servers throw a method-not-found error).
+     *
+     * Each prompt may declare named arguments; surfaced via `arguments`.
+     */
+    listPrompts(): Promise<Array<{
+        name: string;
+        description?: string;
+        arguments?: Array<{
+            name: string;
+            description?: string;
+            required?: boolean;
+        }>;
+    }>>;
+    /**
+     * Get the rendered text of an MCP prompt. Server-side templates are
+     * applied with the supplied arguments. Multiple message turns are
+     * concatenated with double-newline separators — same shape OH uses for
+     * other prepended prompts.
+     */
+    getPrompt(name: string, args?: Record<string, string>): Promise<string>;
     callTool(name: string, args: Record<string, unknown>): Promise<string>;
     disconnect(): void;
 }

package/dist/mcp/client.js

@@ -91,6 +91,43 @@ export class McpClient {
             .map((c) => c.text)
             .join("\n");
     }
+    /**
+     * List the prompts an MCP server exposes. Returns `[]` for servers that
+     * don't implement the `prompts/list` capability — this is a normal case
+     * (most non-prompt-aware MCP servers throw a method-not-found error).
+     *
+     * Each prompt may declare named arguments; surfaced via `arguments`.
+     */
+    async listPrompts() {
+        try {
+            const res = await this.sdk.listPrompts();
+            return (res?.prompts ?? []);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Get the rendered text of an MCP prompt. Server-side templates are
+     * applied with the supplied arguments. Multiple message turns are
+     * concatenated with double-newline separators — same shape OH uses for
+     * other prepended prompts.
+     */
+    async getPrompt(name, args = {}) {
+        const res = await this.sdk.getPrompt({ name, arguments: args });
+        const messages = (res?.messages ?? []);
+        const parts = [];
+        for (const m of messages) {
+            const content = m.content;
+            if (typeof content === "string") {
+                parts.push(content);
+            }
+            else if (content && content.type === "text" && typeof content.text === "string") {
+                parts.push(content.text);
+            }
+        }
+        return parts.join("\n\n");
+    }
     async callTool(name, args) {
         // Retry up to 2 times on transport-closed / timeout errors
         let lastErr = null;

package/dist/mcp/loader.d.ts

@@ -5,6 +5,26 @@ export declare function loadMcpTools(): Promise<Tool[]>;
 export declare function disconnectMcpClients(): void;
 /** Names of connected MCP servers */
 export declare function connectedMcpServers(): string[];
+export type McpPromptHandle = {
+    /** `<server>:<prompt>` qualified name — the slash command is `/<server>:<prompt>`. */
+    qualifiedName: string;
+    description: string;
+    /** List of named arguments the prompt template expects. */
+    arguments?: Array<{
+        name: string;
+        description?: string;
+        required?: boolean;
+    }>;
+    /** Render the prompt with the supplied named arguments. */
+    render(args?: Record<string, string>): Promise<string>;
+};
+/**
+ * Enumerate prompts on every already-connected MCP server. Servers that don't
+ * implement the `prompts/list` capability return an empty list (handled
+ * inside `client.listPrompts`). Call AFTER `loadMcpTools()` so the client
+ * connections are warm.
+ */
+export declare function loadMcpPrompts(): Promise<McpPromptHandle[]>;
 /** Get MCP server instructions to inject into system prompt (sandboxed with origin markers) */
 export declare function getMcpInstructions(): string[];
 /** List all available resources across connected MCP servers */

package/dist/mcp/loader.js

@@ -78,6 +78,33 @@ export function disconnectMcpClients() {
 export function connectedMcpServers() {
     return connectedClients.map((c) => c.name);
 }
+/**
+ * Enumerate prompts on every already-connected MCP server. Servers that don't
+ * implement the `prompts/list` capability return an empty list (handled
+ * inside `client.listPrompts`). Call AFTER `loadMcpTools()` so the client
+ * connections are warm.
+ */
+export async function loadMcpPrompts() {
+    const handles = [];
+    for (const client of connectedClients) {
+        let prompts;
+        try {
+            prompts = await client.listPrompts();
+        }
+        catch {
+            continue; // Defensive — listPrompts already swallows method-not-found
+        }
+        for (const p of prompts) {
+            handles.push({
+                qualifiedName: `${client.name}:${p.name}`,
+                description: p.description ?? `MCP prompt from ${client.name}`,
+                ...(p.arguments ? { arguments: p.arguments } : {}),
+                render: (args = {}) => client.getPrompt(p.name, args),
+            });
+        }
+    }
+    return handles;
+}
 const MAX_MCP_INSTRUCTION_LENGTH = 2000;
 /** Get MCP server instructions to inject into system prompt (sandboxed with origin markers) */
 export function getMcpInstructions() {

package/dist/providers/ollama.d.ts

@@ -9,6 +9,19 @@ export declare class OllamaProvider implements Provider {
     private baseUrl;
     private defaultModel;
     constructor(config: ProviderConfig);
+    /**
+     * Estimate the prompt size and pick a `num_ctx` for Ollama. Without this
+     * Ollama defaults to a 2048-token context window — anything bigger gets
+     * silently truncated server-side. OH's typical system prompt + tool list
+     * already pushes ~4 K, so multi-turn chats lose prior turns and the model
+     * appears to "forget" what was just said. See issue #61.
+     *
+     * Strategy: rough char/4 token estimate, +1 K headroom for the response,
+     * then round up to the next power of 2 ≥ 8192. Capped at 32 K to keep KV
+     * cache bounded; users with bigger models can override via
+     * `OLLAMA_NUM_CTX`.
+     */
+    private computeNumCtx;
     private convertMessages;
     private convertTools;
     stream(messages: Message[], systemPrompt: string, tools?: APIToolDef[], model?: string): AsyncGenerator<StreamEvent, void>;

package/dist/providers/ollama.js

@@ -10,6 +10,45 @@ export class OllamaProvider {
         this.baseUrl = (config.baseUrl ?? "http://localhost:11434").replace(/\/$/, "");
         this.defaultModel = config.defaultModel ?? "llama3.1";
     }
+    /**
+     * Estimate the prompt size and pick a `num_ctx` for Ollama. Without this
+     * Ollama defaults to a 2048-token context window — anything bigger gets
+     * silently truncated server-side. OH's typical system prompt + tool list
+     * already pushes ~4 K, so multi-turn chats lose prior turns and the model
+     * appears to "forget" what was just said. See issue #61.
+     *
+     * Strategy: rough char/4 token estimate, +1 K headroom for the response,
+     * then round up to the next power of 2 ≥ 8192. Capped at 32 K to keep KV
+     * cache bounded; users with bigger models can override via
+     * `OLLAMA_NUM_CTX`.
+     */
+    computeNumCtx(messages, systemPrompt, tools) {
+        const override = process.env.OLLAMA_NUM_CTX;
+        if (override) {
+            const parsed = Number(override);
+            if (Number.isFinite(parsed) && parsed > 0)
+                return Math.floor(parsed);
+        }
+        const estimate = (s) => Math.ceil(s.length / 4);
+        let total = systemPrompt ? estimate(systemPrompt) : 0;
+        for (const m of messages) {
+            total += estimate(m.content);
+            if (m.toolCalls)
+                for (const tc of m.toolCalls)
+                    total += estimate(JSON.stringify(tc.arguments));
+            if (m.toolResults)
+                for (const tr of m.toolResults)
+                    total += estimate(tr.output);
+        }
+        if (tools)
+            for (const t of tools)
+                total += estimate(JSON.stringify(t));
+        const padded = Math.ceil(total * 1.25) + 1024;
+        let nc = 8192;
+        while (nc < padded && nc < 32768)
+            nc *= 2;
+        return Math.min(nc, 32768);
+    }
     convertMessages(messages, systemPrompt) {
         const converted = [];
         if (systemPrompt) {
@@ -69,6 +108,7 @@ export class OllamaProvider {
             model: m,
             messages: msgs,
             stream: true,
+            options: { num_ctx: this.computeNumCtx(messages, systemPrompt, tools) },
         };
         const ollamaTools = this.convertTools(tools);
         if (ollamaTools)
@@ -219,6 +259,7 @@ export class OllamaProvider {
             model: m,
             messages: msgs,
             stream: false,
+            options: { num_ctx: this.computeNumCtx(messages, systemPrompt, tools) },
         };
         const ollamaTools = this.convertTools(tools);
         if (ollamaTools)

package/dist/query/tools.js

@@ -42,11 +42,12 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
     // Permission check
     const perm = checkPermission(permissionMode, tool.riskLevel, tool.isReadOnly(parsed.data), tool.name, parsed.data);
     if (!perm.allowed) {
-        if (perm.reason === "needs-approval" && askUser) {
-            const { formatToolArgs } = await import("../utils/tool-summary.js");
-            const description = formatToolArgs(tool.name, toolCall.arguments);
-            // Hook: permissionRequest — fires between preToolUse and the interactive askUser prompt.
-            // Only fires when checkPermission says "needs-approval" AND askUser is provided.
+        if (perm.reason === "needs-approval") {
+            // Hook: permissionRequest — fires whenever checkPermission says
+            // "needs-approval", in both interactive and headless modes. Configured
+            // hooks get first say; if they return "ask" or have no decision, we
+            // fall through to the interactive prompt when one is available, or
+            // fail-closed deny in headless mode (issue #62).
             const hookOutcome = await emitHookWithOutcome("permissionRequest", {
                 toolName: tool.name,
                 toolArgs: JSON.stringify(toolCall.arguments).slice(0, 1000),
@@ -54,22 +55,48 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 permissionMode,
                 permissionAction: "ask",
             });
+            const denyAndEmit = (source, reason, output) => {
+                emitHook("permissionDenied", {
+                    toolName: tool.name,
+                    toolArgs: JSON.stringify(toolCall.arguments).slice(0, 1000),
+                    permissionMode,
+                    denySource: source,
+                    denyReason: reason,
+                });
+                return { output, isError: true };
+            };
             if (hookOutcome.permissionDecision === "allow") {
-                // Hook granted permission — skip interactive prompt and proceed to execution.
+                // Hook granted permission — proceed to execution.
             }
             else if (hookOutcome.permissionDecision === "deny" || !hookOutcome.allowed) {
                 const reason = hookOutcome.reason ? `: ${hookOutcome.reason}` : "";
-                return { output: `Permission denied by hook${reason}`, isError: true };
+                return denyAndEmit("hook", hookOutcome.reason ?? "hook denied", `Permission denied by hook${reason}`);
             }
-            else {
-                // "ask" or no decision → fall through to interactive prompt
+            else if (askUser) {
+                // "ask" or no decision → interactive prompt when available
+                const { formatToolArgs } = await import("../utils/tool-summary.js");
+                const description = formatToolArgs(tool.name, toolCall.arguments);
                 const allowed = await askUser(tool.name, description, tool.riskLevel);
                 if (!allowed) {
-                    return { output: "Permission denied by user.", isError: true };
+                    return denyAndEmit("user", "user declined", "Permission denied by user.");
                 }
             }
+            else {
+                // Headless mode with no hook decision and no interactive prompt:
+                // fail-closed deny. SDK consumers should configure a permissionRequest
+                // hook (or use canUseTool) to make per-call decisions.
+                return denyAndEmit("headless", "no hook decision and no interactive prompt available", "Permission denied: needs-approval (no interactive prompt available; configure a permissionRequest hook to gate this tool)");
+            }
         }
         else {
+            // Auto-mode policy block (deny / acceptEdits / etc) — symmetric event.
+            emitHook("permissionDenied", {
+                toolName: tool.name,
+                toolArgs: JSON.stringify(toolCall.arguments).slice(0, 1000),
+                permissionMode,
+                denySource: "policy",
+                denyReason: perm.reason,
+            });
             return { output: `Permission denied: ${perm.reason}`, isError: true };
         }
     }
@@ -188,6 +215,7 @@ export async function* executeToolCalls(toolCalls, tools, context, permissionMod
     const onOutputChunk = (callId, chunk) => {
         outputChunks.push({ type: "tool_output_delta", callId, chunk });
     };
+    const allToolNames = toolCalls.map((tc) => tc.toolName);
     for (const batch of batches) {
         if (batch.concurrent) {
             const results = await Promise.all(batch.calls.map((tc) => executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser)));
@@ -210,5 +238,17 @@ export async function* executeToolCalls(toolCalls, tools, context, permissionMod
             }
         }
     }
+    // Hook: postToolBatch — fires once after the model's full set of tool
+    // calls for this turn have all resolved (across however many serial /
+    // concurrent batches partitionToolCalls produced), before the next model
+    // call. Per-tool postToolUse / postToolUseFailure still fire as before;
+    // this is the batch-level boundary for hooks that want to act once per
+    // turn instead of once per tool.
+    if (toolCalls.length > 0) {
+        emitHook("postToolBatch", {
+            batchSize: String(toolCalls.length),
+            batchTools: allToolNames.slice(0, 50).join(","),
+        });
+    }
 }
 //# sourceMappingURL=tools.js.map

package/dist/tools/TaskCreateTool/index.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { z } from "zod";
+import { emitHook } from "../../harness/hooks.js";
 const inputSchema = z.object({
     subject: z.string(),
     description: z.string(),
@@ -42,6 +43,10 @@ export const TaskCreateTool = {
             };
             tasks.push(newTask);
             await fs.writeFile(filePath, JSON.stringify(tasks, null, 2), "utf-8");
+            emitHook("taskCreated", {
+                taskId: String(newTask.id),
+                taskSubject: newTask.subject.slice(0, 200),
+            });
             return { output: `Task #${newTask.id} created: ${newTask.subject}`, isError: false };
         }
         catch (err) {

package/dist/tools/TaskUpdateTool/index.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { z } from "zod";
+import { emitHook } from "../../harness/hooks.js";
 const inputSchema = z.object({
     taskId: z.number(),
     status: z.enum(["pending", "in_progress", "completed", "cancelled", "deleted"]).optional(),
@@ -32,6 +33,7 @@ export const TaskUpdateTool = {
             if (!task) {
                 return { output: `Error: Task #${input.taskId} not found.`, isError: true };
             }
+            const previousStatus = task.status;
             // Handle deletion
             if (input.status === "deleted") {
                 const idx = tasks.indexOf(task);
@@ -69,6 +71,15 @@ export const TaskUpdateTool = {
                 task.blockedBy = [...new Set([...(task.blockedBy ?? []), ...input.addBlockedBy])];
             }
             await fs.writeFile(filePath, JSON.stringify(tasks, null, 2), "utf-8");
+            // Hook: taskCompleted — fires only on the pending|in_progress → completed
+            // transition. Re-saving an already-completed task is a no-op for the hook.
+            if (input.status === "completed" && previousStatus !== "completed") {
+                emitHook("taskCompleted", {
+                    taskId: String(task.id),
+                    taskSubject: task.subject.slice(0, 200),
+                    taskPreviousStatus: previousStatus,
+                });
+            }
             return { output: `Task #${task.id} updated. Status: ${task.status}`, isError: false };
         }
         catch (err) {

package/dist/utils/parse-budget.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Parse the `--max-budget-usd` CLI argument into a positive USD amount.
+ *
+ * Accepts plain decimals (`5`, `0.50`, `2.5`) and an optional leading `$`.
+ * Negative or zero values are rejected — a budget of zero would block the
+ * very first call before any cost has accumulated.
+ *
+ * Returns `{ ok: true, value }` on success or `{ ok: false, message }` on
+ * invalid input. The CLI wrapper translates failures into a stderr message
+ * and exit code 2.
+ */
+export type ParseBudgetResult = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function parseMaxBudgetUsd(raw: string): ParseBudgetResult;
+//# sourceMappingURL=parse-budget.d.ts.map

package/dist/utils/parse-budget.js

@@ -0,0 +1,12 @@
+export function parseMaxBudgetUsd(raw) {
+    const cleaned = raw.replace(/^\$/, "").trim();
+    if (cleaned === "") {
+        return { ok: false, message: `--max-budget-usd must be a positive USD amount, got '${raw}'` };
+    }
+    const n = Number(cleaned);
+    if (!Number.isFinite(n) || n <= 0) {
+        return { ok: false, message: `--max-budget-usd must be a positive USD amount, got '${raw}'` };
+    }
+    return { ok: true, value: n };
+}
+//# sourceMappingURL=parse-budget.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.18.0",
+  "version": "2.20.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {
@@ -22,17 +22,23 @@
     "README.md",
     "LICENSE"
   ],
+  "workspaces": [
+    "packages/sdk"
+  ],
   "scripts": {
     "dev": "tsx src/main.tsx",
     "build": "tsc",
+    "build:sdk": "npm --workspace @zhijiewang/openharness-sdk run build",
     "prepare": "husky",
     "prepublishOnly": "npm run build",
-    "test": "node scripts/test.mjs",
+    "test": "node scripts/test.mjs && npm --workspace @zhijiewang/openharness-sdk run test",
+    "test:cli": "node scripts/test.mjs",
+    "test:sdk": "npm --workspace @zhijiewang/openharness-sdk run test",
     "test:coverage": "node scripts/coverage.mjs",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome check src/",
-    "lint:fix": "biome check --write src/",
-    "format": "biome format --write src/",
+    "typecheck": "tsc --noEmit && npm --workspace @zhijiewang/openharness-sdk run typecheck",
+    "lint": "biome check src/ packages/sdk/src/",
+    "lint:fix": "biome check --write src/ packages/sdk/src/",
+    "format": "biome format --write src/ packages/sdk/src/",
     "start": "node dist/main.js"
   },
   "dependencies": {