oh-my-harness 0.22.0 → 0.23.0

package/README.md

@@ -33,7 +33,7 @@ That is the whole setup. Your agent now hits a wall when it tries to:
 | save a file | ✅ auto-lint |
 | push a branch | ✅ auto-PR |
 
-Every decision is logged to `.omh/state/events.jsonl` — `omh stats` shows what your agent tried and what got stopped.
+Every decision is logged to `.omh/state/events.jsonl` — `omh stats` shows what your agent tried and what got stopped, and `omh explain` tells you in plain language why the last few calls were blocked and how to allow once or change the rule.
 
 ## Why not just write CLAUDE.md?
 
@@ -66,7 +66,43 @@ omh diff          # Preview what `omh sync` would change
 omh sync --check  # Fail (exit 1) if generated files are out of date — CI gate
 ```
 
-📖 Deeper: [what gets generated & CI drift check](docs/generated-files.md) · [how it works, project detector, AI providers](docs/how-it-works.md)
+📖 Deeper: [what gets generated & CI drift check](docs/generated-files.md) · [how it works, project detector, presets & Jev, AI providers](docs/how-it-works.md)
+
+---
+
+## 🎛️ Presets and the Jev chooser
+
+You do not need a chat model to set up a harness.
+
+**Presets** are deterministic and offline. The project detector fills in test, lint and typecheck commands and build directories; rule text is templated; a block whose required parameter cannot be detected is left out rather than half-configured.
+
+| Preset | What it enables |
+|--------|-----------------|
+| `minimal` | dangerous-command guard, main-branch guard, build-output guard |
+| `safe` | minimal + tests and typecheck must pass before a commit, lockfile and secret-file guards, lint on save |
+| `strict` | safe + test-first (TDD) on every source edit |
+
+```bash
+omh init --preset safe        # confirm prompt; add -y to skip it
+```
+
+**Jev** picks the blocks for you from a description. [Jev](https://docs.typesafe.ai/introduction) is TypeSafe's System One model: it does not generate text, it answers typed questions with calibrated probabilities. `omh init "description"` sends the description plus the detector facts and asks, in one call, "should block X be enabled?" for every selectable block and "how strict?" once. Probabilities at or above 0.65 enable a block, at or below 0.35 disable it, anything in between keeps the preset default. Rule text and free-form params never come from the model.
+
+```bash
+export TYPESAFE_API_KEY=...   # or put it in the project's .env
+omh init "Next.js + FastAPI, TDD enforced, no auto PRs"
+# Jev (jev-latest) chose: strictness=strict, 1716 input tokens
+#   enabled:   ... tdd-guard, sql-guard ...
+#   disabled:  auto-pr
+```
+
+- Get a key from the [TypeSafe console](https://typesafe.ai) (early access at the time of writing). One init costs a fraction of a cent (input $0.042 per million tokens, output free) and takes about half a second.
+- `--preset` always wins and never calls Jev. No key and no LLM provider? `omh init "description"` falls back to `safe` and says so.
+- `omh doctor` and `omh config --show` tell you whether the chooser is active. Remove the key to go back to the LLM providers or presets.
+- Interactive `omh init` offers both: "Describe your project (Jev picks the blocks)" and "Use a preset (no AI)".
+- Descriptions in English work best; other languages are handled but with lower confidence, so include the specifics.
+
+The always-on guards (harness self-protection, `--no-verify`, force-push) are added to every preset and every Jev result.
 
 ---
 
@@ -155,6 +191,7 @@ Hand omh a `WORKPLAN.md` and it runs one work order per fresh agent session, in
 # 🚀 Initialize
 omh init "your project description"      # Jev with TYPESAFE_API_KEY, else an LLM provider, else the "safe" preset
 omh init --preset strict                  # No provider: minimal | safe | strict
+omh explain                               # Why were the last tool calls blocked, and what to do about it
 omh init                                  # Interactive TUI (import existing harness.yaml)
 
 # 📋 Catalog

package/dist/catalog/blocks/branch-guard.js

@@ -10,12 +10,46 @@ export const branchGuard = {
         { name: "mainBranch", type: "string", description: "Main branch name", default: "main", required: false },
     ],
     tags: ["git", "branch", "merge", "guard"],
+    explain: {
+        allowOnce: "create a feature branch (git switch -c feat/x) and commit there",
+        change: "harness.yaml > hooks > branch-guard > params.mainBranch, or remove the hook, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)
 COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
 if _omh_cmd_matches "$COMMAND" git commit || _omh_cmd_matches "$COMMAND" git push; then
-  BRANCH=$(git branch --show-current 2>/dev/null)
+  # Where does the commit/push run? Follow cd / pushd and git -C (#133). A repo
+  # outside this project is not ours to guard; an unresolvable cwd is treated
+  # as the project itself (fail closed).
+  GIT_CWD=$(_omh_simple_commands "$COMMAND" | awk -F '\\t' -v root="$_OMH_PROJECT_ROOT" -v home="\${HOME:-}" "\${_OMH_AWK_PATHLIB}"'
+    BEGIN { cwd = root }
+    found != "" { next }
+    { i = 1
+      while (i <= NF && $i ~ /^[A-Za-z_][A-Za-z0-9_]*=/) i++
+      if (i <= NF && ($i == "sudo" || $i == "doas")) { i++; while (i <= NF && $i ~ /^-/) i++ }
+      if (i > NF) next
+      if ($i == "cd" || $i == "pushd" || $i == "popd") { cwd = omh_cd_cmd(cwd, i, home); next }
+      if ($i != "git") next
+      c = cwd; ex = 0; j = i + 1
+      while (j <= NF && $j ~ /^-/) {
+        if ($j == "-C") { if ($(j + 1) ~ /^\\//) ex = 1; c = omh_cd(c, $(j + 1), home); j++ }
+        else if ($j == "-c") j++
+        j++
+      }
+      if (j <= NF && ($j == "commit" || $j == "push")) { found = c; explicit = ex } }
+    END { print found "\\t" explicit }')
+  GIT_EXPLICIT="\${GIT_CWD#*	}"; GIT_CWD="\${GIT_CWD%%	*}"
+  [[ "$GIT_CWD" == "?" || -z "$GIT_CWD" ]] && GIT_CWD="$_OMH_PROJECT_ROOT"
+  # ';' / newline chaining: a failed cd would leave the commit in this project, so judge it
+  # here, unless the target came from an explicit absolute git -C.
+  [[ "$(_omh_seq_unsafe "$COMMAND")" == "1" && "$GIT_EXPLICIT" != "1" ]] && GIT_CWD="$_OMH_PROJECT_ROOT"
+  case "$GIT_CWD" in
+    "$_OMH_PROJECT_ROOT"|"$_OMH_PROJECT_ROOT"/*) ;;
+    *) exit 0 ;;
+  esac
+  # A subdirectory of the project is the same repository; if it does not exist yet, ask the root.
+  BRANCH=$(git -C "$GIT_CWD" branch --show-current 2>/dev/null || git -C "$_OMH_PROJECT_ROOT" branch --show-current 2>/dev/null)
   [[ -z "$BRANCH" ]] && exit 0
   MAIN='{{mainBranch}}'
   if [[ "$BRANCH" == "$MAIN" ]] || [[ "$BRANCH" == "master" && "$MAIN" == "main" ]]; then
@@ -32,8 +66,8 @@ if _omh_cmd_matches "$COMMAND" git commit || _omh_cmd_matches "$COMMAND" git pus
     fi
   fi
   if [[ "$MERGED" -eq 0 ]]; then
-    git fetch origin "$MAIN" --quiet >/dev/null 2>&1 || true
-    if git branch -r --merged "origin/$MAIN" 2>/dev/null | grep -qE "origin/\${BRANCH}$"; then
+    git -C "$GIT_CWD" fetch origin "$MAIN" --quiet >/dev/null 2>&1 || true
+    if git -C "$GIT_CWD" branch -r --merged "origin/$MAIN" 2>/dev/null | grep -qE "origin/\${BRANCH}$"; then
       MERGED=1
     fi
   fi

package/dist/catalog/blocks/command-guard.js

@@ -16,6 +16,10 @@ export const commandGuard = {
         },
     ],
     tags: ["security", "bash", "guard", "dangerous"],
+    explain: {
+        allowOnce: "rewrite the command without the blocked pattern (a narrower path, no sudo, no -R 777)",
+        change: "harness.yaml > hooks > command-guard > params.patterns: remove or edit the pattern, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/commit-test-gate.js

@@ -17,6 +17,10 @@ export const commitTestGate = {
         },
     ],
     tags: ["git", "test", "quality", "guard"],
+    explain: {
+        allowOnce: "make the test command pass, or commit only after fixing the failing test",
+        change: "harness.yaml > hooks > commit-test-gate: change testCommand or cacheTtlSeconds, set mode: ask, or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/commit-typecheck-gate.js

@@ -17,6 +17,10 @@ export const commitTypecheckGate = {
         },
     ],
     tags: ["git", "typecheck", "quality", "guard"],
+    explain: {
+        allowOnce: "fix the type errors the typecheck command reports",
+        change: "harness.yaml > hooks > commit-typecheck-gate: change typecheckCommand, set mode: ask, or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/force-push-guard.js

@@ -32,6 +32,10 @@ export const forcePushGuard = {
         },
     ],
     tags: ["git", "push", "guard", "force"],
+    explain: {
+        allowOnce: "push to a feature branch and open a pull request; use --force-with-lease if you really need to rewrite your own branch",
+        change: "harness.yaml > hooks > force-push-guard > params.protected / allowLease, or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/harness-guard.js

@@ -6,6 +6,10 @@
 // ls, diff, sed without -i) stay allowed so the agent can inspect its own rules, and `omh` is
 // never a writer here, so `omh sync` / `omh hook add` remain the sanctioned
 // way to change the harness.
+// Scope (#133): by default only paths that resolve inside this project root
+// count, following cd / pushd, ~, .. and absolute paths, so another checkout's
+// .omh is not this harness's business. Tokens that cannot be resolved ($VAR,
+// backticks, unknown cwd) fall back to name matching and stay fail-closed.
 // ponytail: harness.yaml itself is deliberately not protected (it is the
 // user's knob); per-hook `locked: true` is tracked in #118. `rm -rf .` / `*`
 // from the project root are left to command-guard patterns.
@@ -25,8 +29,19 @@ export const harnessGuard = {
             default: [],
             required: false,
         },
+        {
+            name: "scope",
+            type: "string",
+            description: "project: only paths that resolve inside this project root are protected (cd and absolute paths are followed); any: match the protected names anywhere in the command",
+            default: "project",
+            required: false,
+        },
     ],
     tags: ["security", "bash", "guard", "harness", "self-protection"],
+    explain: {
+        allowOnce: "edit harness.yaml and run omh sync; hook scripts and runtime config are generated, not hand-edited",
+        change: "harness.yaml > hooks > harness-guard: scope: any / project, extraPaths, mode: ask, or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)
@@ -41,12 +56,15 @@ WRITERS="rm mv cp tee chmod chown chgrp truncate dd ln touch install rsync shred
 GIT_WRITERS="checkout restore clean rm mv"
 
 HIT=$(_omh_simple_commands "$COMMAND" | awk -F '\\t' \\
-  -v protected="$(IFS='|'; printf '%s' "\${PROTECTED[*]}")" -v writers="$WRITERS" -v gitw="$GIT_WRITERS" '
+  -v protected="$(IFS='|'; printf '%s' "\${PROTECTED[*]}")" -v writers="$WRITERS" -v gitw="$GIT_WRITERS" \\
+  -v root="$_OMH_PROJECT_ROOT" -v home="\${HOME:-}" -v scope='{{scope}}' -v seq_unsafe="$(_omh_seq_unsafe "$COMMAND")" "\${_OMH_AWK_PATHLIB}"'
   BEGIN {
+    cwd = root
     np = split(protected, P, "|")
     nw = split(writers, W, " "); for (k = 1; k <= nw; k++) isw[W[k]] = 1
     ng = split(gitw, G, " ");    for (k = 1; k <= ng; k++) isg[G[k]] = 1
   }
+  # name-based matching: scope=any, and the fallback for tokens that cannot be resolved
   function hits(t,   k, p, L) {
     sub(/^\\.\\//, "", t)
     for (k = 1; k <= np; k++) {
@@ -59,13 +77,34 @@ HIT=$(_omh_simple_commands "$COMMAND" | awk -F '\\t' \\
     }
     return ""
   }
+  # project scope: the token must resolve (through cd, ~, .., absolute paths) to a protected path under root
+  function check_at(base, t,   a, rel, k, p, L) {
+    a = omh_abs(base, t, home)
+    if (a == "") return hits(t)
+    if (!omh_under(a, root)) return ""
+    rel = (a == root) ? "" : substr(a, length(root) + 2)
+    for (k = 1; k <= np; k++) {
+      p = P[k]; if (p == "") continue
+      sub(/^\\.\\//, "", p); L = length(p)
+      if (rel == p || substr(rel, 1, L + 1) == p "/") return p
+    }
+    return ""
+  }
+  function check(t,   p) {
+    if (scope == "any") return hits(t)
+    p = check_at(cwd, t)
+    # with semicolon or newline chaining a failed cd leaves the shell where it was: judge from the root too
+    if (p == "" && seq_unsafe == "1" && cwd != root && t !~ /^\\//) p = check_at(root, t)
+    return p
+  }
   found != "" { next }
   {
-    if ($1 == "__omh_redirect__") { p = hits($2); if (p != "") found = "redirect into " p; next }
+    if ($1 == "__omh_redirect__") { p = check($2); if (p != "") found = "redirect into " p; next }
     i = 1
     while (i <= NF && $i ~ /^[A-Za-z_][A-Za-z0-9_]*=/) i++
     if (i <= NF && ($i == "sudo" || $i == "doas")) { i++; while (i <= NF && $i ~ /^-/) i++ }
     if (i > NF) next
+    if ($i == "cd" || $i == "pushd" || $i == "popd") { cwd = omh_cd_cmd(cwd, i, home); next }
     a0 = $i
     write = 0
     if (isw[a0]) write = 1
@@ -82,7 +121,7 @@ HIT=$(_omh_simple_commands "$COMMAND" | awk -F '\\t' \\
     }
     else if (a0 == "find") { for (k = i; k <= NF; k++) if ($k == "-delete" || $k == "-exec" || $k == "-execdir") write = 1 }
     if (!write) next
-    for (k = i + 1; k <= NF; k++) { p = hits($k); if (p != "") { found = a0 " on " p; next } }
+    for (k = i + 1; k <= NF; k++) { p = check($k); if (p != "") { found = a0 " on " p; next } }
   }
   END { if (found != "") print found }')
 if [[ -n "$HIT" ]]; then

package/dist/catalog/blocks/lockfile-guard.js

@@ -16,6 +16,10 @@ export const lockfileGuard = {
         },
     ],
     tags: ["security", "file", "lockfile", "guard"],
+    explain: {
+        allowOnce: "change the dependency with the package manager (npm/pnpm/yarn/pip add or remove) so it rewrites the lockfile",
+        change: "harness.yaml > hooks > lockfile-guard > params.lockfiles: remove the file, or remove the hook, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/loop-guard.js

@@ -30,6 +30,10 @@ export const loopGuard = {
             default: [],
         },
     ],
+    explain: {
+        allowOnce: "the loop must not write its own work orders or architect-only paths; do that from an architect session",
+        change: "harness.yaml > loop.architectOnly / loop.workOrders, or disable the loop, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/no-verify-guard.js

@@ -18,6 +18,10 @@ export const noVerifyGuard = {
     canBlock: true,
     params: [],
     tags: ["git", "hooks", "guard", "bypass"],
+    explain: {
+        allowOnce: "fix what the git hook reports and commit or push again without --no-verify",
+        change: "harness.yaml > hooks > no-verify-guard: set mode: ask or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/path-guard.js

@@ -22,6 +22,10 @@ export const pathGuard = {
         },
     ],
     tags: ["security", "file", "path", "guard"],
+    explain: {
+        allowOnce: "write to a source path instead; build output and dependency directories are regenerated by their tools",
+        change: "harness.yaml > hooks > path-guard > params.blockedPaths: remove the path (protectHarness: false lifts the self-protection), then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/secret-file-guard.js

@@ -16,6 +16,10 @@ export const secretFileGuard = {
         },
     ],
     tags: ["security", "secrets", "credentials", "guard"],
+    explain: {
+        allowOnce: "edit the secret file yourself outside the agent",
+        change: "harness.yaml > hooks > secret-file-guard > params.patterns: remove the pattern, or remove the hook, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/sql-guard.js

@@ -16,6 +16,10 @@ export const sqlGuard = {
         },
     ],
     tags: ["security", "sql", "guard", "database"],
+    explain: {
+        allowOnce: "run the statement yourself outside the agent, or use a narrower statement",
+        change: "harness.yaml > hooks > sql-guard > params.patterns: remove or edit the pattern, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/blocks/tdd-guard.js

@@ -22,6 +22,10 @@ export const tddGuard = {
             default: "\\.(test|spec)\\.(ts|tsx|js|jsx)$",
         },
     ],
+    explain: {
+        allowOnce: "edit or create the matching test file first (the guard records test edits per session), then edit the source",
+        change: "harness.yaml > hooks > tdd-guard: narrow srcPattern/testPattern, set mode: ask, or remove it, then omh sync",
+    },
     template: `#!/bin/bash
 set -euo pipefail
 INPUT=$(cat)

