oh-my-harness 0.12.0 → 0.13.0

package/README.md

@@ -89,7 +89,7 @@ your-project/
 │   ├── settings.json                  # Claude permissions + hooks → .omh/hooks/*.sh
 │   └── oh-my-harness.json             # Harness init/sync state
 └── .codex/
-    ├── config.toml                    # [features] codex_hooks = true, goals = true
+    ├── config.toml                    # [features] hooks = true, goals = true
     └── hooks.json                     # Codex hooks → .omh/hooks/*.sh (same scripts)
 ```
 
@@ -195,6 +195,7 @@ All enforcement is powered by **catalog blocks** — reusable, parameterized hoo
 hooks:
   - block: branch-guard
   - block: tdd-guard
+    mode: ask          # ask for approval instead of hard-blocking (Claude)
   - block: commit-test-gate
     params:
       testCommand: "npx vitest run"
@@ -217,6 +218,20 @@ hooks:
       baseBranch: main
 ```
 
+#### `mode`: block vs. ask
+
+Any blocking hook accepts an optional `mode` (default `block`):
+
+- **`block`** — hard-blocks the tool call. The agent cannot proceed.
+- **`ask`** — escalates to the user for approval instead of blocking outright.
+  - **Claude Code**: shows a native permission prompt (`permissionDecision: "ask"`).
+  - **Codex**: `ask` is **not** supported, so the hook falls back to a hard
+    block — your guardrail is never silently downgraded to "allow". The same
+    generated script detects the calling runtime and responds accordingly.
+
+`mode: ask` only applies to blocks that can block (`canBlock: true`); setting it
+on a non-blocking block (e.g. `lint-on-save`) is reported and ignored.
+
 ---
 
 ## 🖥️ Commands
@@ -402,8 +417,8 @@ oh-my-harness/
 - [x] Codex emitter — `AGENTS.md` + `.codex/hooks.json` + `.codex/config.toml`
 - [x] Unified `.omh/` layout — single source of truth for hooks & state across runtimes
 - [ ] Cursor (`.cursor/rules/`) emitter
