@fusengine/harness 0.1.89 → 0.1.91

package/src/prompt/types.ts

@@ -0,0 +1,36 @@
+/** How a policy outcome should surface in a harness. */
+export type PromptKind = "ask" | "block" | "inform";
+
+/**
+ * Portable, harness-agnostic representation of a policy outcome as a prompt.
+ * Adapters render this into their harness's native shape (a Claude
+ * `permissionDecision`, a Cursor block, a CLI exit + message, ...).
+ */
+export interface Prompt {
+  kind: PromptKind;
+  /** Stable policy identifier for confirmation diagnostics. */
+  ruleId?: string;
+  /** Short title, e.g. "SOLID file-size limit". */
+  title: string;
+  /** Why this fired. */
+  reason: string;
+  /** Concrete next actions to proceed. */
+  actions?: string[];
+  /**
+   * User-facing notice (Python `hook_output.allow_pass`/`post_pass` parity):
+   * shown to the HUMAN — Claude Code's `systemMessage` — never to the agent,
+   * unlike `reason`/additionalContext. Excluded from {@link formatPrompt}.
+   */
+  userMessage?: string;
+}
+
+/** Render a {@link Prompt} as a consistent, agent-readable memo block. */
+export function formatPrompt(p: Prompt): string {
+  const tag = p.kind === "block" ? "BLOCKED" : p.kind === "ask" ? "CONFIRM" : "NOTE";
+  const lines = [`[${tag}] ${p.title}`, p.reason];
+  if (p.actions?.length) {
+    lines.push("Next:");
+    p.actions.forEach((a, i) => lines.push(`  ${i + 1}. ${a}`));
+  }
+  return lines.join("\n");
+}

package/src/refs/discover.ts

