@zhijiewang/openharness 2.12.0 → 2.13.0

package/README.md

@@ -317,6 +317,8 @@ hooks:
 
 Use `match` to restrict a hook to a specific tool name (e.g., `match: Bash` only triggers for the Bash tool).
 
+See [docs/hooks.md](docs/hooks.md) for the full event reference including the new `userPromptSubmit`, `permissionRequest`, and `postToolUseFailure` events.
+
 ## Cybergotchi
 
 OpenHarness ships with a Tamagotchi-style companion that lives in the side panel. It reacts to your session in real time — celebrating streaks, complaining when tools fail, and getting hungry if you ignore it.

package/dist/commands/info.js

@@ -11,6 +11,7 @@ import { getContextWindow } from "../harness/cost.js";
 import { normalizeMcpConfig } from "../mcp/config-normalize.js";
 import { connectedMcpServers } from "../mcp/loader.js";
 import { getAuthStatus } from "../mcp/oauth.js";
+import { getRouteSelection } from "../providers/router.js";
 import { mcpLoginHandler, mcpLogoutHandler } from "./mcp-auth.js";
 export function registerInfoCommands(register, getCommandMap) {
     register("help", "Show available commands", () => {
@@ -45,6 +46,7 @@ export function registerInfoCommands(register, getCommandMap) {
                 "mcp-login",
                 "mcp-logout",
                 "mcp-registry",
+                "router",
                 "init",
                 "bug",
                 "feedback",
@@ -468,6 +470,24 @@ export function registerInfoCommands(register, getCommandMap) {
     register("mcp-logout", "Wipe local OAuth tokens for an MCP server", async (args) => {
         return mcpLogoutHandler(args);
     });
+    register("router", "Show the model router state", (_args, ctx) => {
+        const cfg = readOhConfig()?.modelRouter;
+        const defaultModel = ctx.model ?? "unknown";
+        if (!cfg || (!cfg.fast && !cfg.balanced && !cfg.powerful)) {
+            return { output: `Router: off (single model: ${defaultModel})`, handled: true };
+        }
+        const last = ctx.sessionId ? getRouteSelection(ctx.sessionId) : undefined;
+        const lines = [
+            "Model router:",
+            `  fast       ${cfg.fast ?? `(default: ${defaultModel})`}`,
+            `  balanced   ${cfg.balanced ?? `(default: ${defaultModel})`}`,
+            `  powerful   ${cfg.powerful ?? `(default: ${defaultModel})`}`,
+        ];
+        if (last) {
+            lines.push("", `Last selection: ${last.tier} — "${last.reason}"`);
+        }
+        return { output: lines.join("\n"), handled: true };
+    });
     register("init", "Initialize project with .oh/ config", () => {
         const ohDir = join(process.cwd(), ".oh");
         if (existsSync(ohDir)) {

package/dist/harness/config.d.ts

@@ -51,6 +51,9 @@ export type HooksConfig = {
     sessionEnd?: HookDef[];
     preToolUse?: HookDef[];
     postToolUse?: HookDef[];
+    postToolUseFailure?: HookDef[];
+    userPromptSubmit?: HookDef[];
+    permissionRequest?: HookDef[];
     fileChanged?: HookDef[];
     cwdChanged?: HookDef[];
     subagentStart?: HookDef[];

package/dist/harness/hooks.d.ts

@@ -10,7 +10,7 @@
  * - prompt: LLM yes/no check via provider.complete()
  */
 import type { HookDef } from "./config.js";
-export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse" | "fileChanged" | "cwdChanged" | "subagentStart" | "subagentStop" | "preCompact" | "postCompact" | "configChange" | "notification";
+export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse" | "postToolUseFailure" | "userPromptSubmit" | "permissionRequest" | "fileChanged" | "cwdChanged" | "subagentStart" | "subagentStop" | "preCompact" | "postCompact" | "configChange" | "notification";
 export type HookContext = {
     toolName?: string;
     toolArgs?: string;
@@ -30,6 +30,14 @@ export type HookContext = {
     agentId?: string;
     /** For notification: the message */
     message?: string;
+    /** For userPromptSubmit: the raw prompt text the user is about to submit */
+    prompt?: string;
+    /** For postToolUseFailure: short error label ("TimeoutError", "ExecutionError", "ReportedError") */
+    toolError?: string;
+    /** For postToolUseFailure: full error message */
+    errorMessage?: string;
+    /** For permissionRequest: the decision OH would take absent the hook ("ask", "allow", "deny") — informational */
+    permissionAction?: "ask" | "allow" | "deny";
 };
 /** Clear hook cache (call after config changes) */
 export declare function invalidateHookCache(): void;
@@ -58,4 +66,30 @@ export declare function emitHook(event: HookEvent, ctx?: HookContext): boolean;
  * Supports all hook types (command, HTTP, prompt).
  */
 export declare function emitHookAsync(event: HookEvent, ctx?: HookContext): Promise<boolean>;
+/** Parsed shape of a jsonIO hook's stdout JSON response. */
+export type ParsedJsonIoResponse = {
+    decision?: "allow" | "deny";
+    reason?: string;
+    additionalContext?: string;
+    permissionDecision?: "allow" | "deny" | "ask";
+};
+/** Parse a hook's stdout as a jsonIO envelope. Returns an empty object on malformed input. */
+export declare function parseJsonIoResponse(raw: string): ParsedJsonIoResponse;
+export type HookOutcome = {
+    allowed: boolean;
+    additionalContext?: string;
+    permissionDecision?: "allow" | "deny" | "ask";
+    reason?: string;
+};
+/**
+ * Emit a hook event and return a structured HookOutcome parsed from jsonIO responses.
+ *
+ * Merge semantics:
+ * - First `deny` (or `permissionDecision: "deny"`) short-circuits: {allowed: false, ...}.
+ * - `permissionDecision: "allow"` short-circuits: {allowed: true, permissionDecision: "allow"}.
+ * - `additionalContext` from multiple hooks is concatenated in order, "\n\n" separated.
+ * - For NOTIFY_ONLY_OUTCOME_EVENTS (postToolUseFailure), decision/permissionDecision
+ *   from hooks is ignored — outcome.allowed is always true. additionalContext is still collected.
+ */
+export declare function emitHookWithOutcome(event: HookEvent, ctx?: HookContext): Promise<HookOutcome>;
 //# sourceMappingURL=hooks.d.ts.map

package/dist/harness/hooks.js

@@ -56,6 +56,17 @@ function buildEnv(event, ctx) {
         env.OH_AGENT_ID = ctx.agentId;
     if (ctx.message)
         env.OH_MESSAGE = ctx.message;
+    if (ctx.prompt !== undefined) {
+        // Cap at 8KB to avoid Windows env-var length limits.
+        const PROMPT_MAX = 8 * 1024;
+        env.OH_PROMPT = ctx.prompt.length > PROMPT_MAX ? ctx.prompt.slice(0, PROMPT_MAX) : ctx.prompt;
+    }
+    if (ctx.toolError !== undefined)
+        env.OH_TOOL_ERROR = ctx.toolError;
+    if (ctx.errorMessage !== undefined)
+        env.OH_ERROR_MESSAGE = ctx.errorMessage;
+    if (ctx.permissionAction !== undefined)
+        env.OH_PERMISSION_ACTION = ctx.permissionAction;
     return env;
 }
 /**
@@ -142,20 +153,15 @@ function runCommandHookAsync(command, env, timeoutMs = 10_000) {
     });
 }
 /**
- * Run a JSON-mode command hook (Claude Code convention).
- *
- * Sends `{event, ...context}` as JSON on stdin. Parses stdout as JSON
- * `{ decision: "allow" | "deny", reason?: string, hookSpecificOutput?: any }`.
+ * Run a JSON-mode command hook and return the raw stdout string.
  *
- * Gating logic:
- *   - `decision: "deny"` → blocks (returns false).
- *   - `decision: "allow"` or omitted decision → allow (returns true).
- *   - Non-zero exit code → block.
- *   - Invalid/empty JSON on stdout → fall back to exit code (0 = allow).
- *   - Timeout or spawn error → block.
+ * Rejects (throws) on timeout or spawn error so callers can decide how to
+ * interpret the failure. Returns an empty string when stdout is empty.
+ * Rejects when the process exits with a non-zero code (callers treat this as
+ * a block).
  */
-function runJsonIoHookAsync(command, env, event, ctx, timeoutMs = 10_000) {
-    return new Promise((resolve) => {
+function runJsonIoHookCaptureStdout(command, env, event, ctx, timeoutMs = 10_000) {
+    return new Promise((resolve, reject) => {
         const proc = spawn(command, {
             shell: true,
             timeout: timeoutMs,
@@ -168,7 +174,7 @@ function runJsonIoHookAsync(command, env, event, ctx, timeoutMs = 10_000) {
             if (!settled) {
                 settled = true;
                 proc.kill();
-                resolve(false);
+                reject(new Error("hook timed out"));
             }
         }, timeoutMs);
         proc.stdout?.on("data", (chunk) => {
@@ -188,39 +194,56 @@ function runJsonIoHookAsync(command, env, event, ctx, timeoutMs = 10_000) {
                 return;
             settled = true;
             clearTimeout(timer);
-            // Non-zero exit is always a block, regardless of stdout.
             if ((code ?? 1) !== 0) {
-                resolve(false);
-                return;
-            }
-            // Empty stdout → treat exit code as the signal (allow for exit 0).
-            if (!stdoutBuf.trim()) {
-                resolve(true);
+                reject(new Error(`hook exited with code ${code ?? 1}`));
                 return;
             }
-            try {
-                const parsed = JSON.parse(stdoutBuf);
-                if (parsed.decision === "deny") {
-                    resolve(false);
-                }
-                else {
-                    resolve(true); // "allow" or omitted → allow
-                }
-            }
-            catch {
-                // Malformed JSON with a zero exit — fail closed conservatively.
-                resolve(false);
-            }
+            resolve(stdoutBuf);
         });
-        proc.on("error", () => {
+        proc.on("error", (err) => {
             if (!settled) {
                 settled = true;
                 clearTimeout(timer);
-                resolve(false);
+                reject(err);
             }
         });
     });
 }
+/**
+ * Run a JSON-mode command hook (Claude Code convention).
+ *
+ * Sends `{event, ...context}` as JSON on stdin. Parses stdout as JSON
+ * `{ decision: "allow" | "deny", reason?: string, hookSpecificOutput?: any }`.
+ *
+ * Gating logic:
+ *   - `decision: "deny"` → blocks (returns false).
+ *   - `decision: "allow"` or omitted decision → allow (returns true).
+ *   - Non-zero exit code → block.
+ *   - Invalid/empty JSON on stdout → fall back to exit code (0 = allow).
+ *   - Timeout or spawn error → block.
+ */
+async function runJsonIoHookAsync(command, env, event, ctx, timeoutMs = 10_000) {
+    let stdout;
+    try {
+        stdout = await runJsonIoHookCaptureStdout(command, env, event, ctx, timeoutMs);
+    }
+    catch {
+        // timeout, spawn error, or non-zero exit — block
+        return false;
+    }
+    // Empty stdout → treat exit code as the signal (allow for exit 0).
+    if (!stdout.trim()) {
+        return true;
+    }
+    try {
+        const parsed = JSON.parse(stdout);
+        return parsed.decision !== "deny";
+    }
+    catch {
+        // Malformed JSON with a zero exit — fail closed conservatively.
+        return false;
+    }
+}
 /** Run an HTTP hook. POSTs context as JSON, expects { allowed: true/false }. */
 async function runHttpHook(url, event, ctx, timeoutMs = 10_000) {
     try {
@@ -398,4 +421,150 @@ export async function emitHookAsync(event, ctx = {}) {
     }
     return true;
 }
+/** Parse a hook's stdout as a jsonIO envelope. Returns an empty object on malformed input. */
+export function parseJsonIoResponse(raw) {
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    if (!obj || typeof obj !== "object" || Array.isArray(obj))
+        return {};
+    const rec = obj;
+    const out = {};
+    if (rec.decision === "allow" || rec.decision === "deny")
+        out.decision = rec.decision;
+    if (typeof rec.reason === "string")
+        out.reason = rec.reason;
+    const hso = rec.hookSpecificOutput;
+    if (hso && typeof hso === "object" && !Array.isArray(hso)) {
+        const hsoRec = hso;
+        if (typeof hsoRec.additionalContext === "string")
+            out.additionalContext = hsoRec.additionalContext;
+        if (hsoRec.decision === "allow" || hsoRec.decision === "deny" || hsoRec.decision === "ask") {
+            out.permissionDecision = hsoRec.decision;
+        }
+        if (typeof hsoRec.reason === "string" && !out.reason)
+            out.reason = hsoRec.reason;
+    }
+    return out;
+}
+/** Events for which "notify-only" semantics apply — outcome.allowed is always true. */
+const NOTIFY_ONLY_OUTCOME_EVENTS = new Set(["postToolUseFailure"]);
+/**
+ * Map a command-hook's boolean (exit 0 / nonzero) result to a ParsedJsonIoResponse
+ * for the given event, applying per-event semantics:
+ *
+ * - userPromptSubmit: exit 0 → allow ({}); nonzero → deny.
+ * - permissionRequest: exit 0 → "ask" (fall through to user); nonzero → deny.
+ * - postToolUseFailure: notify-only — exit code is irrelevant, always return {}.
+ * - All other events: same as userPromptSubmit (exit 0 allow, nonzero deny).
+ */
+function mapEnvExitToOutcome(event, allowed) {
+    switch (event) {
+        case "permissionRequest":
+            return allowed
+                ? { permissionDecision: "ask" }
+                : { permissionDecision: "deny", decision: "deny", reason: "hook denied (exit code)" };
+        case "postToolUseFailure":
+            // notify-only; exit code is irrelevant
+            return {};
+        default:
+            return allowed ? {} : { decision: "deny", reason: "hook denied (exit code)" };
+    }
+}
+/**
+ * Execute a single hook definition and return a ParsedJsonIoResponse for outcome merging.
+ * Private to this module — not exported.
+ */
+async function runHookForOutcome(def, event, ctx) {
+    if (def.jsonIO && def.command) {
+        const env = buildEnv(event, ctx);
+        let raw;
+        try {
+            raw = await runJsonIoHookCaptureStdout(def.command, env, event, ctx, def.timeout ?? 10_000);
+        }
+        catch {
+            // timeout, spawn error, non-zero exit — treat as deny for gating events
+            return { decision: "deny", reason: "hook failed (timeout or non-zero exit)" };
+        }
+        if (!raw.trim()) {
+            // empty stdout with exit 0 — treat as allow (no decision)
+            return {};
+        }
+        return parseJsonIoResponse(raw);
+    }
+    if (def.command) {
+        // env-var mode — apply per-event exit-code semantics
+        const env = buildEnv(event, ctx);
+        const code = await runCommandHookAsync(def.command, env, def.timeout ?? 10_000);
+        return mapEnvExitToOutcome(event, code === 0);
+    }
+    if (def.http) {
+        const allowed = await runHttpHook(def.http, event, ctx, def.timeout ?? 10_000);
+        return mapEnvExitToOutcome(event, allowed);
+    }
+    if (def.prompt) {
+        const allowed = await runPromptHook(def.prompt, ctx, def.timeout ?? 10_000);
+        return allowed ? {} : { decision: "deny", reason: "prompt hook denied" };
+    }
+    return {};
+}
+/**
+ * Emit a hook event and return a structured HookOutcome parsed from jsonIO responses.
+ *
+ * Merge semantics:
+ * - First `deny` (or `permissionDecision: "deny"`) short-circuits: {allowed: false, ...}.
+ * - `permissionDecision: "allow"` short-circuits: {allowed: true, permissionDecision: "allow"}.
+ * - `additionalContext` from multiple hooks is concatenated in order, "\n\n" separated.
+ * - For NOTIFY_ONLY_OUTCOME_EVENTS (postToolUseFailure), decision/permissionDecision
+ *   from hooks is ignored — outcome.allowed is always true. additionalContext is still collected.
+ */
+export async function emitHookWithOutcome(event, ctx = {}) {
+    const hooks = getHooks();
+    const list = hooks?.[event];
+    if (!list || list.length === 0)
+        return { allowed: true };
+    const notifyOnly = NOTIFY_ONLY_OUTCOME_EVENTS.has(event);
+    const additionalContexts = [];
+    let reason;
+    let askSeen = false;
+    for (const def of list) {
+        if (def.match && !matchesHook(def, ctx))
+            continue;
+        const parsed = await runHookForOutcome(def, event, ctx);
+        if (!notifyOnly) {
+            if (parsed.decision === "deny" || parsed.permissionDecision === "deny") {
+                return {
+                    allowed: false,
+                    reason: parsed.reason ?? reason,
+                    permissionDecision: parsed.permissionDecision,
+                };
+            }
+            if (parsed.permissionDecision === "allow") {
+                if (parsed.additionalContext)
+                    additionalContexts.push(parsed.additionalContext);
+                return {
+                    allowed: true,
+                    permissionDecision: "allow",
+                    additionalContext: additionalContexts.length ? additionalContexts.join("\n\n") : undefined,
+                };
+            }
+            if (parsed.permissionDecision === "ask")
+                askSeen = true;
+        }
+        if (parsed.additionalContext)
+            additionalContexts.push(parsed.additionalContext);
+        if (!reason && parsed.reason)
+            reason = parsed.reason;
+    }
+    return {
+        allowed: true,
+        additionalContext: additionalContexts.length ? additionalContexts.join("\n\n") : undefined,
+        permissionDecision: askSeen ? "ask" : undefined,
+        reason,
+    };
+}
 //# sourceMappingURL=hooks.js.map

package/dist/harness/submit-handler.js

@@ -6,6 +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";
 /**
  * Process user input: handle exit, companion mentions, slash commands,
  * @mentions, and prepare the prompt for the LLM.
@@ -78,10 +79,28 @@ export async function handleUserInput(input, ctx) {
             }
             if (result.prependToPrompt) {
                 messages = [...messages, createUserMessage(input)];
+                const prependPrompt = result.prependToPrompt;
+                const prependOutcome = await emitHookWithOutcome("userPromptSubmit", {
+                    prompt: prependPrompt,
+                    sessionId: ctx.sessionId,
+                    model: ctx.currentModel,
+                    provider: ctx.providerName,
+                    permissionMode: ctx.permissionMode,
+                });
+                if (!prependOutcome.allowed) {
+                    const reason = prependOutcome.reason ? `: ${prependOutcome.reason}` : "";
+                    return {
+                        handled: true,
+                        messages: [...messages, createInfoMessage(`Blocked by userPromptSubmit hook${reason}`)],
+                    };
+                }
+                const finalPrependPrompt = prependOutcome.additionalContext
+                    ? `${prependOutcome.additionalContext}\n\n${prependPrompt}`
+                    : prependPrompt;
                 return {
                     handled: false,
                     messages,
-                    prompt: result.prependToPrompt,
+                    prompt: finalPrependPrompt,
                     newModel: result.newModel ?? undefined,
                 };
             }
@@ -136,6 +155,21 @@ export async function handleUserInput(input, ctx) {
             /* ignore */
         }
     }
-    return { handled: false, messages, prompt: resolvedInput };
+    const outcome = await emitHookWithOutcome("userPromptSubmit", {
+        prompt: resolvedInput,
+        sessionId: ctx.sessionId,
+        model: ctx.currentModel,
+        provider: ctx.providerName,
+        permissionMode: ctx.permissionMode,
+    });
+    if (!outcome.allowed) {
+        const reason = outcome.reason ? `: ${outcome.reason}` : "";
+        return {
+            handled: true,
+            messages: [...messages, createInfoMessage(`Blocked by userPromptSubmit hook${reason}`)],
+        };
+    }
+    const finalPrompt = outcome.additionalContext ? `${outcome.additionalContext}\n\n${resolvedInput}` : resolvedInput;
+    return { handled: false, messages, prompt: finalPrompt };
 }
 //# sourceMappingURL=submit-handler.js.map

package/dist/providers/fallback.js

@@ -33,20 +33,26 @@ export function createFallbackProvider(primary, fallbacks) {
             ];
             for (let i = 0; i < providers.length; i++) {
                 const p = providers[i];
+                let hasYielded = false;
                 try {
-                    let _hasYielded = false;
                     for await (const event of p.provider.stream(messages, systemPrompt, tools, p.model)) {
-                        _hasYielded = true;
+                        hasYielded = true;
                         yield event;
                     }
-                    _activeFallback = i === 0 ? null : p.provider.name;
+                    if (i > 0) {
+                        console.warn(`[provider] fell back from ${primary.name} to ${p.provider.name}`);
+                        _activeFallback = p.provider.name;
+                    }
+                    else {
+                        _activeFallback = null;
+                    }
                     return;
                 }
                 catch (err) {
-                    // Mid-stream failure: can't un-send events, propagate error
-                    if (i > 0 || !isRetriableError(err))
+                    // Mid-stream failure OR non-retriable OR fallback error: propagate.
+                    if (i > 0 || !isRetriableError(err) || hasYielded)
                         throw err;
-                    // Pre-stream failure on primary: try next provider
+                    // Pre-stream retriable failure on primary only: try next provider.
                     _activeFallback = null;
                 }
             }
@@ -63,7 +69,13 @@ export function createFallbackProvider(primary, fallbacks) {
                 const p = providers[i];
                 try {
                     const result = await p.provider.complete(messages, systemPrompt, tools, p.model);
-                    _activeFallback = i === 0 ? null : p.provider.name;
+                    if (i > 0) {
+                        console.warn(`[provider] fell back from ${primary.name} to ${p.provider.name}`);
+                        _activeFallback = p.provider.name;
+                    }
+                    else {
+                        _activeFallback = null;
+                    }
                     return result;
                 }
                 catch (err) {

package/dist/providers/index.js

@@ -1,7 +1,9 @@
 /**
  * Provider factory — create the right provider from a model string.
  */
+import { readOhConfig } from "../harness/config.js";
 import { AnthropicProvider } from "./anthropic.js";
+import { createFallbackProvider } from "./fallback.js";
 import { LlamaCppProvider } from "./llamacpp.js";
 import { OllamaProvider } from "./ollama.js";
 import { OpenAIProvider } from "./openai.js";
@@ -29,8 +31,22 @@ export async function createProvider(modelArg, overrides) {
         defaultModel: model,
         ...overrides,
     };
-    const provider = createProviderInstance(providerName, config);
-    return { provider, model };
+    const primary = createProviderInstance(providerName, config);
+    const fallbackCfgs = readOhConfig()?.fallbackProviders ?? [];
+    if (fallbackCfgs.length === 0) {
+        return { provider: primary, model };
+    }
+    const fallbacks = fallbackCfgs.map((fb) => ({
+        provider: createProviderInstance(fb.provider, {
+            name: fb.provider,
+            apiKey: fb.apiKey ?? process.env[`${fb.provider.toUpperCase()}_API_KEY`],
+            baseUrl: fb.baseUrl,
+            defaultModel: fb.model ?? model,
+        }),
+        model: fb.model,
+    }));
+    const wrapped = createFallbackProvider(primary, fallbacks);
+    return { provider: wrapped, model };
 }
 export { createProviderInstance, guessProviderFromModel };
 function createProviderInstance(name, config) {

package/dist/providers/router.d.ts

@@ -45,4 +45,8 @@ export declare class ModelRouter {
     /** Get all configured tiers */
     get tiers(): Record<ModelTier, string>;
 }
+/** Record the router's selection for a session. Keeps only the most recent 256 sessions. */
+export declare function recordRouteSelection(sessionId: string, result: RouteResult): void;
+/** Retrieve the most recent selection for a session, or undefined. */
+export declare function getRouteSelection(sessionId: string): RouteResult | undefined;
 //# sourceMappingURL=router.d.ts.map

package/dist/providers/router.js

@@ -58,4 +58,23 @@ export class ModelRouter {
         };
     }
 }
+const ROUTE_SELECTION_CAP = 256;
+const routeSelections = new Map();
+/** Record the router's selection for a session. Keeps only the most recent 256 sessions. */
+export function recordRouteSelection(sessionId, result) {
+    // Map preserves insertion order. Delete-then-set moves the key to the end,
+    // so oldest is always keys().next().
+    if (routeSelections.has(sessionId))
+        routeSelections.delete(sessionId);
+    routeSelections.set(sessionId, result);
+    if (routeSelections.size > ROUTE_SELECTION_CAP) {
+        const oldest = routeSelections.keys().next().value;
+        if (oldest !== undefined)
+            routeSelections.delete(oldest);
+    }
+}
+/** Retrieve the most recent selection for a session, or undefined. */
+export function getRouteSelection(sessionId) {
+    return routeSelections.get(sessionId);
+}
 //# sourceMappingURL=router.js.map

package/dist/query/index.js

@@ -8,7 +8,9 @@
  * - types.ts — shared types
  */
 import { DeferredTool } from "../DeferredTool.js";
+import { readOhConfig } from "../harness/config.js";
 import { getContextWindow } from "../harness/cost.js";
+import { ModelRouter } from "../providers/router.js";
 import { StreamingToolExecutor } from "../services/StreamingToolExecutor.js";
 import { toolToAPIFormat } from "../Tool.js";
 import { createAssistantMessage, createToolResultMessage, createUserMessage } from "../types/message.js";
@@ -18,8 +20,27 @@ import { isNetworkError, isOverloadError, isPromptTooLongError, isRateLimitError
 import { executeToolCalls } from "./tools.js";
 export { compressMessages } from "./compress.js";
 const DEFAULT_MAX_TURNS = 50;
+/** Rough context-usage estimate in [0, 1]. Returns undefined when tokenization is unavailable. */
+function estimateRouteContextUsage(messages, provider, model) {
+    const estimate = provider.estimateTokens?.bind(provider);
+    if (!estimate)
+        return undefined;
+    const info = provider.getModelInfo?.(model);
+    const window = info?.contextWindow;
+    if (!window || window <= 0)
+        return undefined;
+    let total = 0;
+    for (const m of messages) {
+        if (typeof m.content === "string")
+            total += estimate(m.content);
+        // Non-string content (tool calls etc.) is skipped — rough estimate only.
+    }
+    return Math.min(1, total / window);
+}
 export async function* query(userMessage, config, existingMessages = []) {
     const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
+    const routerCfg = readOhConfig()?.modelRouter ?? {};
+    const router = new ModelRouter(routerCfg, config.model ?? "");
     const toolContext = {
         workingDir: config.workingDir ?? process.cwd(),
         abortSignal: config.abortSignal,
@@ -160,7 +181,16 @@ export async function* query(userMessage, config, existingMessages = []) {
         let streamError = null;
         const streamingExecutor = new StreamingToolExecutor(config.tools, toolContext, config.permissionMode, config.askUser, config.abortSignal);
         try {
-            for await (const event of config.provider.stream(state.messages, turnPrompt, apiTools, config.model)) {
+            const ctxUsage = estimateRouteContextUsage(state.messages, config.provider, config.model ?? "");
+            const selection = router.select({
+                turn: state.turn,
+                hadToolCalls: state.lastTurnHadTools ?? false,
+                toolCallCount: state.lastTurnToolCount ?? 0,
+                contextUsage: ctxUsage,
+                isFinalResponse: (state.lastTurnHadTools === false || state.lastTurnHadTools === undefined) && state.turn > 1,
+                role: config.role,
+            });
+            for await (const event of config.provider.stream(state.messages, turnPrompt, apiTools, selection.model)) {
                 if (config.abortSignal?.aborted)
                     break;
                 switch (event.type) {
@@ -283,6 +313,8 @@ export async function* query(userMessage, config, existingMessages = []) {
         if (remaining.length > 0) {
             yield* executeToolCalls(remaining, config.tools, toolContext, config.permissionMode, config.askUser, state);
         }
+        state.lastTurnHadTools = toolCalls.length > 0;
+        state.lastTurnToolCount = toolCalls.length;
         state.transition = "next_turn";
     }
     yield { type: "turn_complete", reason: "max_turns" };

package/dist/query/tools.js

@@ -2,7 +2,7 @@
  * Tool execution — permission checking, batching, output capping.
  */
 import { createCheckpoint, getAffectedFiles } from "../harness/checkpoints.js";
-import { emitHook } from "../harness/hooks.js";
+import { emitHook, emitHookWithOutcome } from "../harness/hooks.js";
 import { findToolByName } from "../Tool.js";
 import { createToolResultMessage } from "../types/message.js";
 import { checkPermission } from "../types/permissions.js";
@@ -45,9 +45,28 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
         if (perm.reason === "needs-approval" && askUser) {
             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 };
+            // Hook: permissionRequest — fires between preToolUse and the interactive askUser prompt.
+            // Only fires when checkPermission says "needs-approval" AND askUser is provided.
+            const hookOutcome = await emitHookWithOutcome("permissionRequest", {
+                toolName: tool.name,
+                toolArgs: JSON.stringify(toolCall.arguments).slice(0, 1000),
+                toolInputJson: JSON.stringify(parsed.data).slice(0, 1000),
+                permissionMode,
+                permissionAction: "ask",
+            });
+            if (hookOutcome.permissionDecision === "allow") {
+                // Hook granted permission — skip interactive prompt and 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 };
+            }
+            else {
+                // "ask" or no decision → fall through to interactive prompt
+                const allowed = await askUser(tool.name, description, tool.riskLevel);
+                if (!allowed) {
+                    return { output: "Permission denied by user.", isError: true };
+                }
             }
         }
         else {
@@ -79,12 +98,23 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 toolAbort.addEventListener("abort", () => reject(new Error(`Tool '${tool.name}' timed out after ${TOOL_TIMEOUT_MS / 1000}s`)));
             }),
         ]);
-        // Hook: postToolUse
-        emitHook("postToolUse", {
-            toolName: tool.name,
-            toolArgs: JSON.stringify(toolCall.arguments).slice(0, 1000),
-            toolOutput: result.output.slice(0, 1000),
-        });
+        // Hook: postToolUse / postToolUseFailure (mutually exclusive — strict CC parity)
+        if (result.isError) {
+            emitHook("postToolUseFailure", {
+                toolName: tool.name,
+                toolArgs: JSON.stringify(toolCall.arguments).slice(0, 1000),
+                toolOutput: result.output.slice(0, 1000),
+                toolError: "ReportedError",
+                errorMessage: result.output.slice(0, 1000),
+            });
+        }
+        else {
+            emitHook("postToolUse", {
+                toolName: tool.name,
+                toolArgs: JSON.stringify(toolCall.arguments).slice(0, 1000),
+                toolOutput: result.output.slice(0, 1000),
+            });
+        }
         // Emit fileChanged hook for file-modifying tools
         if (!result.isError && ["Edit", "Write", "MultiEdit"].includes(tool.name)) {
             const filePaths = getAffectedFiles(tool.name, parsed.data);
@@ -141,7 +171,15 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
         return { output, isError: result.isError };
     }
     catch (err) {
-        return { output: `Tool error: ${err instanceof Error ? err.message : String(err)}`, isError: true };
+        const errMsg = err instanceof Error ? err.message : String(err);
+        const errName = err instanceof Error ? err.name : "ExecutionError";
+        emitHook("postToolUseFailure", {
+            toolName: tool.name,
+            toolArgs: JSON.stringify(toolCall.arguments).slice(0, 1000),
+            errorMessage: errMsg,
+            toolError: errName,
+        });
+        return { output: `Tool error: ${errMsg}`, isError: true };
     }
 }
 export async function* executeToolCalls(toolCalls, tools, context, permissionMode, askUser, state) {

package/dist/query/types.d.ts

@@ -20,6 +20,8 @@ export type QueryConfig = {
     workingDir?: string;
     /** Auto-commit after each file-modifying tool */
     gitCommitPerTool?: boolean;
+    /** For sub-agent invocations: the agent role name (feeds into the model router). */
+    role?: string;
 };
 export type TransitionReason = "next_turn" | "retry_network" | "retry_prompt_too_long" | "retry_max_output_tokens";
 export type QueryLoopState = {
@@ -33,5 +35,9 @@ export type QueryLoopState = {
     promptTooLongRetries?: number;
     /** Track consecutive compression failures for circuit breaker */
     compressionFailures?: number;
+    /** Whether the previous turn made any tool calls (feeds ModelRouter) */
+    lastTurnHadTools?: boolean;
+    /** Number of tool calls in the previous turn (feeds ModelRouter) */
+    lastTurnToolCount?: number;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/tools/AgentTool/index.js

@@ -99,7 +99,7 @@ export const AgentTool = {
             const runAgent = async () => {
                 let finalText = "";
                 try {
-                    for await (const event of query(input.prompt, config)) {
+                    for await (const event of query(input.prompt, { ...config, role: role?.id })) {
                         if (event.type === "text_delta")
                             finalText += event.content;
                     }
@@ -137,7 +137,7 @@ export const AgentTool = {
         let finalText = "";
         try {
             try {
-                for await (const event of query(input.prompt, config)) {
+                for await (const event of query(input.prompt, { ...config, role: role?.id })) {
                     if (event.type === "text_delta") {
                         finalText += event.content;
                     }

package/dist/tools/ScheduleWakeupTool/index.d.ts

@@ -5,12 +5,12 @@ declare const inputSchema: z.ZodObject<{
     reason: z.ZodString;
     prompt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    prompt: string;
     reason: string;
+    prompt: string;
     delaySeconds: number;
 }, {
-    prompt: string;
     reason: string;
+    prompt: string;
     delaySeconds: number;
 }>;
 /**

package/package.json

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