@lannguyensi/harness 0.43.0 → 0.45.0

package/dist/policy-packs/builtin/understanding-before-execution/persisted-reports.d.ts

@@ -0,0 +1,177 @@
+export interface PersistedReport {
+    filePath: string;
+    sessionId: string | null;
+    approvalStatus: string | null;
+    approvedAt: string | null;
+    /**
+     * ISO timestamp the producer stamped when it wrote the report; null
+     * for legacy reports without the field.
+     */
+    createdAt: string | null;
+    /**
+     * Effective creation time in epoch ms, resolved `createdAt` →
+     * filename ISO prefix → file mtime. Unlike mtime alone this survives
+     * the approval rewrite (which bumps mtime and would otherwise make a
+     * weeks-old report sort as the freshest, harness-discovery C1).
+     */
+    createdAtMs: number;
+}
+/**
+ * Env var the persisted-report directory can be set from. Honored by
+ * harness (`defaultReportsDir` below + emitted by `harness apply` onto
+ * the pack-contributed hook commands) AND by `@lannguyensi/understanding-gate`
+ * (its `core/persistence.js:resolveReportDir` reads the same name), so
+ * the three actors that touch the directory — Stop hook (package),
+ * PreToolUse blocker (harness), `harness approve understanding` — can
+ * agree on the path regardless of each process's cwd.
+ */
+export declare const REPORTS_DIR_ENV = "UNDERSTANDING_GATE_REPORT_DIR";
+/**
+ * Resolve the persisted-report directory. Precedence:
+ *   1. `UNDERSTANDING_GATE_REPORT_DIR` (taken verbatim — apply emits an
+ *      absolute path, operator-exported values are shell-expanded before
+ *      we see them).
+ *   2. `<cwd>/.understanding-gate/reports` — backward-compat fallback.
+ *      Callers that have a stable anchor (the manifest directory) pass
+ *      it as `cwd` so the fallback agrees with whatever path apply
+ *      baked into the hook commands.
+ */
+export declare function defaultReportsDir(cwd?: string): string;
+/**
+ * Project root anchor for the reports directory: `<dir-of-manifest>/.understanding-gate/reports`.
+ * Used by `harness apply` to bake an absolute, manifest-anchored value into
+ * the pack-contributed hook commands' env, and by `harness approve` as the
+ * fallback when `UNDERSTANDING_GATE_REPORT_DIR` is unset.
+ */
+export declare function reportsDirForManifest(manifestPath: string): string;
+export declare function safeJsonParse(text: string): unknown;
+/**
+ * List persisted reports under `dir`, newest-first by creation time
+ * (JSON `createdAt`, falling back to the filename ISO prefix, falling
+ * back to mtime). Missing directory returns []. Any I/O error on a
+ * single file is silently skipped; the caller falls through to the
+ * ledger result.
+ *
+ * Creation time, NOT mtime, is the sort key: `harness approve
+ * understanding` rewrites the report it flips, which bumps mtime and
+ * made an old just-approved report sort as the freshest
+ * (harness-discovery C1). mtime survives only as the last-resort
+ * fallback for files that carry neither timestamp.
+ */
+export declare function listPersistedReports(dir: string): PersistedReport[];
+/**
+ * Maximum age a sessionId-null report may have for the tolerant
+ * fallback to adopt it on the `harness approve understanding` path.
+ * Sized for the real flow (Stop hook persists at turn end, operator
+ * approves within minutes) with slack for a slow read-through. Live
+ * repro that motivated it: a 17-day-old pending report got adopted,
+ * validated, and stamped for a fresh session because the producer had
+ * silently failed to persist the fresh report (harness-discovery C1,
+ * friction-log #67).
+ */
+export declare const TOLERANT_FALLBACK_MAX_AGE_MS: number;
+/**
+ * Tolerance for a sessionId-less candidate whose `createdAt` lies in
+ * the FUTURE relative to the approve-time clock. A future creation
+ * time is suspect either way: a forged `createdAt` (the producer's
+ * Metadata block lets the agent author it) or serious clock skew.
+ * Beyond this skew the fallback rejects the candidate just like a
+ * stale one rather than trusting a timestamp that cannot be right.
+ */
+export declare const TOLERANT_FALLBACK_FUTURE_SKEW_MS: number;
+export interface FindReportOptions {
+    /**
+     * Behaviour of the sessionId-null tolerant fallback (older Stop-hook
+     * package versions write reports without a `sessionId` field):
+     *  - `"any"` (default): adopt the freshest sessionId-null report
+     *    regardless of its `approvalStatus`. The gate read path
+     *    (`checkPersistedReport`) and post-tool-use expiry
+     *    (`expirePersistedReport`) rely on this so they keep finding the
+     *    session's own report.
+     *  - `"uncompleted"`: skip sessionId-null reports whose
+     *    `approvalStatus` is a terminal `approved` / `expired`. Such a
+     *    report belongs to a prior, finished approval cycle (often from
+     *    a different task days ago) and must not be silently re-adopted
+     *    as the current session's approval. `harness approve
+     *    understanding` passes this so it never flips a stale unrelated
+     *    report into the live session (harness/0dce3880 friction #1).
+     */
+    tolerantFallback?: "any" | "uncompleted";
+    /**
+     * Maximum age (relative to `now`) of a sessionId-null candidate the
+     * tolerant fallback may adopt; older candidates are skipped and
+     * surfaced via `FindReportSelection.staleRejected`. Strict sessionId
+     * matches are never age-limited. Unset means no limit (the legacy
+     * gate-read / expiry contract).
+     */
+    maxFallbackAgeMs?: number;
+    /** Clock anchor for the age computation; defaults to the wall clock. */
+    now?: Date;
+}
+export interface FindReportSelection {
+    report: PersistedReport | null;
+    /**
+     * True when `report` was adopted via the sessionId-null tolerant
+     * fallback rather than a strict sessionId match. Callers that bind
+     * the report to a session (the approve flow) surface this loudly so
+     * the operator can verify the adoption.
+     */
+    fallbackAdopted: boolean;
+    /**
+     * sessionId-null candidates skipped for exceeding `maxFallbackAgeMs`,
+     * newest first. Lets the caller distinguish "no report at all" from
+     * "only stale candidates existed", which are different failures: the
+     * latter usually means the producer failed to persist the fresh
+     * report (harness-discovery C1).
+     */
+    staleRejected: PersistedReport[];
+}
+/**
+ * Select the freshest report for a given session_id, or the freshest
+ * applicable report when the persisted file lacks a sessionId field
+ * (older package versions). `report: null` when nothing matches.
+ *
+ * The strict (sessionId-equals) match always wins. The tolerant
+ * fallback's appetite is controlled by `opts.tolerantFallback` and
+ * `opts.maxFallbackAgeMs` — see `FindReportOptions`. The selection
+ * result carries enough context (`fallbackAdopted`, `staleRejected`)
+ * for the caller to be loud about non-strict adoptions.
+ */
+export declare function selectReportForSession(reports: PersistedReport[], sessionId: string, opts?: FindReportOptions): FindReportSelection;
+/**
+ * Back-compat wrapper around `selectReportForSession` for callers that
+ * only need the report (the gate read and expiry paths).
+ */
+export declare function findLatestReportForSession(reports: PersistedReport[], sessionId: string, opts?: FindReportOptions): PersistedReport | null;
+export interface PersistedReportApprovalCheck {
+    approved: boolean;
+    detail: string;
+    report: PersistedReport | null;
+}
+/**
+ * Flip the latest matching persisted report's approvalStatus to
+ * `expired` so it no longer satisfies the gate's persisted-report
+ * fallback (harness/1ee26e77 follow-up: post-tool-use expiry was
+ * marker-only; the persisted report at .understanding-gate/reports/
+ * silently kept satisfying the gate even after task_finish deleted
+ * the marker).
+ *
+ * Atomic rewrite. Preserves the rest of the report body so the audit
+ * trail (the operator's actual Understanding text + previous approval
+ * timestamps) stays intact; only the status fields change.
+ *
+ * Returns `{ ok: true, filePath, previousStatus }` on success,
+ * `{ ok: false, reason }` when no matching report exists or rewrite
+ * failed. Non-throwing: caller (post-tool-use hook) uses this as a
+ * best-effort cleanup so a missing report dir or unrelated I/O issue
+ * does not escalate into a session-breaking hook failure.
+ */
+export declare function expirePersistedReport(reportsDir: string, sessionId: string, now?: Date): {
+    ok: true;
+    filePath: string;
+    previousStatus: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function checkPersistedReport(reportsDir: string, sessionId: string): PersistedReportApprovalCheck;

package/dist/policy-packs/builtin/understanding-before-execution/persisted-reports.js

@@ -0,0 +1,309 @@
+// Persisted JSON report handling (`.understanding-gate/reports/`), 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.
+//
+// `safeJsonParse` is exported (it was module-private in the monolith) so
+// markers.ts can reuse it for marker-body parsing -- import/export
+// mechanics only, no behavior change.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteFile } from "../../../io/atomic-write.js";
+const DEFAULT_REPORTS_DIRNAME = ".understanding-gate";
+const REPORTS_SUBDIR = "reports";
+/**
+ * Env var the persisted-report directory can be set from. Honored by
+ * harness (`defaultReportsDir` below + emitted by `harness apply` onto
+ * the pack-contributed hook commands) AND by `@lannguyensi/understanding-gate`
+ * (its `core/persistence.js:resolveReportDir` reads the same name), so
+ * the three actors that touch the directory — Stop hook (package),
+ * PreToolUse blocker (harness), `harness approve understanding` — can
+ * agree on the path regardless of each process's cwd.
+ */
+export const REPORTS_DIR_ENV = "UNDERSTANDING_GATE_REPORT_DIR";
+/**
+ * Resolve the persisted-report directory. Precedence:
+ *   1. `UNDERSTANDING_GATE_REPORT_DIR` (taken verbatim — apply emits an
+ *      absolute path, operator-exported values are shell-expanded before
+ *      we see them).
+ *   2. `<cwd>/.understanding-gate/reports` — backward-compat fallback.
+ *      Callers that have a stable anchor (the manifest directory) pass
+ *      it as `cwd` so the fallback agrees with whatever path apply
+ *      baked into the hook commands.
+ */
+export function defaultReportsDir(cwd = process.cwd()) {
+    const fromEnv = process.env[REPORTS_DIR_ENV];
+    if (typeof fromEnv === "string" && fromEnv.length > 0)
+        return fromEnv;
+    return path.join(cwd, DEFAULT_REPORTS_DIRNAME, REPORTS_SUBDIR);
+}
+/**
+ * Project root anchor for the reports directory: `<dir-of-manifest>/.understanding-gate/reports`.
+ * Used by `harness apply` to bake an absolute, manifest-anchored value into
+ * the pack-contributed hook commands' env, and by `harness approve` as the
+ * fallback when `UNDERSTANDING_GATE_REPORT_DIR` is unset.
+ */
+export function reportsDirForManifest(manifestPath) {
+    return path.join(path.dirname(manifestPath), DEFAULT_REPORTS_DIRNAME, REPORTS_SUBDIR);
+}
+export function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse the ISO prefix of a producer filename
+ * (`2026-05-24T06-16-39-409Z-<slug>-<hash>.json`) into epoch ms. The
+ * producer flattens `:` and `.` to `-` for filesystem safety; undo that
+ * before `Date.parse`. null when the name does not carry the prefix.
+ */
+function parseFilenameIsoMs(name) {
+    const m = /^(\d{4}-\d{2}-\d{2})T(\d{2})-(\d{2})-(\d{2})-(\d{3})Z/.exec(name);
+    if (!m)
+        return null;
+    const ms = Date.parse(`${m[1]}T${m[2]}:${m[3]}:${m[4]}.${m[5]}Z`);
+    return Number.isNaN(ms) ? null : ms;
+}
+function readPersistedReport(filePath, mtimeMs) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return null;
+    }
+    const parsed = safeJsonParse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    const obj = parsed;
+    const createdAt = typeof obj["createdAt"] === "string" ? obj["createdAt"] : null;
+    const createdAtJsonMs = createdAt !== null ? Date.parse(createdAt) : Number.NaN;
+    const createdAtMs = !Number.isNaN(createdAtJsonMs)
+        ? createdAtJsonMs
+        : (parseFilenameIsoMs(path.basename(filePath)) ?? mtimeMs);
+    return {
+        filePath,
+        sessionId: typeof obj["sessionId"] === "string" ? obj["sessionId"] : null,
+        approvalStatus: typeof obj["approvalStatus"] === "string" ? obj["approvalStatus"] : null,
+        approvedAt: typeof obj["approvedAt"] === "string" ? obj["approvedAt"] : null,
+        createdAt,
+        createdAtMs,
+    };
+}
+/**
+ * List persisted reports under `dir`, newest-first by creation time
+ * (JSON `createdAt`, falling back to the filename ISO prefix, falling
+ * back to mtime). Missing directory returns []. Any I/O error on a
+ * single file is silently skipped; the caller falls through to the
+ * ledger result.
+ *
+ * Creation time, NOT mtime, is the sort key: `harness approve
+ * understanding` rewrites the report it flips, which bumps mtime and
+ * made an old just-approved report sort as the freshest
+ * (harness-discovery C1). mtime survives only as the last-resort
+ * fallback for files that carry neither timestamp.
+ */
+export function listPersistedReports(dir) {
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const reports = [];
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const full = path.join(dir, name);
+        let stat;
+        try {
+            stat = fs.statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        const report = readPersistedReport(full, stat.mtimeMs);
+        if (!report)
+            continue;
+        reports.push(report);
+    }
+    reports.sort((a, b) => b.createdAtMs - a.createdAtMs);
+    return reports;
+}
+/**
+ * Maximum age a sessionId-null report may have for the tolerant
+ * fallback to adopt it on the `harness approve understanding` path.
+ * Sized for the real flow (Stop hook persists at turn end, operator
+ * approves within minutes) with slack for a slow read-through. Live
+ * repro that motivated it: a 17-day-old pending report got adopted,
+ * validated, and stamped for a fresh session because the producer had
+ * silently failed to persist the fresh report (harness-discovery C1,
+ * friction-log #67).
+ */
+export const TOLERANT_FALLBACK_MAX_AGE_MS = 15 * 60_000;
+/**
+ * Tolerance for a sessionId-less candidate whose `createdAt` lies in
+ * the FUTURE relative to the approve-time clock. A future creation
+ * time is suspect either way: a forged `createdAt` (the producer's
+ * Metadata block lets the agent author it) or serious clock skew.
+ * Beyond this skew the fallback rejects the candidate just like a
+ * stale one rather than trusting a timestamp that cannot be right.
+ */
+export const TOLERANT_FALLBACK_FUTURE_SKEW_MS = 5 * 60_000;
+/**
+ * Select the freshest report for a given session_id, or the freshest
+ * applicable report when the persisted file lacks a sessionId field
+ * (older package versions). `report: null` when nothing matches.
+ *
+ * The strict (sessionId-equals) match always wins. The tolerant
+ * fallback's appetite is controlled by `opts.tolerantFallback` and
+ * `opts.maxFallbackAgeMs` — see `FindReportOptions`. The selection
+ * result carries enough context (`fallbackAdopted`, `staleRejected`)
+ * for the caller to be loud about non-strict adoptions.
+ */
+export function selectReportForSession(reports, sessionId, opts = {}) {
+    // Strict match first.
+    for (const r of reports) {
+        if (r.sessionId === sessionId) {
+            return { report: r, fallbackAdopted: false, staleRejected: [] };
+        }
+    }
+    // Tolerant fallback: a report without sessionId is treated as
+    // applicable to whichever session is asking. Only kicks in when no
+    // matching sessionId-tagged report exists — which includes the case
+    // where the producer Stop hook silently failed to persist the live
+    // session's report, so the candidates here may be entirely unrelated
+    // leftovers. `maxFallbackAgeMs` is the guard against adopting those.
+    const mode = opts.tolerantFallback ?? "any";
+    const nowMs = (opts.now ?? new Date()).getTime();
+    const staleRejected = [];
+    for (const r of reports) {
+        if (r.sessionId !== null)
+            continue;
+        if (mode === "uncompleted" &&
+            (r.approvalStatus === "approved" || r.approvalStatus === "expired")) {
+            // A completed-cycle report from another session/task; skipping it
+            // here is what stops `harness approve understanding` from binding
+            // the live session to a stale, unrelated report.
+            continue;
+        }
+        if (opts.maxFallbackAgeMs !== undefined) {
+            const ageMs = nowMs - r.createdAtMs;
+            if (ageMs > opts.maxFallbackAgeMs || ageMs < -TOLERANT_FALLBACK_FUTURE_SKEW_MS) {
+                staleRejected.push(r);
+                continue;
+            }
+        }
+        return { report: r, fallbackAdopted: true, staleRejected };
+    }
+    return { report: null, fallbackAdopted: false, staleRejected };
+}
+/**
+ * Back-compat wrapper around `selectReportForSession` for callers that
+ * only need the report (the gate read and expiry paths).
+ */
+export function findLatestReportForSession(reports, sessionId, opts = {}) {
+    return selectReportForSession(reports, sessionId, opts).report;
+}
+/**
+ * Flip the latest matching persisted report's approvalStatus to
+ * `expired` so it no longer satisfies the gate's persisted-report
+ * fallback (harness/1ee26e77 follow-up: post-tool-use expiry was
+ * marker-only; the persisted report at .understanding-gate/reports/
+ * silently kept satisfying the gate even after task_finish deleted
+ * the marker).
+ *
+ * Atomic rewrite. Preserves the rest of the report body so the audit
+ * trail (the operator's actual Understanding text + previous approval
+ * timestamps) stays intact; only the status fields change.
+ *
+ * Returns `{ ok: true, filePath, previousStatus }` on success,
+ * `{ ok: false, reason }` when no matching report exists or rewrite
+ * failed. Non-throwing: caller (post-tool-use hook) uses this as a
+ * best-effort cleanup so a missing report dir or unrelated I/O issue
+ * does not escalate into a session-breaking hook failure.
+ */
+export function expirePersistedReport(reportsDir, sessionId, now = new Date()) {
+    const reports = listPersistedReports(reportsDir);
+    if (reports.length === 0) {
+        return { ok: false, reason: `no reports under ${reportsDir}` };
+    }
+    const latest = findLatestReportForSession(reports, sessionId);
+    if (!latest) {
+        return {
+            ok: false,
+            reason: `no report matched session_id=${sessionId} (${reports.length} report(s) for other sessions)`,
+        };
+    }
+    if (latest.approvalStatus !== "approved") {
+        return {
+            ok: false,
+            reason: `latest report ${path.basename(latest.filePath)} already has approvalStatus=${latest.approvalStatus ?? "<missing>"}, nothing to expire`,
+        };
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(latest.filePath, "utf8");
+    }
+    catch (err) {
+        return { ok: false, reason: `failed to read ${latest.filePath}: ${err.message}` };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        return { ok: false, reason: `failed to parse ${latest.filePath}: ${err.message}` };
+    }
+    const previousStatus = typeof parsed["approvalStatus"] === "string" ? parsed["approvalStatus"] : null;
+    parsed["approvalStatus"] = "expired";
+    parsed["expiredAt"] = now.toISOString();
+    try {
+        atomicWriteFile(latest.filePath, `${JSON.stringify(parsed, null, 2)}\n`);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            reason: `failed to rewrite ${latest.filePath}: ${err.message}`,
+        };
+    }
+    return { ok: true, filePath: latest.filePath, previousStatus };
+}
+export function checkPersistedReport(reportsDir, sessionId) {
+    const reports = listPersistedReports(reportsDir);
+    if (reports.length === 0) {
+        return {
+            approved: false,
+            detail: `no reports found at ${reportsDir}`,
+            report: null,
+        };
+    }
+    const latest = findLatestReportForSession(reports, sessionId);
+    if (!latest) {
+        return {
+            approved: false,
+            detail: `no report matched session_id=${sessionId} (${reports.length} report(s) for other sessions)`,
+            report: null,
+        };
+    }
+    if (latest.approvalStatus !== "approved") {
+        return {
+            approved: false,
+            detail: `latest report ${path.basename(latest.filePath)} has approvalStatus=${latest.approvalStatus ?? "<missing>"}`,
+            report: latest,
+        };
+    }
+    return {
+        approved: true,
+        detail: `approved via persisted report ${path.basename(latest.filePath)}${latest.approvedAt ? ` (approved at ${latest.approvedAt})` : ""}`,
+        report: latest,
+    };
+}
+//# sourceMappingURL=persisted-reports.js.map