package/dist/catalog/types.d.ts

@@ -19,6 +19,13 @@ export interface BuildingBlock {
     params: ParamDefinition[];
     template: string;
     tags: string[];
+    /** Plain-language remedies shown by `omh explain` (#115). */
+    explain?: {
+        /** How to get past this block one time without changing the rule. */
+        allowOnce?: string;
+        /** Where the rule lives and how to change it. */
+        change?: string;
+    };
 }
 export interface HookEntry {
     block: string;

package/dist/cli/commands/explain.d.ts

@@ -0,0 +1,28 @@
+import { type HookEvent } from "../event-logger.js";
+import type { BuildingBlock } from "../../catalog/types.js";
+export interface ExplainOptions {
+    projectDir?: string;
+    /** How many block decisions to show, newest first. Default 5. */
+    last?: number;
+    json?: boolean;
+}
+export interface ExplainEntry {
+    ts: string;
+    block: string;
+    hook: string;
+    reason: string;
+    allowOnce?: string;
+    change: string;
+}
+/**
+ * catalog-<id>.sh -> id. Legacy scripts were named harness-<name>.sh, so a
+ * harness- prefix is stripped too, but only when what is left is not itself a
+ * block id: catalog-harness-guard.sh must stay harness-guard.
+ */
+export declare function blockIdFromHook(hook: string, knownIds?: Set<string>): string;
+export declare function toEntry(ev: HookEvent, blocks: BuildingBlock[]): ExplainEntry;
+export declare function formatExplanation(ev: HookEvent, blocks: BuildingBlock[], now?: number): string;
+export declare function explainCommand(options?: ExplainOptions): Promise<{
+    exitCode: number;
+    entries: ExplainEntry[];
+}>;

package/dist/cli/commands/explain.js

@@ -0,0 +1,83 @@
+import chalk from "chalk";
+import { readEvents } from "../event-logger.js";
+import { builtinBlocks } from "../../catalog/blocks/index.js";
+const GENERIC_CHANGE = (id) => `harness.yaml > hooks > ${id}: set mode: ask, adjust its params, or remove the entry, then run omh sync`;
+const UNKNOWN_HOOK_CHANGE = "this hook is not a catalog block: look it up in .claude/settings.json (or harness.yaml if you added it there)";
+const BUILTIN_IDS = new Set(builtinBlocks.map((b) => b.id));
+/**
+ * catalog-<id>.sh -> id. Legacy scripts were named harness-<name>.sh, so a
+ * harness- prefix is stripped too, but only when what is left is not itself a
+ * block id: catalog-harness-guard.sh must stay harness-guard.
+ */
+export function blockIdFromHook(hook, knownIds = BUILTIN_IDS) {
+    const id = hook.replace(/\.sh$/, "").replace(/^catalog-/, "");
+    if (id.startsWith("harness-") && !knownIds.has(id))
+        return id.slice("harness-".length);
+    return id;
+}
+function relativeTime(ts, now) {
+    const diff = Math.max(0, now - Date.parse(ts));
+    const s = Math.round(diff / 1000);
+    if (s < 60)
+        return `${s}s ago`;
+    const m = Math.round(s / 60);
+    if (m < 60)
+        return `${m} min ago`;
+    const h = Math.round(m / 60);
+    if (h < 48)
+        return `${h} h ago`;
+    return `${Math.round(h / 24)} d ago`;
+}
+export function toEntry(ev, blocks) {
+    const id = blockIdFromHook(ev.hook);
+    const block = blocks.find((b) => b.id === id);
+    const reason = (ev.reason ?? "").replace(/^oh-my-harness:\s*/, "");
+    return {
+        ts: ev.ts,
+        block: id,
+        hook: ev.hook,
+        reason,
+        allowOnce: block?.explain?.allowOnce,
+        change: block ? (block.explain?.change ?? GENERIC_CHANGE(id)) : UNKNOWN_HOOK_CHANGE,
+    };
+}
+export function formatExplanation(ev, blocks, now = Date.now()) {
+    const e = toEntry(ev, blocks);
+    const lines = [
+        `${chalk.dim(relativeTime(e.ts, now).padEnd(11))}${chalk.bold(e.block)}  ${chalk.red("blocked")}`,
+        `           Because: ${e.reason || "(no reason recorded)"}`,
+    ];
+    if (e.allowOnce)
+        lines.push(`           To allow once: ${e.allowOnce}`);
+    lines.push(`           To change the rule: ${e.change}`);
+    return lines.join("\n");
+}
+export async function explainCommand(options = {}) {
+    const projectDir = options.projectDir ?? process.cwd();
+    const last = options.last && options.last > 0 ? options.last : 5;
+    let events = [];
+    try {
+        events = await readEvents(projectDir);
+    }
+    catch {
+        events = [];
+    }
+    const blocked = events.filter((e) => e.decision === "block").slice(-last).reverse();
+    const entries = blocked.map((e) => toEntry(e, builtinBlocks));
+    if (options.json) {
+        console.log(JSON.stringify(entries, null, 2));
+        return { exitCode: 0, entries };
+    }
+    if (blocked.length === 0) {
+        console.log("No blocked tool calls in .omh/state/events.jsonl yet.");
+        return { exitCode: 0, entries };
+    }
+    const now = Date.now();
+    console.log(chalk.bold(`Last ${blocked.length} blocked tool call${blocked.length === 1 ? "" : "s"}:`));
+    console.log("");
+    for (const e of blocked) {
+        console.log(formatExplanation(e, builtinBlocks, now));
+        console.log("");
+    }
+    return { exitCode: 0, entries };
+}

package/dist/cli/index.js

@@ -35,6 +35,18 @@ export function createCli() {
             process.exitCode = 1;
         }
     });
