@lannguyensi/harness 0.7.0 → 0.8.1

package/dist/cli/pack/hook-codex-pre-tool-use.js

@@ -0,0 +1,149 @@
+// Phase 6 #6 — `harness pack hook codex-pre-tool-use` runtime verb.
+//
+// Codex variant of the Claude Code blocker (`hook-pre-tool-use.ts`).
+// Same approval logic (ledger + persisted-report, either approves), but
+// a different I/O contract:
+//
+//   stdin  : JSON envelope shaped as `{ session_id, tool_name,
+//            raw_input, event }` — harness's published wire format that
+//            the Codex CLI integration is wrapped to emit. The
+//            integration is documented in
+//            `docs/policy-packs/understanding-before-execution.md`
+//            "Adapter notes / Codex".
+//   stdout : block reason on stderr; allow path is silent on stdout.
+//   exit   : 0 on allow, 2 on block. Codex's blocking convention is
+//            non-zero exit (the JSON-decision shape Claude Code reads
+//            is not part of Codex's hook contract today).
+//
+// Failure mode mirrors the Claude blocker: any error in load / parse /
+// ledger / report scan resolves to ALLOW (exit 0, silent diagnostic on
+// stderr). The package's optional standalone blocker remains a safety
+// net for solo users; the harness blocker is strictly more powerful.
+import { queryLedgerByTag } from "../../policies/index.js";
+import { checkPersistedReport, defaultReportsDir, matchLedgerEntries, } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
+import { loadManifest } from "../loader.js";
+const PACK_NAME = "understanding-before-execution";
+const EXIT_BLOCK = 2;
+async function readStdin(stream) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk) => {
+            data += chunk;
+        });
+        stream.on("end", () => resolve(data));
+        stream.on("error", (err) => reject(err));
+    });
+}
+function pickString(...candidates) {
+    for (const c of candidates) {
+        if (typeof c === "string" && c.length > 0)
+            return c;
+    }
+    return undefined;
+}
+function findGroundingMcp(manifest) {
+    return manifest.tools.mcp.find((m) => m.name === "grounding-mcp") ?? null;
+}
+async function checkLedger(manifest, sessionId, opts) {
+    if (opts.ledgerQuery) {
+        const result = await opts.ledgerQuery(sessionId);
+        if ("degraded" in result) {
+            return { matched: false, detail: `ledger degraded (${result.degraded})` };
+        }
+        return matchLedgerEntries(result, sessionId);
+    }
+    const server = findGroundingMcp(manifest);
+    if (!server) {
+        return { matched: false, detail: "grounding-mcp not declared in manifest" };
+    }
+    const command = Array.isArray(server.command)
+        ? server.command
+        : server.command.trim().split(/\s+/);
+    const env = server.env ?? undefined;
+    const timeoutMs = opts.ledgerTimeoutMs ?? server.health?.timeout_ms ?? 5_000;
+    const result = await queryLedgerByTag({
+        mcpCommand: command,
+        ...(env && { mcpEnv: env }),
+        sessionId,
+        timeoutMs,
+    });
+    if (result.kind === "degraded") {
+        return { matched: false, detail: `ledger degraded (${result.reason})` };
+    }
+    return matchLedgerEntries(result.entries, sessionId);
+}
+function allowResult(detail, source, stderr) {
+    const diagnostic = `harness pack hook codex: ${detail}, allowing.`;
+    stderr.write(`${diagnostic}\n`);
+    return {
+        exitCode: 0,
+        blocked: false,
+        approvalCheck: { approved: true, source, detail },
+        diagnostic,
+    };
+}
+export async function runPackHookCodexPreToolUseCli(opts = {}) {
+    const stdin = opts.stdin ?? process.stdin;
+    const stderr = opts.stderr ?? process.stderr;
+    const packName = opts.pack ?? PACK_NAME;
+    // Read stdin defensively. Bad JSON falls through to allow (matches
+    // Claude blocker's failure mode).
+    const raw = await readStdin(stdin);
+    let event = {};
+    try {
+        event = JSON.parse(raw.trim() || "{}");
+    }
+    catch {
+        /* allow on malformed input */
+    }
+    const sessionId = pickString(event.session_id) ??
+        process.env["CODEX_SESSION_ID"] ??
+        process.env["CLAUDE_SESSION_ID"] ??
+        "";
+    const toolName = pickString(event.tool_name, event.tool) ?? "(unknown)";
+    // Load manifest (or use injection). Bail to allow on any failure so a
+    // missing harness install never bricks the session.
+    let manifest;
+    try {
+        manifest = opts.manifest ?? loadManifest(opts).manifest;
+    }
+    catch (err) {
+        return allowResult(`manifest load failed (${err.message})`, "none", stderr);
+    }
+    // Confirm the pack is enabled.
+    const declared = manifest.policy_packs.find((p) => p.name === packName);
+    if (!declared) {
+        return allowResult(`pack "${packName}" not declared in manifest`, "none", stderr);
+    }
+    if (!declared.enabled) {
+        return allowResult(`pack "${packName}" is enabled:false`, "none", stderr);
+    }
+    if (sessionId === "") {
+        return allowResult("no session_id resolvable from input or $CODEX_SESSION_ID/$CLAUDE_SESSION_ID", "none", stderr);
+    }
+    // Source 1: ledger.
+    const ledger = await checkLedger(manifest, sessionId, opts);
+    if (ledger.matched) {
+        return allowResult(ledger.detail, "ledger", stderr);
+    }
+    // Source 2: persisted report.
+    const reportsDir = opts.reportsDir ?? defaultReportsDir();
+    const report = checkPersistedReport(reportsDir, sessionId);
+    if (report.approved) {
+        return allowResult(report.detail, "persisted-report", stderr);
+    }
+    // Neither source approved. Codex blocks via non-zero exit + stderr
+    // reason; there is no JSON-decision wire to write to stdout.
+    const reason = `${ledger.detail}; ${report.detail}`;
+    const diagnostic = `harness pack hook codex: BLOCK: ${reason}. Tool: ${toolName}. ` +
+        "Run `harness approve understanding` once you have produced and confirmed an Understanding Report.";
+    stderr.write(`${diagnostic}\n`);
+    return {
+        exitCode: EXIT_BLOCK,
+        blocked: true,
+        approvalCheck: { approved: false, source: "none", detail: reason },
+        diagnostic,
+    };
+}
+//# sourceMappingURL=hook-codex-pre-tool-use.js.map