package/dist/policy-packs/builtin/understanding-before-execution/persisted-reports.js.map

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

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

@@ -0,0 +1,106 @@
+import { type ApprovalLifecycle } from "./lifecycle.js";
+import { expirePersistedReport } from "./persisted-reports.js";
+/**
+ * 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 declare const DEFAULT_BASH_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * 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 declare function toolNameMatchesAny(toolName: string, patterns: readonly string[]): boolean;
+/** 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 declare function bashCommandMatchesAny(command: string, patterns: readonly RegExp[]): RegExp | undefined;
+/** Pull the Bash command out of a tool_input payload, `""` when absent
+ * or malformed. */
+export declare function extractBashCommandFromToolInput(toolInput: unknown): string;
+/** 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 declare function extractTaskIdFromToolInput(toolInput: unknown): string;
+/** 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 declare function extractTasksTransitionStatusFromToolInput(toolInput: unknown): string;
+export interface PostToolUseBoundaryMatch {
+    /** Final match decision: `toolNameMatched || bashRegex !== undefined`. */
+    matched: boolean;
+    /** Tool-name match, refined by the tasks_transition status filter. */
+    toolNameMatched: boolean;
+    /** Tool-name match BEFORE the tasks_transition status filter — lets
+     * the caller distinguish "not in the list" from "in the list, but
+     * status keeps the claim" for its diagnostic. */
+    rawToolNameMatched: boolean;
+    /** The `expire_on_bash_match` regex the command satisfied, if any. */
+    bashRegex: RegExp | undefined;
+}
+/**
+ * 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 declare function matchPostToolUseBoundary(toolName: string, toolInput: unknown, lifecycle: Pick<ApprovalLifecycle, "expireOnToolMatch" | "expireOnBashMatch">, bashToolNames?: ReadonlySet<string>): PostToolUseBoundaryMatch;
+export interface ApplyPostToolUseExpiryResult {
+    /** Did the session marker exist before this call cleared it? */
+    wasMarkerPresent: boolean;
+    /** Was a task-scoped marker also cleared? Only possible when
+     * `toolNameMatched` (Bash regex boundaries never carry a taskId). */
+    taskMarkerCleared: boolean;
+    /** The task id whose marker was cleared, `""` when none. */
+    clearedTaskId: string;
+    /** Did the persisted-report expiry succeed? */
+    persistedReportExpired: boolean;
+    /** Full expiry result (success detail or skip reason) for diagnostics. */
+    reportExpiry: ReturnType<typeof expirePersistedReport>;
+}
+/**
+ * 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 declare function applyPostToolUseExpiry(generatedDir: string, sessionId: string, toolInput: unknown, toolNameMatched: boolean, reportsDir: string, now?: Date): ApplyPostToolUseExpiryResult;
+/**
+ * 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 declare function describePostToolUseExpiry(hookLabel: string, sessionId: string, toolName: string, bashRegex: RegExp | undefined, expiry: ApplyPostToolUseExpiryResult): string;