approval-md 0.2.0 → 0.3.0

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

@@ -32,6 +32,20 @@
  * 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";
@@ -352,6 +366,26 @@ export declare const NON_SECRET_ENV_NAMES: readonly string[];
  * 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).
@@ -381,6 +415,38 @@ export interface ClassifierContext {
      * 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 {
@@ -413,6 +479,7 @@ interface RuleContext {
 type Refinement = {
     class: string;
     rule: string;
+    path?: string;
 } | {
     opaque: string;
 };
@@ -435,6 +502,19 @@ export interface CommandRule {
     /** 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.
  *
@@ -446,6 +526,42 @@ export interface CommandRule {
  * 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).
  *
@@ -473,6 +589,39 @@ export declare const CODE_EXECUTING_RULES: readonly string[];
  * 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.)
@@ -488,6 +637,11 @@ export declare const CLASSIFIER_CLASSES: readonly string[];
  * 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;
 /**