@yagni-app/code 0.3.1 → 0.3.3

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";
@@ -138,6 +138,8 @@ export { runInitPass, runTeamSetup, registerTeamSetupCommand, isFreshWorkspace,
 export type { RunInitPassDeps, InitPassOutcome, RunTeamSetupDeps, TeamSetupOutcome, RepoIntake, RepoIntakeFs, EngineeringDraft, DraftTeam, } from "./initPass.js";
 export { isInitDone, markInitDone, initDoneMarkerFile, _setInitDoneHomeForTest } from "./initDone.js";
 export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_ULTRA, BRAND_NAME } from "./branding.js";
+export { loadHooksConfig, makeHookRunner, registerHooks, matchesMatcher, parsePreToolUseOutput, parsePermissionRequestOutput, parseAdditionalContext, parseCompactCancel, HOOK_SUPPORTED_EVENTS, } from "./hooks.js";
+export type { HookEntry, HookGroup, HooksConfig, HookEventName, HookRunner, PreToolUseHookResult, PermissionRequestHookResult, RegisterHooksDeps, } from "./hooks.js";
 export { createUltraHolder, registerUltraCommand } from "./ultra.js";
 export type { UltraHolder } from "./ultra.js";
 export { attributionHeaders, isDriverCaller, fetchCatalog, getToken, getWorkspaceId, resolveBaseUrl, sanitizeCallerSegment, } from "./config.js";
@@ -147,6 +149,11 @@ export { registerGoCommand } from "./pipeline/goCommand.js";
 export type { RegisterGoDeps } from "./pipeline/goCommand.js";
 export { runPipeline } from "./pipeline/orchestrator.js";
 export type { RunPipelineDeps } from "./pipeline/orchestrator.js";
+export { HEADLESS_GO_EXIT, HEADLESS_GO_USAGE, parseHeadlessGoArgs, runHeadlessGo, validateHeadlessGoArgs, } from "./pipeline/headlessGo.js";
+export type { HeadlessGoArgs, HeadlessGoDeps, HeadlessGoOutcome, HeadlessGoResult, HeadlessStageRow, } from "./pipeline/headlessGo.js";
+export { isMissionMode, missionSeed, missionSkippedStages, normalizeMission } from "./pipeline/mission.js";
+export type { MissionInputs } from "./pipeline/mission.js";
+export { clampTier, parseTierCap, resolveTierCap, TIER_CAP_ENV } from "./pipeline/tierCap.js";
 export { withResilience, classifyTransient, composeAbortSignal } from "./pipeline/resilience.js";
 export type { ResilienceAttemptRecord, ResilienceSeams, RunStageFn } from "./pipeline/resilience.js";
 export { DEFAULT_RESILIENCE_POLICY } from "./pipeline/types.js";
@@ -160,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";
@@ -20,6 +20,7 @@ import { registerCostCommand } from "./costHud.js";
 import { isDebug } from "./diagnostics.js";
 import { droppedSessionRuns, sessionRunIds } from "./sessionRuns.js";
 import { codeStateHome } from "./stateHome.js";
+import { logTurnLifecycle } from "./turnLog.js";
 import { createYagniFooterFactory, cyclePermissionMode, formatCwd, GIT_MUTATING_PATTERN, isShiftTab } from "./footer.js";
 import { RerouteNotifier } from "./rerouteNotice.js";
 import { isFreshWorkspace, registerTeamSetupCommand, runInitPass as defaultRunInitPass } from "./initPass.js";
@@ -27,7 +28,8 @@ 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";
 import { registerTodos } from "./todos.js";