+    program
+        .command("explain")
+        .description("Show the last blocked tool calls in plain language, with how to allow once and how to change the rule")
+        .option("-d, --project-dir <dir>", "Project directory")
+        .option("-n, --last <count>", "How many blocks to show (default 5)", (v) => Number.parseInt(v, 10))
+        .option("--json", "Machine-readable output")
+        .action(async (options) => {
+        const { explainCommand } = await import("./commands/explain.js");
+        const result = await explainCommand(options);
+        if (result.exitCode !== 0)
+            process.exitCode = result.exitCode;
+    });
     program
         .command("doctor")
         .description("Validate harness configuration health")

package/dist/cli/stats/data.d.ts

@@ -34,6 +34,8 @@ export interface StatsData {
     dateRange: DateRange;
 }
 export declare function deduplicateBlocks(blocks: BlockStats[]): BlockStats[];
+/** catalog-<id>.sh -> id; legacy harness-<name>.sh -> name, unless the name is itself a block id (harness-guard). */
+export declare function normalizeHookName(hook: string): string;
 export declare function getActiveBlocks(hookEntries: HookEntry[], allBlocks: BuildingBlock[]): {
     block: BuildingBlock;
     params: Record<string, unknown>;

package/dist/cli/stats/data.js

@@ -26,6 +26,14 @@ export function deduplicateBlocks(blocks) {
     }
     return [...map.values()];
 }
