approval-md 0.1.0 → 0.3.0

package/dist/src/core/command-class.d.ts

@@ -0,0 +1,697 @@
+/**
+ * Shell command classification: a pure, deterministic map from a command line
+ * to the SPEC.md §7 side-effect classes it would produce (APRV-82).
+ *
+ * This is the input half of the Claude Code PreToolUse hook. The harness hands
+ * us a command string it is about to run; policy speaks in classes; something
+ * has to translate. That translation is the reviewable artifact of this task, so
+ * it lives in one file, is data-driven, and is exhaustively fixture-tested.
+ *
+ * Three properties are load-bearing.
+ *
+ * **Pure.** No filesystem, no clock, no environment, no network. The same string
+ * always yields the same answer, which is what makes the fixture table a real
+ * specification rather than a sample of observed behaviour.
+ *
+ * **Fail closed, in three named ways.** A construct whose effect cannot be read
+ * off the text is `opaque` (`bash -c`, `eval`, backticks, a tainting command
+ * substitution). A binary the table does not know is `unclassified`. A string
+ * the tokenizer cannot even split is `unparseable`. All three are refusals, and
+ * the hook denies on each: the alternative, guessing a class for a command we do
+ * not understand, would let the least legible command lines through the widest
+ * gap. Ambiguity inside a construct we DO understand resolves to the stricter
+ * class (`git push` with no refspec is `vcs.push.main`, an `rm` path holding an
+ * unexpanded `$VAR` is `files.delete.out_of_scope`).
+ *
+ * **Best effort, and honest about it.** This is a classifier over shell text,
+ * not a shell. It is a speed bump against an agent doing the wrong thing by
+ * mistake, in the SPEC.md §11 sense; it is not scheming-robust, and nothing here
+ * claims otherwise. The hard boundary stays where SPEC.md §10.4 puts it: the
+ * credentials in the vault and the token an adapter demands.
+ *
+ * Self-reported text is never read. The hook passes the command only; the
+ * harness's `description` field is authored by the very agent being gated
+ * (SPEC.md §11.1: self-reported fields never reduce scrutiny).
+ *
+ * Two imports, and both are pure in exactly the same way this file is: no disk,
+ * no clock, no environment, no dependencies.
+ *
+ * `core/read-scope.ts` (APRV-347) holds the read-side path arithmetic, so the
+ * hook and the policy explainer can ask the same questions this file asks, of
+ * the same table, rather than each growing a copy of it.
+ *
+ * `core/policy-match.ts` (APRV-354) is imported for ONE name, the
+ * `harness.launch.` prefix. The classifier emits the family and two enforcement
+ * paths refuse a member of it that no policy rule names, so the three have to
+ * agree on what the family is; a second spelling of the prefix would close one
+ * of those doors and leave the other open. The import is type-safe in the
+ * dependency sense as well: `policy-match.ts` itself imports only types.
+ */
+/** Why a command could not be classified. Each denies; none is a soft failure. */
+export type ClassifierFailureCode = "unclassified" | "opaque" | "unparseable";
+/** One command in a pipeline or list, with the class it resolved to. */
+export interface ClassifiedSegment {
+    /** The segment's source text, as written. */
+    text: string;
+    /** The dotted side-effect class (SPEC.md §7). */
+    class: string;
+    /** Which rule decided it, for `hook classify` output and for tests. */
+    rule: string;
+    /**
+     * The protected path that selected the class, present only when one did
+     * (APRV-143).
+     *
+     * The protected classes (`policy.edit`, `policy.core`, `log.mutate`) are the
+     * classes a segment can take because of a *value* in it rather than because
+     * of its binary, and until this field the value was discarded the moment the
+     * rule fired: an approver was told the class and left to guess which of six
+     * arguments earned it. It is the word the classifier matched, verbatim, so a
+     * channel can name it without a second search of its own.
+     */
+    path?: string;
+    /**
+     * The sandbox wrapper this segment runs inside, when the classifier unwrapped
+     * one (APRV-193). Absent means "not wrapped, as far as this classifier can
+     * tell", which is the direction every caller must fail in: the marker is only
+     * ever read to RELAX a requirement, so an early return that omits it costs a
+     * refusal and never an authorization.
+     *
+     * `runtime` is `approval sandbox -- …`, whose profile this runtime writes.
+     * `external` is a hand-written `sandbox-exec -f <profile> …`, which is
+     * classified honestly (by its inner argv) and trusted for nothing: the
+     * profile is the caller's, and a profile a caller wrote can allow anything.
+     */
+    sandbox?: SandboxWrapper;
+}
+/**
+ * Who wrote the profile a wrapped command runs under (APRV-193).
+ *
+ * The distinction is the whole reason this is not a boolean. Classification
+ * treats the two identically — both are unwrapped to the inner argv, because a
+ * wrapper is a room and the class belongs to what runs in it. Enforcement does
+ * not: `APPROVAL_HOOK_REQUIRE_SANDBOX` is satisfied only by `runtime`, because
+ * `sandbox-exec -f /tmp/anything.sb` with a profile whose only line is
+ * `(allow default)` denies nothing at all, and a requirement a caller can meet
+ * by writing their own permission is not a requirement.
+ */
+export type SandboxWrapper = "runtime" | "external";
+export type CommandClassification = {
+    ok: true;
+    segments: ClassifiedSegment[];
+    classes: string[];
+} | {
+    ok: false;
+    code: ClassifierFailureCode;
+    /** The segment (or whole command) that could not be read. */
+    segment: string;
+    detail: string;
+};
+/**
+ * The pass-through pseudo-class for the gate's own CLI.
+ *
+ * `approval …` is already the enforcement path — gating it with itself would
+ * either deadlock (the hook waiting on a decision that `approval grant` cannot
+ * deliver) or recurse. The hook allows this class without touching the log; it
+ * is never written to any envelope and no policy rule should name it.
+ */
+export declare const GATE_SELF_CLASS = "gate.self";
+/**
+ * The three classes a protected path can select (APRV-198).
+ *
+ * One class used to cover the whole protected surface, so a policy could not
+ * say "an agent may edit the prose that describes the gate, under sampling,
+ * and may never touch the gate itself". These are that sentence, in the order
+ * of decreasing consequence:
+ *
+ * - `log.mutate` — anything aimed at `.approval/log/`. The log is the truth;
+ *   a write to it is not an edit of the rules, it is an edit of the record of
+ *   what happened.
+ * - `policy.core` — the policy file itself and the rest of the gate's own
+ *   directory (env, payload store, vault, keys, `QUEUE.md`), plus the harness
+ *   files that install the hook. An agent that can write these can write
+ *   itself out of the gate without the gate ever seeing it.
+ * - `policy.edit` — the prose and configuration ABOUT the gate: the agent
+ *   instructions, CI and release configuration, and whatever paths the policy
+ *   itself protects. Reviewable after the fact, and the only one of the three
+ *   a policy can sensibly sample.
+ */
+export type ProtectedPathClass = "log.mutate" | "policy.core" | "policy.edit";
+/**
+ * The `policy.edit` sub-class namespace a `protected_paths` entry may route to
+ * (APRV-266).
+ *
+ * One protected surface with one autonomy was the shape until now, so a policy
+ * that wanted its specification sampled at one tenth and its release workflows
+ * gated every time had to choose one of those numbers for both. A routed entry
+ * says which sub-class a path family takes, and the sub-class is an ordinary
+ * §7 class with an ordinary policy line, so each family gets its own autonomy
+ * and its own live rate without any new grammar in `classes`.
+ *
+ * The namespace is closed to ONE extra segment under `policy.edit` and nothing
+ * else. A policy may not route a path to `policy.core`, to `log.mutate`, or to
+ * any class outside this namespace: those are the gate's own organs and the
+ * record of what happened, and §11.1 invariant 9 reserves them — a policy
+ * widening its own protected surface is naming prose and configuration, and
+ * mints no authority over anything else. `policy.schema.json` enforces the
+ * shape; this pattern is the same rule where the matcher can see it.
+ */
+export declare const POLICY_EDIT_SUBCLASS: RegExp;
+/**
+ * Sub-class names this spec reserves, with the meaning an implementation must
+ * give them (APRV-266).
+ *
+ * Reserved so that two policies written by two people mean the same thing by
+ * `policy.edit.ci`, and so a reader of somebody else's policy does not have to
+ * infer it. An author is free to mint their own word beside these — the pattern
+ * above admits any lowercase word — and a minted name carries only the meaning
+ * its own policy line gives it.
+ */
+export declare const RESERVED_POLICY_EDIT_SUBCLASSES: Readonly<Record<string, string>>;
+/**
+ * One `protected_paths` entry: a bare path, or a path routed to a sub-class.
+ *
+ * The bare string is the APRV-107 spelling and keeps its meaning exactly —
+ * `policy.edit`, as though the object form did not exist. Nothing about a
+ * string-only policy changes by a byte, which is the compatibility rule this
+ * type exists to state: `approval hook classify` over such a policy answers
+ * today's class with today's rule name.
+ */
+export type ProtectedPathEntry = string | {
+    path: string;
+    class: string;
+};
+/**
+ * One entry of `policy.protected_paths`, pre-split (APRV-107).
+ *
+ * `directory` records the trailing `/` that distinguishes `design/` (a subtree)
+ * from `design` (a file named `design`).
+ */
+interface ProtectedEntry {
+    segments: string[];
+    directory: boolean;
+    /**
+     * The class this entry routes to (APRV-266). `null` for a bare string entry,
+     * which means `policy.edit` and is matched in the built-in `policy.edit`
+     * tier exactly where it always was.
+     */
+    routed: string | null;
+}
+/**
+ * Read one `policy.protected_paths` entry, or `null` when it names nothing.
+ *
+ * The schema already rejects globs, absolute paths and `..` segments; this
+ * repeats the structural half of that check so a caller that skipped
+ * validation gets an entry that matches nothing rather than an entry that
+ * matches surprisingly. Pure, like everything else here: no resolution against
+ * a checkout, no disk.
+ *
+ * The same defensiveness covers the routed form (APRV-266): an object whose
+ * `class` is not a well-formed `policy.edit` sub-class matches NOTHING at all
+ * rather than falling back to `policy.edit`. A silent fallback would be the
+ * worst of the three available answers — the author would read their file and
+ * see a rate that is not the rate in force — and the loader refuses such a
+ * policy outright, so this branch is only ever reached by a caller that
+ * skipped validation.
+ */
+export declare function parseProtectedEntry(entry: ProtectedPathEntry): ProtectedEntry | null;
+/**
+ * Which protected class does this path name, if any? (APRV-198.)
+ *
+ * Deliberately name-based rather than location-based: the hook runs in whatever
+ * directory the harness is in, and a classifier that resolved paths against a
+ * checkout would answer differently in a worktree than in the primary. A
+ * false positive here costs one approval prompt; a false negative costs the
+ * property the whole file exists to defend.
+ *
+ * **The check order IS the precedence.** A path is answered by the strictest
+ * surface it names, `log.mutate` first, then `policy.core`, then
+ * `policy.edit`: `.approval/log/events.jsonl` is a log write and not merely an
+ * approval-home write, and a `policy.protected_paths` entry that happens to
+ * name a built-in surface cannot demote it, because the built-ins are matched
+ * before the policy's own list is read.
+ *
+ * `extra` carries `policy.protected_paths` (APRV-107). It is strictly
+ * ADDITIVE: the built-in set above is protected whatever a policy says, so a
+ * policy can widen the protected surface and can never narrow it, and every
+ * path it adds in the APRV-107 bare-string spelling lands on `policy.edit` —
+ * the reviewable class — because a policy widening its own surface is naming
+ * prose and configuration, not minting authority over the gate's organs. Still
+ * pure: the caller loads the policy, this function only matches segments.
+ *
+ * ## Routed entries (APRV-266)
+ *
+ * An entry written as `{path, class}` answers with the class it names, and the
+ * routed tier sits between the built-in `policy.core` tier and the built-in
+ * `policy.edit` tier. That position is the whole of the routing rule:
+ *
+ * - It is BELOW `log.mutate` and `policy.core`, so a routing can never reach
+ *   the log or the gate's own organs. `{path: .approval/, class:
+ *   policy.edit.home}` matches nothing, because tier 2 answered first — which
+ *   is invariant 9's "no verb minting authority" holding at the one place a
+ *   policy could otherwise have reached past it. The loader refuses such an
+ *   entry outright rather than letting it sit inert.
+ * - It is ABOVE the built-in `policy.edit` set, so a routing CAN re-label a
+ *   built-in `policy.edit` path: `{path: .github/workflows/, class:
+ *   policy.edit.ci}` is exactly the sentence a project wants to write. What
+ *   stops that from being a demotion is not this function but the load-time
+ *   floor in `policy-load.ts`, which refuses a policy whose routing would
+ *   resolve a built-in path below what the `policy.edit` line itself resolves
+ *   to. The classifier stays pure: it reports the class the policy named and
+ *   judges no autonomy.
+ *
+ * Among several routed entries matching one path, the MOST SPECIFIC wins (most
+ * segments), and declaration order breaks a tie. Most-specific is what a
+ * carve-out means — `design/` routed one way and `design/frozen/` another — and
+ * a tie is two entries of equal depth both claiming one path, which is the
+ * author's own ambiguity and is resolved the only way a pure function can:
+ * by the order they wrote them in.
+ *
+ * A string-only `extra` cannot reach the routed tier at all, so a policy that
+ * has not adopted the object form classifies byte for byte as it did before.
+ */
+export declare function protectedPathClass(candidate: string, extra?: readonly ProtectedPathEntry[]): string | null;
+/**
+ * The class a path takes from the BUILT-IN set alone, ignoring every policy
+ * entry (APRV-266).
+ *
+ * The load-time routing floor needs this and nothing else: "is the path this
+ * entry routes one the runtime protects on its own?" decides whether the floor
+ * applies to it, and asking {@link protectedPathClass} with the policy's own
+ * entries in hand would answer with the routing under test.
+ */
+export declare function builtinProtectedPathClass(candidate: string): ProtectedPathClass | null;
+/**
+ * Does this path name something only a human may write?
+ *
+ * The boolean face of {@link protectedPathClass}, kept because two callers
+ * (`core/wysiwys.ts`'s protected-path view and the hook's file-tool gate) ask
+ * whether a path is protected at all before they ask which surface it is.
+ */
+export declare function isProtectedPath(candidate: string, extra?: readonly ProtectedPathEntry[]): boolean;
+/**
+ * One path, in the spelling an organ attestation records (APRV-272).
+ *
+ * Segment-wise: separators collapse, `./` noise disappears, a trailing slash
+ * goes, and the result is joined with `/` whatever the caller's platform uses.
+ * Two spellings of one file therefore attest and match as one file, which is
+ * the property the guard needs, since git reports `.claude/settings.json` and a
+ * human at a terminal may type `./.claude/settings.json`.
+ *
+ * Pure and disk-free, like everything else in this file: it never resolves,
+ * never follows a link, and never asks whether the path exists.
+ */
+export declare function normalizePathSpelling(candidate: string): string;
+/**
+ * Is this path one of the gate's ORGANS — a `policy.core` surface a human can
+ * attest by content (APRV-272)?
+ *
+ * The organs are the harness files that install the hook: `.claude/settings*`
+ * and Cursor's `hooks.json`, `hooks/` and `agents/`. They are `policy.core`
+ * because an agent that could write them could write itself out of the gate,
+ * and `policy.core` is human-only, so the gate mints no record for them at all
+ * — which is exactly why the protected-path guard could never pass a hand-made
+ * edit to one, and why {@link normalizePathSpelling}-keyed attestation is the
+ * evidence for them.
+ *
+ * Two `policy.core` surfaces are deliberately NOT organs, and both keep their
+ * own rules:
+ *
+ * - The policy file, which has had content attestation since APRV-15 and whose
+ *   attestation the gate reads on every operation. An organ record must never
+ *   be able to stand in for it.
+ * - Everything under the approval home (`.approval/`): the payload store, the
+ *   vault, the keys, the environment map, the queue. Those are the human's own
+ *   ceremony surface, and the log directory under them is `log.mutate`, which
+ *   is stricter still.
+ *
+ * The question is asked of the BUILT-IN set alone. A policy may not route any
+ * path to `policy.core` (§11.1 invariant 9 and the `policy.edit.*` namespace
+ * close that), so consulting the policy's entries here could only ever widen
+ * the set of files a human may attest by a routing the classifier already
+ * refuses to honor.
+ */
+export declare function isGateOrganPath(candidate: string): boolean;
+/**
+ * Environment variables whose NAME says they carry a secret.
+ *
+ * Prefix-matched, because the classifier reads command text and never an
+ * environment: it cannot know which `APPROVAL_*` holds a token, so it treats
+ * the family alike and lets the allowlist below carve out the runtime's own
+ * non-secret names. Erring wide costs one approval prompt.
+ *
+ * Exported since APRV-205: `core/child-env.ts` starves a spawned child of the
+ * same family, and two copies of this list would be one list that drifts.
+ *
+ * `AGENTMAIL_` joins the family with the AgentMail adapter (APRV-224). An
+ * AgentMail API key is a mailbox in one string, and the deployment the adapter
+ * assumes hands the agent a key that cannot send while the sending key waits in
+ * the vault (SPEC.md §10.4). A key of either half in a granted child's
+ * environment would undo that split, so the prefix is withheld like the rest.
+ * The adapter's own declared credentials are vault names (`agentmail.api_key`,
+ * `agentmail.inbox_id`), so nothing under this prefix passes through by
+ * declaration either.
+ */
+export declare const SECRET_ENV_PREFIXES: readonly string[];
+/**
+ * The runtime's own variables under those prefixes that hold no secret: an
+ * identity, a rendering switch, a path. Listed rather than pattern-matched so
+ * that adding one is a deliberate act with a reviewer.
+ */
+export declare const NON_SECRET_ENV_NAMES: readonly string[];
+/**
+ * Does this bare variable name name credential material?
+ *
+ * Exported since APRV-205 for the same reason the two lists are: the scrub that
+ * builds a granted child's environment asks exactly this question, of a real
+ * environment rather than of command text, and it must ask it the same way.
+ */
+export declare function isSecretEnvName(name: string): boolean;
+interface LexWord {
+    /** Literal text, quotes removed and backslash escapes applied. */
+    text: string;
+    /** True when any part of the word was quoted. */
+    quoted: boolean;
+    /** Inner text of each `$(…)` in this word, for recursive classification. */
+    substitutions: string[];
+}
+interface LexRedirect {
+    /** `>` and `>>` write; `<` reads. */
+    op: ">" | ">>" | "<";
+    target: LexWord;
+}
+interface LexSegment {
+    text: string;
+    words: LexWord[];
+    redirects: LexRedirect[];
+    /** Set when the segment contains a construct whose effect cannot be read. */
+    opaque: string | null;
+}
+/**
+ * Facts about the machine the command will run on, resolved by the CALLER
+ * (APRV-267).
+ *
+ * The classifier is pure and stays pure. Some rules, though, turn on something
+ * no string can carry: whether a path names the agent's own scratch space. So
+ * the impure half is hoisted out of this file entirely — the caller resolves
+ * the roots, this file only compares path segments against them — and the
+ * shape is the one `protectedPaths` already established: an optional argument
+ * whose absence yields the strictly NARROWER answer. A caller that forgets it
+ * classifies every delete the way this file classified it before the field
+ * existed; it never invents an authorization.
+ *
+ * Every root must be ABSOLUTE and already resolved (symlinks followed) by the
+ * caller. This file does not touch the disk and cannot check either property,
+ * so a caller handing it a relative or unresolved root gets segment matching
+ * against exactly what it passed.
+ */
+export interface ClassifierContext {
+    /**
+     * Roots under which a delete is the agent tidying after itself: the session
+     * scratchpad the harness allots, and the system temp directory.
+     *
+     * `src/cli/hook.ts` resolves these (`resolveScratchRoots`) and tightens the
+     * answer afterwards with the checks that need the disk — a symlink escaping
+     * the root, a git checkout living inside it. Nothing here is a grant on its
+     * own: a path under a root still has to survive that second pass.
+     */
+    scratchRoots?: readonly string[];
+    /**
+     * Roots a read may stay inside: the gate root, the session scratchpad and the
+     * system temp root, plus whatever `read_scope.roots` added (APRV-347).
+     *
+     * The polarity is the OPPOSITE of `scratchRoots`, and the difference is worth
+     * stating. A scratch root LOOSENS a delete, so forgetting the field is safe
+     * by construction. A read root NARROWS a read, so forgetting the field would
+     * be safe in a different way — it leaves every read `read.shell`, exactly as
+     * this classifier answered before the field existed. An EMPTY array means the
+     * same thing as absent, and deliberately: read against no roots at all would
+     * make every read in the session a decision, which is a fail-closed answer
+     * nobody asked for and the one spelling a caller reaches by accident. A
+     * caller that means to scope reads passes roots.
+     *
+     * As with `scratchRoots`, this file only compares segments. The relative
+     * paths, the symlinks and the working directory are the hook's second pass,
+     * which can only ever tighten the answer reached here.
+     */
+    readRoots?: readonly string[];
+    /**
+     * May a login-shell wrapper be classified by the script it runs (APRV-380)?
+     *
+     * `true` by default, and `false` for exactly one caller: the classifier
+     * itself, recursing into an unwrapped script. That is what keeps the unwrap
+     * ONE LEVEL deep — a shell nested inside the script is the shape the
+     * {@link OPAQUE_BINS} position still covers, and it stays opaque.
+     *
+     * A caller that passes `false` gets the pre-APRV-380 answer, which is the
+     * strictly stricter one: every wrapper refuses. As with every other field
+     * here, forgetting it cannot loosen anything.
+     */
+    unwrapShell?: boolean;
+}
+/** Everything a refinement needs: the binary and the words that followed it. */
+interface RuleContext {
+    bin: string;
+    /** Words after the binary, quotes already removed. */
+    args: string[];
+    /** Words after the binary that are not flags. */
+    positionals: string[];
+    /** The matched subcommand (first positional), or `null`. */
+    sub: string | null;
+    /**
+     * Did any of those words come out of a command substitution? Its text is
+     * gone by the time a rule sees it, so a rule that reads its arguments closely
+     * (APRV-114's fetch refinement) needs to know that one of them is a hole.
+     */
+    substituted: boolean;
+    /** What the caller knows about the machine (APRV-267). Never read from here. */
+    context: ClassifierContext;
+}
+/**
+ * A refinement's answer: a class and the rule id that chose it, or a statement
+ * that this invocation cannot be read at all.
+ *
+ * The opaque arm is APRV-283's. A refinement that returns `null` is answered
+ * with the interpreter message (`runs inline source`), which is true of
+ * `node -e` and false of `find … -exec`, and a refusal that misdescribes the
+ * command it refuses sends the agent looking for a flag it did not pass. A
+ * refinement that has its own reason states it.
+ */
+type Refinement = {
+    class: string;
+    rule: string;
+    path?: string;
+} | {
+    opaque: string;
+};
+/**
+ * One row of the classification table.
+ *
+ * `bins` + `subs` is the match; `class` is the answer. A row with a `refine`
+ * looks at the flags before answering, and declares every class it can emit in
+ * `emits` so the table stays enumerable (the dogfood test reads that list).
+ */
+export interface CommandRule {
+    /** Stable identifier, printed by `hook classify` and pinned by the fixtures. */
+    id: string;
+    bins: readonly string[];
+    /** Match only when the first positional is one of these. */
+    subs?: readonly string[];
+    class: string;
+    /** Additional classes a refinement may return. */
+    emits?: readonly string[];
+    /** Flag-sensitive answer; falls back to `class` when it returns `null`. */
+    refine?: (ctx: RuleContext) => Refinement | null;
+}
+/**
+ * The suffix that marks a Muse model as training on what it is shown.
+ *
+ * Exported since APRV-350 so the hook adapter's contributor guard and this
+ * classifier's `harness.launch.muse` refinement test the SAME mark. Two
+ * spellings of "which models are unsafe" would drift, and the direction they
+ * drift in is the one where a launch is refused and a tool call is not.
+ */
+export declare const CONTRIBUTOR_SUFFIX = "-contributor";
+/** The rule id for a read whose ABSOLUTE target sits outside every root. */
+export declare const READ_OUT_OF_SCOPE_RULE = "read-out-of-scope";
+/** The rule id for a read target whose expansion the text cannot show. */
+export declare const READ_UNREADABLE_TARGET_RULE = "read-unreadable-path";
+/**
+ * The table.
+ *
+ * Order matters: the first row whose binary and subcommand match decides. Rows
+ * are grouped by binary, strictest interpretation first within a binary, and
+ * every class named here is one SPEC.md §7 declares (§7's developer-workstation
+ * namespaces, plus `read.shell` / `read.vcs.remote` / `read.web` under
+ * `read.*`), with one addition: the `log.*` namespace of the two verbs that
+ * move the log file, introduced by SPEC §10.1's APRV-125 amendment.
+ */
+export declare const COMMAND_RULES: readonly CommandRule[];
+/**
+ * The script a LOGIN-SHELL WRAPPER runs, when the segment is exactly one
+ * (APRV-380), or `null`.
+ *
+ * ## Why this is not the second parser the table above refuses
+ *
+ * {@link OPAQUE_BINS} states the position this narrows: a second parser for the
+ * same text is a second answer waiting to disagree with the shell's. The hazard
+ * that names is reading shell text a SECOND WAY. This is not that. When the
+ * argv is exactly `[shell, -lc, script]` and nothing else, the script is the
+ * text a Claude Code `Bash` call hands this classifier directly, and what
+ * happens to it here is what happens to that: the same lexer, the same segment
+ * rules, the same table. No new parser is written, and the text is not read a
+ * second way — it is read the first way, by the only reader there is.
+ *
+ * ## The line, and it is exact
+ *
+ * Three words, no more: a known shell, one inline-script flag, one script. Any
+ * of these keeps the wrapper opaque, because each is a shape whose effect
+ * depends on something the argv alone does not say:
+ *
+ * - extra words (a script FILE, `--`, an option this rule does not model);
+ * - an assignment prefix, which changes the environment the script runs in;
+ * - a redirection on the wrapper, which is the outer shell's and not the
+ *   script's;
+ * - a substitution in any of the three words, whose effect happens before the
+ *   shell even starts;
+ * - a nested shell inside the script, refused by {@link ClassifierContext} when
+ *   the recursion runs (the inner classification unwraps nothing).
+ *
+ * The BINDING does not move. `cli/hook.ts` binds the outer command and argv
+ * exactly as APRV-362 built them; what this changes is only which text is
+ * classified, and the classes are additional evidence about bytes that are
+ * bound elsewhere and unchanged.
+ */
+export declare function loginShellScript(segment: LexSegment): string | null;
+/**
+ * The rules whose commands RUN CODE THIS RUNTIME DID NOT AUTHOR (APRV-193).
+ *
+ * Rule ids rather than classes, because the class does not separate them: `npm
+ * test`, `node build.mjs`, `tsc` and `mkdir` all resolve to
+ * `files.write.workspace`, and only the first three execute a file an agent may
+ * have written a minute ago. That is the whole distinction laundering turns on
+ * — the command's NAME stops describing its effect exactly when the effect is
+ * in a file the name does not mention — so it is drawn here, once, where a
+ * future rule's author will see it.
+ *
+ * Read by `APPROVAL_HOOK_REQUIRE_SANDBOX` (`src/cli/hook.ts`) and by nothing
+ * else. It grants nothing and denies nothing on its own: it says which commands
+ * the hook may be asked to require a sandbox for, and the requirement is off
+ * unless an operator turns it on.
+ */
+export declare const CODE_EXECUTING_RULES: readonly string[];
+/**
+ * Every class the table can emit, for docs and for the dogfood test.
+ *
+ * Fixed, and it does not include the `policy.edit` sub-classes (APRV-266): a
+ * routed class is emitted only because a particular policy named it, so the set
+ * of them is a property of that file rather than of this table. A reader
+ * asking "can the classifier ever emit this class?" of a routed name must ask
+ * it WITH the policy in hand — {@link emittableClass} is that question.
+ */
+export declare const CLASSIFIER_CLASSES: readonly string[];
+/**
+ * The class the DAEMON's own cadence advance is gated as (APRV-382).
+ *
+ * The sub-class exists because the policy grammar has no actor condition and
+ * this repository wanted one: an advance publishes records the log already
+ * holds, so the daemon may make it unattended, while the same act from a
+ * session in a worktree or a human terminal stays supervised. Two classes are
+ * how that is written down, and which of them a cycle asks under is decided by
+ * `core/advance-cycle.ts` from the running process, never from an argument.
+ *
+ * NO COMMAND SPELLS IT, on purpose. `approval log advance` classifies
+ * `log.advance` whoever types it, so the looser line is unreachable from a
+ * shell an agent can drive: it is reached only from inside the daemon process,
+ * which an agent cannot become without a `gate.self` command this policy holds
+ * at the manual default.
+ */
+export declare const ADVANCE_DAEMON_CLASS = "log.advance.daemon";
+/**
+ * Classes this RUNTIME emits for its own gated actions, which no command spells.
+ *
+ * Separate from {@link CLASSIFIER_CLASSES}, which is the binary table's own set
+ * and is what `docs/claude-code-hook.md` documents row by row. A class here is
+ * emitted by a runtime cycle that registers and requests it directly — the
+ * daemon's advance is the first — so a policy declaring it is declaring a line
+ * that CAN fire, and the reachability check `core/policy-expectations.ts` runs
+ * at the amendment ceremony must say so. Without this list that ceremony would
+ * refuse the line `unreachable`, which is a true statement about the command
+ * classifier and a false one about the runtime.
+ *
+ * Adding a name here is a claim that some path in this codebase asks the gate
+ * for that class, and widening it is a reviewable diff.
+ */
+export declare const RUNTIME_CLASSES: readonly string[];
+/**
+ * Can the classifier emit `actionClass` for a project whose policy carries
+ * these `protected_paths`? (APRV-266.)
+ *
+ * {@link CLASSIFIER_CLASSES} answers for the binary table, which is fixed. A
+ * routed class is not in that table and never will be: it exists because one
+ * policy wrote it beside one path, and the same name in another project's
+ * policy would be a different class over different files. So the reachability
+ * question — the one `core/policy-expectations.ts` asks of every class a policy
+ * declares, so that a policy line nobody can ever fire is caught at the
+ * ceremony rather than believed for a year — takes the policy's own entries.
+ *
+ * A routed name is reachable exactly when some entry routes to it. A
+ * `policy.edit.spec` rule in a policy whose `protected_paths` routes nothing to
+ * it is a line that will never fire, and saying so is the whole point.
+ *
+ * {@link RUNTIME_CLASSES} is the third answer (APRV-382): a class no command
+ * spells and a runtime cycle asks for directly is reachable in every project,
+ * with no policy entry needed, because the path that emits it is in this
+ * codebase rather than in the operator's file.
+ */
+export declare function emittableClass(actionClass: string, protectedPaths?: readonly ProtectedPathEntry[]): boolean;
+/**
+ * Classify a shell command line into the classes it would produce.
+ *
+ * Every segment must classify: one unreadable segment refuses the whole
+ * command, because a command line's effect is the union of its parts and a
+ * partial answer would authorize the parts we happened to understand.
+ *
+ * `protectedPaths` is `policy.protected_paths` (APRV-107), added to the
+ * built-in protected set rather than replacing it. Omitting it classifies
+ * against the built-ins alone, which is the strictly narrower answer, so a
+ * caller that forgets it under-reports the protected classes rather than inventing an
+ * authorization; every enforcement path passes the loaded policy's list.
+ *
+ * Since APRV-266 an entry may be `{path, class}`, routing that path family to a
+ * `policy.edit` sub-class. The classifier stays what it was: the entry's class
+ * is DATA it copies out of the policy, matched by the same segment matcher as
+ * every other entry, so this resolves no autonomy at all.
+ *
+ * `context` (APRV-267) carries the machine facts a caller has resolved: today
+ * only `scratchRoots`. It behaves exactly as `protectedPaths` does: omitting it
+ * yields the strictly narrower answer, because every rule that reads it can only
+ * ever LOOSEN a class, and no rule reads it to loosen a protected or credential
+ * one.
+ */
+export declare function classifyCommand(command: string, protectedPaths?: readonly ProtectedPathEntry[], context?: ClassifierContext): CommandClassification;
+/** One segment's words, as the classifier's own tokenizer read them. */
+export interface CommandSegmentWords {
+    /** The segment's source text, as written. */
+    text: string;
+    /** The binary, `VAR=value` prefixes already skipped, quotes already removed. */
+    bin: string;
+    /** Every word after the binary, flags included, in order. */
+    args: string[];
+}
+/**
+ * The words of each segment, from the SAME parse {@link classifyCommand} uses.
+ *
+ * Exported for the channel-side command breakdown (APRV-144): a prompt that
+ * says what a compound command does needs the verb and the arguments of each
+ * segment, and a display layer that re-split the string itself would be a
+ * second tokenizer, free to disagree with the one that chose the class. This
+ * runs {@link lex} — the tokenizer — and applies the same assignment-prefix
+ * skip `classifySegment` applies, and stops there: it classifies nothing and
+ * decides nothing.
+ *
+ * `null` when the tokenizer refuses the string, which is the same input
+ * `classifyCommand` answers `unparseable` for. Segments carrying no binary (a
+ * bare assignment, a lone redirection) are omitted: they have no verb to show.
+ */
+export declare function commandSegmentWords(command: string): CommandSegmentWords[] | null;
+export {};