@lannguyensi/harness 0.6.0 → 0.8.0

package/dist/cli/pack/add.d.ts

@@ -0,0 +1,13 @@
+import { type PackAddEntry } from "./mutate.js";
+export interface PackAddOptions {
+    configPath?: string;
+    homeDir?: string;
+    dryRun?: boolean;
+}
+export interface PackAddResult {
+    path: string;
+    name: string;
+    diff: string;
+    applied: boolean;
+}
+export declare function packAdd(entry: PackAddEntry, opts?: PackAddOptions): Promise<PackAddResult>;

package/dist/cli/pack/add.js

@@ -0,0 +1,71 @@
+// `harness pack add <name>` — managed insert into policy_packs[].
+//
+// Mirrors src/cli/add/index.ts: schema-validate-before-write under a
+// flock; surface dup-name + bad-mode errors at the point the user runs
+// the command, not at the next `harness apply`.
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+import { atomicWriteFile } from "../../io/atomic-write.js";
+import { withFileLock } from "../../io/lock.js";
+import { unifiedDiff } from "../../io/patch.js";
+import { formatValidationErrors, validateBeforeWrite, } from "../../io/validate-before-write.js";
+import { isBuiltinPackName } from "../../policy-packs/index.js";
+import { parsePackSource } from "../../policy-packs/source.js";
+import { EX_FAIL, EX_NOINPUT, HarnessExitError } from "../exit-codes.js";
+import { applyPackAdd } from "./mutate.js";
+const DEFAULT_BASENAME = "harness.yaml";
+const LOCK_BASENAME = ".harness.lock";
+function resolveTargetPath(opts) {
+    if (opts.configPath)
+        return path.resolve(opts.configPath);
+    return path.join(opts.homeDir ?? path.join(os.homedir(), ".claude"), DEFAULT_BASENAME);
+}
+export async function packAdd(entry, opts = {}) {
+    const target = resolveTargetPath(opts);
+    if (!fs.existsSync(target)) {
+        throw new HarnessExitError(`harness manifest not found at ${target}; run \`harness init\` first`, EX_NOINPUT);
+    }
+    // Pre-flight: catch obviously-broken inputs before we touch the file lock.
+    // The schema validate-before-write below catches the same conditions, but
+    // surfacing a typed message here gives the user a one-liner hint instead
+    // of a zod issue tree for the common cases.
+    const sourceParsed = parsePackSource(entry.source ?? "builtin");
+    if (sourceParsed.kind === "unknown") {
+        throw new HarnessExitError(`policy_packs source ${JSON.stringify(entry.source)} is not recognised in v1 (only "builtin" resolves). See docs/policy-packs/.`, EX_FAIL);
+    }
+    if (sourceParsed.kind === "builtin" && !isBuiltinPackName(entry.name)) {
+        throw new HarnessExitError(`policy_packs name ${JSON.stringify(entry.name)} is not a known builtin pack. See docs/policy-packs/ for supported names.`, EX_FAIL);
+    }
+    const original = fs.readFileSync(target, "utf8");
+    const proposed = applyPackAdd(original, entry);
+    const diff = unifiedDiff({
+        fileName: path.basename(target),
+        oldText: original,
+        newText: proposed,
+        oldHeader: "current",
+        newHeader: "proposed",
+    });
+    // Schema gate: this is what catches duplicate-name across packs (the
+    // PolicyPacksSchema superRefine fires here).
+    const schemaResult = validateBeforeWrite(parseYaml(proposed));
+    if (!schemaResult.ok) {
+        throw new HarnessExitError(`proposed manifest fails schema validation:\n${formatValidationErrors(schemaResult.errors)}`, EX_FAIL);
+    }
+    if (opts.dryRun) {
+        return { path: target, name: entry.name, diff, applied: false };
+    }
+    const lockPath = path.join(path.dirname(target), LOCK_BASENAME);
+    await withFileLock(lockPath, () => {
+        const current = fs.readFileSync(target, "utf8");
+        const next = applyPackAdd(current, entry);
+        const recheck = validateBeforeWrite(parseYaml(next));
+        if (!recheck.ok) {
+            throw new HarnessExitError(`proposed manifest fails schema validation after lock acquisition:\n${formatValidationErrors(recheck.errors)}`, EX_FAIL);
+        }
+        atomicWriteFile(target, next);
+    });
+    return { path: target, name: entry.name, diff, applied: true };
+}
+//# sourceMappingURL=add.js.map

package/dist/cli/pack/add.js.map

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

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

@@ -0,0 +1,30 @@
+import { type LedgerEntry } from "../../policies/index.js";
+import { type ApprovalCheckResult } from "../../policy-packs/builtin/understanding-before-execution-runtime.js";
+import type { Manifest } from "../../schema/index.js";
+import { type LoaderOptions } from "../loader.js";
+export interface PackHookCodexPreToolUseOptions extends LoaderOptions {
+    /** Pack name to evaluate. Defaults to understanding-before-execution. */
+    pack?: string;
+    /** Override report directory (test injection). */
+    reportsDir?: string;
+    /** Override timeout per ledger call. */
+    ledgerTimeoutMs?: number;
+    /** Defaults to process.stdin. */
+    stdin?: NodeJS.ReadableStream;
+    /** Defaults to process.stderr. */
+    stderr?: NodeJS.WritableStream;
+    /** Inject an alternate manifest (test). */
+    manifest?: Manifest;
+    /** Inject a fake ledger query (test). */
+    ledgerQuery?: (sessionId: string) => Promise<LedgerEntry[] | {
+        degraded: string;
+    }>;
+}
+export interface PackHookCodexPreToolUseResult {
+    exitCode: number;
+    blocked: boolean;
+    approvalCheck: ApprovalCheckResult;
+    /** Diagnostic line emitted to stderr (always; even on allow). */
+    diagnostic: string;
+}
+export declare function runPackHookCodexPreToolUseCli(opts?: PackHookCodexPreToolUseOptions): Promise<PackHookCodexPreToolUseResult>;

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