@yagni-app/code-staging 0.3.3-staging.1132.1 → 0.3.4-staging.1145.1

package/dist/extension/footer.d.ts

@@ -39,7 +39,7 @@
  * — useful reference for what data to replicate and how to format it.
  */
 import type { ExtensionContext, ReadonlyFooterDataProvider, Theme } from "@earendil-works/pi-coding-agent";
-import type { ModeHolder, PermissionMode } from "./permission.js";
+import type { ModeHolder, PermissionMode } from "./permission/gate.js";
 export declare const BRANCH_MAX_WIDTH = 60;
 export declare function cyclePermissionMode(current: PermissionMode): PermissionMode;
 export declare function isShiftTab(data: string): boolean;

package/dist/extension/index.d.ts

@@ -121,8 +121,8 @@ export { makeAskYagniTool } from "./askYagniTool.js";
 export { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
 export { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
 export { ADVISOR_TIER, DEFAULT_ADVISOR_LIMITS, decideConsult, formatAdvisorSubtotal, makeAdvisorState, } from "./advisor.js";
-export { DEFAULT_GUARDIAN_LIMITS, GUARDIAN_MODEL_TIER, formatGuardianSubtotal, makeGuardianState, resolveGuardianLimits, reviewCommand, } from "./guardian.js";
-export type { GuardianOutcome, GuardianVerdict, GuardianState, GuardianStateHandle, GuardianLimits, ReviewResult, ReviewCommandDeps, } from "./guardian.js";
+export { DEFAULT_GUARDIAN_LIMITS, GUARDIAN_MODEL_TIER, formatGuardianSubtotal, makeGuardianState, resolveGuardianLimits, reviewCommand, } from "./permission/guardian.js";
+export type { GuardianOutcome, GuardianVerdict, GuardianState, GuardianStateHandle, GuardianLimits, ReviewResult, ReviewCommandDeps, } from "./permission/guardian.js";
 export type { Citation, MakeAskYagniToolOptions } from "./askYagniTool.js";
 export { makeReviewBusinessMatchTool } from "./reviewTool.js";
 export type { MakeReviewToolOptions } from "./reviewTool.js";
@@ -167,10 +167,10 @@ export { registerSubagents, makeSubagentTool, discoverSubagents, parseAgentMarkd
 export type { SubagentDef, SubagentSource } from "./subagents.js";
 export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, formatTodoReminder, shouldRemindTodos, todoSummary, TODO_TOOL_NAME, TODO_REMINDER_TURNS, MAX_TODOS, } from "./todos.js";
 export type { TodoItem, TodoStatus, TodoTheme } from "./todos.js";
-export { decideGate, registerPermissionGate, filterStaleModeContext, filterStalePlanContext, buildModeContextMessage, DEFAULT_PERMISSION_POLICY, MODE_CONTEXT_TYPE, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission.js";
-export { classifyCommand, DEFAULT_EXEC_POLICY, } from "./execPolicy.js";
-export type { ExecDecision, ExecPolicy, PrefixRule, ExecClassification, } from "./execPolicy.js";
-export type { PermissionMode, PermissionPolicy, GateDecision, RegisterPermissionDeps, BlessRememberInfo, } from "./permission.js";
+export { decideGate, registerPermissionGate, filterStaleModeContext, filterStalePlanContext, buildModeContextMessage, DEFAULT_PERMISSION_POLICY, MODE_CONTEXT_TYPE, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission/gate.js";
+export { classifyCommand, DEFAULT_EXEC_POLICY, } from "./permission/execPolicy.js";
+export type { ExecDecision, ExecPolicy, PrefixRule, ExecClassification, } from "./permission/execPolicy.js";
+export type { PermissionMode, PermissionPolicy, GateDecision, RegisterPermissionDeps, BlessRememberInfo, } from "./permission/gate.js";
 export { makeBlessStore, blessPath } from "./bless.js";
 export type { BlessStore, BlessRule } from "./bless.js";
 export { bankDecision, fetchDecisions, supersedeDecision, parseDecideArgs, formatDecisionsList, shortId, registerDecisionCommands, DEFAULT_LIST_LIMIT, } from "./decisions.js";

package/dist/extension/index.js

@@ -3,9 +3,9 @@ import { appendFileSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { Text } from "@earendil-works/pi-tui";
 import { DEFAULT_ADVISOR_LIMITS, formatAdvisorSubtotal, makeAdvisorState } from "./advisor.js";
-import { appendGrant, loadGrants, resolveRepoKey, storagePrefix } from "./approvedPrefixes.js";
+import { appendGrant, loadGrants, resolveRepoKey, storagePrefix } from "./permission/approvedPrefixes.js";
 import { redactCommand } from "./redact.js";
-import { formatGuardianSubtotal, GUARDIAN_MODEL_TIER, makeGuardianState, resolveGuardianLimits, reviewCommand } from "./guardian.js";
+import { formatGuardianSubtotal, GUARDIAN_MODEL_TIER, makeGuardianState, resolveGuardianLimits, reviewCommand } from "./permission/guardian.js";
 import { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
 import { makeAskYagniTool } from "./askYagniTool.js";
 import { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
@@ -28,7 +28,7 @@ import { isInitDone as defaultIsInitDone, markInitDone as defaultMarkInitDone }
 import { fetchMcpServers as defaultFetchMcpServers, registerMcpCommand, registerMcpTools, } from "./mcpTools.js";
 import { registerGoCommand } from "./pipeline/goCommand.js";
 import { registerGoCompareCommand } from "./pipeline/goCompareCommand.js";
-import { DEFAULT_PERMISSION_POLICY, createModeHolder, registerPermissionGate } from "./permission.js";
+import { DEFAULT_PERMISSION_POLICY, createModeHolder, registerPermissionGate } from "./permission/gate.js";
 import { loadHooksConfig, makeHookRunner, registerHooks } from "./hooks.js";
 import { registerSubagents } from "./subagents.js";
 import { createUltraHolder, registerUltraCommand } from "./ultra.js";
@@ -887,7 +887,7 @@ export { makeAskYagniTool } from "./askYagniTool.js";
 export { makeFileTicketTool, makeUpdateTicketStatusTool } from "./ticketTools.js";
 export { makeAskAdvisorTool, registerAdviseCommand } from "./askAdvisorTool.js";
 export { ADVISOR_TIER, DEFAULT_ADVISOR_LIMITS, decideConsult, formatAdvisorSubtotal, makeAdvisorState, } from "./advisor.js";
-export { DEFAULT_GUARDIAN_LIMITS, GUARDIAN_MODEL_TIER, formatGuardianSubtotal, makeGuardianState, resolveGuardianLimits, reviewCommand, } from "./guardian.js";
+export { DEFAULT_GUARDIAN_LIMITS, GUARDIAN_MODEL_TIER, formatGuardianSubtotal, makeGuardianState, resolveGuardianLimits, reviewCommand, } from "./permission/guardian.js";
 export { makeReviewBusinessMatchTool } from "./reviewTool.js";
 export { makeRecordEngineeringContextTool } from "./recordContextTool.js";
 export { makeRecordDecisionTool } from "./recordDecisionTool.js";
@@ -930,8 +930,8 @@ export { registerSubagents, makeSubagentTool, discoverSubagents, parseAgentMarkd
 export { registerTodos, makeTodoTool, normalizeTodos, reconstructTodos, renderTodoWidget, formatTodoList, formatTodoReminder, shouldRemindTodos, todoSummary, TODO_TOOL_NAME, TODO_REMINDER_TURNS, MAX_TODOS, } from "./todos.js";
 // P3 + W4: the permission gate seam (decideGate is pure; policy injectable) plus
 // the session bless-with-remember capture hook.
-export { decideGate, registerPermissionGate, filterStaleModeContext, filterStalePlanContext, buildModeContextMessage, DEFAULT_PERMISSION_POLICY, MODE_CONTEXT_TYPE, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission.js";
-export { classifyCommand, DEFAULT_EXEC_POLICY, } from "./execPolicy.js";
+export { decideGate, registerPermissionGate, filterStaleModeContext, filterStalePlanContext, buildModeContextMessage, DEFAULT_PERMISSION_POLICY, MODE_CONTEXT_TYPE, PLAN_CONTEXT_TYPE, PLAN_CONTEXT_MESSAGE, } from "./permission/gate.js";
+export { classifyCommand, DEFAULT_EXEC_POLICY, } from "./permission/execPolicy.js";
 // W4 judgment loop: the session bless store (tool + path-prefix, session-only).
 export { makeBlessStore, blessPath } from "./bless.js";
 // W4 judgment loop: the decisions surface (/decide + /decisions) + shared bank.

package/dist/extension/{approvedPrefixes.js → permission/approvedPrefixes.js}

@@ -29,7 +29,7 @@ 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";
+import { codeStateHome } from "../stateHome.js";
 // --- Derivation ---
 /** Tools whose second token is a subcommand worth capturing in a prefix. */
 const MULTI_SUBCOMMAND_TOOLS = new Set([

package/dist/extension/permission/dbReadPolicy.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Database read auto-allow policy (YAG-561).
+ *
+ * Auto-allows *provably read-only* inline SQL for a small set of database
+ * clients, so routine SELECTs never reach the Guardian. Anything we cannot
+ * prove read-only is left ENTIRELY to the Guardian — this module has no
+ * "deny" outcome (see the invariant below).
+ *
+ * The hard, easy part is extracting the SQL safely WITHOUT regex over the raw
+ * command. We reuse execPolicy's shellParse — the same quote-aware tokenizer
+ * that powers the whole classifier — so `-c "SELECT 1; SELECT 2"` arrives as
+ * one clean, dequoted token and a `;` OUTSIDE quotes still reads as a real
+ * command separator. Extraction failures (unknown flag, unknown short-cluster,
+ * `-f file`, stdin `<`) simply left as `readonly: false`.
+ *
+ * ── The single invariant ────────────────────────────────────────────────
+ *   classifySql returns "read" ONLY when the SQL is provably read-only. A
+ *   false "read" auto-runs a write across every workspace's DB, which is
+ *   unacceptable; a false "unknown" costs one Guardian consult, which is free.
+ *   We therefore over-reject: a write marker, a mutating function name, or a
+ *   `\` meta-command ANYWHERE in the SQL downgrades the whole thing to
+ *   "unknown". No attempt is made to distinguish "called" from "mentioned in
+ *   a string literal" — erring toward prompt is always the safe direction.
+ *
+ *   NOTE: a non-"read" result is NOT "forbidden". An UPDATE/INSERT/DELETE is
+ *   sent to the Guardian where a human/LLM judges intent. This module never
+ *   flat-denies a DB write.
+ *
+ * ── How to extend ────────────────────────────────────────────────────────
+ *   Add a new client: push a DbClientSpec to DB_CLIENTS.
+ *   Add a new mutating function: append to the relevant client's
+ *     mutatingFunctions list (schema-prefix-agnostic word-boundary match).
+ *   Add a new way to pass SQL: add a SqlArgExtractor to the client.
+ *   Every change needs a paired allow + regression test in dbReadPolicy.test.ts.
+ *   See AGENTS.md alongside this directory for the full recipe.
+ */
+/** A single argv shape that carries inline SQL (e.g. psql `-c "…"`). */
+export interface SqlArgExtractor {
+    /**
+     * Token forms introducing SQL: `-c`, `--command`, `-e`, `--execute`, … The
+     * extractor accepts these in three forms: glued long (`--command=…`), glued
+     * short (`-c…` for the 2-char flags only), and bare (`-c` → SQL is the next
+     * token). A bare single-dash flag may also match a short cluster
+     * (`-Atc`) when its terminal letter is `shortCluster.terminal` and every
+     * preceding letter is in `shortCluster.allowedPrefixes`.
+     */
+    flags: readonly string[];
+    shortCluster?: {
+        terminal: string;
+        allowedPrefixes: readonly string[];
+    };
+}
+/** Everything we know about one database client. */
+export interface DbClientSpec {
+    binaries: readonly string[];
+    sqlArgExtractors: readonly SqlArgExtractor[];
+    /** Is this (dequoted, full) SQL provably read-only? */
+    classifySql: (sql: string) => boolean;
+    /** Function names that make a bare SELECT mutate/abuse — reject as unknown. */
+    mutatingFunctions: readonly string[];
+}
+/**
+ * The shared "provably read-only" gate. Returns true only when every
+ * statement in `sql` (after comment-stripping) begins with SELECT/WITH and
+ * contains no write verb, write clause, mutating function, or backslash
+ * meta-command.
+ */
+export declare function isSqlReadOnly(sql: string, mutatingFunctions: readonly string[]): boolean;
+/** The supported database clients. Add a new one here to expand coverage. */
+export declare const DB_CLIENTS: DbClientSpec[];
+/**
+ * Resolve the SQL string for a known client binary from its tokenized argv.
+ * Returns `{ sql }` on success (the dequoted SQL as one string) or null when
+ * the argv shape can't be proven to carry inline SQL. Null → left to Guardian.
+ *
+ * Supported token shapes, in the order tried:
+ *   1. glued long flag   `--command=SELECT …` / `--execute=SELECT …`
+ *   2. glued short flag  `-cSELECT …` / `-eSELECT …` (2-char flag + payload)
+ *   3. bare flag         `-c` / `--command` / `-Atc`  → SQL is the NEXT token
+ */
+export declare function extractSqlArg(tokens: readonly string[], spec: DbClientSpec): {
+    sql: string;
+} | null;
+/**
+ * Top-level: should this database command be auto-allowed? Consumes the raw
+ * tokenized argv (tokens[0] is the binary) and returns true ONLY when the
+ * inline SQL was extracted AND classified read-only.
+ */
+export declare function classifyDbRead(tokens: readonly string[]): boolean;
+//# sourceMappingURL=dbReadPolicy.d.ts.map

package/dist/extension/permission/dbReadPolicy.js

@@ -0,0 +1,227 @@
+/**
+ * Database read auto-allow policy (YAG-561).
+ *
+ * Auto-allows *provably read-only* inline SQL for a small set of database
+ * clients, so routine SELECTs never reach the Guardian. Anything we cannot
+ * prove read-only is left ENTIRELY to the Guardian — this module has no
+ * "deny" outcome (see the invariant below).
+ *
+ * The hard, easy part is extracting the SQL safely WITHOUT regex over the raw
+ * command. We reuse execPolicy's shellParse — the same quote-aware tokenizer
+ * that powers the whole classifier — so `-c "SELECT 1; SELECT 2"` arrives as
+ * one clean, dequoted token and a `;` OUTSIDE quotes still reads as a real
+ * command separator. Extraction failures (unknown flag, unknown short-cluster,
+ * `-f file`, stdin `<`) simply left as `readonly: false`.
+ *
+ * ── The single invariant ────────────────────────────────────────────────
+ *   classifySql returns "read" ONLY when the SQL is provably read-only. A
+ *   false "read" auto-runs a write across every workspace's DB, which is
+ *   unacceptable; a false "unknown" costs one Guardian consult, which is free.
+ *   We therefore over-reject: a write marker, a mutating function name, or a
+ *   `\` meta-command ANYWHERE in the SQL downgrades the whole thing to
+ *   "unknown". No attempt is made to distinguish "called" from "mentioned in
+ *   a string literal" — erring toward prompt is always the safe direction.
+ *
+ *   NOTE: a non-"read" result is NOT "forbidden". An UPDATE/INSERT/DELETE is
+ *   sent to the Guardian where a human/LLM judges intent. This module never
+ *   flat-denies a DB write.
+ *
+ * ── How to extend ────────────────────────────────────────────────────────
+ *   Add a new client: push a DbClientSpec to DB_CLIENTS.
+ *   Add a new mutating function: append to the relevant client's
+ *     mutatingFunctions list (schema-prefix-agnostic word-boundary match).
+ *   Add a new way to pass SQL: add a SqlArgExtractor to the client.
+ *   Every change needs a paired allow + regression test in dbReadPolicy.test.ts.
+ *   See AGENTS.md alongside this directory for the full recipe.
+ */
+// --- Read-only classifier helpers ---
+/** Strip leading/leading whitespace and `/* … *​/` block + `-- …` line comments. */
+function stripSqlComments(sql) {
+    let out = sql;
+    // Block comments (non-greedy, across newlines).
+    out = out.replace(/\/\*[\s\S]*?\*\//g, " ");
+    // Line comments to end-of-line.
+    out = out.replace(/--[^\n]*/g, " ");
+    return out;
+}
+/** Write verbs / statements that are never read-only. */
+const WRITE_VERBS = /\b(insert|update|delete|truncate|drop|create|alter|grant|revoke|copy|vacuum|merge|call|set|replace|load)\b/i;
+/** Statements that use SELECT but still write (INTO, FOR UPDATE, …). */
+const WRITE_CLAUSES = /\b(into\s+(outfile|dumpfile|new\s+table|table)|for\s+(update|share)|returning)\b/i;
+/** Match a function name with a word boundary (catches `schema.fn` and `fn(`). */
+function mentionsFunction(sql, fn) {
+    const re = new RegExp(`(^|[^\\w])${fn}\\s*\\(`, "i");
+    return re.test(sql);
+}
+/**
+ * The shared "provably read-only" gate. Returns true only when every
+ * statement in `sql` (after comment-stripping) begins with SELECT/WITH and
+ * contains no write verb, write clause, mutating function, or backslash
+ * meta-command.
+ */
+export function isSqlReadOnly(sql, mutatingFunctions) {
+    const stripped = stripSqlComments(sql).trim();
+    // Any backslash is a psql/mysql meta-command (`\copy`, `\!`, `\i`) — not a
+    // plain SQL statement. Never auto-allow.
+    if (stripped.includes("\\"))
+        return false;
+    // A mutating function ANYWHERE (schema-prefixed, string-literal mention, or
+    // genuine call) downgrades the whole thing. Over-reject on purpose.
+    if (mutatingFunctions.some((fn) => mentionsFunction(stripped, fn)))
+        return false;
+    // Write verbs / clauses anywhere → not read-only. (Single pass over the whole
+    // multi-statement string means any `;`-joined write poisons the read.)
+    if (WRITE_VERBS.test(stripped))
+        return false;
+    if (WRITE_CLAUSES.test(stripped))
+        return false;
+    // The first statement must open with SELECT or WITH. (A leading `WITH`
+    // CTE is safe, but `WITH` can also be INSERT … WITH — the WRITE_VERBS
+    // check already caught any write verb, so a remaining `WITH` lead is a CTE.)
+    if (!/^(select|with)\b/i.test(stripped))
+        return false;
+    return true;
+}
+// --- Client registry ---
+/**
+ * PostgreSQL. Inline SQL via `-c` / `--command` (glued or `=`) and the
+ * `-Atc`-style short cluster. Mutating built-ins that a plain SELECT can
+ * smuggle are rejected as unknown.
+ */
+const postgresMutatingFunctions = [
+    // sequence / identity
+    "nextval", "setval",
+    // large objects (server filesystem writes)
+    "lo_import", "lo_export", "lo_creat", "lo_create", "lo_unlink", "lo_put",
+    // server admin / signaling
+    "pg_terminate_backend", "pg_cancel_backend", "pg_reload_conf",
+    "pg_rotate_logfile", "pg_promote", "pg_log_backend_memory_contexts",
+    // advisory locks / notification / snapshots (state-changing)
+    "pg_advisory_lock", "pg_advisory_lock_shared", "pg_advisory_xact_lock",
+    "pg_advisory_xact_lock_shared", "pg_try_advisory_lock",
+    "pg_try_advisory_lock_shared", "pg_try_advisory_xact_lock",
+    "pg_try_advisory_xact_lock_shared", "pg_advisory_unlock",
+    "pg_advisory_unlock_shared", "pg_advisory_unlock_all", "pg_notify",
+    "pg_export_snapshot",
+    // replication slots
+    "pg_create_logical_replication_slot", "pg_drop_replication_slot",
+    "pg_create_physical_replication_slot",
+    // superuser server-side filesystem reads (exfil surface)
+    "pg_read_file", "pg_read_binary_file", "pg_ls_dir", "pg_stat_file",
+    // resource abuse
+    "pg_sleep", "pg_sleep_for", "pg_sleep_until",
+    // remote execution via dblink
+    "dblink", "dblink_exec", "dblink_connect", "dblink_disconnect",
+    "dblink_send_query", "dblink_get_result", "dblink_open", "dblink_fetch",
+];
+const mysqlMutatingFunctions = [
+    "sleep", "benchmark", "load_file",
+    "get_lock", "release_lock", "release_all_locks",
+];
+/** The supported database clients. Add a new one here to expand coverage. */
+export const DB_CLIENTS = [
+    {
+        binaries: ["psql"],
+        sqlArgExtractors: [
+            {
+                flags: ["-c", "--command"],
+                shortCluster: {
+                    terminal: "c",
+                    allowedPrefixes: ["A", "t", "P", "q", "X", "a", "b", "e", "E", "f", "h", "n", "o", "p", "s", "S", "T", "U", "v", "V", "w", "W", "x", "z"],
+                },
+            },
+        ],
+        classifySql: (sql) => isSqlReadOnly(sql, postgresMutatingFunctions),
+        mutatingFunctions: postgresMutatingFunctions,
+    },
+    {
+        binaries: ["mysql", "mariadb"],
+        sqlArgExtractors: [
+            { flags: ["-e", "--execute"] },
+        ],
+        classifySql: (sql) => isSqlReadOnly(sql, mysqlMutatingFunctions),
+        mutatingFunctions: mysqlMutatingFunctions,
+    },
+];
+// --- SQL extraction (reuses shellParse — no regex over the raw command) ---
+/**
+ * Does the flag (exact equality) match a token, including a single-dash
+ * short-cluster form like `-Atc` (terminal flag letter + an allowlisted set of
+ * prefix letters)? Only used when the token has no glued SQL payload.
+ */
+function matchesFlagExactly(token, extractor) {
+    if (extractor.flags.includes(token))
+        return true;
+    if (extractor.shortCluster && token.startsWith("-") && !token.startsWith("--")) {
+        const { terminal, allowedPrefixes } = extractor.shortCluster;
+        const body = token.slice(1); // drop the leading '-'
+        if (!body.endsWith(terminal) || body.length < 2)
+            return false;
+        const prefixes = body.slice(0, -1).split("");
+        return prefixes.every((p) => allowedPrefixes.includes(p));
+    }
+    return false;
+}
+/**
+ * Resolve the SQL string for a known client binary from its tokenized argv.
+ * Returns `{ sql }` on success (the dequoted SQL as one string) or null when
+ * the argv shape can't be proven to carry inline SQL. Null → left to Guardian.
+ *
+ * Supported token shapes, in the order tried:
+ *   1. glued long flag   `--command=SELECT …` / `--execute=SELECT …`
+ *   2. glued short flag  `-cSELECT …` / `-eSELECT …` (2-char flag + payload)
+ *   3. bare flag         `-c` / `--command` / `-Atc`  → SQL is the NEXT token
+ */
+export function extractSqlArg(tokens, spec) {
+    for (let i = 1; i < tokens.length; i++) {
+        const tok = tokens[i];
+        for (const extractor of spec.sqlArgExtractors) {
+            // 1. glued long flag: `--command=SELECT …`
+            for (const f of extractor.flags) {
+                if (f.startsWith("--") && tok.startsWith(f + "=")) {
+                    const sql = tok.slice(f.length + 1);
+                    if (sql.length > 0)
+                        return { sql };
+                    return null;
+                }
+            }
+            // 2. glued short flag: `-cSELECT …` (only for bare 2-char flags in the
+            //    extractor, not short-clusters — a cluster like `-Atc` is a pure
+            //    flag, not glue).
+            for (const f of extractor.flags) {
+                if (f.length === 2 && f.startsWith("-") && !f.startsWith("--")) {
+                    if (tok.startsWith(f) && tok.length > 2) {
+                        const sql = tok.slice(2);
+                        if (sql.length > 0)
+                            return { sql };
+                        return null;
+                    }
+                }
+            }
+            // 3. bare flag → SQL is the next token.
+            if (matchesFlagExactly(tok, extractor)) {
+                const v = tokens[i + 1];
+                if (typeof v === "string" && v.length > 0)
+                    return { sql: v };
+                return null;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Top-level: should this database command be auto-allowed? Consumes the raw
+ * tokenized argv (tokens[0] is the binary) and returns true ONLY when the
+ * inline SQL was extracted AND classified read-only.
+ */
+export function classifyDbRead(tokens) {
+    const binary = tokens[0];
+    const spec = DB_CLIENTS.find((c) => c.binaries.includes(binary));
+    if (!spec)
+        return false;
+    const extracted = extractSqlArg(tokens, spec);
+    if (!extracted)
+        return false;
+    return spec.classifySql(extracted.sql);
+}
+//# sourceMappingURL=dbReadPolicy.js.map

package/dist/extension/{execPolicy.js → permission/execPolicy.js}

@@ -34,6 +34,8 @@
  * 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.
  */
+import { classifyDbRead } from "./dbReadPolicy.js";
+import { forwarderLabel, forwarderTailStart, normalizePackageManagerTokens, PACKAGE_MANAGER_ALLOW_RULES, } from "./packageManagerPolicy.js";
 /**
  * Parse a shell command string into tokens and control operators.
  *
@@ -574,11 +576,13 @@ function matchRule(tokens, rule) {
         const pat = rule.pattern[i];
         const tok = tokens[i];
         if (typeof pat === "string") {
-            if (pat !== tok)
+            // A trailing "*" glob lets a single pattern cover a namespace of tokens
+            // (e.g. "test:*" matches "test:backend", "test:file", …).
+            if (!tokenMatchesEntry(tok, pat))
                 return false;
         }
         else {
-            if (!pat.includes(tok))
+            if (!pat.some((entry) => tokenMatchesEntry(tok, entry)))
                 return false;
         }
     }
@@ -633,11 +637,28 @@ function classifySegmentTokens(rawTokens, policy, opts) {
     const pathPrefixed = normalizedWord !== cmdWord;
     let tokens = pathPrefixed ? [normalizedWord, ...strippedTokens.slice(1)] : strippedTokens;
     tokens = normalizeGitTokens(tokens);
+    tokens = normalizePackageManagerTokens(tokens);
     const neverAllow = stripped || pathPrefixed;
-    // xargs forwards to its argv tail: classify the tail as its own segment so
-    // `xargs rm -rf` inherits rm's forbidden. xargs itself is never allow.
-    if (tokens[0] === "xargs" && opts.depth < MAX_SCAN_DEPTH) {
-        let j = 1;
+    // Database read promotion: a known client (psql / mysql / …) whose inline
+    // SQL is provably read-only is auto-allowed BEFORE rule matching. A
+    // non-read (write, unknown shape, -f file) result means classifyDbRead
+    // returns false and we fall straight through to the prompt-band `psql`/
+    // `mysql` rule — never to a forbidden outcome. Only consulted when the
+    // command is not already disqualified (neverAllow) and we are not in the
+    // forbidden-only danger scan.
+    if (!neverAllow && !opts.forbiddenOnly && classifyDbRead(tokens)) {
+        return {
+            decision: "allow",
+            justification: "database read-only query (SELECT/WITH, no write or mutation)",
+        };
+    }
+    // Forwarders (xargs / npx / <mgr> exec / <mgr> dlx) run their argv tail:
+    // classify the tail as its own segment so `pnpm exec rm -rf` inherits rm's
+    // forbidden floor and `npx tsc --noEmit` inherits tsc's allow. The forwarder
+    // itself is never allow; an unknown tail stays in the prompt band.
+    const tailStart = forwarderTailStart(tokens);
+    if (tailStart !== null && opts.depth < MAX_SCAN_DEPTH) {
+        let j = tailStart;
         while (j < tokens.length && tokens[j].startsWith("-"))
             j++;
         const tail = tokens.slice(j);
@@ -646,12 +667,18 @@ function classifySegmentTokens(rawTokens, policy, opts) {
             if (tailResult.decision === "forbidden")
                 return tailResult;
             if (tailResult.decision === "allow" && !neverAllow) {
-                return { decision: "allow", justification: "xargs forwards to a read-only command" };
+                return {
+                    decision: "allow",
+                    justification: `${forwarderLabel(tokens)} forwards to a read-only command`,
+                };
             }
         }
         if (opts.forbiddenOnly)
             return { decision: "allow", justification: "no forbidden match" };
-        return { decision: "prompt", justification: "xargs executes its argument command — review the target" };
+        return {
+            decision: "prompt",
+            justification: `${forwarderLabel(tokens)} executes its argument command — review the target`,
+        };
     }
     // First match wins (rules are ordered; more specific rules come first).
     for (const rule of policy.rules) {
@@ -949,11 +976,12 @@ export const DEFAULT_EXEC_POLICY = {
         { pattern: ["pnpm", "lint"], decision: "allow", justification: "run linter (routine dev-loop operation)" },
         { pattern: ["npm", "test"], decision: "allow", justification: "run tests (routine dev-loop operation)" },
         { pattern: ["npm", "run", "lint"], decision: "allow", justification: "run linter (routine dev-loop operation)" },
-        { pattern: ["npx", "tsc", "--noEmit"], decision: "allow", justification: "typecheck only (no file writes)" },
-        { pattern: ["npx", "tsx", "--test"], decision: "allow", justification: "run tests (routine dev-loop operation)" },
-        { pattern: ["npx", "vitest"], decision: "allow", justification: "run vitest tests (routine dev-loop operation)" },
-        { pattern: ["npx", "vitest", "run"], decision: "allow", justification: "run vitest tests (routine dev-loop operation)" },
-        { pattern: ["npx", "jest"], decision: "allow", justification: "run jest tests (routine dev-loop operation)" },
+        // package-manager dev-loop band: dev-loop binaries (tsc --noEmit, tsx
+        // --test, vitest, jest) plus the test:/build:/lint: script namespaces.
+        // The npx/<mgr> exec/<mgr> dlx spellings reach these through tail
+        // forwarding (see classifySegmentTokens), so there is no separate
+        // "npx tsc" rule — `npx tsc --noEmit` forwards to the bare tsc rule.
+        ...PACKAGE_MANAGER_ALLOW_RULES,
         // misc read-only commands
         { pattern: ["printenv"], decision: "allow", justification: "print environment variables (read-only)" },
         { pattern: ["npm", ["view", "info"]], decision: "allow", justification: "read package metadata from registry" },

package/dist/extension/{permission.d.ts → permission/gate.d.ts}

@@ -28,8 +28,8 @@
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type ApprovedPrefixGrant } from "./approvedPrefixes.js";
-import type { HookRunner } from "./hooks.js";
-import { type BlessStore } from "./bless.js";
+import type { HookRunner } from "../hooks.js";
+import { type BlessStore } from "../bless.js";
 import { type ExecPolicy } from "./execPolicy.js";
 import { type GuardianError, type GuardianRiskLevel } from "./guardian.js";
 export type PermissionMode = "auto" | "plan" | "review";
@@ -209,4 +209,4 @@ export declare const filterStalePlanContext: typeof filterStaleModeContext;
  * auto, so absent any /mode this is a no-op over today's behavior.
  */
 export declare function registerPermissionGate(pi: ExtensionAPI, deps?: RegisterPermissionDeps): void;
-//# sourceMappingURL=permission.d.ts.map
+//# sourceMappingURL=gate.d.ts.map

package/dist/extension/{permission.js → permission/gate.js}

@@ -27,9 +27,9 @@
  * the context so the model doesn't keep believing it is restricted.
  */
 import { describePrefix, matchesGrant, validateGrant, } from "./approvedPrefixes.js";
-import { makeBlessStore as defaultMakeBlessStore } from "./bless.js";
+import { makeBlessStore as defaultMakeBlessStore } from "../bless.js";
 import { classifyCommand, DEFAULT_EXEC_POLICY } from "./execPolicy.js";
-import { isDebug } from "./diagnostics.js";
+import { isDebug } from "../diagnostics.js";
 import { buildDiagnosticEvent, checkCircuitBreaker, DEFAULT_GUARDIAN_LIMITS, } from "./guardian.js";
 export function createModeHolder(initial = "auto") {
     let current = initial;
@@ -931,4 +931,4 @@ export function registerPermissionGate(pi, deps = {}) {
         },
     });
 }
-//# sourceMappingURL=permission.js.map
+//# sourceMappingURL=gate.js.map

package/dist/extension/{guardian.d.ts → permission/guardian.d.ts}

@@ -27,8 +27,8 @@
  * exoneration — so an ask-preferring model cannot disarm the breaker by
  * alternating deny/ask.
  */
-import { runStage as defaultRunStage } from "./pipeline/runner.js";
-import type { PipelineStage } from "./pipeline/types.js";
+import { runStage as defaultRunStage } from "../pipeline/runner.js";
+import type { PipelineStage } from "../pipeline/types.js";
 export type GuardianOutcome = "allow" | "ask" | "deny";
 export type GuardianRiskLevel = "low" | "medium" | "high" | "critical";
 export interface GuardianVerdict {

package/dist/extension/{guardian.js → permission/guardian.js}

@@ -27,7 +27,7 @@
  * exoneration — so an ask-preferring model cannot disarm the breaker by
  * alternating deny/ask.
  */
-import { runStage as defaultRunStage } from "./pipeline/runner.js";
+import { runStage as defaultRunStage } from "../pipeline/runner.js";
 export const DEFAULT_GUARDIAN_LIMITS = {
     maxReviews: 120,
     maxConsecutiveDenials: 3,

package/dist/extension/permission/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Permission domain barrel.
+ *
+ * This file is the *public* re-export surface ONLY. Internal modules import
+ * each other directly (gate.ts → ./execPolicy.js), never through this barrel,
+ * to keep the dependency graph grep-able and avoid circular imports.
+ *
+ * See AGENTS.md alongside this directory for the seam map and how to extend.
+ */
+export * from "./execPolicy.js";
+export * from "./guardian.js";
+export * from "./approvedPrefixes.js";
+export * from "./gate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/extension/permission/index.js

@@ -0,0 +1,14 @@
+/**
+ * Permission domain barrel.
+ *
+ * This file is the *public* re-export surface ONLY. Internal modules import
+ * each other directly (gate.ts → ./execPolicy.js), never through this barrel,
+ * to keep the dependency graph grep-able and avoid circular imports.
+ *
+ * See AGENTS.md alongside this directory for the seam map and how to extend.
+ */
+export * from "./execPolicy.js";
+export * from "./guardian.js";
+export * from "./approvedPrefixes.js";
+export * from "./gate.js";
+//# sourceMappingURL=index.js.map

package/dist/extension/permission/packageManagerPolicy.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Package-manager and dev-loop auto-allow policy (YAG-561).
+ *
+ * Companion to execPolicy.ts: this file owns the *data* and *parsing* for the
+ * package-manager / dev-loop band, while execPolicy.ts owns the core classifier
+ * (rule matching, construct floor, danger scan) and wires these helpers in.
+ *
+ * Two independent mechanisms live here:
+ *
+ * 1. Workspace-selector normalization — `pnpm --filter <pkg> test:file` should
+ *    match the same rules as `pnpm test:file`. We strip ONLY the value-bearing
+ *    "which workspace" options (never arbitrary flags), because an option we
+ *    do NOT recognize must degrade to `prompt`, never to `allow`.
+ *
+ * 2. Exec/dlx forwarders — `npx`, `pnpm exec`, `npm exec`, `yarn exec`,
+ *    `pnpm dlx`, `yarn dlx`, and `xargs` all forward to their argv tail. The
+ *    tail is classified as its own segment so `pnpm exec rm -rf` inherits rm's
+ *    forbidden floor and `npx tsc --noEmit` inherits tsc's allow.
+ *
+ * The allow rules themselves (`PACKAGE_MANAGER_ALLOW_RULES`) cover:
+ *   - dev-loop binaries reachable through a forwarder (and directly):
+ *     tsc (requires --noEmit), tsx (requires --test), vitest, jest;
+ *   - script namespaces `test:*` / `build:*` / `lint:*` across pnpm/npm/yarn.
+ *
+ * Deliberately NOT auto-allowed here: arbitrary `pnpm exec <binary>`, any
+ * `run <script>` outside the three namespaces (`pnpm run deploy` is prompt),
+ * and `pnpm install/add/remove` (they mutate node_modules). Those stay in the
+ * prompt band and go to the Guardian.
+ *
+ * See AGENTS.md alongside this directory for the "add a new spelling" recipe.
+ */
+import type { PrefixRule } from "./execPolicy.js";
+/**
+ * Strip value-bearing "which workspace" options so they don't break prefix
+ * matching. Matching-only: the returned tokens are used to CLASSIFY, never to
+ * run. Only the handlers below are stripped; anything unrecognized falls
+ * through untouched and degrades to `prompt` (fail closed).
+ *
+ *   pnpm: --filter <pkg> / -F <pkg>   (+ --filter=<pkg> glue)
+ *   npm : --workspace <pkg> / -w <pkg> (+ --workspace=<pkg> glue)
+ *   yarn: (none handled yet — `yarn workspace <name>` is left alone on purpose)
+ */
+export declare function normalizePackageManagerTokens(tokens: string[]): string[];
+/**
+ * If `tokens[0]` names a forwarder (xargs / npx / <mgr> exec / <mgr> dlx),
+ * return the index at which the forwarded command's argv begins. Return null
+ * otherwise. Forwarders exercise `require`d escape hatch: they match only when
+ * the manager word is a bare, path-unprefixed, unwrapped token (callers already
+ * forced `neverAllow` for wrappers/paths before this runs).
+ */
+export declare function forwarderTailStart(tokens: string[]): number | null;
+/** Human label for a forwarder, used in justification strings. */
+export declare function forwarderLabel(tokens: string[]): string;
+export declare const PACKAGE_MANAGER_ALLOW_RULES: PrefixRule[];
+//# sourceMappingURL=packageManagerPolicy.d.ts.map

package/dist/extension/permission/packageManagerPolicy.js

@@ -0,0 +1,170 @@
+/**
+ * Package-manager and dev-loop auto-allow policy (YAG-561).
+ *
+ * Companion to execPolicy.ts: this file owns the *data* and *parsing* for the
+ * package-manager / dev-loop band, while execPolicy.ts owns the core classifier
+ * (rule matching, construct floor, danger scan) and wires these helpers in.
+ *
+ * Two independent mechanisms live here:
+ *
+ * 1. Workspace-selector normalization — `pnpm --filter <pkg> test:file` should
+ *    match the same rules as `pnpm test:file`. We strip ONLY the value-bearing
+ *    "which workspace" options (never arbitrary flags), because an option we
+ *    do NOT recognize must degrade to `prompt`, never to `allow`.
+ *
+ * 2. Exec/dlx forwarders — `npx`, `pnpm exec`, `npm exec`, `yarn exec`,
+ *    `pnpm dlx`, `yarn dlx`, and `xargs` all forward to their argv tail. The
+ *    tail is classified as its own segment so `pnpm exec rm -rf` inherits rm's
+ *    forbidden floor and `npx tsc --noEmit` inherits tsc's allow.
+ *
+ * The allow rules themselves (`PACKAGE_MANAGER_ALLOW_RULES`) cover:
+ *   - dev-loop binaries reachable through a forwarder (and directly):
+ *     tsc (requires --noEmit), tsx (requires --test), vitest, jest;
+ *   - script namespaces `test:*` / `build:*` / `lint:*` across pnpm/npm/yarn.
+ *
+ * Deliberately NOT auto-allowed here: arbitrary `pnpm exec <binary>`, any
+ * `run <script>` outside the three namespaces (`pnpm run deploy` is prompt),
+ * and `pnpm install/add/remove` (they mutate node_modules). Those stay in the
+ * prompt band and go to the Guardian.
+ *
+ * See AGENTS.md alongside this directory for the "add a new spelling" recipe.
+ */
+// --- Workspace-selector normalization ---
+/**
+ * Strip value-bearing "which workspace" options so they don't break prefix
+ * matching. Matching-only: the returned tokens are used to CLASSIFY, never to
+ * run. Only the handlers below are stripped; anything unrecognized falls
+ * through untouched and degrades to `prompt` (fail closed).
+ *
+ *   pnpm: --filter <pkg> / -F <pkg>   (+ --filter=<pkg> glue)
+ *   npm : --workspace <pkg> / -w <pkg> (+ --workspace=<pkg> glue)
+ *   yarn: (none handled yet — `yarn workspace <name>` is left alone on purpose)
+ */
+export function normalizePackageManagerTokens(tokens) {
+    const cmd = tokens[0];
+    if (cmd !== "pnpm" && cmd !== "npm" && cmd !== "yarn")
+        return tokens;
+    const out = [cmd];
+    let i = 1;
+    while (i < tokens.length) {
+        const t = tokens[i];
+        if (cmd === "pnpm") {
+            // `--filter pkg` / `-F pkg` → skip option + its value
+            if (t === "--filter" || t === "-F") {
+                i += 2;
+                continue;
+            }
+            // glued `--filter=pkg` / `-F=pkg` → skip the single token
+            if (t.startsWith("--filter=") || t.startsWith("-F=")) {
+                i += 1;
+                continue;
+            }
+        }
+        else if (cmd === "npm") {
+            // `--workspace pkg` / `-w pkg` → skip option + its value
+            if (t === "--workspace" || t === "-w") {
+                i += 2;
+                continue;
+            }
+            if (t.startsWith("--workspace=") || t.startsWith("-w=")) {
+                i += 1;
+                continue;
+            }
+        }
+        // First non-selector token (yarn has none we handle) — stop stripping.
+        break;
+    }
+    out.push(...tokens.slice(i));
+    return out;
+}
+// --- Exec/dlx forwarders ---
+/**
+ * If `tokens[0]` names a forwarder (xargs / npx / <mgr> exec / <mgr> dlx),
+ * return the index at which the forwarded command's argv begins. Return null
+ * otherwise. Forwarders exercise `require`d escape hatch: they match only when
+ * the manager word is a bare, path-unprefixed, unwrapped token (callers already
+ * forced `neverAllow` for wrappers/paths before this runs).
+ */
+export function forwarderTailStart(tokens) {
+    const cmd = tokens[0];
+    if (cmd === "xargs" || cmd === "npx")
+        return 1;
+    if (tokens.length < 2)
+        return null;
+    const sub = tokens[1];
+    if (sub === "exec" && (cmd === "pnpm" || cmd === "npm" || cmd === "yarn"))
+        return 2;
+    if (sub === "dlx" && (cmd === "pnpm" || cmd === "yarn"))
+        return 2;
+    return null;
+}
+/** Human label for a forwarder, used in justification strings. */
+export function forwarderLabel(tokens) {
+    const cmd = tokens[0];
+    if (cmd === "npx" || cmd === "xargs")
+        return cmd;
+    return tokens.slice(0, 2).join(" ");
+}
+// --- Allow rules ---
+/**
+ * The auto-allow rules for the package-manager / dev-loop band. Appended to
+ * DEFAULT_EXEC_POLICY.rules by execPolicy.ts (first-match-wins ordering puts
+ * these specific rules ahead of the `npx`/`run`/`exec` prompt fallbacks).
+ *
+ * Safety invariants for every entry:
+ *   - tsc only allows with --noEmit (bare `tsc` would emit .js/.d.ts).
+ *   - tsx only allows with --test (bare `tsx file.ts` executes arbitrary TS).
+ *   - vitest / jest are pure test runners (no mutating flag to fence).
+ *   - script namespaces are read-only-by-convention test/build/lint and are
+ *     the ONLY `run` targets allowed; everything else (`run deploy`) is prompt.
+ */
+// The bare script name AND its `name:*` namespace (e.g. both `test` and
+// `test:backend`) — declared once so each manager rule reuses the same set.
+const SCRIPT_NAMESPACES = ["test", "test:*", "build", "build:*", "lint", "lint:*"];
+export const PACKAGE_MANAGER_ALLOW_RULES = [
+    // dev-loop binaries (reachable directly or through a forwarder)
+    {
+        pattern: ["tsc"],
+        flagsAnywhere: ["--noEmit"],
+        decision: "allow",
+        justification: "typecheck only (--noEmit writes no files)",
+    },
+    {
+        pattern: ["tsx"],
+        flagsAnywhere: ["--test"],
+        decision: "allow",
+        justification: "run tests via tsx (--test only, no script execution)",
+    },
+    { pattern: ["vitest"], decision: "allow", justification: "run vitest tests (routine dev-loop operation)" },
+    { pattern: ["vitest", "run"], decision: "allow", justification: "run vitest tests (routine dev-loop operation)" },
+    { pattern: ["jest"], decision: "allow", justification: "run jest tests (routine dev-loop operation)" },
+    // script namespaces — direct form (pnpm/yarn support `mgr <script>`) and
+    // universal `run <script>` form. npm direct form is omitted: npm requires
+    // `run` for colon-namespaced scripts.
+    {
+        pattern: ["pnpm", SCRIPT_NAMESPACES],
+        decision: "allow",
+        justification: "run a test/build/lint script (routine dev-loop operation)",
+    },
+    {
+        pattern: ["pnpm", "run", SCRIPT_NAMESPACES],
+        decision: "allow",
+        justification: "run a test/build/lint script (routine dev-loop operation)",
+    },
+    {
+        pattern: ["yarn", SCRIPT_NAMESPACES],
+        decision: "allow",
+        justification: "run a test/build/lint script (routine dev-loop operation)",
+    },
+    {
+        pattern: ["yarn", "run", SCRIPT_NAMESPACES],
+        decision: "allow",
+        justification: "run a test/build/lint script (routine dev-loop operation)",
+    },
+    {
+        pattern: ["npm", "run", SCRIPT_NAMESPACES],
+        decision: "allow",
+        justification: "run a test/build/lint script (routine dev-loop operation)",
+    },
+];
+//# sourceMappingURL=packageManagerPolicy.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yagni-app/code-staging",
-  "version": "0.3.3-staging.1132.1",
+  "version": "0.3.4-staging.1145.1",
   "description": "YAGNI Code: a terminal coding agent that already knows your company. One YAGNI login routes the model and grounds the agent in your team's context.",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "YAGNI, Inc. <jack@yagni.app> (https://yagni.app)",
@@ -39,5 +39,5 @@
     "smol-toml": "^1.8.0",
     "typebox": "^1.3.11"
   },
-  "yagniSourceSha": "843cd82c45cfecff3b30092b4610ee1bd7103d48"
+  "yagniSourceSha": "23495abda59558b06033f88e56f41c8e2417e294"
 }