package/dist/cli/pack/hook-codex-pre-tool-use.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-codex-pre-tool-use.js","sourceRoot":"","sources":["../../../src/cli/pack/hook-codex-pre-tool-use.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,EAAE;AACF,qEAAqE;AACrE,wEAAwE;AACxE,4BAA4B;AAC5B,EAAE;AACF,+DAA+D;AAC/D,wEAAwE;AACxE,+DAA+D;AAC/D,0CAA0C;AAC1C,mEAAmE;AACnE,sCAAsC;AACtC,qEAAqE;AACrE,oEAAoE;AACpE,sEAAsE;AACtE,0DAA0D;AAC1D,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,sEAAsE;AACtE,qEAAqE;AAErE,OAAO,EAAE,gBAAgB,EAAoB,MAAM,yBAAyB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,GAEnB,MAAM,sEAAsE,CAAC;AAE9E,OAAO,EAAE,YAAY,EAAsB,MAAM,cAAc,CAAC;AAEhE,MAAM,SAAS,GAAG,gCAAgC,CAAC;AACnD,MAAM,UAAU,GAAG,CAAC,CAAC;AAuCrB,KAAK,UAAU,SAAS,CAAC,MAA6B;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAClC,IAAI,IAAI,KAAK,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,UAAU,CAAC,GAAG,UAAqB;IAC1C,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;QAC3B,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAkB;IAC1C,OAAO,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,eAAe,CAAC,IAAI,IAAI,CAAC;AAC5E,CAAC;AAED,KAAK,UAAU,WAAW,CACxB,QAAkB,EAClB,SAAiB,EACjB,IAAoC;IAEpC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,UAAU,IAAI,MAAM,EAAE,CAAC;YACzB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,MAAM,CAAC,QAAQ,GAAG,EAAE,CAAC;QAC5E,CAAC;QACD,OAAO,kBAAkB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC;IACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,wCAAwC,EAAE,CAAC;IAC9E,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;QAC3C,CAAC,CAAC,MAAM,CAAC,OAAO;QAChB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACvC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,SAAS,CAAC;IACpC,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,UAAU,IAAI,KAAK,CAAC;IAC7E,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC;QACpC,UAAU,EAAE,OAAO;QACnB,GAAG,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QAC3B,SAAS;QACT,SAAS;KACV,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO,kBAAkB,CAAC,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,WAAW,CAClB,MAAc,EACd,MAAqC,EACrC,MAA6B;IAE7B,MAAM,UAAU,GAAG,4BAA4B,MAAM,aAAa,CAAC;IACnE,MAAM,CAAC,KAAK,CAAC,GAAG,UAAU,IAAI,CAAC,CAAC;IAChC,OAAO;QACL,QAAQ,EAAE,CAAC;QACX,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE;QACjD,UAAU;KACX,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,OAAuC,EAAE;IAEzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC;IAExC,mEAAmE;IACnE,kCAAkC;IAClC,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC;IACnC,IAAI,KAAK,GAAuB,EAAE,CAAC;IACnC,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,IAAI,CAAuB,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,8BAA8B;IAChC,CAAC;IAED,MAAM,SAAS,GACb,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC;QAC/B,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;QAChC,EAAE,CAAC;IACL,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC;IAExE,sEAAsE;IACtE,oDAAoD;IACpD,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,WAAW,CAChB,yBAA0B,GAAa,CAAC,OAAO,GAAG,EAClD,MAAM,EACN,MAAM,CACP,CAAC;IACJ,CAAC;IAED,+BAA+B;IAC/B,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IACxE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,WAAW,CAAC,SAAS,QAAQ,4BAA4B,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACpF,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACtB,OAAO,WAAW,CAAC,SAAS,QAAQ,oBAAoB,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5E,CAAC;IAED,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACrB,OAAO,WAAW,CAChB,6EAA6E,EAC7E,MAAM,EACN,MAAM,CACP,CAAC;IACJ,CAAC;IAED,oBAAoB;IACpB,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAC5D,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACtD,CAAC;IAED,8BAA8B;IAC9B,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,iBAAiB,EAAE,CAAC;IAC1D,MAAM,MAAM,GAAG,oBAAoB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IAC3D,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,OAAO,WAAW,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,EAAE,MAAM,CAAC,CAAC;IAChE,CAAC;IAED,mEAAmE;IACnE,6DAA6D;IAC7D,MAAM,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC;IACpD,MAAM,UAAU,GACd,mCAAmC,MAAM,WAAW,QAAQ,IAAI;QAChE,mGAAmG,CAAC;IACtG,MAAM,CAAC,KAAK,CAAC,GAAG,UAAU,IAAI,CAAC,CAAC;IAChC,OAAO;QACL,QAAQ,EAAE,UAAU;QACpB,OAAO,EAAE,IAAI;QACb,aAAa,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE;QAClE,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/cli/pack/hook-codex-stop.d.ts