@@ -0,0 +1,69 @@
+import { readdirSync } from "node:fs";
+import { join, delimiter } from "node:path";
+
+/** Immediate subdirectory names of `p`, or `[]` when it is missing/inaccessible. */
+function subdirs(p: string): string[] {
+  try {
+    return readdirSync(p, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Every `skills/` parent dir across the Open-Agent-Skills layouts
+ * (agentskills.io) of Claude Code, Codex and Cursor: the standalone skill roots
+ * (`<base>/{.claude,.codex,.cursor,.agents}/skills` + `/etc/codex/skills`) plus
+ * installed-plugin roots (`<plugin>/skills` under the Claude marketplace and the
+ * Claude/Codex version caches). Shallow `readdir` only — no deep walk — so it is
+ * cheap enough to run on every hook.
+ */
+function skillParents(home: string, cwd: string, marketplaces: string[]): string[] {
+  const out: string[] = [];
+  for (const base of [cwd, home]) {
+    for (const tool of [".claude", ".codex", ".cursor", ".agents"]) out.push(join(base, tool, "skills"));
+  }
+  out.push(join("/etc", "codex", "skills"));
+  // Claude marketplace: <mkt>/plugins/<plugin>/skills.
+  const mktRoot = join(home, ".claude", "plugins", "marketplaces");
+  for (const mkt of subdirs(mktRoot)) {
+    if (!marketplaces.includes(mkt)) continue;
+    const pluginsDir = join(mktRoot, mkt, "plugins");
+    for (const plugin of subdirs(pluginsDir)) out.push(join(pluginsDir, plugin, "skills"));
+  }
+  // Version caches: <cache>/<mkt>/<plugin>/<version>/skills.
+  for (const cacheRoot of [join(home, ".claude", "plugins", "cache"), join(home, ".codex", "plugins", "cache")]) {
+    for (const mkt of subdirs(cacheRoot)) {
+      if (!marketplaces.includes(mkt)) continue;
+      for (const plugin of subdirs(join(cacheRoot, mkt))) {
+        for (const ver of subdirs(join(cacheRoot, mkt, plugin))) out.push(join(cacheRoot, mkt, plugin, ver, "skills"));
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Auto-discover SOLID reference dirs (`<skill>/references` for every `solid-*`
+ * skill) across the Claude/Codex/Cursor skill layouts — the fallback used when
+ * `FUSE_HARNESS_REFS` is unset. Deduped by skill name (first source wins, so a
+ * marketplace skill shadows its version-cache copy). Returns a path-delimiter
+ * list, or `""` when none is found — with no refs the SOLID-read gate stays off.
+ * @param home - User home dir (`os.homedir()`).
+ * @param cwd - Current project dir (`process.cwd()`).
+ * @param marketplaces - Allowlist of marketplace names to scan (env
+ *   `FUSE_HARNESS_MARKETPLACES`, default `["fusengine-plugins"]`); a marketplace
+ *   absent from disk simply contributes nothing. Standalone
+ *   `.claude`/`.codex`/`.cursor`/`.agents` skill roots are always scanned.
+ * @returns A `path.delimiter`-joined list of `references` dirs, or `""`.
+ */
+export function discoverRefs(home: string, cwd: string, marketplaces: string[]): string {
+  const bySkill = new Map<string, string>();
+  for (const parent of skillParents(home, cwd, marketplaces)) {
+    for (const skill of subdirs(parent)) {
+      if (!skill.startsWith("solid-") || bySkill.has(skill)) continue;
+      if (subdirs(join(parent, skill)).includes("references")) bySkill.set(skill, join(parent, skill, "references"));
+    }
+  }
+  return [...bySkill.values()].join(delimiter);
+}

package/src/refs/frontmatter.ts

@@ -0,0 +1,24 @@
+/** Extract frontmatter key/value pairs from markdown content (quotes stripped). */
+export function parseFrontmatter(content: string): Record<string, string> {
+  const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m?.[1]) return {};
+  const result: Record<string, string> = {};
+  for (const line of m[1].split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx > 0) {
+      result[line.slice(0, idx).trim()] = line.slice(idx + 1).trim().replace(/^["']|["']$/g, "");
+    }
+  }
+  return result;
+}
+
+/** Convert a simple glob (`**`, `*`) to an anchored RegExp. */
+export function globToRe(g: string): RegExp {
+  const escaped = g
+    .trim()
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "\0")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\0/g, ".*");
+  return new RegExp(`^${escaped}$`);
+}

package/src/refs/index.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./frontmatter";
+export * from "./router";
+export * from "./loader";

package/src/refs/loader.ts

@@ -0,0 +1,59 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, delimiter } from "node:path";
+import { parseFrontmatter } from "./frontmatter";
+import type { RefMeta } from "./types";
+
+function pick(fm: Record<string, string>, ...keys: string[]): string {
+  for (const k of keys) {
+    const v = fm[k];
+    if (v) return v;
+  }
+  return "";
+}
+
+const SOLID_SLUGS = new Set(["single-responsibility", "open-closed", "liskov-substitution", "interface-segregation", "dependency-inversion", "solid-principles"]);
+
+/** Infer a ref's level from its path when the frontmatter omits it (templates/→template, SOLID slug→principle). */
+function inferLevel(filePath: string): string {
+  if (filePath.includes("/templates/")) return "template";
+  const stem = (filePath.split("/").pop() ?? "").replace(/\.md$/, "");
+  return SOLID_SLUGS.has(stem) ? "principle" : "architecture";
+}
+
+/** Build a {@link RefMeta} from parsed frontmatter, tolerant of kebab/camel keys. */
+export function toRefMeta(fm: Record<string, string>, filePath: string): RefMeta {
+  return {
+    name: pick(fm, "name") || filePath,
+    description: pick(fm, "description"),
+    keywords: pick(fm, "keywords"),
+    priority: pick(fm, "priority"),
+    related: pick(fm, "related"),
+    appliesTo: pick(fm, "appliesTo", "applies-to", "applies_to"),
+    triggerOnEdit: pick(fm, "triggerOnEdit", "trigger-on-edit", "trigger_on_edit"),
+    level: pick(fm, "level") || inferLevel(filePath),
+    filePath,
+  };
+}
+
+/**
+ * Scan a directory recursively for `.md` reference files and parse each into a
+ * {@link RefMeta}. The content is entirely the consumer's — point this at any
+ * refs dir (`FUSE_HARNESS_REFS`). Returns an empty list when the dir is absent.
+ */
+export async function loadRefs(dirs: string): Promise<RefMeta[]> {
+  const refs: RefMeta[] = [];
+  for (const dir of dirs.split(delimiter).filter(Boolean)) {
+    let entries: string[];
+    try {
+      entries = (await readdir(dir, { recursive: true })) as string[];
+    } catch {
+      continue;
+    }
+    for (const rel of entries) {
+      if (!rel.endsWith(".md")) continue;
+      const filePath = join(dir, rel);
+      refs.push(toRefMeta(parseFrontmatter(await readFile(filePath, "utf8")), filePath));
+    }
+  }
+  return refs;
+}

package/src/refs/ref-key.ts

@@ -0,0 +1,41 @@
+/**
+ * Path shapes {@link discoverRefs}'s `skillParents` treats as legitimate skill
+ * roots: standalone `.claude`/`.codex`/`.cursor`/`.agents` skill dirs, marketplace
+ * and version-cache plugins installed UNDER one of those same config dirs, and
+ * the system-rooted `/etc/codex/skills`. Kept as a pure path-shape regex (no
+ * disk access, no home/cwd) so {@link skillRefKey} stays a cheap string test
+ * callable from the synchronous `solidReadGate`. Every alternative uses only
+ * bounded `[^/]+` groups — no nested quantifiers, so no ReDoS exposure.
+ *
+ * ANCHORING: the marketplace/cache branches require the `.claude`/`.codex`/
+ * `.cursor`/`.agents` segment to IMMEDIATELY precede `plugins/…/skills/` —
+ * a bare `/plugins/cache/<a>/<b>/<c>/skills/` floating anywhere (e.g. under an
+ * attacker-writable `/tmp/plugins/cache/...`) is NOT enough. `/etc/codex/skills/`
+ * is anchored at the string start (`^`), since that shape is a real absolute
+ * system path, not a directory name that can legitimately appear mid-path.
+ */
+const RECOGNIZED_SKILL_ROOT_RE =
+  /(^|\/)\.(claude|codex|cursor|agents)\/(skills\/|plugins\/(marketplaces\/[^/]+\/plugins\/[^/]+|cache\/[^/]+\/[^/]+\/[^/]+)\/skills\/)|^\/etc\/codex\/skills\//;
+
+/**
+ * Normalize a reference path to its `skills/<skill>/...` suffix — the part
+ * that stays IDENTICAL between a marketplace-first path (what `discoverRefs`
+ * returns, carried by `ctx.refs`/`routed.*.filePath`) and the same skill read
+ * by a sub-agent/teammate through a different root: a version-cache path
+ * (extra version segment, plugin dir name that can diverge from the
+ * marketplace one, e.g. `solid` vs `fuse-solid`) or a standalone
+ * `.codex`/`.cursor`/`.agents` skills dir.
+ *
+ * ANTI-FORGERY: returns `null` — never a usable key — unless `path` also
+ * matches one of the recognized skill-root SHAPES above. A path like
+ * `/tmp/skills/solid-generic/references/solid-principles.md` has the right
+ * suffix but no recognized root, so it cannot credit a SOLID read by suffix
+ * alone; only an exact byte-for-byte match (same as any unrelated file) would.
+ * @param path - Absolute path to normalize (a `ctx.refs` entry or a `refsRead` entry).
+ * @returns The `skills/...` suffix, or `null` when `path` isn't a recognized skill path.
+ */
+export function skillRefKey(path: string): string | null {
+  if (!RECOGNIZED_SKILL_ROOT_RE.test(path)) return null;
+  const i = path.lastIndexOf("skills/");
+  return i === -1 ? null : path.slice(i);
+}

package/src/refs/router.ts

@@ -0,0 +1,63 @@
+import { globToRe } from "./frontmatter";
+import type { RefMeta, ScoredRef, RouteResult } from "./types";
+
+/**
+ * Score references against a file edit (pure) — flat scoring, parity with the
+ * Python `ref_router._score_ref` (comma-split, single award per category):
+ * +10 once if ANY `applies-to` glob matches, +5 once if ANY `trigger-on-edit`
+ * fragment (trailing `/` stripped) is a substring of the path, +1 per keyword.
+ */
+export function scoreReferences(refs: RefMeta[], filePath: string, content: string): ScoredRef[] {
+  const scored: ScoredRef[] = [];
+  const hay = `${filePath} ${content}`.toLowerCase();
+  for (const meta of refs) {
+    let score = 0;
+    if (meta.appliesTo?.split(",").some((g) => g.trim() && globToRe(g.trim()).test(filePath))) score += 10;
+    if (meta.triggerOnEdit?.split(",").some((f) => { const t = f.trim().replace(/\/+$/, ""); return t && filePath.includes(t); })) score += 5;
+    if (meta.keywords) {
+      for (const kw of meta.keywords.split(",")) {
+        const k = kw.trim().toLowerCase();
+        if (k && hay.includes(k)) score += 1;
+      }
+    }
+    if (score > 0) scored.push({ meta, score });
+  }
+  return scored;
+}
+
+/**
+ * Route references for a file edit: top-2 required + next-2 optional, ensuring a
+ * `principle` and a `template` appear in the top 4. Returns null when nothing scores.
+ */
+export function routeReferences(
+  refs: RefMeta[],
+  filePath: string,
+  content: string,
+  skillPath = "",
+): RouteResult | null {
+  const scored = scoreReferences(refs, filePath, content);
+  if (!scored.length) return null;
+  scored.sort((a, b) => b.score - a.score);
+  const hoist = (level: string): void => {
+    if (scored.slice(0, 4).some((r) => r.meta.level === level)) return;
+    const found = scored.find((r) => r.meta.level === level);
+    if (found) {
+      scored.splice(scored.indexOf(found), 1);
+      scored.splice(3, 0, found);
+    }
+  };
+  hoist("principle");
+  hoist("template");
+  return { required: scored.slice(0, 2), optional: scored.slice(2, 4), skillPath: skillPath || skillPathFromRef(scored[0]?.meta.filePath ?? "") };
+}
+
+/**
+ * Derive a skill's `SKILL.md` path from one of its `references/` file paths
+ * (`<skill>/references/...` → `<skill>/SKILL.md`), matching the on-disk skill
+ * layout {@link discoverRefs} walks. Returns "" when the ref's path doesn't
+ * follow that layout (e.g. ad-hoc refs dirs used in tests).
+ */
+function skillPathFromRef(refFilePath: string): string {
+  const i = refFilePath.indexOf("/references/");
+  return i === -1 ? "" : `${refFilePath.slice(0, i)}/SKILL.md`;
+}

package/src/refs/types.ts

@@ -0,0 +1,25 @@
+/** Parsed frontmatter metadata from a reference .md file. */
+export interface RefMeta {
+  name: string;
+  description: string;
+  keywords: string;
+  priority: string;
+  related: string;
+  appliesTo: string;
+  triggerOnEdit: string;
+  level: string;
+  filePath: string;
+}
+
+/** A reference with its computed routing score. */
+export interface ScoredRef {
+  meta: RefMeta;
+  score: number;
+}
+
+/** Routing result with categorized references. */
+export interface RouteResult {
+  required: ScoredRef[];
+  optional: ScoredRef[];
+  skillPath: string;
+}

package/src/runtime/activity.ts

@@ -0,0 +1,99 @@
+import type { Activity } from "./record";
+import type { AgentQuality } from "../tracking/session-state";
+import { classifyExplore } from "../freshness/explore-tools";
+import { docFramework } from "../freshness/query-framework";
+import { shellReadRefPaths } from "../policy/shell-read-refs";
+import { isAgentTool } from "./is-agent-tool";
+
+/** A live tool-use, already normalized to `tool` + `input` by the adapter. */
+export interface ToolEvent {
+  /** The harness's `tool_name` (Cline: `preToolUse.toolName`), as a plain string. */
+  tool: string;
+  input?: Record<string, unknown>;
+  sessionId: string;
+  framework: string;
+  now: number;
+  /** Length of the tool response (POST events) — drives agent `quality`. */
+  responseLength?: number;
+}
+
+/** Quality thresholds (chars): lead agent calls vs direct explore/research (parity Python `> 50`). */
+const AGENT_QUALITY_MIN = 500;
+const EXPLORE_QUALITY_MIN = 50;
+
+/** Read tools across harnesses (Claude `Read`, Gemini/Cline `read_file`, …). */
+const READ_TOOLS = new Set(["Read", "read_file", "read_many_files"]);
+
+/** Grade a response length against a threshold; `undefined` when length is unknown. */
+function qualityFor(len: number | undefined, min: number): AgentQuality | undefined {
+  return len === undefined ? undefined : len > min ? "sufficient" : "insufficient";
+}
+
+/** Build an `agent` activity, attaching `quality` only when graded. */
+function agentActivity(name: string, ts: number, quality: AgentQuality | undefined): Activity {
+  return quality ? { kind: "agent", name, ts, quality } : { kind: "agent", name, ts };
+}
+
+/**
+ * The documentation source a tool satisfies for the doc-consultation gate, or
+ * undefined. Context7/Exa are the primary sources; fuse-browser is the fallback
+ * when Exa is down (`browser_fetch`/`browser_crawl`/`browser_serp_batch`); the
+ * built-in WebSearch/WebFetch also count.
+ * @param tool - The harness tool name.
+ */
+function docSourceOf(tool: string): string | undefined {
+  if (/context7/i.test(tool)) return "context7";
+  if (/exa/i.test(tool)) return "exa";
+  if (/browser_(fetch|crawl|serp)/i.test(tool)) return "fuse-browser";
+  if (tool === "WebSearch") return "websearch";
+  if (tool === "WebFetch") return "webfetch";
+  if (/^mcp__shadcn__/i.test(tool)) return "shadcn-mcp";
+  if (/^mcp__gemini-design__/i.test(tool)) return "gemini-mcp";
+  return undefined;
+}
+
+/**
+ * Map a live tool-use to the activity to record, or null when nothing is
+ * tracked. Works across harnesses — tool names are globally distinct:
+ * - MCP doc calls (`context7` / `exa`, any separator) → `doc`
+ * - `Task`/`Agent`/`AgentSwarm` + `subagent_type` (Claude/Cursor/Kimi) → `agent` (bare agent name)
+ * - direct exploration/research (Glob/Grep, explore Bash, web, MCP cache reads)
+ *   → `agent` credited to the matching REQUIRED_AGENTS phase
+ * - a read tool opening a `.md` reference → `ref`
+ */
+export function activityFor(event: ToolEvent): Activity[] {
+  const out: Activity[] = [];
+  // Doc consultation is recorded ALONGSIDE the research-phase credit (Python runs
+  // track-doc-consultation + track-subagent-research as two independent hooks):
+  // context7/exa/WebSearch/WebFetch AND fuse-browser (browser_fetch/crawl/serp_batch,
+  // in RESEARCH_TOOLS since explore-tools.ts:38) all credit BOTH doc and research-expert.
+  const docSource = docSourceOf(event.tool);
+  if (docSource) out.push({ kind: "doc", framework: docFramework(event.input, event.framework), sessionId: event.sessionId, source: docSource, ts: event.now });
+
+  // AgentSwarm is Kimi Code's batch launcher — same `subagent_type` identity field.
+  if (isAgentTool(event.tool)) {
+    const name = String(event.input?.subagent_type ?? event.input?.name ?? "").split(":").pop() ?? "";
+    if (name) out.push(agentActivity(name, event.now, qualityFor(event.responseLength, AGENT_QUALITY_MIN)));
+    return out;
+  }
+  const hit = classifyExplore(event.tool, event.input);
+  if (hit) {
+    const quality = hit.cacheHit ? "sufficient" : qualityFor(event.responseLength, EXPLORE_QUALITY_MIN);
+    out.push(agentActivity(hit.phase, event.now, quality));
+  } else if (READ_TOOLS.has(event.tool)) {
+    const path = String(event.input?.file_path ?? event.input?.path ?? "");
+    // `event.now` is the event timestamp `recordRefRead` stamps into
+    // `refsReadAt` (SOLID read TTL, parity track-solid-reads.py); `record.ts`
+    // forwards it as `recordRefRead(track, path, ts)`.
+    if (path.endsWith(".md")) out.push({ kind: "ref", path, ts: event.now });
+  }
+  // Codex teammates often read a skill/SOLID `.md` reference via a shell
+  // command (`cat`, `head`, …) instead of a native Read — independent of the
+  // classification above (a Bash call can ALSO be classified as `explore`
+  // evidence by classifyExplore), so every detected path is credited as its
+  // own `ref` activity (see shell-read-refs.ts for the read-only whitelist).
+  if (event.tool === "Bash") {
+    for (const path of shellReadRefPaths(event.input?.command)) out.push({ kind: "ref", path, ts: event.now });
+  }
+  return out;
+}

package/src/runtime/apply-patch-gate.ts

@@ -0,0 +1,41 @@
+import { protectedPathGate } from "../policy/trivial-edits";
+import { evaluate } from "../policy/evaluate";
+import { dryGate } from "./dry";
+import { existingLineCounts } from "./gate-helpers";
+import type { NormalizedFile } from "./normalize";
+import type { Prompt } from "../prompt/types";
+
+/**
+ * OR the static per-file verdict for a Codex `apply_patch` envelope: run the
+ * file-level gates (protected-path, SOLID file-size, DRY) that key off
+ * `filePath`/`content` over EACH touched file and return the first blocking
+ * {@link Prompt}. One violating hunk blocks the whole patch — the parity the
+ * single-file `Write`/`Edit` path already has, extended to the multi-file
+ * primitive.
+ *
+ * Only the read-only/pure gates run here (no session-state writes), so the
+ * `~11×` hook fan-out stays idempotent — the stateful APEX freshness/skill
+ * gates are tool-level and never policed `apply_patch` (its `filePath` was
+ * always undefined), so they are intentionally out of scope.
+ *
+ * File-size tool mapping mirrors Claude: an `add` is judged like a `Write`
+ * (full new content), an `update` like an `Edit` (partial content, compared
+ * against the on-disk count so an already-oversized file still blocks).
+ * @param files - Per-file changes from {@link NormalizedFile}.
+ * @param cwd - Project root for the DRY codebase grep.
+ * @returns The first blocking prompt, or null when every file passes.
+ */
+export function applyPatchGate(files: readonly NormalizedFile[], cwd: string): Prompt | null {
+  for (const f of files) {
+    const tool = f.op === "add" ? "Write" : "Edit";
+    const protectedDeny = protectedPathGate(tool, f.filePath);
+    if (protectedDeny) return protectedDeny;
+    if (f.op === "delete") continue;
+    const { raw: existingLines } = existingLineCounts(f.filePath);
+    const quick = evaluate({ tool, filePath: f.filePath, content: f.content, existingLines });
+    if (quick.decision !== "allow" && quick.prompt) return quick.prompt;
+    const dry = dryGate(tool, f.filePath, f.content, cwd);
+    if (dry) return dry;
+  }
+  return null;
+}

package/src/runtime/burst-window.ts

@@ -0,0 +1,21 @@
+/**
+ * @module burst-window
+ * Single source of truth for the multi-plugin hook fan-out window.
+ *
+ * Every DEPLOYED plugin registers its OWN PreToolUse/PostToolUse hook, so ONE
+ * Claude tool event spawns ~11 sibling harness processes that each record the
+ * same deny / one-shot / sniper reminder within milliseconds. Left unchecked
+ * the deny-loop counter jumped by ~11 per real attempt ([REPEAT] "#9" on the
+ * FIRST try), the one-shot metric inflated ~11×, and the sniper reminder was
+ * injected ~11× (token noise).
+ *
+ * A record landing within this window after an identical prior one (same
+ * operation hash + same `session_id`) is treated as the SAME event and folded
+ * into it instead of re-counted. Two REAL agent retries are always spaced
+ * further apart than the burst, so this never masks a genuine loop. No env var:
+ * the fan-out is a physical property of the installed plugin set, not policy.
+ * @packageDocumentation
+ */
+
+/** Fan-out dedup window (ms). The ~11 sibling hooks for one event land in <2s. */
+export const BURST_DEDUP_MS = 2000;

package/src/runtime/codex-shell-tool.ts

@@ -0,0 +1,37 @@
+/**
+ * @module codex-shell-tool
+ * Canonicalizes a Codex-only shell `tool_name` alias to `"Bash"`, so every
+ * existing `tool === "Bash"` consumer (activity credit, explore-tools
+ * classification, the protected-path guard, the design corpus read gate, …)
+ * treats a Code Mode exec dispatch exactly like a native Bash call — no
+ * per-consumer change needed.
+ *
+ * A Code Mode-wrapped call (`functions.exec` -> `tools.exec_command(...)`)
+ * surfaces via the generic `CoreToolRuntime` hook default (openai/codex#23757,
+ * commit 5c20513), which keeps the raw function-tool name `"exec_command"`
+ * verbatim — unlike a DIRECT `exec_command` dispatch, which
+ * `ExecCommandHandler`'s own `pre_tool_use_payload` override re-labels
+ * `"Bash"` (`tool_name: HookToolName::bash()`). This is the exact call chain
+ * a real Codex CLI 0.146.0 session was observed emitting for a `sed -n` skill
+ * read. Only ONE alias is confirmed here — `ToolName::plain("exec_command")`
+ * in `core/src/tools/handlers/unified_exec/exec_command.rs`; `shell`,
+ * `unified_exec`, `local_shell`, and `shell_command` were audited but not
+ * evidenced as a distinct hook `tool_name` value, so they are deliberately
+ * left out rather than guessed.
+ * @packageDocumentation
+ */
+
+/** Codex `tool_name` values that are a shell execution but not literally `"Bash"`. */
+const CODEX_SHELL_TOOL_ALIASES = new Set(["exec_command"]);
+
+/**
+ * Canonicalize a Codex-only shell tool alias to `"Bash"`. Scoped to
+ * `id === "codex"` — every other harness id, and every non-aliased tool
+ * name, passes through unchanged (see `test/codex-shell-read-credit.test.ts`
+ * for the non-regression proof).
+ * @param id - Harness adapter id (e.g. "codex", "claude-code", "kimi").
+ * @param tool - Raw `tool_name` from the hook payload.
+ */
+export function canonicalizeCodexShellTool(id: string, tool: string): string {
+  return id === "codex" && CODEX_SHELL_TOOL_ALIASES.has(tool) ? "Bash" : tool;
+}

package/src/runtime/command-string.ts

@@ -0,0 +1,37 @@
+/** Shell basenames whose `-c`-style argv carries the real script in argv[2]. */
+const SHELLS = new Set(["bash", "sh", "zsh", "dash"]);
+
+/** True when `arg` is (a path to) a POSIX shell we know wraps a `-c` script. */
+function isShell(arg: string | undefined): boolean {
+  if (arg === undefined) return false;
+  const base = arg.slice(arg.lastIndexOf("/") + 1);
+  return SHELLS.has(base);
+}
+
+/** True for a shell command flag (`-c`, `-lc`, `-ic`, …) — anything ending in `c`. */
+function isCommandFlag(arg: string | undefined): boolean {
+  return arg !== undefined && /^-[a-z]*c$/.test(arg);
+}
+
+/**
+ * Coerce a hook payload's `command` field to the shell string the guard chain
+ * expects. Harnesses disagree on the wire shape: Claude Code, Cursor, and Hermes
+ * send a plain string, but Codex CLI sends an argv ARRAY
+ * (`["bash", "-lc", "git commit -m x"]`). A naive `typeof === "string"` check
+ * dropped the array to `undefined`, blinding every `ctx.command` guard
+ * (destructive-git, mutators, install…) into a silent fail-open. This restores
+ * the script so the array and string payloads reach an identical verdict.
+ *
+ * @param v - Raw `command` value off the payload (string, argv array, or other).
+ * @returns A string as-is; a `[shell, -c|-lc, script]` argv reduced to its
+ *   script; any other all-string array joined with spaces; and `undefined` for
+ *   empty arrays, arrays holding non-strings, or any other type.
+ */
+export function commandToString(v: unknown): string | undefined {
+  if (typeof v === "string") return v;
+  if (!Array.isArray(v)) return undefined;
+  if (v.length === 0 || !v.every((e) => typeof e === "string")) return undefined;
+  const argv = v as string[];
+  if (argv.length >= 3 && isShell(argv[0]) && isCommandFlag(argv[1])) return argv[2];
+  return argv.join(" ");
+}