@zhijiewang/openharness 2.20.0 → 2.22.0

package/dist/query/types.d.ts

@@ -22,6 +22,16 @@ export type QueryConfig = {
     gitCommitPerTool?: boolean;
     /** For sub-agent invocations: the agent role name (feeds into the model router). */
     role?: string;
+    /**
+     * MCP tool name (e.g. `mcp__myperm__check`) consulted when a tool needs
+     * approval and no permission hook gave a decision (audit B1). Mirrors
+     * Claude Code's `--permission-prompt-tool`. The tool is invoked with
+     * `{ tool_name, input }` and is expected to return a JSON string with
+     * shape `{ "behavior": "allow" | "deny", "message"?: string }`. Falls
+     * through to the interactive `askUser` prompt (or headless deny) when
+     * the tool is missing, throws, or returns malformed JSON.
+     */
+    permissionPromptTool?: string;
 };
 export type TransitionReason = "next_turn" | "retry_network" | "retry_prompt_too_long" | "retry_max_output_tokens";
 export type QueryLoopState = {

package/dist/tools/EnterWorktreeTool/index.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { createWorktree, isGitRepo } from "../../git/index.js";
+import { emitHook } from "../../harness/hooks.js";
 const inputSchema = z.object({
     branch: z.string().optional().describe("Branch name for the worktree (auto-generated if omitted)"),
 });
@@ -22,6 +23,9 @@ export const EnterWorktreeTool = {
         if (!path) {
             return { output: "Failed to create worktree.", isError: true };
         }
+        // Symmetric to taskCreated — fire only on the success path so audit hooks
+        // can react to the new worktree (e.g. set up a per-worktree scratch dir).
+        emitHook("worktreeCreate", { worktreePath: path, worktreeParent: context.workingDir });
         return { output: `Worktree created at: ${path}\nUse ExitWorktree to clean up when done.`, isError: false };
     },
     prompt() {

package/dist/tools/ExitWorktreeTool/index.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { hasWorktreeChanges, removeWorktree } from "../../git/index.js";
+import { emitHook } from "../../harness/hooks.js";
 const inputSchema = z.object({
     path: z.string().describe("Path to the worktree to remove"),
     force: z.boolean().optional().describe("Force removal even with uncommitted changes"),
@@ -24,6 +25,12 @@ export const ExitWorktreeTool = {
         }
         try {
             removeWorktree(input.path);
+            // Fire after removeWorktree resolves so the hook only sees confirmed
+            // removals — symmetric to worktreeCreate firing on success.
+            emitHook("worktreeRemove", {
+                worktreePath: input.path,
+                worktreeForced: input.force ? "true" : "false",
+            });
             return { output: `Worktree removed: ${input.path}`, isError: false };
         }
         catch (err) {

package/dist/utils/debug.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Categorized debug logger — gates verbose internal traces behind a runtime
+ * switch so they're silent by default but easy to flip on for support / CI.
+ *
+ * Activation precedence (highest first):
+ *   1. `configureDebug({ categories })` from a CLI flag (`--debug [cats]`)
+ *   2. `OH_DEBUG` env var
+ *
+ * Sink precedence:
+ *   1. `configureDebug({ file })` from `--debug-file <path>`
+ *   2. `OH_DEBUG_FILE` env var
+ *   3. `process.stderr` (default)
+ *
+ * Categories are arbitrary strings — call sites pick them. The CLI accepts a
+ * comma-separated list (`--debug mcp,hooks`) or `--debug` alone for "all".
+ *
+ * Wire pattern:
+ *   import { configureDebug, debug } from "./utils/debug.js";
+ *   configureDebug({ categories: opts.debug, file: opts.debugFile });
+ *   debug("mcp", "connected", server.name);
+ */
+/**
+ * Parse the raw flag value into a Set of enabled categories.
+ *
+ * Accepted values:
+ *   - `undefined` / empty / `false`     → no debug
+ *   - `true` / `"*"` / `"all"` / `"1"`  → all categories
+ *   - `"mcp,hooks,provider"`            → comma-separated explicit list
+ *
+ * Whitespace is trimmed and empty entries dropped, so `"mcp, ,hooks"` is
+ * equivalent to `"mcp,hooks"`. Pure function — exposed for testability.
+ */
+export declare function parseDebugCategories(raw: string | boolean | undefined): Set<string>;
+export interface ConfigureDebugOptions {
+    /** CLI flag value: `--debug` → true, `--debug mcp` → "mcp", absent → undefined. */
+    categories?: string | boolean | undefined;
+    /** CLI flag value: `--debug-file <path>` — appended to, never truncated. */
+    file?: string;
+    /** Test injection — overrides the file/stderr sink. Not used at runtime. */
+    sink?: NodeJS.WritableStream;
+}
+/**
+ * Apply debug configuration. Safe to call multiple times — later calls fully
+ * replace earlier state. When `categories` is undefined, falls back to
+ * `OH_DEBUG`; when `file` is undefined, falls back to `OH_DEBUG_FILE`.
+ *
+ * File output uses `appendFileSync` rather than a `WriteStream` so each
+ * `debug()` line lands on disk before the function returns. That trades a
+ * little throughput for ordering guarantees that matter when debugging
+ * crashes — a streamed sink could lose its tail buffer on `process.exit`.
+ */
+export declare function configureDebug(opts?: ConfigureDebugOptions): void;
+/** Whether the given category is currently emitting. Cheap — a Set lookup. */
+export declare function isDebugEnabled(category: string): boolean;
+/**
+ * Emit a debug line for the given category. Cheap no-op when the category is
+ * disabled — argument formatting is skipped entirely. Each line is prefixed
+ * with `[debug:<cat>] +<elapsed_ms>ms` so categories interleave readably.
+ */
+export declare function debug(category: string, ...args: unknown[]): void;
+/** @internal Test-only: reset module-level state between cases. */
+export declare function _resetDebugForTest(): void;
+//# sourceMappingURL=debug.d.ts.map

package/dist/utils/debug.js

@@ -0,0 +1,122 @@
+/**
+ * Categorized debug logger — gates verbose internal traces behind a runtime
+ * switch so they're silent by default but easy to flip on for support / CI.
+ *
+ * Activation precedence (highest first):
+ *   1. `configureDebug({ categories })` from a CLI flag (`--debug [cats]`)
+ *   2. `OH_DEBUG` env var
+ *
+ * Sink precedence:
+ *   1. `configureDebug({ file })` from `--debug-file <path>`
+ *   2. `OH_DEBUG_FILE` env var
+ *   3. `process.stderr` (default)
+ *
+ * Categories are arbitrary strings — call sites pick them. The CLI accepts a
+ * comma-separated list (`--debug mcp,hooks`) or `--debug` alone for "all".
+ *
+ * Wire pattern:
+ *   import { configureDebug, debug } from "./utils/debug.js";
+ *   configureDebug({ categories: opts.debug, file: opts.debugFile });
+ *   debug("mcp", "connected", server.name);
+ */
+import { appendFileSync } from "node:fs";
+const ALL = "*";
+let enabledCategories = new Set();
+let debugFilePath;
+let sinkOverride;
+let started = Date.now();
+/**
+ * Parse the raw flag value into a Set of enabled categories.
+ *
+ * Accepted values:
+ *   - `undefined` / empty / `false`     → no debug
+ *   - `true` / `"*"` / `"all"` / `"1"`  → all categories
+ *   - `"mcp,hooks,provider"`            → comma-separated explicit list
+ *
+ * Whitespace is trimmed and empty entries dropped, so `"mcp, ,hooks"` is
+ * equivalent to `"mcp,hooks"`. Pure function — exposed for testability.
+ */
+export function parseDebugCategories(raw) {
+    if (raw === undefined || raw === false || raw === "")
+        return new Set();
+    if (raw === true)
+        return new Set([ALL]);
+    const lower = raw.toLowerCase();
+    if (lower === "*" || lower === "all" || lower === "true" || lower === "1")
+        return new Set([ALL]);
+    return new Set(raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean));
+}
+/**
+ * Apply debug configuration. Safe to call multiple times — later calls fully
+ * replace earlier state. When `categories` is undefined, falls back to
+ * `OH_DEBUG`; when `file` is undefined, falls back to `OH_DEBUG_FILE`.
+ *
+ * File output uses `appendFileSync` rather than a `WriteStream` so each
+ * `debug()` line lands on disk before the function returns. That trades a
+ * little throughput for ordering guarantees that matter when debugging
+ * crashes — a streamed sink could lose its tail buffer on `process.exit`.
+ */
+export function configureDebug(opts = {}) {
+    const rawCats = opts.categories !== undefined ? opts.categories : process.env.OH_DEBUG;
+    enabledCategories = parseDebugCategories(rawCats);
+    sinkOverride = opts.sink;
+    debugFilePath = opts.sink ? undefined : (opts.file ?? process.env.OH_DEBUG_FILE);
+    started = Date.now();
+}
+/** Whether the given category is currently emitting. Cheap — a Set lookup. */
+export function isDebugEnabled(category) {
+    return enabledCategories.has(ALL) || enabledCategories.has(category);
+}
+/**
+ * Emit a debug line for the given category. Cheap no-op when the category is
+ * disabled — argument formatting is skipped entirely. Each line is prefixed
+ * with `[debug:<cat>] +<elapsed_ms>ms` so categories interleave readably.
+ */
+export function debug(category, ...args) {
+    if (!isDebugEnabled(category))
+        return;
+    const elapsed = Date.now() - started;
+    const formatted = args
+        .map((a) => {
+        if (typeof a === "string")
+            return a;
+        if (a instanceof Error)
+            return a.stack ?? a.message;
+        try {
+            return JSON.stringify(a);
+        }
+        catch {
+            return String(a);
+        }
+    })
+        .join(" ");
+    const line = `[debug:${category}] +${elapsed}ms ${formatted}\n`;
+    if (sinkOverride) {
+        sinkOverride.write(line);
+    }
+    else if (debugFilePath) {
+        try {
+            appendFileSync(debugFilePath, line);
+        }
+        catch (err) {
+            // Fall back to stderr so a broken --debug-file doesn't swallow output.
+            process.stderr.write(`[debug] could not append to '${debugFilePath}': ${err instanceof Error ? err.message : String(err)}\n`);
+            process.stderr.write(line);
+            debugFilePath = undefined;
+        }
+    }
+    else {
+        process.stderr.write(line);
+    }
+}
+/** @internal Test-only: reset module-level state between cases. */
+export function _resetDebugForTest() {
+    enabledCategories = new Set();
+    debugFilePath = undefined;
+    sinkOverride = undefined;
+    started = Date.now();
+}
+//# sourceMappingURL=debug.js.map

package/dist/utils/install-method.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Detect how the running OH CLI was installed (audit B7) so `oh update` can
+ * print the appropriate upgrade command. Pure function — `detectInstallMethod`
+ * inspects the process's own filesystem path and current working directory;
+ * exported for unit testing and reuse.
+ *
+ * Detection rules, in order:
+ *   - "local-clone"   → `dist/main.js` lives inside a git repo whose root is
+ *                       the package itself (the user is running from a clone).
+ *                       Suggest `git pull && npm install && npm run build`.
+ *   - "npm-global"    → `dist/main.js` lives under a directory containing the
+ *                       segment `node_modules/@zhijiewang/openharness/`. This
+ *                       is the standard npm global install layout. Suggest
+ *                       `npm install -g @zhijiewang/openharness@latest`.
+ *   - "npx-cache"     → `dist/main.js` lives under a path containing
+ *                       `_npx/` (npx caches packages there). npx auto-fetches
+ *                       the latest by default; suggest re-running with
+ *                       `@latest` to bypass cache.
+ *   - "unknown"       → Couldn't classify. Print all three options and let
+ *                       the user choose.
+ */
+export type InstallMethod = "local-clone" | "npm-global" | "npx-cache" | "unknown";
+export interface InstallMethodResult {
+    method: InstallMethod;
+    /** The detected install root, mostly for diagnostics. */
+    root: string;
+    /** Multi-line user-facing message describing the upgrade command. */
+    message: string;
+}
+/**
+ * Classify the install method given the running script's filesystem path.
+ * `mainPath` defaults to `import.meta.url`-derived path in the CLI; tests
+ * override it.
+ */
+export declare function detectInstallMethod(mainPath: string): InstallMethodResult;
+/**
+ * Default `mainPath` resolver — walks up from `process.argv[1]` to find the
+ * package root. Exported so tests can stub it. Falls back to argv[1] verbatim
+ * when nothing matches.
+ */
+export declare function getDefaultMainPath(): string;
+//# sourceMappingURL=install-method.d.ts.map

package/dist/utils/install-method.js

@@ -0,0 +1,110 @@
+/**
+ * Detect how the running OH CLI was installed (audit B7) so `oh update` can
+ * print the appropriate upgrade command. Pure function — `detectInstallMethod`
+ * inspects the process's own filesystem path and current working directory;
+ * exported for unit testing and reuse.
+ *
+ * Detection rules, in order:
+ *   - "local-clone"   → `dist/main.js` lives inside a git repo whose root is
+ *                       the package itself (the user is running from a clone).
+ *                       Suggest `git pull && npm install && npm run build`.
+ *   - "npm-global"    → `dist/main.js` lives under a directory containing the
+ *                       segment `node_modules/@zhijiewang/openharness/`. This
+ *                       is the standard npm global install layout. Suggest
+ *                       `npm install -g @zhijiewang/openharness@latest`.
+ *   - "npx-cache"     → `dist/main.js` lives under a path containing
+ *                       `_npx/` (npx caches packages there). npx auto-fetches
+ *                       the latest by default; suggest re-running with
+ *                       `@latest` to bypass cache.
+ *   - "unknown"       → Couldn't classify. Print all three options and let
+ *                       the user choose.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+/**
+ * Classify the install method given the running script's filesystem path.
+ * `mainPath` defaults to `import.meta.url`-derived path in the CLI; tests
+ * override it.
+ */
+export function detectInstallMethod(mainPath) {
+    // Normalize to forward slashes so the substring tests below work on Windows.
+    const normalized = mainPath.replace(/\\/g, "/");
+    // npx-cache: path contains `/_npx/` (Node's npx puts packages there)
+    if (normalized.includes("/_npx/")) {
+        return {
+            method: "npx-cache",
+            root: dirname(mainPath),
+            message: [
+                "You're running OH via npx (auto-fetched on each invocation).",
+                "To force the latest version on the next run, use:",
+                "",
+                "  npx @zhijiewang/openharness@latest",
+                "",
+                "Or install globally to avoid the npx cache entirely:",
+                "  npm install -g @zhijiewang/openharness@latest",
+            ].join("\n"),
+        };
+    }
+    // local-clone: walk up to find a package.json whose name matches AND a .git dir
+    let dir = dirname(mainPath);
+    while (dir && dir !== dirname(dir)) {
+        const pkgPath = join(dir, "package.json");
+        if (existsSync(pkgPath)) {
+            const isClone = existsSync(join(dir, ".git"));
+            if (isClone) {
+                return {
+                    method: "local-clone",
+                    root: dir,
+                    message: [
+                        `Detected a local clone at: ${dir}`,
+                        "Pull the latest and rebuild:",
+                        "",
+                        `  cd ${dir}`,
+                        "  git pull && npm install && npm run build",
+                    ].join("\n"),
+                };
+            }
+            // npm-global: the package.json belongs to OH and lives under a global
+            // node_modules directory.
+            if (normalized.includes("/node_modules/@zhijiewang/openharness/")) {
+                return {
+                    method: "npm-global",
+                    root: dir,
+                    message: [
+                        `Detected a global npm install at: ${dir}`,
+                        "Upgrade with:",
+                        "",
+                        "  npm install -g @zhijiewang/openharness@latest",
+                    ].join("\n"),
+                };
+            }
+            break;
+        }
+        dir = dirname(dir);
+    }
+    return {
+        method: "unknown",
+        root: dirname(mainPath),
+        message: [
+            "Could not determine how OH was installed. Pick the option that matches your setup:",
+            "",
+            "  Global npm install:  npm install -g @zhijiewang/openharness@latest",
+            "  npx (one-shot):      npx @zhijiewang/openharness@latest",
+            "  Local clone:         git pull && npm install && npm run build",
+        ].join("\n"),
+    };
+}
+/**
+ * Default `mainPath` resolver — walks up from `process.argv[1]` to find the
+ * package root. Exported so tests can stub it. Falls back to argv[1] verbatim
+ * when nothing matches.
+ */
+export function getDefaultMainPath() {
+    const entry = process.argv[1] ?? "";
+    if (!entry)
+        return "";
+    // If argv[1] points at a `dist/main.js`, that's already the right anchor.
+    // Otherwise return as-is and let `detectInstallMethod` figure it out.
+    return entry.split(sep).join("/");
+}
+//# sourceMappingURL=install-method.js.map

package/package.json

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