@zhijiewang/openharness 2.21.0 → 2.22.1

package/dist/providers/index.d.ts

@@ -4,11 +4,35 @@
 import type { Provider, ProviderConfig } from "./base.js";
 /**
  * Create a provider from a model string like "ollama/llama3" or "gpt-4o".
+ *
+ * `opts.fallbackModel` (audit B2) is the CLI override path for the existing
+ * `fallbackProviders` config — when set, REPLACES the config-file fallbacks
+ * with a single entry derived from the model string. Mirrors Claude Code's
+ * `--fallback-model <model>` for one-shot CI runs that want a fallback
+ * without editing `.oh/config.yaml`. Format matches `modelArg`:
+ * `provider/model` or just `model` (provider guessed). When unset, the
+ * existing config-file path is unchanged.
  */
-export declare function createProvider(modelArg?: string, overrides?: Partial<ProviderConfig>): Promise<{
+export declare function createProvider(modelArg?: string, overrides?: Partial<ProviderConfig>, opts?: {
+    fallbackModel?: string;
+}): Promise<{
     provider: Provider;
     model: string;
 }>;
+/**
+ * Parse `--fallback-model <value>` into the same shape as a `fallbackProviders[]`
+ * entry. Accepts `provider/model` (explicit) or just `model` (provider guessed
+ * via `guessProviderFromModel`, same as the primary modelArg). Exposed for
+ * tests.
+ *
+ * @internal
+ */
+export declare function parseFallbackModel(raw: string): {
+    provider: string;
+    model?: string;
+    apiKey?: string;
+    baseUrl?: string;
+};
 export { createProviderInstance, guessProviderFromModel };
 declare function createProviderInstance(name: string, config: ProviderConfig): Provider;
 declare function guessProviderFromModel(model: string): string;

package/dist/providers/index.js

@@ -10,8 +10,16 @@ import { OpenAIProvider } from "./openai.js";
 import { OpenRouterProvider } from "./openrouter.js";
 /**
  * Create a provider from a model string like "ollama/llama3" or "gpt-4o".
+ *
+ * `opts.fallbackModel` (audit B2) is the CLI override path for the existing
+ * `fallbackProviders` config — when set, REPLACES the config-file fallbacks
+ * with a single entry derived from the model string. Mirrors Claude Code's
+ * `--fallback-model <model>` for one-shot CI runs that want a fallback
+ * without editing `.oh/config.yaml`. Format matches `modelArg`:
+ * `provider/model` or just `model` (provider guessed). When unset, the
+ * existing config-file path is unchanged.
  */
-export async function createProvider(modelArg, overrides) {
+export async function createProvider(modelArg, overrides, opts = {}) {
     let providerName = "ollama";
     let model = "llama3";
     if (modelArg) {
@@ -32,7 +40,9 @@ export async function createProvider(modelArg, overrides) {
         ...overrides,
     };
     const primary = createProviderInstance(providerName, config);
-    const fallbackCfgs = readOhConfig()?.fallbackProviders ?? [];
+    const fallbackCfgs = opts.fallbackModel
+        ? [parseFallbackModel(opts.fallbackModel)]
+        : (readOhConfig()?.fallbackProviders ?? []);
     if (fallbackCfgs.length === 0) {
         return { provider: primary, model };
     }
@@ -48,6 +58,21 @@ export async function createProvider(modelArg, overrides) {
     const wrapped = createFallbackProvider(primary, fallbacks);
     return { provider: wrapped, model };
 }
+/**
+ * Parse `--fallback-model <value>` into the same shape as a `fallbackProviders[]`
+ * entry. Accepts `provider/model` (explicit) or just `model` (provider guessed
+ * via `guessProviderFromModel`, same as the primary modelArg). Exposed for
+ * tests.
+ *
+ * @internal
+ */
+export function parseFallbackModel(raw) {
+    if (raw.includes("/")) {
+        const [p, m] = raw.split("/", 2);
+        return { provider: p, model: m };
+    }
+    return { provider: guessProviderFromModel(raw), model: raw };
+}
 export { createProviderInstance, guessProviderFromModel };
 function createProviderInstance(name, config) {
     switch (name) {

package/dist/query/index.js

@@ -311,7 +311,7 @@ export async function* query(userMessage, config, existingMessages = []) {
         // Execute remaining tools not started during streaming
         const remaining = toolCalls.filter((tc) => !executedIds.has(tc.id));
         if (remaining.length > 0) {
-            yield* executeToolCalls(remaining, config.tools, toolContext, config.permissionMode, config.askUser, state);
+            yield* executeToolCalls(remaining, config.tools, toolContext, config.permissionMode, config.askUser, state, config.permissionPromptTool);
         }
         state.lastTurnHadTools = toolCalls.length > 0;
         state.lastTurnToolCount = toolCalls.length;

package/dist/query/tools.d.ts

@@ -11,7 +11,7 @@ type Batch = {
     calls: ToolCall[];
 };
 export declare function partitionToolCalls(toolCalls: ToolCall[], tools: Tools): Batch[];
-export declare function executeSingleTool(toolCall: ToolCall, tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn): Promise<ToolResult>;
-export declare function executeToolCalls(toolCalls: ToolCall[], tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn, state?: QueryLoopState): AsyncGenerator<StreamEvent, void>;
+export declare function executeSingleTool(toolCall: ToolCall, tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn, permissionPromptTool?: string): Promise<ToolResult>;
+export declare function executeToolCalls(toolCalls: ToolCall[], tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn, state?: QueryLoopState, permissionPromptTool?: string): AsyncGenerator<StreamEvent, void>;
 export {};
 //# sourceMappingURL=tools.d.ts.map

package/dist/query/tools.js

@@ -8,6 +8,42 @@ import { createToolResultMessage } from "../types/message.js";
 import { checkPermission } from "../types/permissions.js";
 const MAX_TOOL_RESULT_CHARS = 100_000;
 const TOOL_TIMEOUT_MS = 120_000;
+/**
+ * Invoke the configured `--permission-prompt-tool` (audit B1). The tool is
+ * looked up by name in the active tool registry (so MCP tools wired through
+ * `loadMcpTools` are reachable). Failure modes — missing tool, exception
+ * during call, malformed JSON, unknown `behavior` — collapse into
+ * `behavior: "fallthrough"` so the caller can try the next branch
+ * (interactive prompt or headless deny). A broken permission tool must
+ * not lock the user out.
+ */
+async function callPermissionPromptTool(toolName, tools, context, permissionedToolName, permissionedInput) {
+    const promptTool = findToolByName(tools, toolName);
+    if (!promptTool)
+        return { behavior: "fallthrough" };
+    let raw;
+    try {
+        raw = await promptTool.call({ tool_name: permissionedToolName, input: permissionedInput }, context);
+    }
+    catch {
+        return { behavior: "fallthrough" };
+    }
+    if (raw.isError)
+        return { behavior: "fallthrough" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.output);
+    }
+    catch {
+        return { behavior: "fallthrough" };
+    }
+    if (parsed.behavior === "allow")
+        return { behavior: "allow" };
+    if (parsed.behavior === "deny") {
+        return parsed.message ? { behavior: "deny", message: parsed.message } : { behavior: "deny" };
+    }
+    return { behavior: "fallthrough" };
+}
 export function partitionToolCalls(toolCalls, tools) {
     const batches = [];
     let currentConcurrent = [];
@@ -30,7 +66,7 @@ export function partitionToolCalls(toolCalls, tools) {
     }
     return batches;
 }
-export async function executeSingleTool(toolCall, tools, context, permissionMode, askUser) {
+export async function executeSingleTool(toolCall, tools, context, permissionMode, askUser, permissionPromptTool) {
     const tool = findToolByName(tools, toolCall.toolName);
     if (!tool) {
         return { output: `Error: Unknown tool '${toolCall.toolName}'`, isError: true };
@@ -72,6 +108,34 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 const reason = hookOutcome.reason ? `: ${hookOutcome.reason}` : "";
                 return denyAndEmit("hook", hookOutcome.reason ?? "hook denied", `Permission denied by hook${reason}`);
             }
+            else if (permissionPromptTool) {
+                // No hook decision → consult the configured MCP permission tool
+                // (audit B1). Mirrors Claude Code's --permission-prompt-tool. The
+                // tool returns JSON: { "behavior": "allow" | "deny", "message"?: string }.
+                // On any failure (tool missing, throws, malformed JSON, unknown
+                // behavior) we fall through to askUser / headless deny so a broken
+                // permission tool doesn't lock the user out.
+                const promptDecision = await callPermissionPromptTool(permissionPromptTool, tools, context, tool.name, parsed.data);
+                if (promptDecision.behavior === "allow") {
+                    // Permission tool granted — proceed.
+                }
+                else if (promptDecision.behavior === "deny") {
+                    return denyAndEmit("permission-prompt-tool", promptDecision.message ?? "denied", `Permission denied by ${permissionPromptTool}${promptDecision.message ? `: ${promptDecision.message}` : ""}`);
+                }
+                else if (askUser) {
+                    // promptDecision.behavior === "fallthrough" — tool was unavailable
+                    // or its response was malformed. Try the interactive prompt next.
+                    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 denyAndEmit("user", "user declined", "Permission denied by user.");
+                    }
+                }
+                else {
+                    return denyAndEmit("headless", "permission-prompt-tool unavailable and no interactive prompt", `Permission denied: ${permissionPromptTool} did not produce a usable decision and no interactive prompt is available.`);
+                }
+            }
             else if (askUser) {
                 // "ask" or no decision → interactive prompt when available
                 const { formatToolArgs } = await import("../utils/tool-summary.js");
@@ -209,7 +273,7 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
         return { output: `Tool error: ${errMsg}`, isError: true };
     }
 }
-export async function* executeToolCalls(toolCalls, tools, context, permissionMode, askUser, state) {
+export async function* executeToolCalls(toolCalls, tools, context, permissionMode, askUser, state, permissionPromptTool) {
     const batches = partitionToolCalls(toolCalls, tools);
     const outputChunks = [];
     const onOutputChunk = (callId, chunk) => {
@@ -218,7 +282,7 @@ export async function* executeToolCalls(toolCalls, tools, context, permissionMod
     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)));
+            const results = await Promise.all(batch.calls.map((tc) => executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser, permissionPromptTool)));
             for (const chunk of outputChunks.splice(0))
                 yield chunk;
             for (let i = 0; i < batch.calls.length; i++) {
@@ -230,7 +294,7 @@ export async function* executeToolCalls(toolCalls, tools, context, permissionMod
         }
         else {
             for (const tc of batch.calls) {
-                const result = await executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser);
+                const result = await executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser, permissionPromptTool);
                 for (const chunk of outputChunks.splice(0))
                     yield chunk;
                 yield { type: "tool_call_end", callId: tc.id, output: result.output, isError: result.isError };

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/DiagnosticsTool/index.js

@@ -44,7 +44,7 @@ async function getClient(filePath, workingDir) {
 }
 export const DiagnosticsTool = {
     name: "Diagnostics",
-    description: "Get code diagnostics (errors, warnings), go-to-definition, or find-references using the language server.",
+    description: "Language Server Protocol (LSP) code intelligence — pick action: diagnostics (errors/warnings), definition (go-to-def), references (find-refs), or hover (type info / docs). Supports TypeScript, JavaScript, Python, Go, Rust.",
     inputSchema,
     riskLevel: "low",
     isReadOnly() {
@@ -101,22 +101,10 @@ export const DiagnosticsTool = {
                     return { output: "line and character are required for hover.", isError: true };
                 }
                 await client.openFile(input.file_path);
-                // Hover uses textDocument/hover which returns MarkupContent
-                try {
-                    const result = await client.send("textDocument/hover", {
-                        textDocument: { uri: `file://${input.file_path.replace(/\\/g, "/")}` },
-                        position: { line: input.line, character: input.character },
-                    });
-                    if (!result?.contents)
-                        return { output: "No hover information.", isError: false };
-                    const content = typeof result.contents === "string"
-                        ? result.contents
-                        : (result.contents.value ?? JSON.stringify(result.contents));
-                    return { output: content, isError: false };
-                }
-                catch {
-                    return { output: "Hover not supported by this language server.", isError: false };
-                }
+                const content = await client.getHover(input.file_path, input.line, input.character);
+                if (!content)
+                    return { output: "No hover information.", isError: false };
+                return { output: content, isError: false };
             }
             return { output: `Unknown action: ${input.action}`, isError: true };
         }
@@ -128,11 +116,11 @@ export const DiagnosticsTool = {
         }
     },
     prompt() {
-        return `Get code intelligence from the language server. Supports TypeScript, JavaScript, Python, Go, and Rust. Actions:
-- diagnostics: Get errors and warnings for a file
-- definition: Go to definition of a symbol at a given position
-- references: Find all references to a symbol at a given position
-- hover: Get type information and documentation for a symbol
+        return `LSP code intelligence — diagnostics, go-to-definition, find-references, hover. Supports TypeScript, JavaScript, Python, Go, Rust (a language server must be installed: typescript-language-server / pylsp / gopls / rust-analyzer). Actions:
+- diagnostics: Errors and warnings for the file
+- definition: Resolve the symbol at (line, character) to its declaration
+- references: Find all references to the symbol at (line, character)
+- hover: Type information and documentation for the symbol at (line, character)
 Parameters:
 - file_path (string, required): Absolute path to the file
 - action (string): "diagnostics" | "definition" | "references" | "hover" (default: diagnostics)

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.21.0",
+  "version": "2.22.1",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {