@pugi/cli 0.1.0-beta.18 → 0.1.0-beta.19

package/dist/core/engine/tool-bridge.js

@@ -9,7 +9,9 @@ import { webSearchTool } from '../../tools/web-search.js';
 import { agentTool } from '../../tools/agent-tool.js';
 import { multiEdit } from '../../tools/multi-edit.js';
 import { buildMcpToolDefs, defaultNonInteractiveMcpPrompt, dispatchMcpTool, MCP_TOOL_PREFIX, } from '../../tools/mcp-tool.js';
+import { buildDenialContext, DENIAL_REMINDER_THRESHOLD, } from '../denial-tracking/state.js';
 import { stripInternalFields } from './strip-internal-fields.js';
+import { applyAskAnswer, gate as permissionGate, getToolClass, PermissionDenied, } from '../permissions/index.js';
 /**
  * Tool-bridge: turns the abstract tool registry into:
  *   1. An OpenAI-shaped tools schema for `EngineLoopClient.send`.
@@ -433,6 +435,26 @@ export function buildToolsSchema(kind, options = { allowFetch: false, allowSearc
         parameters: stripInternalFields(tool.parameters),
     }));
 }
+/**
+ * α7 L11: tolerant args-parse for the denial fingerprint. Unlike
+ * `parseArgs` (which throws on malformed JSON so the model sees a
+ * parse error), this swallows failures and returns `{}` — the denial
+ * tracker needs SOME key even when the raw payload is unparseable,
+ * because malformed-args spam is itself a pattern operators want to
+ * see in `/permissions denials`.
+ */
+function safeParseForTracking(raw) {
+    if (!raw || raw.trim() === '')
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // Use the raw string as the fingerprint payload so repeated
+        // identical malformed dispatches still cluster.
+        return { _rawArgs: raw.slice(0, 512) };
+    }
+}
 function parseArgs(raw) {
     if (!raw || raw.trim() === '')
         return {};
@@ -469,10 +491,48 @@ function requireString(obj, key) {
     throw new Error(`tool argument "${key}" must be a string`);
 }
 export function buildExecutor(input) {
-    const { kind, ctx, hooks, sessionId, askUserBridge, interactive, allowFetch, allowSearch, agentDispatch, mcpRegistry } = input;
+    const { kind, ctx, hooks, sessionId, askUserBridge, interactive, allowFetch, allowSearch, agentDispatch, mcpRegistry, permissionMode, permissionAlwaysCache, permissionAsk, } = input;
     const mcpPrompt = input.mcpPrompt ?? defaultNonInteractiveMcpPrompt;
     const workspaceRoot = input.workspaceRoot ?? ctx.root;
     const planMode = kind === 'plan';
+    const denialTracking = input.denialTracking;
+    // α7 L11: helper that records a denial (when tracking is wired) and
+    // ALWAYS returns an Error whose message includes a compact
+    // `<denial-context>` reminder when the same (tool, args) pair has
+    // already been refused at least once before in this session.
+    //
+    // The reminder is appended to the THROWN message — the engine loop
+    // appends thrown messages to the transcript as tool-result strings,
+    // so the model sees the aggregate the next time it considers a
+    // dispatch. Without this every retry would only see the latest
+    // single-turn reason and could loop indefinitely.
+    //
+    // Best-effort: a hash/clone failure inside the tracker MUST NOT
+    // mask the original refusal. The catch path falls back to a bare
+    // Error with the reason text.
+    const recordDenial = (toolName, args, reason) => {
+        if (!denialTracking)
+            return new Error(reason);
+        try {
+            const record = denialTracking.recordDenial(toolName, args, reason);
+            // Only inject the reminder once the threshold is hit — the very
+            // first denial is the model's first chance to learn, no need to
+            // shout. From the 2nd repeat onwards the model has demonstrated
+            // it is not learning from the single-turn sentinel, so we splice
+            // the aggregate context.
+            if (record.count >= DENIAL_REMINDER_THRESHOLD) {
+                const reminder = buildDenialContext(denialTracking);
+                if (reminder.length > 0) {
+                    return new Error(`${reason}\n\n${reminder}`);
+                }
+            }
+        }
+        catch {
+            // Tracking is best-effort. Fall through to the bare Error so
+            // the refusal still propagates.
+        }
+        return new Error(reason);
+    };
     return async ({ name, arguments: argsRaw }) => {
         // β4 M1/M3: MCP tool names live outside WIRED_TOOLS. They are
         // validated lazily by the dispatcher (the registry knows which
@@ -480,15 +540,64 @@ export function buildExecutor(input) {
         // so a bad `mcp__bogus__foo` does not collide with the native
         // unknown-tool branch.
         const isMcpName = name.startsWith(MCP_TOOL_PREFIX);
+        // α7 L11: parse-or-empty args once up-front so every deny path
+        // below can fingerprint the call against the denial tracker. We
+        // tolerate parse failure — `{}` keys still produce a stable hash
+        // (the model may have sent malformed JSON, but the refusal is
+        // semantic, not parse-driven).
+        const argsForTracking = safeParseForTracking(argsRaw);
         if (!isMcpName && !WIRED_TOOLS.has(name)) {
-            throw new Error(`unknown tool: ${name}`);
+            throw recordDenial(name, argsForTracking, `unknown tool: ${name}`);
         }
-        if (planMode) {
+        // Leak L6 — canonical 4-mode permission gate. Routes the dispatch
+        // decision BEFORE the legacy plan-mode-only enforcement so the new
+        // surface is the source of truth when the caller opted in. Absent
+        // `permissionMode` falls through to the legacy plan-mode branch
+        // (existing semantics preserved for callsites that have not
+        // migrated yet).
+        let hooksBypassed = false;
+        if (permissionMode) {
+            const decision = permissionGate(name, argsRaw, {
+                permissionMode,
+                ...(permissionAlwaysCache ? { alwaysCache: permissionAlwaysCache } : {}),
+            });
+            if (decision.decision === 'deny') {
+                throw new PermissionDenied(name, getToolClass(name), permissionMode, decision.reason);
+            }
+            if (decision.decision === 'ask') {
+                if (!permissionAsk) {
+                    // Non-interactive caller (CI / pipes / agent-as-tool) cannot
+                    // surface a prompt. Collapse to deny so the loop receives a
+                    // deterministic refusal instead of hanging.
+                    throw new PermissionDenied(name, decision.toolClass, permissionMode, `Ask mode: no operator prompt available for ${name} (non-interactive caller)`);
+                }
+                const answer = await permissionAsk({
+                    toolName: name,
+                    toolClass: decision.toolClass,
+                    question: decision.question,
+                    options: decision.options,
+                });
+                const verdict = permissionAlwaysCache
+                    ? applyAskAnswer(permissionAlwaysCache, name, answer)
+                    : applyAskAnswer({ alwaysAllowed: new Set(), alwaysDenied: new Set() }, name, answer);
+                if (verdict.decision === 'deny') {
+                    throw new PermissionDenied(name, decision.toolClass, permissionMode, verdict.reason);
+                }
+                // verdict.decision === 'allow' falls through to dispatch.
+            }
+            else {
+                // allow — honour the bypass flag for the hook layer below.
+                hooksBypassed = decision.hooksBypassed === true;
+            }
+        }
+        else if (planMode) {
+            // Legacy plan-mode enforcement (kind === 'plan') stays in place
+            // for callers that have not opted into the canonical gate.
             // MCP tools are uniformly refused in plan mode (see schema-side
             // rationale in buildToolsSchema). Native tools split via
             // READ_ONLY_TOOLS as before.
             if (isMcpName || !READ_ONLY_TOOLS.has(name)) {
-                throw new Error(`PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
+                throw recordDenial(name, argsForTracking, `PLAN_MODE_REFUSED: ${name} is not allowed in plan mode`);
             }
         }
         // α6.9: refuse cancelled-token tool dispatch BEFORE PreToolUse
@@ -497,13 +606,18 @@ export function buildExecutor(input) {
         // by `runEngineLoop` as a terminal-cancel signal so the loop
         // returns control to the caller rather than retrying the model.
         if (ctx.cancellation && ctx.cancellation.isAborted) {
-            throw new Error(`OPERATOR_ABORTED: ${name} refused — operator cancelled the dispatch.`);
+            throw recordDenial(name, argsForTracking, `OPERATOR_ABORTED: ${name} refused — operator cancelled the dispatch.`);
         }
         // Fire PreToolUse hooks. The match grammar takes the tool name and
         // (when extractable) the target path. Each new tool dispatch starts a
         // fresh dedup batch so a hook fires once per dispatch, not once per
         // session.
-        if (hooks && sessionId) {
+        //
+        // Leak L6 — bypass mode skips the entire hook layer (PreToolUse +
+        // PostToolUse + PostToolUseFailure). The gate's allow decision
+        // carries the `hooksBypassed` flag; we honour it here so the
+        // executor stays single-pass.
+        if (hooks && sessionId && !hooksBypassed) {
             hooks.resetBatch();
             const path = extractToolPath(name, argsRaw);
             const preCtx = {
@@ -523,7 +637,11 @@ export function buildExecutor(input) {
                 const hook = matchingPreHooks[i];
                 const result = preResults[i];
                 if (hook && result && hook.onFailure === 'block' && !result.ok) {
-                    throw new Error(`HOOK_BLOCKED: PreToolUse hook (${hook.run.slice(0, 80)}) refused ${name} (exit=${result.exitCode})`);
+                    // α7 L11: record the PreToolUse hook denial so the model
+                    // sees the pattern reminder on subsequent turns. Without
+                    // this the model would re-issue the same refused call and
+                    // burn a turn each time before noticing the loop.
+                    throw recordDenial(name, argsForTracking, `HOOK_BLOCKED: PreToolUse hook (${hook.run.slice(0, 80)}) refused ${name} (exit=${result.exitCode})`);
                 }
             }
         }
@@ -580,7 +698,7 @@ export function buildExecutor(input) {
                 // model spawn a write-capable child and break the read-only
                 // contract.
                 if (planMode) {
-                    throw new Error('PLAN_MODE_REFUSED: agent is not allowed in plan mode');
+                    throw recordDenial(name, argsForTracking, 'PLAN_MODE_REFUSED: agent is not allowed in plan mode');
                 }
                 return dispatchAgent(args, agentDispatch);
             }
@@ -588,7 +706,7 @@ export function buildExecutor(input) {
         };
         try {
             const result = await dispatch();
-            if (hooks && sessionId) {
+            if (hooks && sessionId && !hooksBypassed) {
                 const path = extractToolPath(name, argsRaw);
                 await hooks.fire({
                     sessionId,
@@ -601,6 +719,27 @@ export function buildExecutor(input) {
             return result;
         }
         catch (error) {
+            // Leak L6 — surface the PermissionDenied sentinel as a model-
+            // readable message instead of leaking the raw Error type. The
+            // string format is stable so the engine adapter / spec layer
+            // can pattern-match against it.
+            if (error instanceof PermissionDenied) {
+                // PostToolUseFailure fires for visibility unless bypass is on.
+                if (hooks && sessionId && !hooksBypassed) {
+                    await hooks.fire({
+                        sessionId,
+                        event: 'PostToolUseFailure',
+                        tool: name,
+                        payload: {
+                            tool: name,
+                            arguments: argsRaw,
+                            ok: false,
+                            error: error.toModelMessage(),
+                        },
+                    });
+                }
+                throw new Error(error.toModelMessage());
+            }
             // α6.9: re-shape OperatorAbortedError throws from the
             // file-tools layer into the same `OPERATOR_ABORTED:` sentinel
             // the upstream cancellation gate uses so `runEngineLoop` sees
@@ -608,7 +747,7 @@ export function buildExecutor(input) {
             // the abort landed pre-dispatch or mid-tool (e.g. inside the
             // grep file-loop).
             if (error instanceof OperatorAbortedError) {
-                if (hooks && sessionId) {
+                if (hooks && sessionId && !hooksBypassed) {
                     const path = extractToolPath(name, argsRaw);
                     await hooks.fire({
                         sessionId,
@@ -623,7 +762,7 @@ export function buildExecutor(input) {
                         },
                     });
                 }
-                throw new Error(`OPERATOR_ABORTED: ${name} aborted mid-execution.`);
+                throw recordDenial(name, argsForTracking, `OPERATOR_ABORTED: ${name} aborted mid-execution.`);
             }
             // Leak L1 (2026-05-27): re-shape StaleReadError into a
             // deterministic STALE_READ:<reason> sentinel so the model's
@@ -634,7 +773,7 @@ export function buildExecutor(input) {
             // operator can build a "warn me when stale edits keep happening"
             // hook (likely a concurrency / multi-agent indicator).
             if (error instanceof StaleReadError) {
-                if (hooks && sessionId) {
+                if (hooks && sessionId && !hooksBypassed) {
                     const path = extractToolPath(name, argsRaw);
                     await hooks.fire({
                         sessionId,
@@ -649,9 +788,9 @@ export function buildExecutor(input) {
                         },
                     });
                 }
-                throw new Error(`STALE_READ: ${name} on ${error.path} refused (${error.reason}). Re-read the file with the \`read\` tool, then retry the ${name}.`);
+                throw recordDenial(name, argsForTracking, `STALE_READ: ${name} on ${error.path} refused (${error.reason}). Re-read the file with the \`read\` tool, then retry the ${name}.`);
             }
-            if (hooks && sessionId) {
+            if (hooks && sessionId && !hooksBypassed) {
                 const path = extractToolPath(name, argsRaw);
                 await hooks.fire({
                     sessionId,

package/dist/core/permissions/gate.js

@@ -0,0 +1,187 @@
+/**
+ * Permission gate — Leak L6 canonical 4-mode enforcement.
+ *
+ * Single dispatch entry point. Every tool call goes through `gate()`
+ * before the executor runs the tool body; the executor surfaces the
+ * `PermissionDenied` error as a model-readable sentinel so the model
+ * can either reformulate the request or wait for the operator to
+ * change the mode.
+ *
+ * Routing matrix (mode × class):
+ *
+ *                 |  read  | write  | dispatch
+ *   plan          |  allow |  deny  |  deny
+ *   ask           |  ask   |  ask   |  ask
+ *   allow         |  allow |  allow |  allow
+ *   bypass        |  allow |  allow |  allow   (plus: hooks bypassed)
+ *
+ * In ask mode the gate consults a session-scoped `always-allow` cache
+ * keyed by tool name (set when the operator picks "always-allow-tool"
+ * in the prompt). The cache is in-memory only — restarting the session
+ * resets it, by design (every-session-fresh ask consent).
+ *
+ * Bypass mode does NOT take a different code path in this module — the
+ * `hooksBypassed` flag in the decision payload signals the executor /
+ * hook layer to skip policy hooks. The classification logic is the
+ * same as `allow` because the gate doesn't own hook execution; the
+ * caller decides what to do with the bypass signal.
+ */
+import { getToolClass } from './tool-class.js';
+export const ASK_OPTIONS = Object.freeze([
+    'allow-once',
+    'always-this-tool',
+    'deny-once',
+    'always-deny-this-tool',
+]);
+export function createAskAlwaysCache() {
+    return {
+        alwaysAllowed: new Set(),
+        alwaysDenied: new Set(),
+    };
+}
+/**
+ * Apply the operator's answer to an `ask` decision. Caller invokes this
+ * after the operator picks an option so the cache stays in sync.
+ * Returns the effective decision: `allow-once` / `always-this-tool`
+ * become `allow`; `deny-once` / `always-deny-this-tool` become `deny`.
+ *
+ * `always-*` answers persist to the cache and short-circuit the next
+ * gate call for the same tool name within the same session.
+ */
+export function applyAskAnswer(cache, toolName, answer) {
+    switch (answer) {
+        case 'allow-once':
+            return { decision: 'allow', reason: `Allowed once for ${toolName}` };
+        case 'always-this-tool':
+            cache.alwaysAllowed.add(toolName);
+            cache.alwaysDenied.delete(toolName);
+            return { decision: 'allow', reason: `Allowed for ${toolName} this session` };
+        case 'deny-once':
+            return { decision: 'deny', reason: `Denied once for ${toolName}` };
+        case 'always-deny-this-tool':
+            cache.alwaysDenied.add(toolName);
+            cache.alwaysAllowed.delete(toolName);
+            return { decision: 'deny', reason: `Denied for ${toolName} this session` };
+    }
+}
+/**
+ * Permission-denied sentinel. Distinguishable from other tool errors
+ * (parse errors, IO failures) so the caller can route the message back
+ * to the model with the canonical recovery hint.
+ */
+export class PermissionDenied extends Error {
+    name = 'PermissionDenied';
+    mode;
+    toolName;
+    toolClass;
+    /**
+     * Human-friendly reason surfaced in logs / hook payloads. Distinct
+     * from `message` so the spec layer can pattern-match the canonical
+     * `PERMISSION_DENIED:` sentinel verbatim while operators see the
+     * full explanation in console output.
+     */
+    reason;
+    constructor(toolName, toolClass, mode, reason) {
+        // The base Error.message is the canonical sentinel so default
+        // toString() / re-throw paths preserve the format the model and
+        // the spec layer pattern-match against.
+        super(`PERMISSION_DENIED: ${toolName} blocked in ${mode} mode. Operator can switch with /permissions <mode>.`);
+        this.mode = mode;
+        this.toolName = toolName;
+        this.toolClass = toolClass;
+        this.reason = reason;
+    }
+    /**
+     * Render the sentinel message the executor surfaces to the model.
+     * The string format is stable so a parent agent / E2E spec can
+     * pattern-match `PERMISSION_DENIED: <tool> blocked in <mode> mode.`
+     * verbatim. Equivalent to `this.message`; kept as a method so
+     * downstream callers can use whichever spelling reads better at the
+     * site.
+     */
+    toModelMessage() {
+        return this.message;
+    }
+}
+/**
+ * Core dispatch gate. Pure function — no IO, no side effects beyond
+ * mutating the caller-supplied `alwaysCache`. Safe to call from any
+ * layer (engine adapter, agent-as-tool bridge, doctor command).
+ *
+ * Argument bag mirrors the executor entry shape:
+ *   - `toolName` is the registered tool key (e.g. `read`, `write`,
+ *     `mcp__github__list_issues`).
+ *   - `args` is the raw arg payload. Currently unused in the routing
+ *     decision — the matrix only cares about class. Plumbed in
+ *     because future "always-allow-this-pattern" rules (e.g.
+ *     `git status` auto-allow) will consume it without changing the
+ *     callsite contract.
+ *   - `ctx` carries mode + session-scoped state.
+ */
+export function gate(toolName, 
+// Reserved for future pattern-based rules (always-allow `git status`).
+// Suppress unused-argument lint — the contract is stable on purpose.
+_args, ctx) {
+    const toolClass = getToolClass(toolName);
+    const cache = ctx.alwaysCache;
+    // Ask-mode session memory: an explicit "always-deny" beats any other
+    // routing because the operator has actively refused this tool.
+    if (cache?.alwaysDenied.has(toolName)) {
+        return {
+            decision: 'deny',
+            reason: `Tool ${toolName} denied for the session via /permissions ask`,
+        };
+    }
+    // "Always-allow" in ask mode skips the prompt for subsequent calls.
+    // Plan mode IGNORES the always-allow cache because plan mode's
+    // contract is structural (read-only), not consent-based.
+    if (cache?.alwaysAllowed.has(toolName) && ctx.permissionMode === 'ask') {
+        return {
+            decision: 'allow',
+            reason: `Tool ${toolName} always-allowed for this session`,
+        };
+    }
+    switch (ctx.permissionMode) {
+        case 'plan': {
+            if (toolClass === 'read') {
+                return { decision: 'allow', reason: `Plan mode: read tools allowed (${toolName})` };
+            }
+            return {
+                decision: 'deny',
+                reason: `Plan mode: ${toolClass} tools blocked. Switch with /permissions allow.`,
+            };
+        }
+        case 'ask': {
+            return {
+                decision: 'ask',
+                reason: `Ask mode: prompt before ${toolName}`,
+                question: buildAskQuestion(toolName, toolClass, ctx.target),
+                options: ASK_OPTIONS,
+                toolClass,
+            };
+        }
+        case 'allow': {
+            return {
+                decision: 'allow',
+                reason: `Allow mode: ${toolName} executed`,
+            };
+        }
+        case 'bypass': {
+            return {
+                decision: 'allow',
+                reason: `Bypass mode: ${toolName} executed (policy hooks skipped)`,
+                hooksBypassed: true,
+            };
+        }
+    }
+}
+/**
+ * Build the operator-facing question string for an ask-mode prompt.
+ * Kept in one place so the wording stays consistent across the REPL
+ * Ink modal and the simpler stdin fallback.
+ */
+function buildAskQuestion(toolName, toolClass, target) {
+    const suffix = target ? ` on ${target}` : '';
+    return `Allow ${toolName} (${toolClass})${suffix}?`;
+}
+//# sourceMappingURL=gate.js.map

package/dist/core/permissions/index.js

@@ -0,0 +1,18 @@
+/**
+ * Permission gate (Leak L6) public surface.
+ *
+ * Re-exports the canonical 4-mode types, the tool-class classifier,
+ * the dispatch gate, and the workspace + global session-state helpers
+ * so callers import from one place:
+ *
+ *   import { gate, resolveMode, PermissionDenied } from '<...>/permissions/index.js';
+ *
+ * Keeps the internal file split (mode / tool-class / gate / state)
+ * invisible to consumers — those files are an implementation detail
+ * the engine adapter does not need to know about.
+ */
+export { DEFAULT_PERMISSION_MODE, PERMISSION_MODE_GLOSS, PERMISSION_MODES, isPermissionMode, parsePermissionMode, toLegacyMode, } from './mode.js';
+export { getToolClass, listBuiltInToolClasses, } from './tool-class.js';
+export { ASK_OPTIONS, PermissionDenied, applyAskAnswer, createAskAlwaysCache, gate, } from './gate.js';
+export { getCurrentMode, getGlobalDefaultMode, globalConfigPath, resolveMode, sessionStatePath, setCurrentMode, setGlobalDefaultMode, } from './state.js';
+//# sourceMappingURL=index.js.map

package/dist/core/permissions/mode.js

@@ -0,0 +1,102 @@
+/**
+ * Permission modes — canonical 4-mode taxonomy (Leak L6).
+ *
+ * Pugi historically shipped a 6-mode taxonomy in `@pugi/sdk`
+ * (`plan | ask | acceptEdits | auto | dontAsk | bypassPermissions`)
+ * which the legacy `core/permission.ts` engine maps tools onto. Claude
+ * Code, Codex, and the openclaude / openwork leaks all converge on a
+ * smaller, sharper 4-mode set:
+ *
+ *   - `plan`    — read-only proposal mode. Write/dispatch tools refused
+ *                 with a deterministic sentinel; the model is expected
+ *                 to surface a plan, not execute it.
+ *   - `ask`     — every tool execution prompts the operator. Default
+ *                 mode for new operators; the safe ground state.
+ *   - `allow`   — every tool executes without per-call prompts, BUT
+ *                 the policy hook layer (skill-steering, denial audit,
+ *                 destructive deny-list) still fires.
+ *   - `bypass`  — same as allow but ALSO skips policy hooks. Power-user
+ *                 mode for trusted scripted runs; surface a banner on
+ *                 entry so an operator who flips here by accident sees
+ *                 they have disengaged the audit layer.
+ *
+ * This module owns the union type, the canonical default, and the
+ * mode-resolution helper. The runtime gate (`gate.ts`) consumes it; the
+ * legacy 6-mode SDK enum remains the system-of-record for bash-class
+ * decisions inside `core/permission.ts` — the canonical 4-mode layer
+ * sits in front and short-circuits the dispatch decision before bash
+ * classification ever runs.
+ */
+/**
+ * Closed list — useful for input validation and slash-command help.
+ */
+export const PERMISSION_MODES = Object.freeze([
+    'plan',
+    'ask',
+    'allow',
+    'bypass',
+]);
+/**
+ * Default mode applied when no `--mode` flag, no per-workspace session
+ * state, and no `defaultPermissionMode` in `~/.pugi/config.json`. We
+ * default cautious (`ask`) — an operator who has not configured anything
+ * is treated as a new operator who deserves visibility into every tool
+ * call.
+ */
+export const DEFAULT_PERMISSION_MODE = 'ask';
+/**
+ * Type guard for arbitrary string input (CLI flag, session.json
+ * deserialization). Returns false for casing variants — caller is
+ * expected to lowercase before testing.
+ */
+export function isPermissionMode(value) {
+    return typeof value === 'string' && PERMISSION_MODES.includes(value);
+}
+/**
+ * Parse + validate a mode string. Returns null for invalid input so the
+ * caller can surface a typed error (`unknown mode: <value>`) instead of
+ * throwing from a parse helper.
+ */
+export function parsePermissionMode(value) {
+    const lower = value.trim().toLowerCase();
+    return isPermissionMode(lower) ? lower : null;
+}
+/**
+ * Map the canonical 4-mode taxonomy to the legacy 6-mode SDK enum used
+ * by `core/permission.ts::evaluateBashPermission` and friends. The map
+ * is intentionally surjective on a narrower target — the canonical
+ * layer is the new public contract, the legacy layer is plumbing.
+ *
+ *   plan   -> 'plan'              (read-only)
+ *   ask    -> 'ask'               (prompt every action)
+ *   allow  -> 'auto'              (allow non-destructive; deny destructive)
+ *   bypass -> 'bypassPermissions' (allow everything except destructive override)
+ *
+ * Callers that need the legacy enum (existing bash classifier, settings
+ * persistence) should funnel through this helper so the mapping is in
+ * one place.
+ */
+export function toLegacyMode(mode) {
+    switch (mode) {
+        case 'plan':
+            return 'plan';
+        case 'ask':
+            return 'ask';
+        case 'allow':
+            return 'auto';
+        case 'bypass':
+            return 'bypassPermissions';
+    }
+}
+/**
+ * One-line human-readable summary surfaced by the `/permissions` table
+ * and `pugi --help` text. Kept inline so the strings stay localizable
+ * via a single edit point.
+ */
+export const PERMISSION_MODE_GLOSS = Object.freeze({
+    plan: 'Read-only — propose, never execute. Write + dispatch tools refused.',
+    ask: 'Prompt before every tool call. Default for new operators.',
+    allow: 'Execute tools without prompts. Policy hooks still fire.',
+    bypass: 'Execute tools without prompts AND skip policy hooks. Power-user only.',
+});
+//# sourceMappingURL=mode.js.map