@lannguyensi/harness 0.43.0 → 0.45.0

package/dist/policy-packs/builtin/understanding-before-execution/post-tool-use-boundary.js

@@ -0,0 +1,209 @@
+// PostToolUse boundary matching + expiry (task a1348c89, Codex parity),
+// split out of the former monolithic understanding-before-execution-runtime.ts
+// (structural concentration slice 2, agent-tasks 348a4d42). Pure move: see
+// src/policy-packs/builtin/understanding-before-execution/index.ts for
+// the re-exported public surface.
+import * as fs from "node:fs";
+import { expandToolNameAliases } from "../../../runtime/tool-name-aliases.js";
+import { approvalMarkerPathFor, clearApprovalMarker } from "./markers.js";
+import { expirePersistedReport } from "./persisted-reports.js";
+import { clearTaskApprovalMarker, taskApprovalMarkerPathFor } from "./task-markers.js";
+// ---------------------------------------------------------------------
+// PostToolUse boundary matching + expiry (task a1348c89, Codex parity).
+// Shared between `harness pack hook post-tool-use` (Claude) and
+// `harness pack hook codex-post-tool-use` (Codex): both clear the SAME
+// marker/task-marker/persisted-report state on the SAME configured
+// task-boundary tools. Before this extraction the matching logic lived
+// only inline in the Claude hook file; a Codex sibling copying it by
+// hand would have re-implemented (and eventually drifted from) it —
+// the exact drift class task e7c2ec3c fixed on the PreToolUse side via
+// `checkOperatorApprovalMarkers` above. One implementation, two thin
+// runtime-specific callers.
+// ---------------------------------------------------------------------
+/**
+ * Tool names treated as "the Bash tool" for `expire_on_bash_match`
+ * command-regex matching. Claude Code has exactly one Bash tool name;
+ * a runtime with shell-tool aliases (e.g. Codex's `shell` /
+ * `exec_command` / `functions.exec_command`) passes its own set.
+ */
+export const DEFAULT_BASH_TOOL_NAMES = new Set(["Bash"]);
+/** Canonical agent-tasks v1 tool name whose `tool_input.status` gates
+ * marker expiry (see `matchPostToolUseBoundary` below). Not imported
+ * from `hook-track-active-claim.ts`'s own `TOOL_NAME_TASKS_TRANSITION`
+ * constant: `policy-packs/` may not import from `cli/` (layering rule,
+ * `.dependency-cruiser.cjs`). */
+const TASKS_TRANSITION_TOOL_NAME = "mcp__agent-tasks__tasks_transition";
+/**
+ * Tool-name membership test against `expire_on_tool_match`. No GLOB
+ * wildcard expansion by design (agent-tasks/d8ee60ca): operators write
+ * the exact tool name they mean.
+ *
+ * It IS alias-aware, though: a tool name is compared against `patterns`
+ * after expanding it through `expandToolNameAliases` (shell-tool
+ * aliases `Bash`/`shell`/`exec_command`/`functions.exec_command`, and
+ * MCP tool-name variants — server hyphen/underscore swap, the
+ * `mcp__server__.tool` dotted form). This mirrors the normalization
+ * `harness policy intercept`'s `policyMatchesEvent` already applies to
+ * the incoming `event.tool_name` (`src/runtime/intercept.ts`, commit
+ * 9aacbcd "Fix Codex hook tool matching") — that fix exists precisely
+ * because Codex can emit an MCP tool name in one of these variant
+ * forms for the identical tool. Before this, a Codex session sending
+ * `mcp__agent-tasks__.task_finish` (dotted) or an underscore-server
+ * variant would silently never expire the marker: the Codex generator
+ * alias-expands the EMITTED TOML `matcher` (`expandCodexHookMatchPattern`
+ * in `generate-codex-config.ts`) so Codex's own dispatcher still
+ * invokes the hook command, but this function's comparison against the
+ * canonical `expire_on_tool_match` config list would reject the
+ * variant `tool_name` once inside the hook body — the boundary would
+ * silently never fire even though the hook ran (review finding on task
+ * a1348c89).
+ */
+export function toolNameMatchesAny(toolName, patterns) {
+    const patternSet = new Set(patterns);
+    return expandToolNameAliases(toolName).some((alias) => patternSet.has(alias));
+}
+/** First `expire_on_bash_match` regex the command satisfies, or
+ * undefined. Patterns are pre-compiled by `parseApprovalLifecycle`
+ * (invalid ones already dropped with a warning). Empty command
+ * short-circuits to undefined. */
+export function bashCommandMatchesAny(command, patterns) {
+    if (command === "")
+        return undefined;
+    for (const re of patterns) {
+        if (re.test(command))
+            return re;
+    }
+    return undefined;
+}
+function toolInputRecord(toolInput) {
+    if (typeof toolInput !== "object" || toolInput === null || Array.isArray(toolInput)) {
+        return null;
+    }
+    return toolInput;
+}
+/** Pull the Bash command out of a tool_input payload, `""` when absent
+ * or malformed. */
+export function extractBashCommandFromToolInput(toolInput) {
+    const command = toolInputRecord(toolInput)?.["command"];
+    return typeof command === "string" ? command : "";
+}
+/** Pull `taskId` out of an MCP tool_input payload (`""` when absent /
+ * malformed). Task-boundary agent-tasks verbs carry this as a
+ * top-level string field. */
+export function extractTaskIdFromToolInput(toolInput) {
+    const tid = toolInputRecord(toolInput)?.["taskId"];
+    return typeof tid === "string" ? tid : "";
+}
+/** Pull the legacy v1 `tasks_transition` `status` field out of a
+ * tool_input payload (`""` when absent / malformed). Only `"done"`
+ * releases the work claim; the caller treats any other value as
+ * keep-claim. */
+export function extractTasksTransitionStatusFromToolInput(toolInput) {
+    const s = toolInputRecord(toolInput)?.["status"];
+    return typeof s === "string" ? s : "";
+}
+/**
+ * Decide whether `toolName` (+ its `tool_input`) crosses one of the
+ * configured `approval_lifecycle` boundaries. Pure — no filesystem
+ * access. Callers branch on `.matched` before touching marker/report
+ * state (see `applyPostToolUseExpiry`).
+ */
+export function matchPostToolUseBoundary(toolName, toolInput, lifecycle, bashToolNames = DEFAULT_BASH_TOOL_NAMES) {
+    const rawToolNameMatched = toolNameMatchesAny(toolName, lifecycle.expireOnToolMatch);
+    // Legacy v1 `tasks_transition`: only `status=done` releases the work
+    // claim (per task_finish docs: "The work claim is cleared when going
+    // to done and kept when going to review"). open / in_progress /
+    // review / missing status keep the marker. Detected via the same
+    // alias-aware `toolNameMatchesAny` as the general match above (not a
+    // raw `===`): a Codex dotted/server-variant `tasks_transition`
+    // tool_name must still get the status filter applied, otherwise it
+    // would fall through to the unconditional `true` branch below and
+    // clear the marker on ANY status — a worse bug than a missed match
+    // (review finding on task a1348c89).
+    const tasksTransitionStatusOk = toolNameMatchesAny(toolName, [
+        TASKS_TRANSITION_TOOL_NAME,
+    ])
+        ? extractTasksTransitionStatusFromToolInput(toolInput) === "done"
+        : true;
+    const toolNameMatched = rawToolNameMatched && tasksTransitionStatusOk;
+    // Bash check only runs when the event is actually a Bash(-alias) call;
+    // an MCP tool whose name happens to match a regex is not a Bash
+    // boundary.
+    const bashRegex = bashToolNames.has(toolName)
+        ? bashCommandMatchesAny(extractBashCommandFromToolInput(toolInput), lifecycle.expireOnBashMatch)
+        : undefined;
+    return {
+        matched: toolNameMatched || bashRegex !== undefined,
+        toolNameMatched,
+        rawToolNameMatched,
+        bashRegex,
+    };
+}
+/**
+ * Side-effecting: clear the session marker, the task-scoped marker
+ * (when `toolNameMatched` and `tool_input.taskId` names an existing
+ * marker), and expire the persisted report. Call ONLY after
+ * `matchPostToolUseBoundary(...).matched` is true — this function does
+ * not re-check the match itself. Mirrors the Claude hook's original
+ * side effects exactly so both runtimes share one clearing
+ * implementation (task a1348c89).
+ */
+export function applyPostToolUseExpiry(generatedDir, sessionId, toolInput, toolNameMatched, reportsDir, now) {
+    const markerPath = approvalMarkerPathFor(generatedDir, sessionId);
+    const wasMarkerPresent = fs.existsSync(markerPath);
+    clearApprovalMarker(generatedDir, sessionId);
+    // Task-scoped marker cleanup (harness/1ee26e77). Only when the
+    // matched tool is an MCP task-transition verb whose tool_input.taskId
+    // names a specific task; Bash regex boundaries don't carry a taskId
+    // by design.
+    let taskMarkerCleared = false;
+    let clearedTaskId = "";
+    if (toolNameMatched) {
+        const taskId = extractTaskIdFromToolInput(toolInput);
+        if (taskId !== "") {
+            const taskMarkerPath = taskApprovalMarkerPathFor(generatedDir, taskId);
+            if (fs.existsSync(taskMarkerPath)) {
+                clearTaskApprovalMarker(generatedDir, taskId);
+                taskMarkerCleared = true;
+                clearedTaskId = taskId;
+            }
+        }
+    }
+    // Persisted-report expiry (harness/1ee26e77 follow-up). Closes the
+    // silent bypass that existed since PR #172: marker-deletion alone did
+    // not invalidate the persisted-report fallback. Best-effort.
+    const reportExpiry = expirePersistedReport(reportsDir, sessionId, now);
+    return {
+        wasMarkerPresent,
+        taskMarkerCleared,
+        clearedTaskId,
+        persistedReportExpired: reportExpiry.ok,
+        reportExpiry,
+    };
+}
+/**
+ * Compose the stderr diagnostic line for a matched-and-applied PostToolUse
+ * expiry. Shared by `harness pack hook post-tool-use` (Claude) and
+ * `harness pack hook codex-post-tool-use` (Codex) — before this extraction
+ * the two hooks each built this line by hand from the same four pieces
+ * (`matchSource`/`taskNote`/`reportNote`/the present-vs-absent branch),
+ * which `check:duplication` flagged as new clones the moment the Codex
+ * sibling landed (task a1348c89). `hookLabel` is the caller's own
+ * `harness pack hook ...` command string so the message still names the
+ * right verb.
+ */
+export function describePostToolUseExpiry(hookLabel, sessionId, toolName, bashRegex, expiry) {
+    const matchSource = bashRegex !== undefined
+        ? `bash regex /${bashRegex.source}/`
+        : `tool name`;
+    const taskNote = expiry.taskMarkerCleared
+        ? `; also cleared task marker for task ${expiry.clearedTaskId}`
+        : "";
+    const reportNote = expiry.reportExpiry.ok
+        ? `; expired persisted report ${expiry.reportExpiry.filePath}`
+        : `; persisted-report expiry skipped (${expiry.reportExpiry.reason})`;
+    return expiry.wasMarkerPresent
+        ? `${hookLabel}: expired approval marker for session ${sessionId} after ${toolName} (${matchSource})${taskNote}${reportNote}`
+        : `${hookLabel}: ${toolName} matched ${matchSource} but no marker present for session ${sessionId}${taskNote}${reportNote}`;
+}
+//# sourceMappingURL=post-tool-use-boundary.js.map

