@zhijiewang/openharness 2.15.0 → 2.17.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;
@@ -148,6 +152,13 @@ export type OhConfig = {
 };
 /** Clear cached config (call after writes or to force re-read) */
 export declare function invalidateConfigCache(): void;
-export declare function readOhConfig(root?: string): OhConfig | null;
+export type SettingSource = "user" | "project" | "local";
+export declare function readOhConfig(root?: string, sources?: readonly SettingSource[]): OhConfig | null;
+/**
+ * Parse the `--setting-sources` CLI flag (comma-separated source names).
+ * Returns `undefined` when the flag is absent or empty (caller uses defaults).
+ * Unknown names are silently dropped.
+ */
+export declare function parseSettingSources(raw: string | undefined): SettingSource[] | undefined;
 export declare function writeOhConfig(cfg: OhConfig, root?: string): void;
 //# sourceMappingURL=config.d.ts.map

package/dist/harness/config.js

@@ -34,50 +34,72 @@ function readGlobalConfig() {
         return null;
     }
 }
-export function readOhConfig(root) {
+const ALL_SOURCES = ["user", "project", "local"];
+export function readOhConfig(root, sources) {
     const effectiveRoot = root ?? ".";
-    if (_configCache !== undefined && _configCacheRoot === effectiveRoot)
+    // Only cache when merging the full default set. Callers that pass a subset
+    // are expressing a request-scoped intent and shouldn't poison the cache.
+    const usingDefaults = sources === undefined;
+    if (usingDefaults && _configCache !== undefined && _configCacheRoot === effectiveRoot)
         return _configCache;
-    const p = configPath(root);
-    // Layer 1: Global defaults from ~/.oh/config.yaml
-    const globalCfg = readGlobalConfig();
-    // Layer 2: Project config from .oh/config.yaml
+    const enabled = new Set(sources ?? ALL_SOURCES);
+    // Layer 1: Global defaults from ~/.oh/config.yaml (source: "user")
+    const globalCfg = enabled.has("user") ? readGlobalConfig() : null;
+    // Layer 2: Project config from .oh/config.yaml (source: "project")
     let projectCfg = null;
-    if (existsSync(p)) {
-        try {
-            projectCfg = parse(readFileSync(p, "utf-8"));
-        }
-        catch {
-            /* ignore malformed project config */
+    if (enabled.has("project")) {
+        const p = configPath(root);
+        if (existsSync(p)) {
+            try {
+                projectCfg = parse(readFileSync(p, "utf-8"));
+            }
+            catch {
+                /* ignore malformed project config */
+            }
         }
     }
-    // If neither exists, no config
-    if (!globalCfg && !projectCfg) {
-        _configCache = null;
-        _configCacheRoot = effectiveRoot;
-        return null;
-    }
-    // Merge: global → project (project overrides global)
-    const base = { ...globalCfg, ...projectCfg };
-    // Layer 3: Local overrides from .oh/config.local.yaml (gitignored personal settings)
-    const localPath = join(root ?? ".", ".oh", "config.local.yaml");
-    if (existsSync(localPath)) {
-        try {
-            const local = parse(readFileSync(localPath, "utf-8"));
-            if (local) {
-                const merged = { ...base, ...local };
-                _configCache = merged;
-                _configCacheRoot = effectiveRoot;
-                return merged;
+    // Layer 3: Local overrides from .oh/config.local.yaml (source: "local")
+    let localCfg = null;
+    if (enabled.has("local")) {
+        const localPath = join(root ?? ".", ".oh", "config.local.yaml");
+        if (existsSync(localPath)) {
+            try {
+                localCfg = parse(readFileSync(localPath, "utf-8"));
+            }
+            catch {
+                /* ignore malformed local config */
             }
         }
-        catch {
-            /* ignore malformed local config */
+    }
+    if (!globalCfg && !projectCfg && !localCfg) {
+        if (usingDefaults) {
+            _configCache = null;
+            _configCacheRoot = effectiveRoot;
         }
+        return null;
+    }
+    // Precedence: local > project > user
+    const merged = { ...(globalCfg ?? {}), ...(projectCfg ?? {}), ...(localCfg ?? {}) };
+    if (usingDefaults) {
+        _configCache = merged;
+        _configCacheRoot = effectiveRoot;
     }
-    _configCache = base;
-    _configCacheRoot = effectiveRoot;
-    return base;
+    return merged;
+}
+/**
+ * Parse the `--setting-sources` CLI flag (comma-separated source names).
+ * Returns `undefined` when the flag is absent or empty (caller uses defaults).
+ * Unknown names are silently dropped.
+ */
+export function parseSettingSources(raw) {
+    if (!raw)
+        return undefined;
+    const valid = new Set(["user", "project", "local"]);
+    const out = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => valid.has(s));
+    return out.length > 0 ? out : undefined;
 }
 export function writeOhConfig(cfg, root) {
     invalidateConfigCache();

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

@@ -15,8 +15,8 @@ import { homedir } from "node:os";
 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 { parseSettingSources, readOhConfig } from "./harness/config.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";
@@ -120,6 +120,8 @@ program
     .option("--append-system-prompt <text>", "Append text to the system prompt")
     .option("--allowed-tools <tools>", "Comma-separated list of allowed tools")
     .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.")
     .action(async (promptArg, opts) => {
     // Read from stdin if prompt is "-" or omitted and stdin is not a TTY
     let prompt;
@@ -137,7 +139,8 @@ program
     else {
         prompt = promptArg;
     }
-    const savedConfig = readOhConfig();
+    const settingSources = parseSettingSources(opts.settingSources);
+    const savedConfig = readOhConfig(undefined, settingSources);
     const permissionMode = (opts.trust
         ? "trust"
         : opts.deny
@@ -189,7 +192,50 @@ program
     let fullOutput = "";
     const toolResults = [];
     const callIdToName = {};
-    for await (const event of query(prompt, config)) {
+    // Resume a saved session if --resume <id> was passed. Replays its message
+    // 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.
+    let priorMessages;
+    let sessionId;
+    if (opts.resume) {
+        const { loadSession } = await import("./harness/session.js");
+        try {
+            const src = loadSession(opts.resume);
+            priorMessages = src.messages;
+            sessionId = src.id;
+        }
+        catch {
+            process.stderr.write(`Error: could not load session '${opts.resume}'\n`);
+            process.exit(1);
+        }
+    }
+    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 }));
+        }
+        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, priorMessages)) {
         if (event.type === "text_delta") {
             fullOutput += event.content;
             if (outputFormat === "text")
@@ -245,6 +291,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;
             }
@@ -269,8 +319,11 @@ program
     .option("--disallowed-tools <tools>", "Comma-separated disallowed tool names")
     .option("--max-turns <n>", "Maximum turns per prompt", "20")
     .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).")
     .action(async (opts) => {
-    const savedConfig = readOhConfig();
+    const settingSources = parseSettingSources(opts.settingSources);
+    const savedConfig = readOhConfig(undefined, settingSources);
     const permissionMode = (opts.permissionMode ??
         savedConfig?.permissionMode ??
         "trust");
@@ -303,9 +356,37 @@ program
         model,
     };
     // Conversation history, shared across all prompts for this process.
+    // Seeded from a prior session when --resume <id> is passed.
     const conversation = [];
+    let sessionId;
+    if (opts.resume) {
+        const { loadSession } = await import("./harness/session.js");
+        try {
+            const src = loadSession(opts.resume);
+            conversation.push(...src.messages);
+            sessionId = src.id;
+        }
+        catch {
+            console.log(JSON.stringify({ type: "error", message: `could not load session '${opts.resume}'` }));
+            return;
+        }
+    }
+    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" }));
+    console.log(JSON.stringify({ type: "ready", sessionId }));
     const readline = await import("node:readline");
     const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
     for await (const rawLine of rl) {
@@ -333,6 +414,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 +465,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/dist/tools/MemoryTool/index.d.ts

@@ -11,7 +11,7 @@ declare const inputSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     action: "search" | "save" | "list";
     content?: string | undefined;
-    type?: "user" | "convention" | "preference" | "project" | "debugging" | "feedback" | "reference" | undefined;
+    type?: "user" | "project" | "convention" | "preference" | "debugging" | "feedback" | "reference" | undefined;
     name?: string | undefined;
     description?: string | undefined;
     global?: boolean | undefined;
@@ -19,7 +19,7 @@ declare const inputSchema: z.ZodObject<{
 }, {
     action: "search" | "save" | "list";
     content?: string | undefined;
-    type?: "user" | "convention" | "preference" | "project" | "debugging" | "feedback" | "reference" | undefined;
+    type?: "user" | "project" | "convention" | "preference" | "debugging" | "feedback" | "reference" | undefined;
     name?: string | undefined;
     description?: string | undefined;
     global?: boolean | undefined;

package/package.json

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