@@ -0,0 +1,31 @@
+import type { Manifest } from "../../schema/index.js";
+import { type LoaderOptions } from "../loader.js";
+export interface PackHookCodexStopOptions extends LoaderOptions {
+    pack?: string;
+    reportsDir?: string;
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    manifest?: Manifest;
+    /** Test-injectable clock; defaults to new Date(). */
+    now?: Date;
+}
+export interface ParsedReport {
+    interpretation: string;
+    assumptions: string[];
+    openQuestions: string[];
+    outOfScope: string[];
+    risks: string[];
+    verificationPlan: string;
+}
+export interface PackHookCodexStopResult {
+    exitCode: number;
+    /** Path of the persisted report; null when no file was written. */
+    reportPath: string | null;
+    /** True when at least one Understanding Report field was extracted. */
+    parsed: boolean;
+    diagnostic: string;
+}
+export declare function parseUnderstandingReport(text: string): ParsedReport;
+export declare function reportHasContent(r: ParsedReport): boolean;
+export declare function runPackHookCodexStopCli(opts?: PackHookCodexStopOptions): Promise<PackHookCodexStopResult>;

package/dist/cli/pack/hook-codex-stop.js

@@ -0,0 +1,332 @@
+// Phase 6 #6 follow-up — `harness pack hook codex-stop` runtime verb.
+//
+// Codex Stop-equivalent for the `understanding-before-execution` pack.
+// Mirrors the `@lannguyensi/understanding-gate` claude-code stop bin's
+// contract, scoped to v1: read the agent's stop event on stdin,
+// extract the last assistant message, parse Understanding Report
+// fields, persist as JSON under `.understanding-gate/reports/`. The
+// resulting file lands with `approvalStatus: "pending"` so a later
+// `harness approve understanding` flips it to approved.
+//
+// Wire format on stdin (envelope harness publishes; Codex CLI
+// integration wraps its native event into this shape):
+//
+//   { session_id?: string, last_assistant_message?: string,
+//     messages?: Array<{ role: string, content: string }> }
+//
+// Either `last_assistant_message` is provided directly, OR the last
+// entry in `messages[]` with role === "assistant" is used.
+//
+// Failure mode: any error (malformed input, missing session id,
+// unwritable reports dir, parser yielded zero recognisable fields)
+// falls through to exit 0 + a stderr diagnostic. The Stop event must
+// never block the agent's response path; capture is best-effort.
+//
+// Out of scope for v1 (filed separately when needed):
+//   - Backfill of older transcripts.
+//   - A schema-validating parser; the v1 parser is heading-driven and
+//     intentionally lenient.
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteFile } from "../../io/atomic-write.js";
+import { defaultReportsDir } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
+import { loadManifest } from "../loader.js";
+const PACK_NAME = "understanding-before-execution";
+const RUNTIME_TAG = "codex";
+async function readStdin(stream) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk) => {
+            data += chunk;
+        });
+        stream.on("end", () => resolve(data));
+        stream.on("error", (err) => reject(err));
+    });
+}
+function pickString(...candidates) {
+    for (const c of candidates) {
+        if (typeof c === "string" && c.length > 0)
+            return c;
+    }
+    return undefined;
+}
+function extractLastAssistantText(env) {
+    const direct = pickString(env.last_assistant_message);
+    if (direct !== undefined)
+        return direct;
+    if (!Array.isArray(env.messages))
+        return null;
+    for (let i = env.messages.length - 1; i >= 0; i--) {
+        const row = env.messages[i];
+        if (row && typeof row === "object" && row.role === "assistant") {
+            const content = pickString(row.content);
+            if (content !== undefined)
+                return content;
+        }
+    }
+    return null;
+}
+// Field names recognised by the parser. Lower-case canonical forms;
+// the matcher is case-insensitive and accepts CamelCase / snake_case
+// / spaces.
+const FIELDS = [
+    "interpretation",
+    "assumptions",
+    "openquestions",
+    "outofscope",
+    "risks",
+    "verificationplan",
+];
+const SCALAR_FIELDS = new Set(["interpretation", "verificationplan"]);
+function normalizeFieldKey(raw) {
+    // Strip trailing punctuation that operators commonly leave inside
+    // bold labels (e.g. `**Interpretation:**` → field name is just
+    // "Interpretation"). Then compact whitespace/separators.
+    const compact = raw
+        .trim()
+        .replace(/[:.\s]+$/g, "")
+        .toLowerCase()
+        .replace(/[\s_-]+/g, "");
+    // Accept synonyms / British/American variants.
+    switch (compact) {
+        case "openquestions":
+        case "questions":
+            return "openquestions";
+        case "outofscope":
+        case "scopeexclusions":
+        case "exclusions":
+            return "outofscope";
+        case "verificationplan":
+        case "validation":
+        case "verification":
+            return "verificationplan";
+        default:
+            if (FIELDS.includes(compact)) {
+                return compact;
+            }
+            return null;
+    }
+}
+// A heading/label line opens a section. Recognised:
+//   `## Interpretation`           markdown heading
+//   `**Interpretation:**`         bold label
+//   `Interpretation:` (line)      plain colon-prefixed label
+// Returns the FieldKey on hit, plus any inline content trailing on
+// the same line (e.g. `Interpretation: short paragraph`).
+function matchSectionHeader(line) {
+    const trimmed = line.trim();
+    if (trimmed === "")
+        return null;
+    // Markdown heading: `## Interpretation` or `### Open Questions`.
+    const heading = trimmed.match(/^#{1,6}\s+(.+?)\s*$/);
+    if (heading) {
+        const field = normalizeFieldKey(heading[1] ?? "");
+        if (field)
+            return { field, inlineRest: "" };
+    }
+    // Bold label: `**Interpretation:**` or `**Interpretation**:`.
+    const bold = trimmed.match(/^\*\*([^*]+?)\*\*\s*:?\s*(.*)$/);
+    if (bold) {
+        const field = normalizeFieldKey(bold[1] ?? "");
+        if (field)
+            return { field, inlineRest: bold[2]?.trim() ?? "" };
+    }
+    // Plain label `Interpretation: rest of line` (avoid matching arbitrary
+    // sentence colons by requiring the prefix to be a known field name).
+    const plain = trimmed.match(/^([A-Za-z][A-Za-z _-]*)\s*:\s*(.*)$/);
+    if (plain) {
+        const field = normalizeFieldKey(plain[1] ?? "");
+        if (field)
+            return { field, inlineRest: plain[2]?.trim() ?? "" };
+    }
+    return null;
+}
+function extractBulletText(line) {
+    const trimmed = line.trim();
+    if (trimmed === "")
+        return null;
+    const m = trimmed.match(/^[-*•]\s+(.+)$/);
+    return m ? m[1].trim() : null;
+}
+export function parseUnderstandingReport(text) {
+    const out = {
+        interpretation: "",
+        assumptions: [],
+        openQuestions: [],
+        outOfScope: [],
+        risks: [],
+        verificationPlan: "",
+    };
+    if (typeof text !== "string" || text.trim() === "")
+        return out;
+    const lines = text.split(/\r?\n/);
+    let active = null;
+    let scalarBuffer = [];
+    const flushScalar = () => {
+        if (active && SCALAR_FIELDS.has(active) && scalarBuffer.length > 0) {
+            const joined = scalarBuffer.join(" ").replace(/\s+/g, " ").trim();
+            writeScalar(out, active, joined);
+        }
+        scalarBuffer = [];
+    };
+    for (const line of lines) {
+        const header = matchSectionHeader(line);
+        if (header) {
+            flushScalar();
+            active = header.field;
+            if (header.inlineRest !== "") {
+                if (SCALAR_FIELDS.has(active)) {
+                    scalarBuffer.push(header.inlineRest);
+                }
+                else {
+                    // Inline content on a list-field header counts as the first item.
+                    appendList(out, active, header.inlineRest);
+                }
+            }
+            continue;
+        }
+        if (!active)
+            continue;
+        if (SCALAR_FIELDS.has(active)) {
+            const trimmed = line.trim();
+            if (trimmed === "") {
+                // Blank line within a scalar paragraph terminates accumulation.
+                if (scalarBuffer.length > 0)
+                    flushScalar();
+                continue;
+            }
+            scalarBuffer.push(trimmed);
+        }
+        else {
+            const bullet = extractBulletText(line);
+            if (bullet !== null) {
+                appendList(out, active, bullet);
+            }
+            // Non-bullet lines under a list field are dropped (the upstream
+            // package's contract is "use bullets"; lenient drop avoids
+            // accidentally appending the next paragraph).
+        }
+    }
+    flushScalar();
+    return out;
+}
+function writeScalar(out, field, value) {
+    if (field === "interpretation")
+        out.interpretation = value;
+    else if (field === "verificationplan")
+        out.verificationPlan = value;
+}
+function appendList(out, field, value) {
+    if (field === "assumptions")
+        out.assumptions.push(value);
+    else if (field === "openquestions")
+        out.openQuestions.push(value);
+    else if (field === "outofscope")
+        out.outOfScope.push(value);
+    else if (field === "risks")
+        out.risks.push(value);
+}
+export function reportHasContent(r) {
+    return (r.interpretation !== "" ||
+        r.verificationPlan !== "" ||
+        r.assumptions.length > 0 ||
+        r.openQuestions.length > 0 ||
+        r.outOfScope.length > 0 ||
+        r.risks.length > 0);
+}
+function sessionShortHash(sessionId) {
+    return createHash("sha256").update(sessionId).digest("hex").slice(0, 8);
+}
+function isoFilenameStamp(now) {
+    // 2026-05-10T17:25:30.123Z -> 2026-05-10T17-25-30
+    const iso = now.toISOString();
+    const head = iso.slice(0, iso.indexOf(".") === -1 ? iso.length - 1 : iso.indexOf("."));
+    return head.replace(/:/g, "-");
+}
+function buildReportFilename(sessionId, now) {
+    const stamp = isoFilenameStamp(now);
+    const hash = sessionShortHash(sessionId);
+    return `${stamp}-${RUNTIME_TAG}-${hash}.json`;
+}
+function writeReportFile(reportsDir, filename, body) {
+    fs.mkdirSync(reportsDir, { recursive: true });
+    const target = path.join(reportsDir, filename);
+    atomicWriteFile(target, `${JSON.stringify(body, null, 2)}\n`);
+    return target;
+}
+function allowResult(diagnostic, stderr) {
+    stderr.write(`${diagnostic}\n`);
+    return { exitCode: 0, reportPath: null, parsed: false, diagnostic };
+}
+export async function runPackHookCodexStopCli(opts = {}) {
+    const stdin = opts.stdin ?? process.stdin;
+    const stderr = opts.stderr ?? process.stderr;
+    const packName = opts.pack ?? PACK_NAME;
+    const now = opts.now ?? new Date();
+    // Fail-open on stdin read errors (e.g. EPIPE on a closed pipe). The
+    // Stop hook must never crash the agent's response path; a missed
+    // capture is acceptable, an uncaught reject is not.
+    let raw;
+    try {
+        raw = await readStdin(stdin);
+    }
+    catch (err) {
+        return allowResult(`harness pack hook codex-stop: stdin read failed (${err.message}), skipping capture.`, stderr);
+    }
+    let envelope = {};
+    try {
+        envelope = JSON.parse(raw.trim() || "{}");
+    }
+    catch {
+        return allowResult("harness pack hook codex-stop: malformed JSON on stdin, skipping capture.", stderr);
+    }
+    let manifest;
+    try {
+        manifest = opts.manifest ?? loadManifest(opts).manifest;
+    }
+    catch (err) {
+        return allowResult(`harness pack hook codex-stop: manifest load failed (${err.message}), skipping capture.`, stderr);
+    }
+    const declared = manifest.policy_packs.find((p) => p.name === packName);
+    if (!declared || !declared.enabled) {
+        return allowResult(`harness pack hook codex-stop: pack "${packName}" not enabled, skipping capture.`, stderr);
+    }
+    const sessionId = pickString(envelope.session_id) ??
+        process.env["CODEX_SESSION_ID"] ??
+        process.env["CLAUDE_SESSION_ID"] ??
+        "";
+    if (sessionId === "") {
+        return allowResult("harness pack hook codex-stop: no session_id resolvable, skipping capture.", stderr);
+    }
+    const lastMessage = extractLastAssistantText(envelope);
+    if (lastMessage === null || lastMessage.trim() === "") {
+        return allowResult("harness pack hook codex-stop: no assistant message in stop event, skipping capture.", stderr);
+    }
+    const report = parseUnderstandingReport(lastMessage);
+    if (!reportHasContent(report)) {
+        return allowResult("harness pack hook codex-stop: assistant message did not contain a recognisable Understanding Report (no labelled fields found), skipping capture.", stderr);
+    }
+    const reportsDir = opts.reportsDir ?? defaultReportsDir();
+    const filename = buildReportFilename(sessionId, now);
+    const body = {
+        sessionId,
+        runtime: RUNTIME_TAG,
+        createdAt: now.toISOString(),
+        approvalStatus: "pending",
+        report,
+        rawMessage: lastMessage,
+    };
+    let target;
+    try {
+        target = writeReportFile(reportsDir, filename, body);
+    }
+    catch (err) {
+        return allowResult(`harness pack hook codex-stop: failed to write report (${err.message}), skipping capture.`, stderr);
+    }
+    const diagnostic = `harness pack hook codex-stop: captured Understanding Report at ${target} (approvalStatus: pending).`;
+    stderr.write(`${diagnostic}\n`);
+    return { exitCode: 0, reportPath: target, parsed: true, diagnostic };
+}
+//# sourceMappingURL=hook-codex-stop.js.map

package/dist/cli/pack/hook-codex-stop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-codex-stop.js","sourceRoot":"","sources":["../../../src/cli/pack/hook-codex-stop.ts"],"names":[],"mappings":"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"}

package/dist/cli/pack/hook-codex-user-prompt-submit.d.ts

@@ -0,0 +1,18 @@
+import { type Mode } from "../../policy-packs/builtin/understanding-before-execution.js";
+import type { Manifest } from "../../schema/index.js";
+import { type LoaderOptions } from "../loader.js";
+export interface PackHookCodexUserPromptSubmitOptions extends LoaderOptions {
+    pack?: string;
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    manifest?: Manifest;
+}
+export interface PackHookCodexUserPromptSubmitResult {
+    exitCode: number;
+    emitted: boolean;
+    /** The exact text written to stdout (empty when not emitted). */
+    text: string;
+}
+export declare function buildInstructionBlock(mode: Mode): string;
+export declare function runPackHookCodexUserPromptSubmitCli(opts?: PackHookCodexUserPromptSubmitOptions): Promise<PackHookCodexUserPromptSubmitResult>;

package/dist/cli/pack/hook-codex-user-prompt-submit.js

@@ -0,0 +1,92 @@
+// Phase 6 #6 — `harness pack hook codex-user-prompt-submit` runtime verb.
+//
+// Codex variant of the Understanding-Gate UserPromptSubmit injector.
+// The Claude Code adapter delegates to `@lannguyensi/understanding-gate`'s
+// `understanding-gate-claude-hook` bin (the npm package owns the
+// instruction template). The Codex adapter mirrors that contract here:
+// reads the upstream prompt JSON on stdin, writes a system-style
+// instruction block on stdout that Codex will prepend to its system
+// prompt before the agent runs.
+//
+// Wire format on stdin (envelope harness publishes; Codex CLI
+// integration wraps its native event into this shape):
+//
+//   { session_id?: string, prompt?: string }
+//
+// stdout: a plain-text instruction block (no JSON wrapper) that Codex
+// concatenates into `additional_instructions`. The block is identical
+// across modes for v1; finer-grained per-mode templating is an
+// upstream-package concern.
+//
+// Failure mode: any error → exit 0, no stdout, diagnostic on stderr.
+// A missing injector text must never fail the agent's prompt path.
+import { resolveMode } from "../../policy-packs/builtin/understanding-before-execution.js";
+import { loadManifest } from "../loader.js";
+const PACK_NAME = "understanding-before-execution";
+async function readStdin(stream) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk) => {
+            data += chunk;
+        });
+        stream.on("end", () => resolve(data));
+        stream.on("error", (err) => reject(err));
+    });
+}
+export function buildInstructionBlock(mode) {
+    // Self-contained instruction text. The richer template owned by
+    // @lannguyensi/understanding-gate is a Claude-specific surface; the
+    // Codex variant ships a sibling block that names the same artefacts
+    // (Understanding Report, .understanding-gate/reports/) so the agent's
+    // expected output is byte-shaped to land in the persisted-report
+    // directory the Codex stop-hook captures into.
+    const base = [
+        "## Understanding Gate (mode: " + mode + ")",
+        "",
+        "Before you call any write-capable tool (apply_patch, Bash/shell, file edits),",
+        "produce an *Understanding Report* with these fields:",
+        "",
+        "- **interpretation**: one paragraph explaining what you understand the task to be.",
+        "- **assumptions**: bullet list of assumptions you are making about scope, environment, intent.",
+        "- **openQuestions**: bullet list of things you still need clarification on.",
+        "- **outOfScope**: bullet list of things you will explicitly NOT do.",
+        "- **risks**: bullet list of failure modes / things that could go wrong.",
+        "- **verificationPlan**: how you will know whether the change worked.",
+        "",
+        "Wait for explicit human approval before invoking apply_patch, Bash, or shell tools.",
+        "Approval is recorded by the operator running `harness approve understanding`.",
+        "",
+        "If you are unsure whether the gate applies, ask. Do not pre-emptively edit.",
+    ].join("\n");
+    return base + "\n";
+}
+export async function runPackHookCodexUserPromptSubmitCli(opts = {}) {
+    const stdin = opts.stdin ?? process.stdin;
+    const stdout = opts.stdout ?? process.stdout;
+    const stderr = opts.stderr ?? process.stderr;
+    const packName = opts.pack ?? PACK_NAME;
+    // Drain stdin so the parent isn't blocked. We don't actually need any
+    // field from it for v1 — the instruction block is prompt-independent.
+    await readStdin(stdin).catch(() => "");
+    let manifest;
+    try {
+        manifest = opts.manifest ?? loadManifest(opts).manifest;
+    }
+    catch (err) {
+        stderr.write(`harness pack hook codex-user-prompt-submit: manifest load failed (${err.message}), suppressing injection.\n`);
+        return { exitCode: 0, emitted: false, text: "" };
+    }
+    const declared = manifest.policy_packs.find((p) => p.name === packName);
+    if (!declared || !declared.enabled) {
+        stderr.write(`harness pack hook codex-user-prompt-submit: pack "${packName}" not enabled, suppressing injection.\n`);
+        return { exitCode: 0, emitted: false, text: "" };
+    }
+    const { mode, warning } = resolveMode(declared);
+    if (warning)
+        stderr.write(`${warning}\n`);
+    const text = buildInstructionBlock(mode);
+    stdout.write(text);
+    return { exitCode: 0, emitted: true, text };
+}
+//# sourceMappingURL=hook-codex-user-prompt-submit.js.map