package/dist/policy-packs/builtin/understanding-before-execution/post-tool-use-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"post-tool-use-boundary.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/post-tool-use-boundary.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+EAA+E;AAC/E,2EAA2E;AAC3E,uEAAuE;AACvE,kCAAkC;AAElC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,EAAE,qBAAqB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAEvF,wEAAwE;AACxE,wEAAwE;AACxE,gEAAgE;AAChE,uEAAuE;AACvE,mEAAmE;AACnE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AACpE,uEAAuE;AACvE,qEAAqE;AACrE,4BAA4B;AAC5B,wEAAwE;AAExE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAwB,IAAI,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;AAE9E;;;;iCAIiC;AACjC,MAAM,0BAA0B,GAAG,oCAAoC,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAgB,EAChB,QAA2B;IAE3B,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IACrC,OAAO,qBAAqB,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;kCAGkC;AAClC,MAAM,UAAU,qBAAqB,CACnC,OAAe,EACf,QAA2B;IAE3B,IAAI,OAAO,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACrC,KAAK,MAAM,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC1B,IAAI,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,CAAC;IAClC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,eAAe,CAAC,SAAkB;IACzC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACpF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,SAAoC,CAAC;AAC9C,CAAC;AAED;mBACmB;AACnB,MAAM,UAAU,+BAA+B,CAAC,SAAkB;IAChE,MAAM,OAAO,GAAG,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;IACxD,OAAO,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACpD,CAAC;AAED;;6BAE6B;AAC7B,MAAM,UAAU,0BAA0B,CAAC,SAAkB;IAC3D,MAAM,GAAG,GAAG,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IACnD,OAAO,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5C,CAAC;AAED;;;iBAGiB;AACjB,MAAM,UAAU,yCAAyC,CAAC,SAAkB;IAC1E,MAAM,CAAC,GAAG,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC;IACjD,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;AACxC,CAAC;AAeD;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CACtC,QAAgB,EAChB,SAAkB,EAClB,SAA6E,EAC7E,gBAAqC,uBAAuB;IAE5D,MAAM,kBAAkB,GAAG,kBAAkB,CAAC,QAAQ,EAAE,SAAS,CAAC,iBAAiB,CAAC,CAAC;IACrF,qEAAqE;IACrE,qEAAqE;IACrE,gEAAgE;IAChE,iEAAiE;IACjE,qEAAqE;IACrE,+DAA+D;IAC/D,mEAAmE;IACnE,kEAAkE;IAClE,mEAAmE;IACnE,qCAAqC;IACrC,MAAM,uBAAuB,GAAG,kBAAkB,CAAC,QAAQ,EAAE;QAC3D,0BAA0B;KAC3B,CAAC;QACA,CAAC,CAAC,yCAAyC,CAAC,SAAS,CAAC,KAAK,MAAM;QACjE,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,eAAe,GAAG,kBAAkB,IAAI,uBAAuB,CAAC;IACtE,uEAAuE;IACvE,gEAAgE;IAChE,YAAY;IACZ,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC3C,CAAC,CAAC,qBAAqB,CACnB,+BAA+B,CAAC,SAAS,CAAC,EAC1C,SAAS,CAAC,iBAAiB,CAC5B;QACH,CAAC,CAAC,SAAS,CAAC;IACd,OAAO;QACL,OAAO,EAAE,eAAe,IAAI,SAAS,KAAK,SAAS;QACnD,eAAe;QACf,kBAAkB;QAClB,SAAS;KACV,CAAC;AACJ,CAAC;AAgBD;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,YAAoB,EACpB,SAAiB,EACjB,SAAkB,EAClB,eAAwB,EACxB,UAAkB,EAClB,GAAU;IAEV,MAAM,UAAU,GAAG,qBAAqB,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IAClE,MAAM,gBAAgB,GAAG,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;IACnD,mBAAmB,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IAE7C,+DAA+D;IAC/D,sEAAsE;IACtE,oEAAoE;IACpE,aAAa;IACb,IAAI,iBAAiB,GAAG,KAAK,CAAC;IAC9B,IAAI,aAAa,GAAG,EAAE,CAAC;IACvB,IAAI,eAAe,EAAE,CAAC;QACpB,MAAM,MAAM,GAAG,0BAA0B,CAAC,SAAS,CAAC,CAAC;QACrD,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;YAClB,MAAM,cAAc,GAAG,yBAAyB,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;YACvE,IAAI,EAAE,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC;gBAClC,uBAAuB,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;gBAC9C,iBAAiB,GAAG,IAAI,CAAC;gBACzB,aAAa,GAAG,MAAM,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,sEAAsE;IACtE,6DAA6D;IAC7D,MAAM,YAAY,GAAG,qBAAqB,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;IAEvE,OAAO;QACL,gBAAgB;QAChB,iBAAiB;QACjB,aAAa;QACb,sBAAsB,EAAE,YAAY,CAAC,EAAE;QACvC,YAAY;KACb,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,yBAAyB,CACvC,SAAiB,EACjB,SAAiB,EACjB,QAAgB,EAChB,SAA6B,EAC7B,MAAoC;IAEpC,MAAM,WAAW,GAAG,SAAS,KAAK,SAAS;QACzC,CAAC,CAAC,eAAe,SAAS,CAAC,MAAM,GAAG;QACpC,CAAC,CAAC,WAAW,CAAC;IAChB,MAAM,QAAQ,GAAG,MAAM,CAAC,iBAAiB;QACvC,CAAC,CAAC,uCAAuC,MAAM,CAAC,aAAa,EAAE;QAC/D,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,UAAU,GAAG,MAAM,CAAC,YAAY,CAAC,EAAE;QACvC,CAAC,CAAC,8BAA8B,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE;QAC9D,CAAC,CAAC,sCAAsC,MAAM,CAAC,YAAY,CAAC,MAAM,GAAG,CAAC;IACxE,OAAO,MAAM,CAAC,gBAAgB;QAC5B,CAAC,CAAC,GAAG,SAAS,yCAAyC,SAAS,UAAU,QAAQ,KAAK,WAAW,IAAI,QAAQ,GAAG,UAAU,EAAE;QAC7H,CAAC,CAAC,GAAG,SAAS,KAAK,QAAQ,YAAY,WAAW,sCAAsC,SAAS,GAAG,QAAQ,GAAG,UAAU,EAAE,CAAC;AAChI,CAAC"}

