@yagni-app/code 0.3.2 → 0.3.4

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,7 +28,8 @@
  */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type ApprovedPrefixGrant } from "./approvedPrefixes.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";
@@ -179,6 +180,12 @@ export interface RegisterPermissionDeps {
      * Fail-soft; never blocks.
      */
     onGuardianEvent?: (event: GuardianGateEvent) => void;
+    /**
+     * User-configurable lifecycle hooks (YAG-506). When present, PreToolUse
+     * hooks run before decideGate and can short-circuit (allow/deny/ask),
+     * and PermissionRequest hooks run before the confirm dialog.
+     */
+    hookRunner?: HookRunner;
 }
 /** The customType tag on injected mode-context messages (filterable later). */
 export declare const MODE_CONTEXT_TYPE = "yagni-mode-context";
@@ -202,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;
@@ -296,6 +296,7 @@ export function registerPermissionGate(pi, deps = {}) {
     const basePolicy = deps.policy ?? DEFAULT_PERMISSION_POLICY;
     let mode = deps.mode ?? "auto";
     const makeStore = deps.makeBlessStore ?? defaultMakeBlessStore;
+    const hookRunner = deps.hookRunner;
     deps.modeHolder?.onSet((m) => {
         if (m !== mode)
             approvedCommands.clear();
@@ -422,7 +423,48 @@ export function registerPermissionGate(pi, deps = {}) {
         const modeAtEntry = mode;
         try {
             const input = event.input ?? {};
-            const decision = decideGate(event.toolName, input, modeAtEntry, effectivePolicy);
+            // YAG-506: PreToolUse hooks run BEFORE decideGate. They can short-circuit
+            // (allow/deny/ask) or fall through to the normal gate logic. The result
+            // is cached in preToolUseResult so the "ask" check below does NOT
+            // re-invoke the hook (hooks have side effects — notifications etc.).
+            let preToolUseResult;
+            if (hookRunner) {
+                const cwd = ctx?.cwd ?? ".";
+                try {
+                    preToolUseResult = await hookRunner.preToolUse(event.toolName, input, cwd, ctx?.isProjectTrusted()) ?? undefined;
+                    if (preToolUseResult) {
+                        if (preToolUseResult.decision === "deny") {
+                            return { block: true, reason: preToolUseResult.reason };
+                        }
+                        if (preToolUseResult.decision === "allow") {
+                            // Allow bypasses Guardian/confirm, but the exec policy's forbidden
+                            // band still runs as a hard safety floor (deliberate deviation
+                            // from Claude Code: we don't let a hook auto-allow a forbidden cmd).
+                            if (event.toolName === "bash") {
+                                const cmdRaw = input.command;
+                                const command = typeof cmdRaw === "string" ? cmdRaw.trim() : "";
+                                if (command) {
+                                    const execPolicy = effectivePolicy.execPolicy ?? DEFAULT_EXEC_POLICY;
+                                    const classification = classifyCommand(command, execPolicy);
+                                    if (classification.decision === "forbidden") {
+                                        return {
+                                            block: true,
+                                            reason: `${classification.justification}. Do not attempt the same outcome via a workaround or indirect execution — use a materially safer alternative, or ask the user.`,
+                                        };
+                                    }
+                                }
+                            }
+                            return {};
+                        }
+                        // "ask" → force confirm by overriding the gate decision
+                        // Falls through to decision.confirm logic below
+                    }
+                }
+                catch {
+                    // Fail-soft: a hook error never blocks or allows; fall through to gate
+                }
+            }
+            let decision = decideGate(event.toolName, input, modeAtEntry, effectivePolicy);
             if (decision.block)
                 return { block: true, reason: decision.reason };
             // Prompt band (YAG-510 order): grants → exact-command cache → cap/
@@ -587,6 +629,41 @@ export function registerPermissionGate(pi, deps = {}) {
                                 reason: `Guardian needs user approval: ${verdict.rationale} No UI available — the command was held. Find a safer alternative or leave this step for the user.`,
                             };
                         }
+                        // YAG-506: PermissionRequest hooks fire before the confirm dialog.
+                        // Only when a UI is present (headless path already failed closed above).
+                        if (hookRunner && ctx?.hasUI) {
+                            try {
+                                const hookResult = await hookRunner.permissionRequest(event.toolName, input, cwd, ctx?.isProjectTrusted());
+                                if (hookResult) {
+                                    if (hookResult.decision === "allow") {
+                                        rememberApproved(cwd, command);
+                                        emitGateEvent({
+                                            ...eventBase,
+                                            outcome: "ask_approved",
+                                            riskLevel: verdict.riskLevel,
+                                            rationale: verdict.rationale,
+                                            durationMs,
+                                            consulted: true,
+                                        });
+                                        return {};
+                                    }
+                                    if (hookResult.decision === "deny") {
+                                        emitGateEvent({
+                                            ...eventBase,
+                                            outcome: "ask_denied",
+                                            riskLevel: verdict.riskLevel,
+                                            rationale: verdict.rationale,
+                                            durationMs,
+                                            consulted: true,
+                                        });
+                                        return { block: true, reason: hookResult.reason };
+                                    }
+                                }
+                            }
+                            catch {
+                                // Fail-soft: hook error → dialog proceeds normally
+                            }
+                        }
                         // Offer "don't ask again" only when the grant would actually
                         // cover this command (grant-time validation).
                         const grantCandidate = validateGrant(command, effectivePolicy.execPolicy ?? DEFAULT_EXEC_POLICY, resolveRepoKeyFor(cwd));
@@ -725,7 +802,29 @@ export function registerPermissionGate(pi, deps = {}) {
                 }
                 // review mode with Guardian disabled/capped: fall through to confirm.
             }
+            // YAG-506: PreToolUse "ask" forces confirmation even in auto mode.
+            // Uses the cached result from the top of the handler — no re-invocation.
+            if (preToolUseResult?.decision === "ask") {
+                decision = { block: false, confirm: true };
+            }
             if (decision.confirm) {
+                // YAG-506: PermissionRequest hooks run before the confirm dialog.
+                if (hookRunner) {
+                    try {
+                        const cwd = ctx?.cwd ?? ".";
+                        const hookResult = await hookRunner.permissionRequest(event.toolName, input, cwd, ctx?.isProjectTrusted());
+                        if (hookResult) {
+                            if (hookResult.decision === "allow")
+                                return {};
+                            if (hookResult.decision === "deny") {
+                                return { block: true, reason: hookResult.reason };
+                            }
+                        }
+                    }
+                    catch {
+                        // Fail-soft: hook error → dialog proceeds normally
+                    }
+                }
                 // Review mode needs a confirmation. With no dialog-capable UI (headless),
                 // fail CLOSED: the user explicitly chose a stricter mode, so a write we
                 // cannot get consent for is held rather than silently auto-applied (this
@@ -832,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 {
@@ -45,13 +45,32 @@ export interface GuardianLimits {
     timeoutMs: number;
 }
 export declare const DEFAULT_GUARDIAN_LIMITS: GuardianLimits;
+/**
+ * Client-side safety margin on top of the backend's advertised wall ceiling
+ * (YAG-562). The backend now owns the real timeout (first-output + wall) and
+ * retries once, so the client must NOT pre-empt it; it derives its own
+ * deadline from the catalog's `guardianTimeoutMs * attempts` plus this margin
+ * for child boot + read-tool round-trips + teardown, and treats that bound as
+ * a last-resort floor, not the normal path.
+ */
+export declare const GUARDIAN_CLIENT_OVERHEAD_MS = 10000;
 /**
  * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
  * overrides the sliding-window review cap; anything non-numeric or < 1 falls
  * back to the default (a bad value must never zero out the cap and lock the
- * session).
+ * session). `YAGNI_GUARDIAN_TIMEOUT_MS` overrides the consult deadline for a
+ * single developer (previously documented but unwired).
  */
 export declare function resolveGuardianLimits(env?: Record<string, string | undefined>): GuardianLimits;
+/**
+ * Derive the client's whole-consult deadline from the backend's advertised
+ * wall ceiling and attempt count (YAG-562). Falls back to the resolved limit
+ * when the catalog omitted the fields (older backend).
+ */
+export declare function deriveGuardianTimeoutMs(base: GuardianLimits, advertised: {
+    timeoutMs?: number;
+    maxAttempts?: number;
+}): number;
 /** The model tier the Guardian runs on. Configurable via YAGNI_GUARDIAN_TIER. */
 export declare const GUARDIAN_MODEL_TIER = "efficient";
 /** Read-only tools — the Guardian can read files for context but cannot write or execute. */

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

@@ -27,23 +27,47 @@
  * 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,
     timeoutMs: 15_000,
 };
+/**
+ * Client-side safety margin on top of the backend's advertised wall ceiling
+ * (YAG-562). The backend now owns the real timeout (first-output + wall) and
+ * retries once, so the client must NOT pre-empt it; it derives its own
+ * deadline from the catalog's `guardianTimeoutMs * attempts` plus this margin
+ * for child boot + read-tool round-trips + teardown, and treats that bound as
+ * a last-resort floor, not the normal path.
+ */
+export const GUARDIAN_CLIENT_OVERHEAD_MS = 10_000;
 /**
  * Resolve Guardian limits from the environment. `YAGNI_GUARDIAN_MAX_REVIEWS`
  * overrides the sliding-window review cap; anything non-numeric or < 1 falls
  * back to the default (a bad value must never zero out the cap and lock the
- * session).
+ * session). `YAGNI_GUARDIAN_TIMEOUT_MS` overrides the consult deadline for a
+ * single developer (previously documented but unwired).
  */
 export function resolveGuardianLimits(env = process.env) {
-    const raw = env.YAGNI_GUARDIAN_MAX_REVIEWS?.trim();
-    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
-    const maxReviews = Number.isFinite(parsed) && parsed >= 1 ? parsed : DEFAULT_GUARDIAN_LIMITS.maxReviews;
-    return { ...DEFAULT_GUARDIAN_LIMITS, maxReviews };
+    const rawReviews = env.YAGNI_GUARDIAN_MAX_REVIEWS?.trim();
+    const parsedReviews = rawReviews ? Number.parseInt(rawReviews, 10) : NaN;
+    const maxReviews = Number.isFinite(parsedReviews) && parsedReviews >= 1 ? parsedReviews : DEFAULT_GUARDIAN_LIMITS.maxReviews;
+    const rawTimeout = env.YAGNI_GUARDIAN_TIMEOUT_MS?.trim();
+    const parsedTimeout = rawTimeout ? Number.parseInt(rawTimeout, 10) : NaN;
+    const timeoutMs = Number.isFinite(parsedTimeout) && parsedTimeout >= 1 ? parsedTimeout : DEFAULT_GUARDIAN_LIMITS.timeoutMs;
+    return { ...DEFAULT_GUARDIAN_LIMITS, maxReviews, timeoutMs };
+}
+/**
+ * Derive the client's whole-consult deadline from the backend's advertised
+ * wall ceiling and attempt count (YAG-562). Falls back to the resolved limit
+ * when the catalog omitted the fields (older backend).
+ */
+export function deriveGuardianTimeoutMs(base, advertised) {
+    if (advertised.timeoutMs !== undefined && advertised.maxAttempts !== undefined) {
+        return advertised.timeoutMs * advertised.maxAttempts + GUARDIAN_CLIENT_OVERHEAD_MS;
+    }
+    return base.timeoutMs;
 }
 /** The model tier the Guardian runs on. Configurable via YAGNI_GUARDIAN_TIER. */
 export const GUARDIAN_MODEL_TIER = "efficient";
@@ -190,7 +214,19 @@ export async function reviewCommand(command, deps) {
         if (deps.signal?.aborted) {
             return { verdict: null, error: "aborted", cost };
         }
+        // The backend now owns the timeout (YAG-562) and streams a terminal error
+        // frame when the consult fails; a result with a `stopReason: "error"` or an
+        // `errorMessage` is a real backend failure, NOT the silent-empty shape. Map
+        // it to a concrete error so the gate shows "review timed out" / "service
+        // unavailable" instead of the misleading "no response". A timeout-shaped
+        // message (stream_idle_timeout / "timed out") is distinguished so the gate
+        // can add its timeout-specific note.
         if (!output) {
+            if (result.stopReason === "error" || result.errorMessage) {
+                const msg = (result.errorMessage ?? "").toLowerCase();
+                const isTimeout = /stream_idle_timeout|timed out|idle|wall|timeout/i.test(msg);
+                return { verdict: null, error: isTimeout ? "timeout" : "network", cost };
+            }
             return { verdict: null, error: "empty", cost };
         }
         const verdict = parseVerdict(output);

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