@@ -139,7 +141,12 @@ export async function registerYagni(pi, deps = {}) {
     // `yagni` provider, so /model and Ctrl+P show a single entry. Child
     // processes (/go, subagents, advisor) fetch their own catalog and register
     // their own provider, so they are unaffected by this filter.
-    const catalog = fullCatalog.filter((m) => m.id === "advanced");
+    //
+    // Eval mode is exempt: a headless harness (scoping sessions, code evals)
+    // names its tier explicitly — the backend's scoping sessions run `--model
+    // standard` — and there is no /model picker to keep tidy. Filtering there
+    // turns a valid tier request into "no models match".
+    const catalog = evalMode ? fullCatalog : fullCatalog.filter((m) => m.id === "advanced");
     // YAG-471: the driver's own completions carry attribution headers read from
     // this process's env (YAGNI_SESSION_ID minted by the launcher; YAGNI_CALLER
     // defaults to "driver" when unset, i.e. every session that is not a /go
@@ -206,6 +213,10 @@ export async function registerYagni(pi, deps = {}) {
     // The grounded multi-agent pipeline entry point: /go <ticket> runs
     // map → plan → implement → review → fix, each child grounded by inheritance.
     registerGoCommand(pi, {
+        // /ultra is one dial for the whole session: the same holder the subagent
+        // tool reads widens the implement diamond's parallel ceiling (4 -> 8) for
+        // the fan and its fix turns. Read per run, so a toggle lands on the next /go.
+        isUltra: () => ultraHolder.get(),
         // Task 8: /go's end-of-run summary prefers the server-priced per-stage
         // breakdown for the ONE run that just finished (`?runId=`, aliasing the
         // spend endpoint's `sessionId` param — see the backend route), over
@@ -280,6 +291,12 @@ export async function registerYagni(pi, deps = {}) {
     // rejected as a same-session self-authorization path, PR #1698).
     const sessionGrants = evalMode ? [] : loadGrants();
     const GUARDIAN_EVENT_TIMEOUT_MS = 5_000;
+    // YAG-506: load user-configurable lifecycle hooks config and create the
+    // hook runner for the permission gate. Skipped in eval mode.
+    const hooksConfig = evalMode ? {} : loadHooksConfig();
+    const hookRunner = evalMode ? null : makeHookRunner({ config: hooksConfig });
+    if (!evalMode)
+        registerHooks(pi, { config: hooksConfig });
     registerPermissionGate(pi, {
         modeHolder,
         guardianState,
@@ -362,6 +379,7 @@ export async function registerYagni(pi, deps = {}) {
         onBlessRemember: decisionCapture
             ? (ctx, info) => decisionCapture.captureFromBless(ctx, info)
             : undefined,
+        ...(hookRunner ? { hookRunner } : {}),
     });
     // P2/YAG-383: /cost prefers the server-authoritative session spend (covers
     // subagents and advisor consults directly, since they bill under this same
@@ -564,6 +582,28 @@ export async function registerYagni(pi, deps = {}) {
                 rulesSection,
             }),
         });
+    // Turn-lifecycle WAL: a `turn_start` with no matching `turn_end` is the
+    // silent-freeze tell (the turn that left the UI stuck on "Working…"), even
+    // if the process is later killed. `turn_end` records the final stopReason so
+    // an `error` / `aborted` end is visible at a glance without reading the raw
+    // session .jsonl. Fail-soft; nothing here may break a turn.
+    const turnStartMs = new Map();
+    const sessionIdForLog = () => deps.env?.YAGNI_SESSION_ID;
+    pi.on("turn_start", (event) => {
+        turnStartMs.set(event.turnIndex, Date.now());
+        logTurnLifecycle({ kind: "turn_start", sessionId: sessionIdForLog(), turnIndex: event.turnIndex });
+    });
+    pi.on("turn_end", (event) => {
+        const startedAt = turnStartMs.get(event.turnIndex);
+        turnStartMs.delete(event.turnIndex);
+        logTurnLifecycle({
+            kind: "turn_end",
+            sessionId: sessionIdForLog(),
+            turnIndex: event.turnIndex,
+            stopReason: event.message?.stopReason,
+            elapsedMs: startedAt !== undefined ? Date.now() - startedAt : undefined,
+        });
+    });
     // Two finalized-message guards share this handler (their conditions are
     // mutually exclusive: YAG-460 takes error-stopped messages, YAG-466 takes
     // stop/length ones without an errorMessage).
@@ -847,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";
@@ -859,12 +899,22 @@ export { runInitPass, runTeamSetup, registerTeamSetupCommand, isFreshWorkspace,
 // Onramp Door B (F2a): the one-time init-pass idempotency marker.
 export { isInitDone, markInitDone, initDoneMarkerFile, _setInitDoneHomeForTest } from "./initDone.js";
 export { brandSystemPrompt, YAGNI_IDENTITY, YAGNI_IDENTITY_DRIVER, YAGNI_IDENTITY_ULTRA, BRAND_NAME } from "./branding.js";
+// YAG-506: user-configurable lifecycle hooks.
+export { loadHooksConfig, makeHookRunner, registerHooks, matchesMatcher, parsePreToolUseOutput, parsePermissionRequestOutput, parseAdditionalContext, parseCompactCancel, HOOK_SUPPORTED_EVENTS, } from "./hooks.js";
 // Ultra mode (/ultra): the aggressive fan-out/verify/synthesize dial.
 export { createUltraHolder, registerUltraCommand } from "./ultra.js";
 export { attributionHeaders, isDriverCaller, fetchCatalog, getToken, getWorkspaceId, resolveBaseUrl, sanitizeCallerSegment, } from "./config.js";
 export { buildYagniProvider } from "./provider.js";
 export { registerGoCommand } from "./pipeline/goCommand.js";
 export { runPipeline } from "./pipeline/orchestrator.js";
+// The headless front door (`yagni go --headless`): the same pipeline, driven by
+// a script or the mission sandbox instead of a session.
+export { HEADLESS_GO_EXIT, HEADLESS_GO_USAGE, parseHeadlessGoArgs, runHeadlessGo, validateHeadlessGoArgs, } from "./pipeline/headlessGo.js";
+// Mission mode: the pure rules for entering the pipeline on an already-approved
+// plan (map/plan skipped, memo as the stand-in repo brief, FINISH not ours).
+export { isMissionMode, missionSeed, missionSkippedStages, normalizeMission } from "./pipeline/mission.js";
+// The eval/smoke tier ceiling (YAGNI_GO_TIER_CAP), clamped centrally in runStage.
+export { clampTier, parseTierCap, resolveTierCap, TIER_CAP_ENV } from "./pipeline/tierCap.js";
 // R1: the in-loop resilience HOF a dev can compose with (or replace at) the
 // `runStage` seam, plus its policy type and the default policy.
 export { withResilience, classifyTransient, composeAbortSignal } from "./pipeline/resilience.js";
@@ -880,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