package/dist/cli/pack/hook-codex-user-prompt-submit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-codex-user-prompt-submit.js","sourceRoot":"","sources":["../../../src/cli/pack/hook-codex-user-prompt-submit.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,EAAE;AACF,qEAAqE;AACrE,2EAA2E;AAC3E,iEAAiE;AACjE,uEAAuE;AACvE,iEAAiE;AACjE,oEAAoE;AACpE,gCAAgC;AAChC,EAAE;AACF,8DAA8D;AAC9D,uDAAuD;AACvD,EAAE;AACF,6CAA6C;AAC7C,EAAE;AACF,sEAAsE;AACtE,sEAAsE;AACtE,+DAA+D;AAC/D,4BAA4B;AAC5B,EAAE;AACF,qEAAqE;AACrE,mEAAmE;AAEnE,OAAO,EAAa,WAAW,EAAE,MAAM,8DAA8D,CAAC;AAEtG,OAAO,EAAE,YAAY,EAAsB,MAAM,cAAc,CAAC;AAEhE,MAAM,SAAS,GAAG,gCAAgC,CAAC;AAiBnD,KAAK,UAAU,SAAS,CAAC,MAA6B;IACpD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAC3B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAClC,IAAI,IAAI,KAAK,CAAC;QAChB,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,IAAU;IAC9C,gEAAgE;IAChE,oEAAoE;IACpE,oEAAoE;IACpE,sEAAsE;IACtE,iEAAiE;IACjE,+CAA+C;IAC/C,MAAM,IAAI,GAAG;QACX,+BAA+B,GAAG,IAAI,GAAG,GAAG;QAC5C,EAAE;QACF,+EAA+E;QAC/E,sDAAsD;QACtD,EAAE;QACF,oFAAoF;QACpF,gGAAgG;QAChG,6EAA6E;QAC7E,qEAAqE;QACrE,yEAAyE;QACzE,sEAAsE;QACtE,EAAE;QACF,qFAAqF;QACrF,+EAA+E;QAC/E,EAAE;QACF,6EAA6E;KAC9E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,OAAO,IAAI,GAAG,IAAI,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mCAAmC,CACvD,OAA6C,EAAE;IAE/C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,CAAC;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC;IAExC,sEAAsE;IACtE,sEAAsE;IACtE,MAAM,SAAS,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAC;IAEvC,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,KAAK,CACV,qEACG,GAAa,CAAC,OACjB,6BAA6B,CAC9B,CAAC;QACF,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACnD,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IACxE,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACnC,MAAM,CAAC,KAAK,CACV,qDAAqD,QAAQ,yCAAyC,CACvG,CAAC;QACF,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;IACnD,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,OAAO;QAAE,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACnB,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC9C,CAAC"}