-- [ ] PI (Process Isolation) emitter — sandboxed tool execution
-- [ ] `ask` mode — request approval before executing risky tools
+- [ ] Pi ([pi.dev](https://pi.dev)) emitter — generate harness config for the Pi coding agent
+- [x] `ask` mode — request approval before executing risky tools (Claude; Codex falls back to block)
 - [ ] Community harness.yaml registry — share and reuse configs
 - [ ] `omh modify "change X"` — NL config editing
 

package/dist/catalog/converter.d.ts

@@ -4,6 +4,7 @@ export interface HookConfigEntry {
     type: "command";
     command: string;
     matcher?: string;
+    mode?: "block" | "ask";
 }
 export interface ConvertResult {
     hooksConfig: Record<string, HookConfigEntry[]>;

package/dist/catalog/converter.js

@@ -31,9 +31,18 @@ export async function convertHookEntries(entries, registry, _projectDir) {
         const scriptName = count === 0 ? `${entry.block}.sh` : `${entry.block}-${count}.sh`;
         const scriptPath = `${OMH_HOOKS_DIR}/${scriptName}`;
         scripts.set(scriptPath, scriptContent);
+        // Resolve ask/block mode. "ask" only makes sense for blocks that can
+        // block a tool call; for non-blocking blocks it is meaningless, so warn
+        // and fall back to "block" rather than emitting a no-op ask.
+        let mode = entry.mode ?? "block";
+        if (mode === "ask" && !block.canBlock) {
+            errors.push(`Block "${entry.block}" does not support ask mode (canBlock=false); falling back to block.`);
+            mode = "block";
+        }
         const hookEntry = {
             type: "command",
             command: scriptPath,
+            mode,
         };
         if (block.matcher) {
             hookEntry.matcher = block.matcher;

package/dist/catalog/types.d.ts

@@ -23,6 +23,7 @@ export interface BuildingBlock {
 export interface HookEntry {
     block: string;
     params: Record<string, unknown>;
+    mode?: "block" | "ask";
 }
 export declare const ParamDefinitionSchema: z.ZodObject<{
     name: z.ZodString;
@@ -110,10 +111,13 @@ export declare const BuildingBlockSchema: z.ZodObject<{
 export declare const HookEntrySchema: z.ZodObject<{
     block: z.ZodString;
     params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    mode: z.ZodDefault<z.ZodEnum<["block", "ask"]>>;
 }, "strip", z.ZodTypeAny, {
-    params: Record<string, unknown>;
     block: string;
+    params: Record<string, unknown>;
+    mode: "block" | "ask";
 }, {
     block: string;
     params?: Record<string, unknown> | undefined;
+    mode?: "block" | "ask" | undefined;
 }>;

package/dist/catalog/types.js

@@ -21,4 +21,5 @@ export const BuildingBlockSchema = z.object({
 export const HookEntrySchema = z.object({
     block: z.string(),
     params: z.record(z.unknown()).default({}),
+    mode: z.enum(["block", "ask"]).default("block"),
 });

package/dist/cli/commands/doctor.js

@@ -68,8 +68,10 @@ export async function doctorCommand(options = {}) {
         JSON.parse(await fs.readFile(codexHooksPath, "utf-8"));
         const tomlRaw = await fs.readFile(codexTomlPath, "utf-8");
         const parsed = parse(tomlRaw);
-        if (parsed.features?.codex_hooks !== true) {
-            messages.push("FAIL: .codex/config.toml missing [features] codex_hooks = true.");
+        if (parsed.features?.hooks !== true) {
+            messages.push(parsed.features?.codex_hooks === true
+                ? "FAIL: .codex/config.toml uses deprecated [features] codex_hooks; run `omh sync` to migrate to hooks = true."
+                : "FAIL: .codex/config.toml missing [features] hooks = true.");
         }
         else if (parsed.features?.goals !== true) {
             messages.push("FAIL: .codex/config.toml missing [features] goals = true.");

package/dist/core/harness-converter-v2.js

@@ -90,6 +90,7 @@ export async function harnessToMergedConfigV2(harness, registry, projectDir) {
                 matcher: entry.matcher ?? "",
                 description: `Catalog block: ${blockId}`,
                 inline: catalogResult.scripts.get(entry.command),
+                mode: entry.mode ?? "block",
             };
             additionalHooks[field].push(hookDef);
         }

package/dist/core/harness-schema.d.ts

@@ -104,12 +104,15 @@ export declare const HarnessConfigSchema: z.ZodObject<{
     hooks: z.ZodDefault<z.ZodArray<z.ZodObject<{
         block: z.ZodString;
         params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        mode: z.ZodDefault<z.ZodEnum<["block", "ask"]>>;
     }, "strip", z.ZodTypeAny, {
-        params: Record<string, unknown>;
         block: string;
+        params: Record<string, unknown>;
+        mode: "block" | "ask";
     }, {
         block: string;
         params?: Record<string, unknown> | undefined;
+        mode?: "block" | "ask" | undefined;
     }>, "many">>;
     permissions: z.ZodDefault<z.ZodObject<{
         allow: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
@@ -123,8 +126,9 @@ export declare const HarnessConfigSchema: z.ZodObject<{
     }>>;
 }, "strip", z.ZodTypeAny, {
     hooks: {
-        params: Record<string, unknown>;
         block: string;
+        params: Record<string, unknown>;
+        mode: "block" | "ask";
     }[];
     permissions: {
         allow: string[];
@@ -167,6 +171,7 @@ export declare const HarnessConfigSchema: z.ZodObject<{
     hooks?: {
         block: string;
         params?: Record<string, unknown> | undefined;
+        mode?: "block" | "ask" | undefined;
     }[] | undefined;
     permissions?: {
         allow?: string[] | undefined;

package/dist/core/merged-config.d.ts

@@ -5,6 +5,7 @@ export interface HookDefinition {
     script?: string;
     inline?: string;
     variables?: Record<string, unknown>;
+    mode?: "block" | "ask";
 }
 export interface ClaudeMdSection {
     id: string;

package/dist/generators/codex-config.js

@@ -10,14 +10,18 @@ const CODEX_SUPPORTED_EVENTS = new Set([
     "Stop",
 ]);
 const CODEX_CONFIG_HEADER = "# Managed by oh-my-harness.\n" +
-    "# The codex_hooks=true entry under [features] is required for Codex hooks.\n" +
+    "# The hooks=true entry under [features] is required for Codex hooks.\n" +
     "# The goals=true entry under [features] enables Codex /goal.\n" +
     "# Add your own tables (e.g. [mcp_servers.foo]) above or below freely.\n" +
     "# https://github.com/kyu1204/oh-my-harness\n\n";
 const REQUIRED_CODEX_FEATURES = {
-    codex_hooks: true,
+    hooks: true,
     goals: true,
 };
+// Feature flags Codex has deprecated. We strip these on every sync so a
+// previously-generated config.toml stops emitting Codex's deprecation warning
+// (`[features].codex_hooks is deprecated. Use [features].hooks instead.`).
+const DEPRECATED_CODEX_FEATURES = ["codex_hooks"];
 function normalizeMatcher(matcher) {
     if (!matcher)
         return matcher;
@@ -78,6 +82,11 @@ export function buildCodexConfigToml(existing) {
     // array — only treat it as an existing table when it actually is one.
     const isPlainObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
     const features = isPlainObject(data.features) ? data.features : {};
+    // Strip deprecated flags first so a config generated by an older
+    // oh-my-harness (which wrote codex_hooks) migrates cleanly to the new key.
+    for (const deprecated of DEPRECATED_CODEX_FEATURES) {
+        delete features[deprecated];
+    }
     for (const [feature, enabled] of Object.entries(REQUIRED_CODEX_FEATURES)) {
         features[feature] = enabled;
     }

package/dist/generators/hooks.d.ts

@@ -1,5 +1,5 @@
 import type { MergedConfig } from "../core/merged-config.js";
-export declare function wrapWithLogger(script: string, event?: string, projectDir?: string): string;
+export declare function wrapWithLogger(script: string, event?: string, projectDir?: string, mode?: "block" | "ask"): string;
 export interface GenerateHooksOptions {
     projectDir: string;
     config: MergedConfig;

package/dist/generators/hooks.js

@@ -7,7 +7,7 @@ import { OMH_HOOKS_DIR, OMH_STATE_DIR, OMH_MANIFEST, OMH_EVENTS_FILE } from "../
 function shellSingleQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-function buildLoggerSnippet(event, projectDir) {
+function buildLoggerSnippet(event, projectDir, mode = "block") {
     const stateDir = projectDir
         ? `${projectDir}/${OMH_STATE_DIR}`
         : OMH_STATE_DIR;
@@ -16,6 +16,7 @@ _OMH_STATE_DIR=${shellSingleQuote(stateDir)}
 mkdir -p "$_OMH_STATE_DIR" 2>/dev/null || true
 _OMH_HOOK_NAME="$(basename "$0")"
 _OMH_EVENT="${event}"
+_OMH_DECISION_MODE="${mode}"
 _OMH_LOGGED=0
 _log_event() {
   # Build the JSONL record entirely through jq so every string field is
@@ -52,16 +53,32 @@ _log_event() {
 # via echo "{...}" — a file name or pattern containing a quote, backslash,
 # or newline would otherwise produce invalid JSON that the runtime cannot
 # parse as a block decision.
+#
+# In ask mode the same hook escalates to the user instead of hard-blocking,
+# but only on runtimes that understand a permissionDecision:"ask" response.
+# Claude's PreToolUse payload carries a transcript_path field; Codex's does
+# not. A runtime we cannot positively identify as Claude falls through to a
+# hard block, so a guardrail (e.g. TDD) is never silently downgraded to allow.
+# The two requirements (Claude=ask, Codex=block) cannot coexist in one JSON —
+# a legacy {decision:"block"} overrides permissionDecision:"ask" on Claude —
+# so we branch on the caller instead of emitting a combined object.
 _emit_decision() {
   local decision="\${1:-block}" reason="\${2:-}"
+  if [ "\${_OMH_DECISION_MODE:-block}" = "ask" ] && [ "$decision" = "block" ]; then
+    if printf '%s' "\${INPUT:-}" | jq -e 'has("transcript_path")' >/dev/null 2>&1; then
+      jq -cn --arg reason "$reason" --arg event "$_OMH_EVENT" \\
+        '{hookSpecificOutput:{hookEventName:$event,permissionDecision:"ask",permissionDecisionReason:$reason}}'
+      return 0
+    fi
+  fi
   jq -cn --arg decision "$decision" --arg reason "$reason" \\
     '{decision:$decision,reason:$reason}'
 }
 trap '_OMH_EXIT_CODE=$?; if [ "$_OMH_LOGGED" -eq 0 ]; then if [ "$_OMH_EXIT_CODE" -ne 0 ]; then _log_event "error" "hook exited with code $_OMH_EXIT_CODE"; else _log_event "allow"; fi; fi' EXIT
 # --- end logger ---`;
 }
-export function wrapWithLogger(script, event = "unknown", projectDir) {
-    const snippet = buildLoggerSnippet(event, projectDir);
+export function wrapWithLogger(script, event = "unknown", projectDir, mode = "block") {
+    const snippet = buildLoggerSnippet(event, projectDir, mode);
     if (script.includes("INPUT=$(cat)")) {
         return script.replace("INPUT=$(cat)", `INPUT=$(cat)\n\n${snippet}`);
     }
@@ -156,7 +173,7 @@ export async function generateHooks(options) {
             event: hook.event,
             matcher: hook.matcher,
             scriptPath: join(hooksDir, scriptName),
-            wrappedScript: wrapWithLogger(hook.inline, hook.event, projectDir),
+            wrappedScript: wrapWithLogger(hook.inline, hook.event, projectDir, hook.mode ?? "block"),
         });
     }
     // Independent IO across hooks — parallelize.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-harness",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Tame your AI coding agents with natural language",
   "type": "module",
   "bin": {