@yagni-app/code 0.3.1 → 0.3.3

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;
         }
     }
@@ -612,6 +616,16 @@ function classifySegmentTokens(rawTokens, policy, opts) {
     }
     const { tokens: strippedTokens, stripped } = stripLeadingTokens(rawTokens);
     if (strippedTokens.length === 0) {
+        // env standalone: `env` or `env VAR=val` with no following command prints
+        // environment variables — a read-only operation. stripLeadingTokens removes
+        // `env` as a wrapper word, leaving empty tokens. Recognize this case instead
+        // of returning "empty command segment" (YAG-549).
+        if (!opts.forbiddenOnly && rawTokens.length > 0 && basenameToken(rawTokens[0]) === "env") {
+            const onlyEnvAndAssignments = rawTokens.every((t) => basenameToken(t) === "env" || ENV_ASSIGNMENT_RE.test(t));
+            if (onlyEnvAndAssignments) {
+                return { decision: "allow", justification: "print environment variables (read-only)" };
+            }
+        }
         return opts.forbiddenOnly
             ? { decision: "allow", justification: "no forbidden match" }
             : { decision: "prompt", justification: "empty command segment" };
@@ -623,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);
@@ -636,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) {
@@ -894,6 +931,60 @@ export const DEFAULT_EXEC_POLICY = {
         { pattern: ["pnpm", "list"], decision: "allow", justification: "list installed packages" },
         { pattern: ["pnpm", "--version"], decision: "allow", justification: "check pnpm version" },
         { pattern: ["tsc", "--version"], decision: "allow", justification: "check typescript version" },
+        // --- allow: CLI tool reads (YAG-549, based on prod Guardian data) ---
+        // linear CLI — read subcommands; write subcommands (create/update/delete/start/pr/attach/comment) stay prompt
+        { pattern: ["linear", "issue", "comment", "list"], decision: "allow", justification: "list Linear issue comments (read-only)" },
+        {
+            pattern: ["linear", "issue"],
+            decision: "allow",
+            justification: "read Linear issue data",
+            unlessTokens: ["start", "create", "update", "delete", "pull-request", "pr", "attach", "comment"],
+        },
+        { pattern: ["linear", ["--help", "-h"]], decision: "allow", justification: "show Linear CLI help" },
+        { pattern: ["linear", ["--version", "-V"]], decision: "allow", justification: "show Linear CLI version" },
+        // gh api — REST GET (no params, no method override) and GraphQL queries (no mutation)
+        // gh api defaults to POST when -f/-F params are present, so params are disqualifying.
+        // GraphQL is always POST, but queries are reads; mutations/subscriptions are disqualifying.
+        {
+            pattern: ["gh", "api", "graphql"],
+            decision: "allow",
+            justification: "GraphQL query (read-only)",
+            unlessTokens: ["query=mutation*", "query=subscription*"],
+        },
+        {
+            pattern: ["gh", "api"],
+            decision: "allow",
+            justification: "GitHub API GET request (read-only)",
+            unlessTokens: ["--method", "-X", "-X*", "graphql", "POST", "PATCH", "DELETE", "PUT", "-f", "-F", "--raw-field", "--field"],
+        },
+        { pattern: ["gh", "release", ["list", "view"]], decision: "allow", justification: "read GitHub release data" },
+        { pattern: ["gh", "label", "list"], decision: "allow", justification: "list GitHub labels" },
+        { pattern: ["gh", "milestone", "list"], decision: "allow", justification: "list GitHub milestones" },
+        { pattern: ["gh", "auth", "status"], decision: "allow", justification: "show GitHub auth status" },
+        // git read-only subcommands
+        { pattern: ["git", "tag"], decision: "allow", justification: "list tags (read-only)" },
+        { pattern: ["git", "reflog"], decision: "allow", justification: "show reference log" },
+        { pattern: ["git", "ls-remote"], decision: "allow", justification: "list remote refs" },
+        { pattern: ["git", "cat-file"], decision: "allow", justification: "inspect git objects (read-only)" },
+        { pattern: ["git", "for-each-ref"], decision: "allow", justification: "enumerate refs (read-only)" },
+        { pattern: ["git", "rev-list"], decision: "allow", justification: "walk commit history (read-only)" },
+        { pattern: ["git", "show-ref"], decision: "allow", justification: "list all refs" },
+        { pattern: ["git", "name-rev"], decision: "allow", justification: "map commit to name (read-only)" },
+        { pattern: ["git", "merge-base"], decision: "allow", justification: "find common ancestor (read-only)" },
+        // package manager test/lint — routine dev-loop operations
+        { pattern: ["pnpm", "test"], decision: "allow", justification: "run tests (routine dev-loop operation)" },
+        { 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)" },
+        // 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" },
         // --- prompt: potentially destructive but context-dependent ---
         { pattern: ["rm"], decision: "prompt", justification: "file deletion — review the target" },
         { pattern: ["git", "commit"], decision: "prompt", justification: "creates a commit — confirm intent" },

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,12 +180,18 @@ 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";
 /** Legacy alias — the original plan-mode tag, kept for backward compat. */
 export declare const PLAN_CONTEXT_TYPE = "yagni-mode-context";
-export declare const PLAN_CONTEXT_MESSAGE = "[PLAN MODE ACTIVE]\nYou are in plan mode: explore and design, change nothing.\n- write, edit, and bash are held by the permission gate; do not attempt them.\n- Read, search, and ask_yagni freely to ground the plan in how this company works.\n- Produce a concrete numbered plan of the steps you would take, with the files involved.\n- End by asking the user to review the plan; they run /mode auto (or /mode review) to execute it.\n- Once executing, track the plan's steps with todo_write.";
+export declare const PLAN_CONTEXT_MESSAGE = "[PLAN MODE ACTIVE]\nYou are in plan mode: explore and design, change nothing.\n- Read-only bash commands (ls, grep, git status, gh pr view, etc.) run freely to help you explore.\n- Ambiguous bash commands are reviewed by the Guardian; if non-mutating they run, if potentially mutating you will be asked.\n- write, edit, file_ticket, and update_ticket_status are held by the permission gate; do not attempt them.\n- Read, search, and ask_yagni freely to ground the plan in how this company works.\n- Produce a concrete numbered plan of the steps you would take, with the files involved.\n- End by asking the user to review the plan; they run /mode auto (or /mode review) to execute it.\n- Once executing, track the plan's steps with todo_write.";
 /** Build the mode-awareness context message for the current permission mode. */
 export declare function buildModeContextMessage(mode: PermissionMode): string;
 /**
@@ -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;
@@ -56,6 +56,42 @@ export const DEFAULT_PERMISSION_POLICY = {
  */
 export function decideGate(toolName, params, mode, policy) {
     if (mode === "plan") {
+        // Non-bash tools in planBlockTools are held outright — they are
+        // inherently mutating (write, edit, file_ticket, update_ticket_status).
+        // Bash is the exploration tool: run it through the exec policy so
+        // read-only commands (git status, ls, grep, gh pr view) work, and
+        // prompt-band commands are routed to the Guardian. The gate handler
+        // ensures Guardian-unavailable/capped/disabled states fail closed.
+        if (toolName === "bash") {
+            const command = typeof params.command === "string" ? params.command.trim() : "";
+            if (command) {
+                try {
+                    const execPolicy = policy.execPolicy ?? DEFAULT_EXEC_POLICY;
+                    const classification = classifyCommand(command, execPolicy);
+                    if (classification.decision === "allow")
+                        return { block: false };
+                    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.`,
+                        };
+                    }
+                    // prompt — Guardian reviews. The gate handler runs the Guardian
+                    // and handles allow/ask/deny. Grants and cache are skipped in
+                    // plan mode (they can cover writes). Guardian unavailable/capped/
+                    // disabled → block (fail closed).
+                    return { block: false, classify: "prompt", classifyJustification: classification.justification };
+                }
+                catch {
+                    // classifyCommand threw — fail closed in plan mode.
+                    return {
+                        block: true,
+                        reason: `plan mode: could not classify this bash command and it is held. Switch to /mode auto to apply changes.`,
+                    };
+                }
+            }
+            return { block: false };
+        }
         if (policy.planBlockTools.includes(toolName)) {
             return {
                 block: true,
@@ -122,7 +158,9 @@ const AUTO_MARKER = "[AUTO MODE]";
 const REVIEW_MARKER = "[REVIEW MODE]";
 export const PLAN_CONTEXT_MESSAGE = `${PLAN_MARKER}
 You are in plan mode: explore and design, change nothing.
-- write, edit, and bash are held by the permission gate; do not attempt them.
+- Read-only bash commands (ls, grep, git status, gh pr view, etc.) run freely to help you explore.
+- Ambiguous bash commands are reviewed by the Guardian; if non-mutating they run, if potentially mutating you will be asked.
+- write, edit, file_ticket, and update_ticket_status are held by the permission gate; do not attempt them.
 - Read, search, and ask_yagni freely to ground the plan in how this company works.
 - Produce a concrete numbered plan of the steps you would take, with the files involved.
 - End by asking the user to review the plan; they run /mode auto (or /mode review) to execute it.
@@ -258,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();
@@ -384,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/
@@ -414,7 +494,9 @@ export function registerPermissionGate(pi, deps = {}) {
                     }
                 }
                 // 2. Session exact-command approval cache (ticket 4.5).
-                if (command && approvedCommands.has(cacheKey(cwd, command))) {
+                // Skipped in plan mode: a cached approval can cover a write command,
+                // and plan mode's contract is no mutations without Guardian review.
+                if (modeAtEntry !== "plan" && command && approvedCommands.has(cacheKey(cwd, command))) {
                     emitGateEvent({ ...eventBase, outcome: "cached_allow", consulted: false });
                     return {};
                 }
@@ -423,13 +505,13 @@ export function registerPermissionGate(pi, deps = {}) {
                 if (guardianAvailable && guardianState.read().reviews >= limits.maxReviews) {
                     // Sliding-window consult cap (capacity recovers as old reviews age
                     // out — a long-lived session is never bricked). Review mode falls
-                    // through to its ordinary confirm (no LLM cost); auto blocks.
-                    if (modeAtEntry === "auto") {
+                    // through to its ordinary confirm (no LLM cost); auto and plan block.
+                    if (modeAtEntry === "auto" || modeAtEntry === "plan") {
                         if (ctx?.hasUI)
                             ctx.ui.notify(`Guardian review cap reached (${limits.maxReviews} in the last hour).`, "warning");
                         return { block: true, reason: `Guardian review cap reached (${limits.maxReviews} in the last hour). Capacity recovers as older reviews age out; switch to /mode review to approve manually, or retry this step later.` };
                     }
-                    // fall through to decision.confirm below
+                    // review mode: fall through to decision.confirm below
                 }
                 else if (guardianAvailable) {
                     // Circuit breaker (pre-consult). With a UI, escalate to ONE ask per
@@ -547,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));
@@ -675,9 +792,39 @@ export function registerPermissionGate(pi, deps = {}) {
                     // approval cache were already consulted above.
                     return {};
                 }
+                else if (modeAtEntry === "plan") {
+                    // Guardian disabled or not wired in plan mode: fail closed. Without
+                    // the Guardian to verify the command is non-mutating, the plan-mode
+                    // contract (no changes) cannot be upheld. The user can switch to
+                    // /mode auto or /mode review to proceed.
+                    emitGateEvent({ ...eventBase, outcome: "breaker_blocked", consulted: false });
+                    return { block: true, reason: "Guardian unavailable in plan mode. Switch to /mode auto to run commands, or /mode review to approve manually." };
+                }
                 // 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
@@ -784,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