@lannguyensi/harness 0.64.0 → 1.0.0

package/dist/runtime/intercept.d.ts

@@ -1,623 +0,0 @@
-import { type ExtractBuiltins, type ExtractEventContext, type LedgerQueryResult } from "../policies/index.js";
-import type { Manifest, Policy } from "../schema/index.js";
-import { type AmpAwareNormalizedCommand, type CommandSegment, type NormalizedCommand, type QuoteAwareNormalizedCommand } from "./command-normalize.js";
-import { type EnvironmentResolution } from "./environment-resolver.js";
-import { type GitRepoContext } from "./git-context.js";
-import { type RiskProfile } from "./risk-classifier.js";
-export interface ToolEvent {
-    hook_event_name?: string;
-    tool_name?: string;
-    tool_input?: unknown;
-    session_id?: string;
-    cwd?: string;
-    [key: string]: unknown;
-}
-export type PolicyOutcome = "allow" | "warn" | "require_approval" | "deny" | "warn-degraded" | "deny-degraded";
-export interface PolicyDecision {
-    policyName: string;
-    enforcement: Policy["enforcement"];
-    outcome: PolicyOutcome;
-    reason: string;
-    extractValues: Record<string, string>;
-    ledgerTag: string;
-    requiresEval?: {
-        matchedCount: number;
-        reason: string;
-    };
-    /**
-     * Risk Classifier verdict for the action this decision was made
-     * about. Present only when the Risk Gate was active for the event
-     * (the manifest declared at least one `when:`-bearing policy); absent
-     * for a pure Phase-4 manifest, keeping its decisions byte-identical.
-     * Recorded to the audit ledger so `harness explain --trace` can
-     * replay the classification.
-     */
-    risk?: RiskProfile;
-    /** Context Resolver verdict, present under the same condition as `risk`. */
-    environment?: EnvironmentResolution;
-    /**
-     * One-line "to satisfy" hint synthesised from the policy's `requires`
-     * spec. Carried on the live decision so the deny-envelope formatter
-     * can append it to the user-facing reason text together with the
-     * session id. Optional because the warn-degraded path (requires eval
-     * threw) skips the requires evaluator and has no hint to forward.
-     */
-    recordHint?: string;
-    /**
-     * True when the policy's `when:` block matched because the action was
-     * unclassified (the fail-close rule in `when-eval.ts`: "unknown is not
-     * safe" for `risk.category_in` / `action.reversible`, the "treated as
-     * high" rung for `risk.severity_at_least`). Absent when the policy has
-     * no `when:` block, when the match was a genuine classification hit,
-     * or when `unclassifiedFallback` was false. Present in the audit
-     * record, the non-ux block-time deny message, AND (task 2929c5b7) the
-     * ux-declared `cannot:` deny message, so an operator — or the agent
-     * reading its own deny — can distinguish a real critical-severity
-     * match from a fail-closed unclassified command at a glance.
-     */
-    whenUnclassifiedFallback?: boolean;
-    /**
-     * Set when the policy's `ledger_tag` references `${REPO}` / `${BRANCH}`
-     * and the value resolved for this context was empty (cwd outside every
-     * git repository, detached HEAD, or an empty override), so the engine
-     * decided per enforcement WITHOUT rendering or querying a ledger tag.
-     * In-memory only: it is not part of the serialised audit row (the
-     * `reason` and the placeholder `ledgerTag` already carry the cause).
-     * The agent envelope renders `reason` with precedence over the policy's
-     * `ux:` / `producers:` text when this is set.
-     */
-    emptyIdentifier?: EmptyIdentifier;
-    /**
-     * Set when this decision was made for a FOREIGN attributed context: the
-     * repository a target-naming command (`git -C <dir>`, `cd <dir> &&`)
-     * resolved to, as opposed to the working directory's own. Absent for
-     * every cwd-context decision. In-memory only (not part of the serialised
-     * audit row); the block message uses it to name the repository and
-     * directory whose evidence is missing.
-     */
-    foreignTarget?: ForeignTarget;
-    evaluatedAt: string;
-}
-/** The repository name and directory a foreign attributed context resolved to. */
-export interface ForeignTarget {
-    repo: string;
-    dir: string;
-}
-/**
- * Claude Code hook "block" output. The top-level `decision: "block"` /
- * `reason` pair is the form every hook event accepts (UserPromptSubmit,
- * PostToolUse, Stop, ...). The `hookSpecificOutput.permissionDecision`
- * envelope is PreToolUse-only per Anthropic's hook protocol, so it is
- * present only when the inbound event is PreToolUse and absent
- * otherwise. Emitting both keys for a PreToolUse event keeps the deny
- * JSON readable by older Claude Code CLIs (which look at top-level
- * `decision`) and current 2.1+ ones (which prefer the envelope).
- *
- * The legacy `decision` value MUST be `"block"`, not `"deny"`: Claude
- * Code never recognised `"deny"` at the top level, so an emitter that
- * shipped that value silently let the tool call through.
- */
-export interface ClaudeDenyJson {
-    decision: "block";
-    reason: string;
-    hookSpecificOutput?: {
-        hookEventName: "PreToolUse";
-        permissionDecision: "deny";
-        permissionDecisionReason: string;
-    };
-}
-export interface InterceptResult {
-    decisions: PolicyDecision[];
-    /** non-null iff at least one matching policy with enforcement=block denied. */
-    blockJson: ClaudeDenyJson | null;
-}
-export interface LedgerClient {
-    query(tag: string, sessionId: string, timeoutMs?: number): Promise<LedgerQueryResult>;
-    /**
-     * Record a `policy_decision` entry to the evidence ledger. Implementations
-     * MUST be best-effort: failures bubble back as `null`/false so a degraded
-     * audit log doesn't itself block the tool call.
-     */
-    record(decision: PolicyDecision, sessionId: string): Promise<void>;
-    /**
-     * Release any pooled connection (the real client holds one grounding-mcp
-     * subprocess across all queries + records of an intercept invocation).
-     * Owned by the CLI wrapper that constructed the client — `intercept()`
-     * itself never calls it. Optional so injected test doubles and the
-     * degraded no-op client don't have to implement it.
-     */
-    dispose?(): void;
-}
-export interface InterceptOptions {
-    manifest: Manifest;
-    event: ToolEvent;
-    ledger: LedgerClient;
-    builtins: ExtractBuiltins;
-    /** Timeout passed through to the ledger client. */
-    ledgerTimeoutMs?: number;
-    /** Override "now" for deterministic tests. */
-    now?: Date;
-    /**
-     * Current git HEAD sha for the event's cwd, resolved by the CLI
-     * wrapper. Threaded through to `evaluateRequires` so the `at_head`
-     * branch can compare against ledger entries' `head:<sha>` token.
-     * Optional: omitted on non-git events, in which case the at_head
-     * branch falls through to the standard time-window check.
-     */
-    currentHeadSha?: string;
-    /**
-     * Ambient context for the Risk Gate stages — the Action Envelope
-     * build (#2) and the environment resolution (#4). Resolved by the CLI
-     * wrapper (git / user / host / kube-config / env reads) and threaded
-     * in, keeping `intercept()` itself I/O-free, the same
-     * resolved-by-the-wrapper pattern as `currentHeadSha` and `builtins`.
-     *
-     * Optional: omitted by Phase-4-era callers and by unit tests that do
-     * not exercise `when:`. When omitted, the envelope is built from the
-     * event alone — risk then classifies as unclassified and the
-     * environment resolves to `unknown`. A manifest with no `when:`
-     * policy never reads any of this regardless (see `intercept`).
-     */
-    riskContext?: RiskGateContext;
-    /**
-     * Precomputed `NormalizedCommand` for a Bash event's
-     * `tool_input.command`. `runInterceptCli` already calls
-     * `normalizeCommand` once (for `bash_match` trigger normalisation);
-     * threading the SAME result in here lets `policyMatchesEvent` reuse it
-     * for every policy in the `matching` loop below instead of recomputing
-     * it — same resolved-by-the-wrapper pattern as `currentHeadSha`,
-     * `builtins`, and `riskContext`. Optional: omitted by non-Bash events
-     * and by callers/tests that don't supply one, in which case
-     * `policyMatchesEvent` computes it lazily per policy (correct, just
-     * not de-duplicated).
-     *
-     * INVARIANT: this is NOT checked against `event` at runtime — nothing
-     * verifies the `NormalizedCommand`
-     * passed in was actually derived from THIS event's own
-     * `tool_input.command`. Safe today because there is exactly one
-     * production caller (`runInterceptCli`, `src/cli/policy/intercept.ts`),
-     * which computes it from the SAME `event` it then passes to
-     * `intercept()`. A future second caller that threads a mismatched
-     * `NormalizedCommand` (e.g. reused across two different events) would
-     * silently apply the wrong command's `bash_match` normalisation with
-     * no error — keep this pairing manual-but-obvious at every call site
-     * rather than assuming it self-enforces.
-     */
-    normalizedCommand?: NormalizedCommand;
-    /**
-     * Memoised thunk resolving the ampersand-aware SECOND normalisation
-     * pass for the SAME Bash event's `tool_input.command` (task aabbad63,
-     * `src/runtime/command-normalize.ts`'s `normalizeCommandAmpAware`).
-     * `policyMatchesEvent`'s third arm calls this ONLY when a policy's
-     * regex has already missed BOTH the raw command and `normalizedCommand`
-     * above — most events never reach it. Threaded as a THUNK rather than
-     * a precomputed value (unlike `normalizedCommand`) specifically so that
-     * "compute at most once per event" can be achieved WITHOUT paying the
-     * cost on the common (already-matched) path: `runInterceptCli`
-     * constructs one self-memoising closure per event and hands it here;
-     * every policy in the `matching` loop below that still needs the amp
-     * form calls the SAME thunk, and only the FIRST such call does the
-     * actual work.
-     *
-     * Optional: omitted by non-Bash events and by callers/tests that don't
-     * supply one, in which case `policyMatchesEvent` falls back to calling
-     * `normalizeCommandAmpAware` directly per policy (correct, just not
-     * de-duplicated) — the same fallback shape `normalizedCommand` already
-     * has.
-     *
-     * SAME INVARIANT as `normalizedCommand` above: this is NOT checked
-     * against `event` at runtime. Nothing verifies the thunk passed in was
-     * actually derived from THIS event's own `tool_input.command`. Safe
-     * today because there is exactly one production caller
-     * (`runInterceptCli`), which builds the thunk from the SAME `event` it
-     * then passes to `intercept()` — keep this pairing manual-but-obvious
-     * at every call site rather than assuming it self-enforces.
-     */
-    ampNormalizedCommandThunk?: () => AmpAwareNormalizedCommand;
-    /**
-     * Memoised thunk resolving the quote-aware THIRD normalisation pass for
-     * the SAME Bash event's `tool_input.command` (task cf3dff51,
-     * `src/runtime/command-normalize.ts`'s `normalizeCommandQuoteAware`).
-     * `policyMatchesEvent`'s FOURTH arm calls this ONLY when a policy's
-     * regex has already missed the raw command, `normalizedCommand`, AND
-     * `ampNormalizedCommandThunk` above — mirrors `ampNormalizedCommandThunk`
-     * exactly (same memoise-once-per-event-via-thunk shape, same reason:
-     * "compute at most once per event" without paying the cost on the
-     * common, already-matched path).
-     *
-     * Optional: omitted by non-Bash events and by callers/tests that don't
-     * supply one, in which case `policyMatchesEvent` falls back to calling
-     * `normalizeCommandQuoteAware` directly per policy (correct, just not
-     * de-duplicated) — the same fallback shape `normalizedCommand` /
-     * `ampNormalizedCommandThunk` already have.
-     *
-     * SAME INVARIANT as `normalizedCommand` / `ampNormalizedCommandThunk`
-     * above: this is NOT checked against `event` at runtime. Nothing
-     * verifies the thunk passed in was actually derived from THIS event's
-     * own `tool_input.command`. Safe today because there is exactly one
-     * production caller (`runInterceptCli`), which builds the thunk from
-     * the SAME `event` it then passes to `intercept()` — keep this pairing
-     * manual-but-obvious at every call site rather than assuming it
-     * self-enforces.
-     */
-    quoteNormalizedCommandThunk?: () => QuoteAwareNormalizedCommand;
-    /**
-     * Precomputed per-segment view (`command-normalize.ts`'s
-     * `segmentViewOf`) of a Bash event's `tool_input.command`, EAGERLY
-     * supplied (task `98ad072f`, T-003). `null` mirrors `segmentViewOf`'s
-     * own contract: the command exceeded `MAX_NORMALIZE_LENGTH`, so no
-     * segment view exists (treated as `[]` — unattributable, cwd builtins,
-     * identical to a command with no `bash_match` trigger at all).
-     *
-     * CORRECTED (D-015, fix round, run 2026-08-02-per-repo-gate-scoping-
-     * redesign): the prior wording here claimed a manifest with no
-     * `${REPO}`/`${BRANCH}`/`at_head` policy "never pays this cost even
-     * when uninjected" — true only for a caller that omits BOTH this field
-     * AND `commandSegmentsThunk` below. The one production caller
-     * (`runInterceptCli`) previously injected THIS field eagerly, computed
-     * unconditionally for every Bash event regardless of whether any policy
-     * needed it — measured a real, avoidable second segmentation walk (see
-     * `segmentViewOf`'s own doc comment in `command-normalize.ts` for the
-     * +206% number). It now injects `commandSegmentsThunk` instead, which
-     * IS deferred until first use. This eager field still exists for a
-     * caller that already has a segment view in hand (or a test asserting
-     * against a specific one) and wants to skip `intercept()`'s own lazy
-     * resolution entirely — it is simply not, by itself, a laziness
-     * guarantee. Optional: omitted by non-Bash events and by callers/tests
-     * that don't supply one, in which case `resolveCommandSegments` falls
-     * through to `commandSegmentsThunk`, then to computing it lazily itself.
-     *
-     * SAME INVARIANT as `normalizedCommand` / `ampNormalizedCommandThunk`
-     * above: not checked against `event` at runtime; the one production
-     * caller derives it from the identical event, same as those two.
-     */
-    commandSegments?: CommandSegment[] | null;
-    /**
-     * Memoised thunk resolving the per-segment view (task `98ad072f`,
-     * T-003; D-015 fix round) — the SAME resolved-by-the-wrapper,
-     * compute-at-most-once-per-event pattern `ampNormalizedCommandThunk`
-     * above already uses, applied to `commandSegments` so the segmentation
-     * walk it wraps is deferred until some matching policy actually needs
-     * it (`usesPerRepoBuiltins` below), not paid on every Bash event
-     * regardless. Preferred over the eager `commandSegments` field above
-     * when both are supplied. Optional: omitted by non-Bash events and by
-     * callers/tests that don't supply one, in which case
-     * `resolveCommandSegments` falls back to `commandSegments`, then to
-     * computing it lazily itself — same fallback chain shape as
-     * `normalizedCommand` / `ampNormalizedCommandThunk`.
-     *
-     * SAME INVARIANT as `normalizedCommand` / `ampNormalizedCommandThunk`
-     * above: not checked against `event` at runtime.
-     */
-    commandSegmentsThunk?: () => CommandSegment[] | null;
-    /**
-     * Whether `options.builtins.REPO` / `.BRANCH` were set by an explicit
-     * operator override (`HARNESS_REPO` / `HARNESS_BRANCH` env vars) rather
-     * than derived from the cwd's git context (D-015 fix round, run
-     * 2026-08-02-per-repo-gate-scoping-redesign). `src/cli/policy/
-     * intercept.ts`'s own comment on its `builtins` object says "an
-     * explicit env var still wins" — true for the cwd context, but a
-     * per-policy ATTRIBUTED context (a foreign target's resolved
-     * `${REPO}`/`${BRANCH}`) unconditionally overwrote REPO/BRANCH with the
-     * target repo's own identity, discarding the override — measured.
-     * When true here, `resolveAttributedContexts` keeps
-     * `options.builtins.REPO` (already the override value — see the CLI
-     * wrapper) instead of substituting the attributed target's own repo
-     * name; independently for BRANCH via `branchOverridden`. `false` /
-     * absent — the default for every caller that does not set this,
-     * including every existing test — when the corresponding builtin was
-     * derived, not overridden.
-     */
-    repoOverridden?: boolean;
-    /** See `repoOverridden` above; the same override for `${BRANCH}`. */
-    branchOverridden?: boolean;
-    /**
-     * Destination for audit-write failure diagnostics. Defaults to
-     * `process.stderr` when omitted. Goes to stderr so Claude Code's
-     * stdout deny-JSON contract is unaffected.
-     *
-     * Injected by callers (tests, CLI wrapper) so the function stays
-     * deterministic and testable without capturing process.stderr.
-     */
-    stderr?: NodeJS.WritableStream;
-}
-/**
- * Ambient inputs the Risk Gate needs that the CLI wrapper resolves from
- * the host (filesystem + process). Mirrors the `EnvelopeContext` /
- * `SignalInputs` split the debug verbs already use.
- */
-export interface RiskGateContext {
-    /** Git context resolved against the event's cwd. */
-    git: GitRepoContext;
-    /** Working directory the action runs in. */
-    cwd: string;
-    /** OS user, or "" when unavailable. */
-    user: string;
-    /** Host name, or "" when unavailable. */
-    host: string;
-    /** Environment variables, for resolver `env_var_patterns`. */
-    env: Record<string, string | undefined>;
-    /** Current kube context name, or "" when unknown. */
-    kubeContext: string;
-    /** Current kube namespace, or "" when unknown. */
-    kubeNamespace: string;
-}
-/**
- * Does a policy's `trigger:` match this event? This is the WHICH-tool-
- * calls filter; the WHETHER-it-applies filter is `policy.when:`,
- * evaluated separately (`evaluateWhen`). A policy fires only when both
- * hold. Exported so `harness explain-policy` can report the trigger
- * verdict on its own.
- *
- * `precomputedNormalizedCommand` is an optional caller-supplied
- * `NormalizedCommand` for the event's command: `intercept()` below
- * resolves ONE `NormalizedCommand` per event (via
- * `options.normalizedCommand`, itself computed once by
- * `runInterceptCli`) and threads it into every `policyMatchesEvent`
- * call in its `matching` loop, so a raw-miss event normalises the
- * command exactly ONCE across the whole manifest instead of once per
- * policy. Omitted by standalone callers (`harness explain-policy`, most
- * tests), which fall back to computing it lazily right here — correct
- * either way, since `normalizeCommand` is a pure function of the
- * command string alone.
- *
- * `ampNormalizedCommandThunk` (task aabbad63) is the SAME
- * resolved-by-the-wrapper pattern for the ampersand-aware SECOND
- * normalisation pass, but threaded as a memoised THUNK rather than a
- * precomputed value — see `InterceptOptions.ampNormalizedCommandThunk`
- * for why laziness matters here specifically. Omitted callers fall back
- * to calling `normalizeCommandAmpAware` directly, same shape as the
- * `precomputedNormalizedCommand` fallback above.
- *
- * `quoteNormalizedCommandThunk` (task cf3dff51) is the SAME thunk pattern
- * again, for the quote-aware THIRD normalisation pass — see
- * `InterceptOptions.quoteNormalizedCommandThunk`. Omitted callers fall
- * back to calling `normalizeCommandQuoteAware` directly, same shape as
- * the two fallbacks above.
- */
-export declare function policyMatchesEvent(policy: Policy, event: ToolEvent, precomputedNormalizedCommand?: NormalizedCommand, ampNormalizedCommandThunk?: () => AmpAwareNormalizedCommand, quoteNormalizedCommandThunk?: () => QuoteAwareNormalizedCommand): boolean;
-/**
- * Does a decision abort the tool call? Phase 7 #6 makes the Risk Gate
- * authoritative at the `PreToolUse` boundary:
- *   - `deny` aborts (a `block`-enforcement policy whose requires failed,
- *     the Phase 4 mechanism, unchanged).
- *   - `require_approval` aborts until the approval evidence exists. In
- *     Phase 7 #5 this outcome was returned but did not block; #6 makes
- *     it block. The approval tag is satisfiable through the policy's
- *     `requires:` (an operator runs `harness approve risk`); once the
- *     tag is on record the requires evaluation passes and the outcome
- *     is `allow` instead.
- *   - `deny-degraded` aborts (task f1aea826): it is only ever produced
- *     for `block` / `require_approval` policies under the default
- *     `preserve_enforcement` posture (see `degradedOutcome`), so its
- *     presence alone means "an incident-preventing gate could not read
- *     its evidence" — fail closed.
- *   - `allow` / `warn` / `warn-degraded` never abort.
- *
- * Exported for the CLI wrapper's pending-approval staging
- * (`src/cli/policy/intercept.ts`), which must agree with the runtime on
- * WHICH decision is the first blocking one — a hand-rolled copy there
- * drifted when `deny-degraded` was added (review 2026-08-08, low
- * finding). Keep this the single definition.
- */
-export declare function isBlockingDecision(d: PolicyDecision): boolean;
-/**
- * Bound and clean a transport-level reason before it is interpolated
- * into the agent-facing deny-degraded envelope. The string can embed
- * output captured from the grounding-mcp SUBPROCESS (`exitDiagnostic`
- * in `src/policies/ledger-client.ts` appends the child's last stderr
- * line), i.e. untrusted content that previously only reached stderr
- * and the audit ledger, never model-visible text. The full, untouched
- * string still goes to the audit row and the verbose diagnostic; only
- * the envelope interpolation and the default-verbosity operator hint
- * are bounded.
- *
- * Exported for the CLI wrapper's deny-degraded operator hint (review
- * 2026-08-08, round 3; default-verbosity only, suppressed under
- * verbose), which interpolates the same untrusted reason into its
- * one-line stderr surface.
- */
-export declare function sanitizeEnvelopeReason(reason: string): string;
-/** Which per-repo builtin resolved to an empty value; see {@link emptyIdentifierGuard}. */
-export type EmptyIdentifier = "REPO" | "BRANCH";
-export interface EmptyIdentifierGuard {
-    identifier: EmptyIdentifier;
-    /** Agent-facing text naming a state the agent can establish itself. */
-    message: string;
-}
-/**
- * Does `ledgerTagTemplate` reference `${REPO}` / `${BRANCH}` while the
- * value resolved for this context is empty? An empty identifier must
- * never be rendered into a ledger tag: `preflight:` is a substring of
- * EVERY preflight fact, so a blank tag lets any unrelated fact satisfy
- * the gate (and `preflight-before-push` would render "You cannot push
- * branch  yet."). The caller decides per enforcement with
- * `message` instead of querying the ledger.
- *
- * `REPO` wins over `BRANCH`, and a branch-only template evaluated where
- * REPO is empty too (no repository at all) gets the no-repository text,
- * since "HEAD is detached" would be false there. The messages name a
- * state the agent can establish (`cd` / `git -C` / `git switch`), never
- * a tag to produce, so there is no producer trap, and never an opt-out
- * (a block that names its own disable path is not a gate).
- *
- * Exported so `harness dry-run` shows the same hint instead of a blank
- * tag (`src/cli/dry-run.ts`).
- */
-export declare function emptyIdentifierGuard(ledgerTagTemplate: string, values: Record<string, string>): EmptyIdentifierGuard | null;
-/**
- * Which of a policy's own trigger-satisfying segments name a target — the
- * attribution sibling of `policyMatchesEvent` (task `98ad072f`, T-003).
- * Re-tests the policy's OWN `bash_match` regex against each segment's
- * `text` in isolation: every shipped `bash_match` alternation includes a
- * `^` branch, so testing it against one segment's canonicalised text
- * alone (no leading boundary character — see `CommandSegment.text`'s own
- * doc comment) is well-defined. Returns every segment that matches on its
- * own — usually one, occasionally several (D-004: a decoy read and a cwd
- * read chained in one command can each independently satisfy the SAME
- * trigger).
- *
- * Never changes WHETHER a policy matches — `policyMatchesEvent` already
- * decided that from the WHOLE command (raw-or-normalised-or-amp-
- * normalised), unchanged by this function. This only narrows down WHICH
- * segment(s), if any, are individually responsible for the match, so
- * `intercept()` below knows which segment's target — if any — to resolve
- * the `${REPO}`/`${BRANCH}`/`currentHeadSha` builtins from instead of the
- * event's own cwd. `[]` when the policy has no `bash_match` trigger (an
- * MCP-tool-name-triggered policy — no segment concept applies), when its
- * regex is malformed (mirrors `policyMatchesEvent`'s own defensive
- * `try/catch`), or when the whole-command match came ONLY from the
- * ampersand-aware third arm: `segments` here is always built from the
- * PRIMARY (`BOUNDARY_RE`) segmentation, which — by construction — cannot
- * itself contain the bare-`&` split the amp arm relies on, so an amp-
- * only match finds no individually-matching segment and this returns
- * `[]` (D-003: cwd builtins, identical to shipped).
- */
-export declare function attributeTriggerSegments(policy: Policy, segments: readonly CommandSegment[]): CommandSegment[];
-/**
- * Does a policy's `requires:` reference the per-repo `${REPO}`/`${BRANCH}`
- * builtins, or ask for `at_head`? Only these policies pay the per-policy
- * attribution cost below — every other matching policy keeps the plain,
- * per-event cwd builtins `options.builtins` already carries, byte-
- * identical to before this task. D-005: `at_head` is included even when
- * `ledger_tag` itself doesn't reference `${REPO}`/`${BRANCH}`, because
- * `at_head` compares against `currentHeadSha`, which this task resolves
- * from the SAME per-policy context — splitting the two would check
- * `at_head` against the cwd's HEAD while `${REPO}` (if present elsewhere)
- * named a different repo, the worse inconsistency D-005 rejects.
- */
-export declare function usesPerRepoBuiltins(policy: Policy): boolean;
-/** One `${REPO}`/`${BRANCH}`/`currentHeadSha` context a policy is evaluated against. */
-interface AttributedContext {
-    builtins: ExtractBuiltins;
-    currentHeadSha: string | undefined;
-    /** Set only on a foreign context; the cwd context never carries it. */
-    foreignTarget?: ForeignTarget;
-}
-/**
- * Bound on the number of DISTINCT attributed contexts one policy is
- * evaluated against for one event (D-013, fix round, run
- * 2026-08-02-per-repo-gate-scoping-redesign). Each distinct context costs
- * one ledger query and one audit write in `intercept()`'s evaluation loop
- * below; on a manifest with several per-repo-builtins policies (the
- * shipped `FULL_TEMPLATE` has four), an event naming K distinct targets
- * amplifies to 4K queries/writes, unbounded by `MAX_NORMALIZE_LENGTH` —
- * measured 200/200 at K=200 by reviewer 2, on a hook budget whose timeout
- * is ALLOW (same class as the 07-27 quadratic hot-path fail-open: a slow
- * enough event silently passes). `resolveAttributedContexts` returns a
- * `"bounded"` result instead of a `contexts` array once a policy's DISTINCT
- * targets would exceed this constant; `intercept()` denies that policy
- * directly (naming the ambiguity) without querying the ledger for any of
- * them, rather than silently evaluating all of them.
- */
-export declare const MAX_ATTRIBUTED_CONTEXTS = 4;
-/** Discriminated result of `resolveAttributedContexts` (D-013). */
-export type AttributedContextsResult = {
-    kind: "contexts";
-    contexts: AttributedContext[];
-} | {
-    kind: "bounded";
-    distinctCount: number;
-};
-/**
- * Resolve the distinct `${REPO}`/`${BRANCH}`/`currentHeadSha` contexts a
- * `usesPerRepoBuiltins` policy must be evaluated against (task `98ad072f`,
- * T-003, `01-plan.md` Proposed Approach items 2-4). The engine trusts a
- * trigger-satisfying segment's `effectiveTarget` UNIFORMLY as the
- * directory that segment's own invocation genuinely runs in (bash
- * semantics) — orchestrator decision D-010, 2026-08-02: an earlier
- * revision of this function additionally distrusted an inherited target
- * whenever a DIFFERENT invocation intervened between the `cd` and the
- * satisfying segment — REJECTED: that coupling has no basis in bash's own
- * semantics, is dodgeable by inserting any harmless read between the `cd`
- * and the gated verb, and carried its own unverified `cd`-recognition
- * gap. The `cd <B> && git log && git push` shape this was meant to guard
- * is not a regression at all under this design — `git push` genuinely
- * runs inside B — see `tests/runtime/intercept-cli.test.ts`'s "leading-cd
- * is now a deliverable" block.
- *
- * D-021 (UNIVERSAL-ADDITIVE, operator decision, fix round, run
- * 2026-08-02-per-repo-gate-scoping-redesign): attribution is uniformly
- * ADDITIVE, never REPLACE. Every satisfying segment with an attributable
- * target — `seg.effectiveTarget !== null`, whether it came from the
- * segment's OWN explicit repo-relocating flag (`-C`/`env -C`/`--git-dir`;
- * `--work-tree` is excluded from ever producing a target at all, D-017)
- * or was INHERITED from a preceding `cd` — demands the cwd context AND
- * that target's own context, side by side; `seg.ownTarget` is not
- * consulted for this decision. Any unsatisfied context blocks the whole
- * event (the existing per-context evaluation machinery below is
- * unchanged). `seg.effectiveTarget === null` (fully unattributable —
- * D-003) still adds ONLY the cwd context — there is no foreign target to
- * be additive WITH.
- *
- * Demanding cwd unconditionally makes the engine structurally immune to
- * misattribution of the foreign target: no gap in `command-normalize.ts`'s
- * static, string-only model of shell control flow (subshells, pipes,
- * `cd -`, a later `cd`, an unmodeled git flag composition) can ever make a
- * gate WEAKER than the shipped, cwd-only engine, because cwd's own demand
- * is never dropped — only added to. This replaces an earlier REPLACE-for-
- * own-target design (D-011) that trusted a statically extracted own
- * target as proof of "this one invocation operates there"; four
- * independent review passes each measured a live bypass of that
- * invariant against the shipped binary (a forged `.git/HEAD` directory
- * reached through, respectively, a non-persisting `cd`, `--work-tree`,
- * more than one repo-relocating flag, and a tilde-valued flag not counted
- * by the multi-flag guard) — see `03-decisions.md` D-011/D-017/D-018/
- * D-019/D-020/D-021 for the full history. The static-analysis-proves-it
- * invariant those bypasses each disproved is not carried forward here.
- * Cost accepted by the operator: a legitimate `git -C B` from cwd A now
- * demands BOTH A's and B's context, where the pre-D-021 engine demanded
- * only B's.
- *
- * One exception to "never dropped": when the working directory is outside
- * every git repository (a blank `${REPO}` for the policy, as the guard
- * sees it), its cwd context is not demanded next to a segment whose own
- * target resolved to a real repository (see the loop body). That
- * exception relies on two static models: the target attribution, whose
- * known misattribution (a `GIT_DIR=` prefix or a third repository reached
- * through another construct) exists for every cwd, and the check that the
- * cwd is outside every repository, which errs toward inside: it holds only
- * when neither the cwd nor any ancestor has an entry named `HEAD` or
- * `.git` (`mayBeInsideRepository`). A detached cwd and every other
- * non-blank cwd context are still never dropped.
- *
- * D-012: a target reached through a symlink resolves to its REAL
- * (realpath'd) repository identity, not the symlink's own lexical
- * basename — `resolveGitContext` derives `repo` from the basename of
- * wherever it's pointed, and never itself realpaths, so an agent could
- * otherwise pick the demanded repo identity by naming a symlink.
- *
- * D-013: distinct contexts are bounded at `MAX_ATTRIBUTED_CONTEXTS`; see
- * that constant's own comment.
- *
- * D-015: the cwd context is deduped by its OWN `[REPO, BRANCH, sha]`
- * signature (not the literal string `"cwd"`), so a foreign path that
- * resolves to the SAME repository identity as cwd (e.g. a subdirectory of
- * the cwd repo reached via an explicit `-C`) collapses into the cwd
- * context instead of producing a spurious duplicate decision/audit write.
- * `repoOverridden` / `branchOverridden` (from `InterceptOptions`, both
- * default `false`) keep an operator's `HARNESS_REPO`/`HARNESS_BRANCH`
- * override intact in an attributed foreign context instead of letting the
- * target repo's own identity silently overwrite it — independently per
- * field. `satisfying` is a `Set` (not `Array.includes` per segment) for
- * O(1) membership tests instead of O(n) per segment.
- *
- * A policy with no attributable foreign target (no `bash_match`, no
- * individually-matching segment, only an amp-arm-only match, an
- * unattributable composition, a target resolving to the SAME repository
- * identity as cwd, or a target outside any git repo — D-003) is evaluated
- * EXACTLY as it is today, with the EXACT SAME `options.builtins` object
- * reference (no clone) when nothing attributed, keeping that the
- * byte-identical common case.
- *
- * `resolveGitContextMemo` is a per-`intercept()`-call cache keyed by the
- * REALPATH'D absolute path (never module-level state — no cross-event
- * caching), so several policies (or several satisfying segments) naming
- * the same foreign path within one event pay the `fs` cost once, not
- * once per policy per segment. `mayBeInsideRepositoryMemo` is the same
- * kind of per-call cache for the cwd's own outside-every-repository
- * check, keyed by the cwd's real path, so that walk runs once per event.
- */
-export declare function resolveAttributedContexts(policy: Policy, segments: readonly CommandSegment[], cwdBuiltins: ExtractBuiltins, cwdCurrentHeadSha: string | undefined, resolveGitContextMemo: Map<string, GitRepoContext>, mayBeInsideRepositoryMemo: Map<string, boolean>, repoOverridden: boolean, branchOverridden: boolean, extractContext: ExtractEventContext): AttributedContextsResult;
-export declare function intercept(options: InterceptOptions): Promise<InterceptResult>;
-export {};