package/dist/policy-packs/builtin/understanding-before-execution/task-markers.d.ts

@@ -0,0 +1,78 @@
+import { type ApprovalMarker, type CheckApprovalMarkerOptions, type MarkerCheck } from "./markers.js";
+export declare const APPROVAL_MARKER_TASK_PREFIX = "task-";
+/** Filesystem path of a per-task approval marker. */
+export declare function taskApprovalMarkerPathFor(generatedDir: string, taskId: string): string;
+/**
+ * Operator-side: write a task-scoped marker file. Atomic. Caller is
+ * `harness approve understanding --task <id>`. The session marker is
+ * written separately by the same caller for back-compat.
+ *
+ * Signed the same way as `writeApprovalMarker` (harness/f9485cc7), using
+ * `task-<id>` (the exact string `checkActiveClaimApprovalMarker` looks
+ * up) as the signed markerId — so a validly-signed task marker cannot be
+ * copied onto a different task id (or the session marker's id) and still
+ * verify.
+ */
+export declare function writeTaskApprovalMarker(generatedDir: string, taskId: string, marker: ApprovalMarker): string;
+/**
+ * Gate-side: resolve the active agent-tasks claim (via `active-claim`)
+ * and check ONLY that task's approval marker. When no active claim is
+ * recorded, this returns `matched:false` so the caller falls through
+ * to the session marker — preserving the legacy contract for solo /
+ * non-agent-tasks workflows that never call `task_start`.
+ *
+ * Replaces the v1 "any task marker satisfies the gate" behaviour
+ * (PR #198): a stale approval from a different, already-completed task
+ * was silently authorising every Edit/Write/Bash in the next session
+ * because the scan returned the first existing marker regardless of
+ * which task the agent had actually claimed.
+ *
+ * Same safety filters as `checkApprovalMarker` (signature verification,
+ * symlink rejection, optional freshness via `maxAgeMs`); the only
+ * difference is the filename suffix derived from `active-claim`.
+ */
+export declare function checkActiveClaimApprovalMarker(generatedDir: string, opts?: CheckApprovalMarkerOptions): MarkerCheck;
+export interface OperatorMarkerApproval {
+    matched: boolean;
+    /** Which marker satisfied the gate; null when neither matched. */
+    source: "task" | "session" | null;
+    /** Detail of the decisive check (the match, or the session-scoped miss). */
+    detail: string;
+    /** Task-scoped check detail, for callers that trace the fall-through. */
+    taskCheckDetail: string;
+    /**
+     * True when EITHER the task-scoped or the session-scoped marker
+     * existed but aged past `approval_lifecycle.max_age` (task 6e888423).
+     * False when `matched` is true, and false when a marker was simply
+     * absent (never approved, or cleared by a task-completion boundary
+     * tool) — distinguishing "this identity had a real approval that
+     * merely expired" from "this identity was never approved" / "a new
+     * task just started". PreToolUse hooks use this (never on its own —
+     * always alongside `isRecoveryGitCommit`) to decide whether a bare
+     * recovery `git commit` may proceed without a fresh Understanding
+     * Report; see src/runtime/recovery-git-commit.ts.
+     */
+    expired: boolean;
+    /**
+     * True when EITHER the task-scoped or the session-scoped marker
+     * existed but FAILED signature verification (harness/f9485cc7) —
+     * missing/invalid signature, wrong `alg`, or tampered payload. Distinct
+     * from a marker simply being absent, so a caller can log a forgery
+     * attempt distinctly from the routine "not approved yet" case.
+     */
+    forged: boolean;
+}
+/**
+ * Shared marker resolution for the Claude and Codex understanding-gate
+ * PreToolUse hooks (task e7c2ec3c): parse `approval_lifecycle` from the
+ * pack config, consult the task-scoped (active-claim) marker first and
+ * the session-scoped marker second, both under the same TTL. One code
+ * path on purpose — the Codex hook previously called the bare session
+ * check, so `max_age` and task-scoping silently applied only to Claude
+ * sessions.
+ */
+export declare function checkOperatorApprovalMarkers(generatedDir: string, sessionId: string, packConfig: unknown, stderr?: {
+    write: (s: string) => void;
+} | null): OperatorMarkerApproval;
+/** Clear a specific task-scoped marker. Used by the post-tool-use hook. */
+export declare function clearTaskApprovalMarker(generatedDir: string, taskId: string): void;

