@zhijiewang/openharness 2.15.0 → 2.16.0

package/dist/harness/config.d.ts

@@ -62,6 +62,10 @@ export type HooksConfig = {
     postCompact?: HookDef[];
     configChange?: HookDef[];
     notification?: HookDef[];
+    /** Fires at the start of each top-level agent turn (after a user prompt is accepted, before model call). */
+    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[];
 };
 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 } from "./config.js";
-export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse" | "postToolUseFailure" | "userPromptSubmit" | "permissionRequest" | "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" | "turnStart" | "turnStop";
 export type HookContext = {
     toolName?: string;
     toolArgs?: string;
@@ -38,6 +38,10 @@ export type HookContext = {
     errorMessage?: string;
     /** For permissionRequest: the decision OH would take absent the hook ("ask", "allow", "deny") — informational */
     permissionAction?: "ask" | "allow" | "deny";
+    /** For turnStart/turnStop: zero-indexed turn number within the current session */
+    turnNumber?: string;
+    /** For turnStop: reason the turn ended ("completed", "max_turns", "error", "interrupted") */
+    turnReason?: string;
 };
 /** Clear hook cache (call after config changes) */
 export declare function invalidateHookCache(): void;
@@ -92,4 +96,22 @@ export type HookOutcome = {
  *   from hooks is ignored — outcome.allowed is always true. additionalContext is still collected.
  */
 export declare function emitHookWithOutcome(event: HookEvent, ctx?: HookContext): Promise<HookOutcome>;
+export type HookDecisionNotification = {
+    event: HookEvent;
+    /** Present when the hook fired in a tool-specific context. */
+    tool?: string;
+    /** The effective decision. "ask" means defer to the user / default permission flow. */
+    decision: "allow" | "deny" | "ask";
+    /** Reason returned by the hook, if any. */
+    reason?: string;
+};
+type HookDecisionObserver = (n: HookDecisionNotification) => void;
+/**
+ * Register (or clear) a single observer that receives one notification per
+ * `emitHookWithOutcome` call that produces a decision. Used by
+ * `oh run --output-format stream-json` to emit `hook_decision` NDJSON events
+ * so the Python SDK can surface permission outcomes in real time.
+ */
+export declare function setHookDecisionObserver(cb: HookDecisionObserver | null): void;
+export {};
 //# sourceMappingURL=hooks.d.ts.map

package/dist/harness/hooks.js

@@ -67,6 +67,10 @@ function buildEnv(event, ctx) {
         env.OH_ERROR_MESSAGE = ctx.errorMessage;
     if (ctx.permissionAction !== undefined)
         env.OH_PERMISSION_ACTION = ctx.permissionAction;
+    if (ctx.turnNumber !== undefined)
+        env.OH_TURN_NUMBER = ctx.turnNumber;
+    if (ctx.turnReason !== undefined)
+        env.OH_TURN_REASON = ctx.turnReason;
     return env;
 }
 /**
@@ -263,6 +267,50 @@ async function runHttpHook(url, event, ctx, timeoutMs = 10_000) {
         return false;
     }
 }
+/**
+ * Run an HTTP hook and return its full structured response. POSTs `{event, ...ctx}`
+ * as JSON and parses the response body with the same jsonIO envelope shape used
+ * by command hooks:
+ *   { decision?: "allow" | "deny", reason?: string,
+ *     hookSpecificOutput?: { decision?: "allow" | "deny" | "ask", reason?, additionalContext? } }
+ *
+ * Also honors a legacy `{ allowed: boolean }` shape (downgrades to decision).
+ *
+ * Network errors / non-2xx responses / malformed JSON all return a "deny" outcome
+ * so the caller can fail closed.
+ */
+async function runHttpHookDetailed(url, event, ctx, timeoutMs = 10_000) {
+    try {
+        const body = JSON.stringify({ event, ...ctx });
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return { decision: "deny", reason: `hook HTTP ${res.status}` };
+        const text = await res.text();
+        if (!text.trim())
+            return {};
+        const parsed = parseJsonIoResponse(text);
+        // If the response only used the legacy `{ allowed: false }` shape, surface as deny.
+        if (!parsed.decision && !parsed.permissionDecision) {
+            try {
+                const legacy = JSON.parse(text);
+                if (legacy.allowed === false)
+                    return { decision: "deny", reason: "hook denied" };
+            }
+            catch {
+                // already handled by parseJsonIoResponse
+            }
+        }
+        return parsed;
+    }
+    catch {
+        return { decision: "deny", reason: "hook HTTP error" };
+    }
+}
 /**
  * Run a prompt hook. Uses an LLM to make a yes/no allow/deny decision.
  *
@@ -503,8 +551,7 @@ async function runHookForOutcome(def, event, ctx) {
         return mapEnvExitToOutcome(event, code === 0);
     }
     if (def.http) {
-        const allowed = await runHttpHook(def.http, event, ctx, def.timeout ?? 10_000);
-        return mapEnvExitToOutcome(event, allowed);
+        return await runHttpHookDetailed(def.http, event, ctx, def.timeout ?? 10_000);
     }
     if (def.prompt) {
         const allowed = await runPromptHook(def.prompt, ctx, def.timeout ?? 10_000);
@@ -537,20 +584,24 @@ export async function emitHookWithOutcome(event, ctx = {}) {
         const parsed = await runHookForOutcome(def, event, ctx);
         if (!notifyOnly) {
             if (parsed.decision === "deny" || parsed.permissionDecision === "deny") {
-                return {
+                const outcome = {
                     allowed: false,
                     reason: parsed.reason ?? reason,
                     permissionDecision: parsed.permissionDecision,
                 };
+                notifyHookDecision(event, ctx, outcome);
+                return outcome;
             }
             if (parsed.permissionDecision === "allow") {
                 if (parsed.additionalContext)
                     additionalContexts.push(parsed.additionalContext);
-                return {
+                const outcome = {
                     allowed: true,
                     permissionDecision: "allow",
                     additionalContext: additionalContexts.length ? additionalContexts.join("\n\n") : undefined,
                 };
+                notifyHookDecision(event, ctx, outcome);
+                return outcome;
             }
             if (parsed.permissionDecision === "ask")
                 askSeen = true;
@@ -560,11 +611,43 @@ export async function emitHookWithOutcome(event, ctx = {}) {
         if (!reason && parsed.reason)
             reason = parsed.reason;
     }
-    return {
+    const outcome = {
         allowed: true,
         additionalContext: additionalContexts.length ? additionalContexts.join("\n\n") : undefined,
         permissionDecision: askSeen ? "ask" : undefined,
         reason,
     };
+    notifyHookDecision(event, ctx, outcome);
+    return outcome;
+}
+let hookDecisionObserver = null;
+/**
+ * Register (or clear) a single observer that receives one notification per
+ * `emitHookWithOutcome` call that produces a decision. Used by
+ * `oh run --output-format stream-json` to emit `hook_decision` NDJSON events
+ * so the Python SDK can surface permission outcomes in real time.
+ */
+export function setHookDecisionObserver(cb) {
+    hookDecisionObserver = cb;
+}
+function notifyHookDecision(event, ctx, outcome) {
+    if (!hookDecisionObserver)
+        return;
+    // Prefer the richer permissionDecision when present; fall back to deny if the hook blocked.
+    let decision = outcome.permissionDecision;
+    if (!decision) {
+        if (!outcome.allowed)
+            decision = "deny";
+        else if (outcome.reason)
+            decision = "allow";
+    }
+    if (!decision)
+        return;
+    try {
+        hookDecisionObserver({ event, tool: ctx.toolName, decision, reason: outcome.reason });
+    }
+    catch {
+        // Observer errors must not break the hook pipeline.
+    }
 }
 //# sourceMappingURL=hooks.js.map

package/dist/main.js

@@ -16,7 +16,7 @@ import { join } from "node:path";
 import { Command, Option } from "commander";
 import { render } from "ink";
 import { readOhConfig } from "./harness/config.js";
-import { emitHook } from "./harness/hooks.js";
+import { emitHook, setHookDecisionObserver } from "./harness/hooks.js";
 import { loadActiveMemories, memoriesToPrompt, userProfileToPrompt } from "./harness/memory.js";
 import { detectProject, projectContextToPrompt } from "./harness/onboarding.js";
 import { discoverSkills, skillsToPrompt } from "./harness/plugins.js";
@@ -189,6 +189,26 @@ program
     let fullOutput = "";
     const toolResults = [];
     const callIdToName = {};
+    if (outputFormat === "stream-json") {
+        setHookDecisionObserver((n) => {
+            console.log(JSON.stringify({
+                type: "hook_decision",
+                event: n.event,
+                tool: n.tool,
+                decision: n.decision,
+                reason: n.reason,
+            }));
+        });
+    }
+    emitHook("turnStart", {
+        turnNumber: "0",
+        model,
+        provider: typeof config.provider === "string" ? config.provider : undefined,
+        permissionMode,
+    });
+    if (outputFormat === "stream-json") {
+        console.log(JSON.stringify({ type: "turnStart", turnNumber: 0 }));
+    }
     for await (const event of query(prompt, config)) {
         if (event.type === "text_delta") {
             fullOutput += event.content;
@@ -245,6 +265,10 @@ program
             if (outputFormat === "stream-json") {
                 console.log(JSON.stringify({ type: "turn_complete", reason: event.reason }));
             }
+            emitHook("turnStop", { turnNumber: "0", turnReason: event.reason, model, permissionMode });
+            if (outputFormat === "stream-json") {
+                console.log(JSON.stringify({ type: "turnStop", turnNumber: 0, reason: event.reason }));
+            }
             if (event.reason !== "completed") {
                 process.exitCode = 1;
             }
@@ -304,6 +328,20 @@ program
     };
     // Conversation history, shared across all prompts for this process.
     const conversation = [];
+    let turnCounter = 0;
+    // Will be set to the current prompt id before each turn so hook_decision
+    // events can be demultiplexed by the client.
+    let activePromptId = "";
+    setHookDecisionObserver((n) => {
+        console.log(JSON.stringify({
+            id: activePromptId,
+            type: "hook_decision",
+            event: n.event,
+            tool: n.tool,
+            decision: n.decision,
+            reason: n.reason,
+        }));
+    });
     // Announce readiness so the client can send the first prompt.
     console.log(JSON.stringify({ type: "ready" }));
     const readline = await import("node:readline");
@@ -333,6 +371,16 @@ program
         const turnToolCalls = [];
         const callIdToName = {};
         const toolResults = [];
+        const turnIdx = turnCounter++;
+        const turnNumber = String(turnIdx);
+        activePromptId = id;
+        emitHook("turnStart", {
+            turnNumber,
+            model,
+            provider: typeof config.provider === "string" ? config.provider : undefined,
+            permissionMode,
+        });
+        console.log(JSON.stringify({ id, type: "turnStart", turnNumber: turnIdx }));
         for await (const event of query(prompt, config, conversation)) {
             if (event.type === "text_delta") {
                 assistantText += event.content;
@@ -374,6 +422,8 @@ program
             }
             else if (event.type === "turn_complete") {
                 console.log(JSON.stringify({ id, type: "turn_complete", reason: event.reason }));
+                emitHook("turnStop", { turnNumber, turnReason: event.reason, model, permissionMode });
+                console.log(JSON.stringify({ id, type: "turnStop", turnNumber: turnIdx, reason: event.reason }));
             }
         }
         // Rebuild this turn's contribution to the conversation.

package/package.json

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