@lannguyensi/harness 0.44.0 → 0.45.0

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

@@ -1,536 +1 @@
-import { type LedgerEntry } from "../../policies/index.js";
-export declare const APPROVED_LEDGER_TAG_PREFIX = "understanding-approved:";
-export declare const APPROVAL_MARKER_DIRNAME = ".approvals";
-export type ApprovalSource = "marker" | "ledger" | "persisted-report" | "none" | "recovery-commit";
-export interface ApprovalCheckResult {
-    approved: boolean;
-    source: ApprovalSource;
-    detail: string;
-}
-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;
-/** Build the per-session ledger tag the pack searches for. */
-export declare function approvedLedgerTagFor(sessionId: string): string;
-/**
- * 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;
-}
-/**
- * Phase 6 #6 — substring-pollution defence shared by every PreToolUse
- * blocker (Claude Code + Codex). Drops policy_decision rows so a
- * `understanding-approved:<sess>` substring inside an audit row's
- * JSON-encoded `reason` cannot accidentally satisfy the gate.
- */
-export declare function isPolicyDecisionRow(e: LedgerEntry): boolean;
-/**
- * Match a ledger fetch against the per-session approval tag. Kept for
- * the audit / forensics path only: a ledger entry tagged
- * `understanding-approved:<sid>` is no longer a sufficient signal to
- * unblock the gate (agent-tasks/88ca4bb3: the agent has the same MCP
- * surface and could self-write the row). Use `checkApprovalMarker`
- * for the gate decision; this helper now serves `harness audit` /
- * `harness explain --trace` style read paths that surface the
- * historic ledger trail without granting approval power.
- */
-export declare function matchLedgerEntries(entries: LedgerEntry[], sessionId: string): {
-    matched: boolean;
-    detail: string;
-};
-/** Filesystem path of the per-session approval marker. */
-export declare function approvalMarkerPathFor(generatedDir: string, sessionId: string): string;
-export interface ApprovalMarker {
-    approvedAt: string;
-    approvedBy: string;
-    /**
-     * sha256 hex of the persisted-report content this approval is bound to
-     * at sign-time (harness/f9485cc7). Optional on write (defaults to
-     * `null` — a marker with no report to bind, e.g. `harness approve
-     * branch-protection`, or a ledger-only approval); always present
-     * (possibly `null`) on a marker `checkApprovalMarker` returns.
-     */
-    reportContentHash?: string | null;
-}
-/**
- * Operator-side: write the marker file the gate consults. Atomic so a
- * crash mid-write cannot leave a half-empty file the gate would accept
- * as approved. Caller is `harness approve understanding`, which the
- * operator runs from their un-hooked shell; if the agent could call
- * this path the gate's value would collapse, so it lives behind the
- * approve CLI rather than as a generally importable verb.
- *
- * The marker is HMAC-signed (harness/f9485cc7) over (sessionId,
- * approvedAt, approvedBy, reportContentHash) using an operator-side key
- * lazily generated at `<generatedDir>/.approval-signing.key` — see
- * `src/runtime/approval-signing.ts` for the key-management contract and
- * the honest trust model. Mode 0600 on the marker file itself, best-
- * effort (matches the signing key's own permission convention); this is
- * defense-in-depth alongside the signature, not a substitute for it.
- */
-export declare function writeApprovalMarker(generatedDir: string, sessionId: string, marker: ApprovalMarker): string;
-export interface MarkerCheck {
-    matched: boolean;
-    detail: string;
-    marker: ApprovalMarker | null;
-    /**
-     * True when `matched` is false SPECIFICALLY because a readable marker
-     * existed but its `approvedAt` exceeded `opts.maxAgeMs`
-     * (agent-tasks/d8ee60ca) — as opposed to the marker being absent
-     * (never approved, or cleared by a task-completion boundary tool via
-     * `clearApprovalMarker`), corrupted, or the session id malformed.
-     * False whenever `matched` is true. This is the signal task 6e888423's
-     * recovery-git-commit exemption keys off: "this session/task DID have
-     * a real operator approval and it merely aged out" is safe to treat
-     * differently from "this session/task was never approved" or "a task
-     * boundary just cleared it for a new task" — see
-     * src/runtime/recovery-git-commit.ts for the full argument.
-     */
-    expired: boolean;
-    /**
-     * True when a marker FILE existed at the expected path but failed
-     * signature verification (harness/f9485cc7): missing `signature`/`alg`
-     * fields (a legacy pre-signing marker, or a marker planted without the
-     * operator-side key), a mismatched `alg`, or a signature that does not
-     * verify against the current key. Distinct from the marker being
-     * simply absent (`forged: false`, `matched: false`) so a caller can
-     * log/alert on an active forgery attempt instead of the routine
-     * "nobody has approved yet" case. `matched` is always false when
-     * `forged` is true — a forged marker never satisfies the gate,
-     * regardless of `approval_lifecycle.max_age`. A transient I/O read
-     * failure (`forged: false`, `matched: false`) is kept distinct from
-     * both: it is neither "no marker" nor evidence of tampering, just a
-     * marker whose integrity cannot be proven right now.
-     */
-    forged: boolean;
-}
-export interface CheckApprovalMarkerOptions {
-    /**
-     * Max marker age in milliseconds (agent-tasks/d8ee60ca). When set,
-     * a marker whose `approvedAt` is older than `now - maxAgeMs` is
-     * treated as expired and returns `matched:false` with an
-     * "expired" detail. When omitted, the marker has no TTL — the
-     * legacy contract (one approval per session, no expiry).
-     */
-    maxAgeMs?: number;
-    /** Override "now" for deterministic tests. */
-    now?: Date;
-}
-/**
- * Gate-side: is the per-session marker file present, readable, AND
- * validly signed? (harness/f9485cc7 — this replaced the earlier
- * "existence is enough" contract: a marker's mere presence used to
- * satisfy the gate even with a malformed or corrupted body, on the
- * theory that Edit/Write/Bash being gated meant only the operator could
- * ever create the file. That theory holds only as long as no OTHER
- * write primitive reaches `harness.generated/` — exactly the invariant
- * this signing scheme no longer has to trust blindly.) A marker with no
- * `signature`, a wrong `alg`, or a signature that fails to verify is
- * REJECTED — see `MarkerCheck.forged` — with the SAME `matched: false`
- * outcome as no marker at all, but a distinct, forgery-specific detail
- * string so callers can tell the two apart for audit.
- *
- * `opts.maxAgeMs` (agent-tasks/d8ee60ca): when set, a validly-signed
- * marker whose `approvedAt` is older than the cutoff returns
- * `matched:false` with an "expired" detail so the agent gets the same
- * "no approval" UX as a never-approved session and must re-approve.
- * Expiry is only evaluated AFTER signature verification succeeds — an
- * unsigned/forged marker is rejected outright, never "expired".
- */
-export declare function checkApprovalMarker(generatedDir: string, sessionId: string, opts?: CheckApprovalMarkerOptions): MarkerCheck;
-export interface ApprovalLifecycle {
-    /** Tool-name patterns whose successful PostToolUse expires the marker. */
-    expireOnToolMatch: string[];
-    /** Pre-compiled regex patterns matched against `Bash` tool_input.command. */
-    expireOnBashMatch: RegExp[];
-    /** Max marker age in milliseconds. Undefined means no TTL. */
-    maxAgeMs?: number;
-    /** Whether the operator explicitly opted out via `{ mode: "session" }`. */
-    legacyMode: boolean;
-}
-/**
- * Parse the optional `approval_lifecycle` block from a pack config.
- * Best-effort: malformed values fall back to the default (no expiry,
- * legacyMode=false) and write a one-line warning to the supplied
- * stderr. The PreToolUse / PostToolUse hooks must keep working even
- * when the operator typed a typo in the YAML.
- */
-export declare function parseApprovalLifecycle(raw: unknown, stderr?: {
-    write: (s: string) => void;
-} | null): ApprovalLifecycle;
-/**
- * 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;
-};
-/** Clear the per-session marker (used by `harness approve --revoke` and tests). */
-export declare function clearApprovalMarker(generatedDir: string, sessionId: string): void;
-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;
-/**
- * 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;
-export declare const ACTIVE_CLAIM_FILENAME = "active-claim";
-export declare function activeClaimPathFor(generatedDir: string): string;
-/**
- * Hook-side: write the active claim file. Atomic. Called from the
- * track-active-claim PostToolUse hook on `task_start`. The body is
- * just the taskId (no JSON) so an operator running
- * `cat ~/.claude/harness.generated/active-claim` sees the id directly.
- */
-export declare function writeActiveClaim(generatedDir: string, taskId: string): string;
-/**
- * Operator-side: read the active claim file. Returns the taskId or
- * null when the file is absent / unreadable / empty. `harness approve
- * understanding` calls this when --task is absent, then passes the
- * resolved id to writeTaskApprovalMarker.
- *
- * Defense-in-depth: if the on-disk content fails the same
- * path-traversal / newline check that gates writes, the read returns
- * null instead of surfacing a poisoned id. The write side guards
- * against a malformed taskId reaching the file in the first place,
- * but a stale file authored before this guard (or hand-edited)
- * shouldn't escalate into a forged task-marker write downstream.
- */
-export declare function readActiveClaim(generatedDir: string): string | null;
-/** Hook-side: remove the active claim file. Idempotent. */
-export declare function clearActiveClaim(generatedDir: string): void;
-export declare function checkPersistedReport(reportsDir: string, sessionId: string): PersistedReportApprovalCheck;
+export * from "./understanding-before-execution/index.js";