approval-md 0.1.0 → 0.2.0

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

@@ -0,0 +1,543 @@
+/**
+ * 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).
+ */
+/** 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;
+/**
+ * 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[];
+}
+/** 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;
+} | {
+    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 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 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[];
+/**
+ * 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.
+ */
+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 {};

package/dist/src/core/command-class.js

@@ -240,6 +240,16 @@ export function protectedPathClass(candidate, extra = []) {
             if (next === "hooks.json" || next === "hooks" || next === "agents")
                 return "policy.core";
         }
+        // Codex installs its hook through these configuration and script paths.
+        if (segment === ".codex") {
+            const next = segments[index + 1];
+            if (next === undefined ||
+                next === "config.toml" ||
+                next === "hooks.json" ||
+                next === "hooks" ||
+                segments.slice(index + 1).includes(".."))
+                return "policy.core";
+        }
     }
     // 3. The policy's own routed entries (APRV-266), above the built-in
     //    `policy.edit` set so a routing can re-label one of those paths, and
@@ -868,27 +878,49 @@ function hasShortFlag(args, letters) {
 function isUnknownValue(word) {
     return word.includes("$") || word.includes("*") || word.includes("?") || word.startsWith("~");
 }
-/** `git push` — the three push classes turn on flags and refspecs. */
+/** A bare release tag: the conventional `v` plus a semantic-version-shaped value. */
+const V_PREFIXED_SEMVER = /^v(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+/** Does one side of a push refspec explicitly name a tag? */
+function isTagRef(name) {
+    if (name.startsWith("refs/tags/"))
+        return true;
+    if (name.startsWith("refs/heads/"))
+        return false;
+    return V_PREFIXED_SEMVER.test(name);
+}
+/** Does either source or destination of this refspec explicitly name a tag? */
+function isTagRefspec(refspec) {
+    const colon = refspec.indexOf(":");
+    if (colon === -1)
+        return isTagRef(refspec);
+    return isTagRef(refspec.slice(0, colon)) || isTagRef(refspec.slice(colon + 1));
+}
+/** `git push` — force, release, trunk and branch classes turn on flags and refspecs. */
 function refineGitPush(ctx) {
     const args = ctx.args.slice(1);
-    if (hasFlag(args, ["--force", "-f", "--force-with-lease", "--force-if-includes"])) {
+    if (hasFlag(args, ["--force", "-f", "--force-with-lease", "--force-if-includes", "--mirror"])) {
         return { class: "vcs.history.rewrite", rule: "git-push-force" };
     }
     const positionals = args.filter((arg) => !isFlag(arg));
-    // A deletion, or a push with no refspec at all: the destination is either the
-    // trunk or unknown, and unknown resolves to the stricter class.
+    const refspecs = positionals.slice(1);
+    if (refspecs.some((refspec) => refspec.startsWith("+"))) {
+        return { class: "vcs.history.rewrite", rule: "git-push-force" };
+    }
+    if (hasFlag(args, ["--tags", "--follow-tags"]) ||
+        refspecs.some(isTagRefspec) ||
+        refspecs.some((word, index) => word === "tag" && index + 1 < refspecs.length)) {
+        return { class: "release.publish", rule: "git-push-tag" };
+    }
+    // A non-tag deletion, or a push with no refspec at all: the destination is
+    // either the trunk or unknown, and unknown resolves to the stricter class.
     if (hasFlag(args, ["--delete", "-d"])) {
         return { class: "vcs.push.main", rule: "git-push-delete" };
     }
-    const refspecs = positionals.slice(1);
     if (refspecs.length === 0) {
         return { class: "vcs.push.main", rule: "git-push-implicit" };
     }
     let sawMain = false;
     for (const refspec of refspecs) {
-        if (refspec.startsWith("+")) {
-            return { class: "vcs.history.rewrite", rule: "git-push-force" };
-        }
         const colon = refspec.indexOf(":");
         const destination = colon === -1 ? refspec : refspec.slice(colon + 1);
         // `:branch` (empty source) and `src:` (empty destination) both delete a
@@ -1401,6 +1433,9 @@ function isGateEntrypoint(path) {
 function refineApprovalVerb(positionals) {
     const verb = positionals[0];
     const sub = positionals[1];
+    if (verb === "quickstart") {
+        return { class: "policy.core", rule: "approval-quickstart" };
+    }
     if (verb === "log") {
         if (sub === "sync")
             return { class: "log.sync", rule: "approval-log-sync" };