+const BUILTIN_IDS = new Set(builtinBlocks.map((b) => b.id));
+/** catalog-<id>.sh -> id; legacy harness-<name>.sh -> name, unless the name is itself a block id (harness-guard). */
+export function normalizeHookName(hook) {
+    const id = hook.replace(/\.sh$/, "").replace(/^catalog-/, "");
+    if (id.startsWith("harness-") && !BUILTIN_IDS.has(id))
+        return id.slice("harness-".length);
+    return id;
+}
 export function getActiveBlocks(hookEntries, allBlocks) {
     const result = [];
     for (const entry of hookEntries) {
@@ -37,7 +45,7 @@ export function getActiveBlocks(hookEntries, allBlocks) {
     return result;
 }
 export function getDormantBlocks(activeBlocks, events) {
-    const hitHooks = new Set(events.map(e => e.hook.replace(/\.sh$/, "").replace(/^catalog-/, "").replace(/^harness-/, "")));
+    const hitHooks = new Set(events.map(e => normalizeHookName(e.hook)));
     return activeBlocks
         .filter(ab => !hitHooks.has(ab.block.id))
         .map(ab => ab.block.id);
@@ -76,7 +84,7 @@ export function getDateFilteredEvents(events, range) {
 export function getBlockDetail(blockId, events, allBlocks, params = {}) {
     const block = allBlocks.find(b => b.id === blockId);
     const hookEvents = events.filter(e => {
-        const normalized = e.hook.replace(/\.sh$/, "").replace(/^catalog-/, "").replace(/^harness-/, "");
+        const normalized = normalizeHookName(e.hook);
         return normalized === blockId;
     });
     const blockCount = hookEvents.filter(e => e.decision === "block").length;

package/dist/generators/hooks.js

@@ -203,7 +203,59 @@ _omh_gate_record() {
   mkdir -p "$(dirname "$file")" 2>/dev/null || true
   printf '%s %s\\n' "$fp" "$(date +%s)" > "$file"
 }`;
-const OMH_CMD_HELPERS = `${OMH_TREE_FINGERPRINT}
+// Path resolution shared by guards that must know whether a token points
+// inside THIS project (#133). Exposed as a bash variable holding awk function
+// definitions; templates concatenate it in front of their own awk program:
+//   awk -v root=... "${_OMH_AWK_PATHLIB}"'BEGIN { ... }'
+// omh_abs returns "" when the token cannot be resolved ($VAR, backticks,
+// unknown cwd); callers fall back to name matching, so unknown stays fail-closed.
+const OMH_AWK_PATHLIB = String.raw `
+function omh_norm(p,    n, parts, out, i, depth, res, s) {
+  n = split(p, parts, "/"); depth = 0
+  for (i = 1; i <= n; i++) {
+    s = parts[i]
+    if (s == "" || s == ".") continue
+    if (s == "..") { if (depth > 0) depth--; continue }
+    out[++depth] = s
+  }
+  res = ""; for (i = 1; i <= depth; i++) res = res "/" out[i]
+  return res == "" ? "/" : res
+}
+function omh_abs(cwd, t, home) {
+  if (t == "" || index(t, "$") > 0 || index(t, "\140") > 0) return ""
+  if (t ~ /^~(\/|$)/) { if (home == "") return ""; t = home substr(t, 2) }
+  else if (t !~ /^\//) { if (cwd == "?") return ""; t = cwd "/" t }
+  return omh_norm(t)
+}
+function omh_cd(cwd, arg, home,   a) {
+  if (arg == "" || arg == "-") return "?"
+  a = omh_abs(cwd, arg, home)
+  return a == "" ? "?" : a
+}
+# cd / pushd / popd with option skipping (cd -P dir) and a directory stack.
+# Returns the new cwd; the caller keeps the stack (omh_stack, omh_sp) between calls.
+function omh_cd_cmd(cwd, i, home,   k, arg) {
+  # pushd -n (no cd), pushd/popd +N or -N (stack rotation) and popd with options
+  # change the stack in ways we do not model: unknown cwd, fail closed.
+  for (k = i + 1; k <= NF; k++) {
+    if ($i != "cd" && ($k == "-n" || $k ~ /^[+-][0-9]+$/)) { omh_sp = 0; return "?" }
+  }
+  if ($i == "popd") { return (omh_sp > 0) ? omh_stack[omh_sp--] : "?" }
+  arg = ""
+  for (k = i + 1; k <= NF; k++) { if ($k ~ /^-./ && $k != "-") continue; arg = $k; break }
+  if ($i == "pushd") omh_stack[++omh_sp] = cwd
+  return omh_cd(cwd, arg, home)
+}
+function omh_under(a, root) {
+  return a == root || substr(a, 1, length(root) + 1) == root "/"
+}`;
+const OMH_CMD_HELPERS = `_OMH_AWK_PATHLIB='${OMH_AWK_PATHLIB}'
+# 1 when the command chains with ';' or newlines: a failed cd then leaves the next
+# command in the OLD directory, so relative paths must also be judged from there.
+_omh_seq_unsafe() { case "\${1:-}" in *";"*|*$'\\n'*) echo 1 ;; *) echo 0 ;; esac; }
+# The project this hook belongs to: the parent of .omh/state (absolute, symlinks resolved).
+_OMH_PROJECT_ROOT="$(cd "$(dirname "$(dirname "$_OMH_STATE_DIR")")" 2>/dev/null && pwd -P || pwd -P)"
+${OMH_TREE_FINGERPRINT}
 _omh_tokenize() {
   printf '%s\\n' "\${1:-}" | awk '${OMH_CMD_TOKENIZER_AWK}'
 }

package/package.json

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