package/dist/policy-packs/builtin/understanding-before-execution/task-markers.js

@@ -0,0 +1,185 @@
+// Task-scoped approval markers (harness/1ee26e77), split out of the
+// former monolithic understanding-before-execution-runtime.ts (structural
+// concentration slice 2, agent-tasks 348a4d42). Pure move: see
+// src/policy-packs/builtin/understanding-before-execution/index.ts for
+// the re-exported public surface.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteFile } from "../../../io/atomic-write.js";
+import { signMarker } from "../../../runtime/approval-signing.js";
+import { readActiveClaim } from "./active-claim.js";
+import { parseApprovalLifecycle } from "./lifecycle.js";
+import { APPROVAL_MARKER_DIRNAME, checkApprovalMarker, } from "./markers.js";
+// Task-scoped approval markers (harness/1ee26e77). When the operator
+// passes `--task <id>` to `harness approve understanding`, a second
+// marker file is written next to the session marker, keyed by the
+// agent-tasks task id and prefixed `task-` so a directory scan can
+// distinguish them from session-keyed markers (UUIDs do not start with
+// `task-`). Either marker satisfies the gate; the session marker
+// remains for back-compat with operators who don't pass --task and for
+// non-agent-tasks workflows.
+//
+// Why task-scope: a session can span many distinct tasks; the operator's
+// Understanding Report for task A doesn't transfer trust to task B
+// (different surface, different acceptance criteria). Without per-task
+// markers a multi-task session re-uses the first task's approval for
+// every subsequent task. The expire_on_tool_match PostToolUse hook
+// already deletes the session marker on `task_finish`, but if delivery
+// is unreliable (e.g. PostToolUse skipped for an MCP tool) the marker
+// silently persists. A task-keyed marker side-steps that delivery
+// concern because the next task's id is different even if the previous
+// marker file outlives its scope.
+export const APPROVAL_MARKER_TASK_PREFIX = "task-";
+/**
+ * Reject taskIds that would escape the approvals/ namespace via path
+ * traversal or directory separators. The operator's --task flag value
+ * lands here verbatim; an accidental shell-expanded `..` or `/` would
+ * otherwise write to a sibling directory. This is defensive — the
+ * caller is the operator's own shell — but pins the trust boundary.
+ */
+function rejectMalformedTaskId(taskId) {
+    if (taskId.length === 0) {
+        throw new Error("taskId is empty");
+    }
+    if (taskId.includes("/") || taskId.includes("\\") || taskId.includes("..")) {
+        throw new Error(`taskId contains path-separator or traversal characters: ${JSON.stringify(taskId)}`);
+    }
+}
+/** Filesystem path of a per-task approval marker. */
+export function taskApprovalMarkerPathFor(generatedDir, taskId) {
+    rejectMalformedTaskId(taskId);
+    return path.join(generatedDir, APPROVAL_MARKER_DIRNAME, `${APPROVAL_MARKER_TASK_PREFIX}${taskId}`);
+}
+/**
+ * Operator-side: write a task-scoped marker file. Atomic. Caller is
+ * `harness approve understanding --task <id>`. The session marker is
+ * written separately by the same caller for back-compat.
+ *
+ * Signed the same way as `writeApprovalMarker` (harness/f9485cc7), using
+ * `task-<id>` (the exact string `checkActiveClaimApprovalMarker` looks
+ * up) as the signed markerId — so a validly-signed task marker cannot be
+ * copied onto a different task id (or the session marker's id) and still
+ * verify.
+ */
+export function writeTaskApprovalMarker(generatedDir, taskId, marker) {
+    const filePath = taskApprovalMarkerPathFor(generatedDir, taskId);
+    const markerId = `${APPROVAL_MARKER_TASK_PREFIX}${taskId}`;
+    const signed = signMarker(generatedDir, markerId, marker);
+    atomicWriteFile(filePath, `${JSON.stringify(signed, null, 2)}\n`, { mode: 0o600 });
+    return filePath;
+}
+/**
+ * Gate-side: resolve the active agent-tasks claim (via `active-claim`)
+ * and check ONLY that task's approval marker. When no active claim is
+ * recorded, this returns `matched:false` so the caller falls through
+ * to the session marker — preserving the legacy contract for solo /
+ * non-agent-tasks workflows that never call `task_start`.
+ *
+ * Replaces the v1 "any task marker satisfies the gate" behaviour
+ * (PR #198): a stale approval from a different, already-completed task
+ * was silently authorising every Edit/Write/Bash in the next session
+ * because the scan returned the first existing marker regardless of
+ * which task the agent had actually claimed.
+ *
+ * Same safety filters as `checkApprovalMarker` (signature verification,
+ * symlink rejection, optional freshness via `maxAgeMs`); the only
+ * difference is the filename suffix derived from `active-claim`.
+ */
+export function checkActiveClaimApprovalMarker(generatedDir, opts = {}) {
+    const claim = readActiveClaim(generatedDir);
+    if (claim === null) {
+        return {
+            matched: false,
+            detail: `no active-claim recorded; task-scoped check skipped`,
+            marker: null,
+            expired: false,
+            forged: false,
+        };
+    }
+    const markerName = `${APPROVAL_MARKER_TASK_PREFIX}${claim}`;
+    const check = checkApprovalMarker(generatedDir, markerName, opts);
+    if (check.matched) {
+        return {
+            matched: true,
+            detail: `task-scoped marker for active-claim ${claim}: ${check.detail}`,
+            marker: check.marker,
+            expired: false,
+            forged: false,
+        };
+    }
+    return {
+        matched: false,
+        detail: `active-claim ${claim} has no fresh task marker (${check.detail})`,
+        marker: null,
+        expired: check.expired,
+        forged: check.forged,
+    };
+}
+/**
+ * Shared marker resolution for the Claude and Codex understanding-gate
+ * PreToolUse hooks (task e7c2ec3c): parse `approval_lifecycle` from the
+ * pack config, consult the task-scoped (active-claim) marker first and
+ * the session-scoped marker second, both under the same TTL. One code
+ * path on purpose — the Codex hook previously called the bare session
+ * check, so `max_age` and task-scoping silently applied only to Claude
+ * sessions.
+ */
+export function checkOperatorApprovalMarkers(generatedDir, sessionId, packConfig, stderr) {
+    const lifecycleRaw = packConfig !== null && typeof packConfig === "object" && !Array.isArray(packConfig)
+        ? packConfig["approval_lifecycle"]
+        : undefined;
+    const lifecycle = parseApprovalLifecycle(lifecycleRaw, stderr);
+    const ageOpts = lifecycle.maxAgeMs !== undefined ? { maxAgeMs: lifecycle.maxAgeMs } : {};
+    const taskMarker = checkActiveClaimApprovalMarker(generatedDir, ageOpts);
+    if (taskMarker.matched) {
+        return {
+            matched: true,
+            source: "task",
+            detail: taskMarker.detail,
+            taskCheckDetail: taskMarker.detail,
+            expired: false,
+            forged: false,
+        };
+    }
+    const sessionMarker = checkApprovalMarker(generatedDir, sessionId, ageOpts);
+    if (sessionMarker.matched) {
+        return {
+            matched: true,
+            source: "session",
+            detail: sessionMarker.detail,
+            taskCheckDetail: taskMarker.detail,
+            expired: false,
+            forged: false,
+        };
+    }
+    return {
+        matched: false,
+        source: null,
+        detail: sessionMarker.detail,
+        taskCheckDetail: taskMarker.detail,
+        // `expired` is computed ONLY on this non-matched path, preserving the
+        // "false when matched is true" invariant (task 6e888423 review):
+        // e.g. a FRESH session marker (matched:true, returned above) must not
+        // read expired:true just because a STALE sibling task marker also
+        // exists — that sibling is irrelevant once the session marker itself
+        // satisfied the gate. Either marker aged out counts here: a
+        // task-scoped approval that expired (even though the session-scoped
+        // check may simply have never existed) is just as legitimate a "this
+        // had approval, it lapsed" signal as a session-scoped expiry.
+        expired: taskMarker.expired || sessionMarker.expired,
+        // Surfaced so a forgery attempt against EITHER marker is visible to
+        // the caller even though the overall result is (correctly) unmatched
+        // — mirrors the `expired` OR-merge above.
+        forged: taskMarker.forged || sessionMarker.forged,
+    };
+}
+/** Clear a specific task-scoped marker. Used by the post-tool-use hook. */
+export function clearTaskApprovalMarker(generatedDir, taskId) {
+    try {
+        fs.rmSync(taskApprovalMarkerPathFor(generatedDir, taskId));
+    }
+    catch {
+        /* already gone */
+    }
+}
+//# sourceMappingURL=task-markers.js.map

package/dist/policy-packs/builtin/understanding-before-execution/task-markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-markers.js","sourceRoot":"","sources":["../../../../src/policy-packs/builtin/understanding-before-execution/task-markers.ts"],"names":[],"mappings":"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"}