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

package/dist/core/file-cache.js

@@ -1,6 +1,45 @@
+/**
+ * Per-session file-read cache + stale-read gate.
+ *
+ * Leak intel L1 (openclaude `FileEditTool.ts`, 2026-05-27 gap analysis
+ * §5.1): every FileEdit must validate the operator's last-known view of
+ * the file before mutating disk. The gate compares BOTH `mtimeMs` and
+ * `sha256(content)` of the file on disk against the record captured at
+ * read time:
+ *
+ *   - mtimeMs is a cheap fast-path. If the inode mtime hasn't moved
+ *     since the read, the content hash cannot have changed (barring a
+ *     filesystem with hash-on-mtime-skew bugs) and we can short-circuit.
+ *   - sha256 is the authoritative gate. A user editor that writes back
+ *     identical content can leave mtime untouched on some filesystems
+ *     (atomic-rename with preserved metadata), and conversely `touch`
+ *     bumps mtime without changing content. Hash is the truth.
+ *
+ * Both signals must agree for the gate to PASS. Any divergence => STALE
+ * => refuse the edit, force the model to re-read.
+ *
+ * Cache lifetime: per-session. `FileReadCache.clear()` is called at
+ * session.end (see `core/session.ts`). The cache is intentionally NOT
+ * durable across sessions — a re-read after restart is cheap and stale
+ * cross-session entries would themselves be a soundness hazard.
+ *
+ * Exception: writeTool for create-new (path doesn't exist on disk) does
+ * not consult the cache. Creating a brand new file has no "last-known
+ * view" to invalidate.
+ */
 import { createHash } from 'node:crypto';
-import { statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { resolve } from 'node:path';
+export class StaleReadError extends Error {
+    reason;
+    path;
+    constructor(path, reason, detail) {
+        super(`stale_read: ${path} — ${detail}. Re-read the file before editing.`);
+        this.name = 'StaleReadError';
+        this.reason = reason;
+        this.path = path;
+    }
+}
 export class FileReadCache {
     records = new Map();
     set(record) {
@@ -9,6 +48,70 @@ export class FileReadCache {
     get(root, path) {
         return this.records.get(resolve(root, path));
     }
+    /**
+     * Validate a candidate edit against the cached read record. Returns
+     * a tagged-union: `{ stale: false }` when the edit may proceed, or
+     * `{ stale: true, reason, detail }` when the gate must refuse.
+     *
+     * Pure function over the cache + supplied `currentMtimeMs` /
+     * `currentContent` — does NOT touch disk. Callers (editTool /
+     * writeTool) do their own `statSync` + `readFileSync` because they
+     * also need the content for the diff/edit itself.
+     *
+     * @param root           workspace root (used to resolve relative path)
+     * @param path           workspace-relative file path
+     * @param currentMtimeMs `fs.statSync().mtimeMs` of the on-disk file
+     * @param currentContent UTF-8 contents of the on-disk file
+     */
+    validate(root, path, currentMtimeMs, currentContent) {
+        const record = this.get(root, path);
+        if (!record) {
+            return {
+                stale: true,
+                reason: 'no_prior_read',
+                detail: 'file must be read first',
+            };
+        }
+        // Fast-path: mtime hasn't moved. Hash check is redundant in the
+        // common case but cheap, so we still verify below. Skipping hash
+        // when mtime matches would allow a subtle bug class (in-place
+        // writers that preserve mtime) to slip through.
+        if (currentMtimeMs > record.mtimeMs) {
+            // mtime advanced — confirm with hash before flagging. A bump
+            // without a content change (e.g. `touch`) shouldn't fire stale.
+            const currentHash = hashContent(currentContent);
+            if (currentHash !== record.sha256) {
+                return {
+                    stale: true,
+                    reason: 'mtime_drift',
+                    detail: `mtime advanced (${record.mtimeMs} → ${currentMtimeMs}) and content hash diverged`,
+                };
+            }
+            // mtime bumped but content identical — treat as fresh. The cache
+            // entry's mtime is intentionally NOT refreshed here; the next
+            // edit will hit the same path and the gate will keep agreeing.
+            return { stale: false };
+        }
+        // mtime hasn't moved — hash MUST still match the record. A
+        // mismatch is a filesystem-level inconsistency or an in-place
+        // editor that preserves mtime; either way, refuse.
+        const currentHash = hashContent(currentContent);
+        if (currentHash !== record.sha256) {
+            return {
+                stale: true,
+                reason: 'hash_drift',
+                detail: 'content hash diverged from last read (mtime unchanged)',
+            };
+        }
+        return { stale: false };
+    }
+    /**
+     * Drop every cached record. Called by session.end so a fresh REPL
+     * session never inherits stale cross-session entries.
+     */
+    clear() {
+        this.records.clear();
+    }
 }
 export function hashContent(content) {
     return createHash('sha256').update(content).digest('hex');
@@ -26,4 +129,13 @@ export function createReadRecord(root, path, content, source) {
         source,
     };
 }
+/**
+ * Convenience helper: does this absolute path exist on disk? Wraps the
+ * existsSync import so file-tools.ts can decide between create-new
+ * (skip stale gate) and update-existing (apply stale gate) without
+ * pulling in another fs import.
+ */
+export function pathExists(absolutePath) {
+    return existsSync(absolutePath);
+}
 //# sourceMappingURL=file-cache.js.map

package/dist/core/mcp/client.js

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
 import { z } from 'zod';
 /**
  * Minimal JSON-RPC 2.0 over stdio MCP client for Pugi CLI M1.
@@ -79,6 +80,22 @@ export async function connect(serverName, config, options = {}) {
         env: { ...process.env, ...config.env },
         stdio: ['pipe', 'pipe', 'pipe'],
     });
+    // L13: optional stderr → log file. We open the stream lazily so a bad
+    // path surfaces synchronously to the caller instead of getting buried
+    // in the child's stderr handler. `mkdir -p` of the parent dir is the
+    // caller's responsibility (the registry does it once per session).
+    let logStream;
+    if (options.logFile) {
+        try {
+            logStream = createWriteStream(options.logFile, { flags: 'a' });
+        }
+        catch {
+            // Log directory missing or unwritable — degrade silently rather
+            // than refuse the handshake. The operator still gets the same
+            // surface they had pre-L13 (stderr dropped on the floor).
+            logStream = undefined;
+        }
+    }
     const connection = {
         serverName,
         child,
@@ -86,6 +103,8 @@ export async function connect(serverName, config, options = {}) {
         pending: new Map(),
         nextId: 1,
         closed: false,
+        ...(logStream ? { logStream } : {}),
+        startedAt: Date.now(),
     };
     // Attach the spawn-error handler BEFORE the reader: ENOENT and similar
     // are emitted asynchronously on the next tick, and without this
@@ -193,11 +212,25 @@ export async function callTool(connection, name, args, options = {}) {
  * SIGKILL if the child has not exited. Safe to call multiple times.
  */
 export async function disconnect(connection) {
-    if (connection.closed)
+    const closeLogStream = () => {
+        const stream = connection.logStream;
+        if (!stream)
+            return;
+        try {
+            stream.end();
+        }
+        catch {
+            // Best-effort — stream may already be destroyed.
+        }
+    };
+    if (connection.closed) {
+        closeLogStream();
         return;
+    }
     const { child } = connection;
     if (child.exitCode !== null || child.killed) {
         connection.closed = true;
+        closeLogStream();
         return;
     }
     return new Promise((resolveDone) => {
@@ -207,6 +240,7 @@ export async function disconnect(connection) {
                 return;
             settled = true;
             connection.closed = true;
+            closeLogStream();
             resolveDone();
         };
         child.once('exit', settle);
@@ -232,6 +266,22 @@ export async function disconnect(connection) {
         }, SHUTDOWN_GRACE_MS);
     });
 }
+/**
+ * L13: cheap liveness probe for `pugi mcp doctor`. True when the child
+ * process is still running AND the connection has not been torn down.
+ * Does NOT issue a JSON-RPC call — that would race with in-flight tool
+ * dispatch and the doctor surface is read-only.
+ */
+export function isAlive(connection) {
+    if (connection.closed)
+        return false;
+    const { child } = connection;
+    if (child.killed)
+        return false;
+    if (child.exitCode !== null)
+        return false;
+    return true;
+}
 function writeFrame(connection, message) {
     if (connection.closed) {
         throw new Error(`mcp server "${connection.serverName}" connection is closed`);
@@ -283,11 +333,21 @@ function attachReader(connection) {
             newlineIndex = buffer.indexOf('\n');
         }
     });
-    // stderr is captured but never thrown. Some MCP servers log diagnostics
-    // there even on success; we route it to nowhere so the CLI stdout stays
-    // pure JSON envelope output. A future iteration may forward this to the
-    // audit log.
-    connection.child.stderr.on('data', () => { });
+    // stderr is captured and (when `connect({ logFile })` was set) mirrored
+    // to a per-server log file under `.pugi/logs/`. Operators can tail the
+    // file via `pugi mcp logs <server>`. Default sink remains "drop on the
+    // floor" so the CLI stdout stays pure JSON envelope output.
+    connection.child.stderr.on('data', (chunk) => {
+        const stream = connection.logStream;
+        if (!stream || stream.destroyed)
+            return;
+        try {
+            stream.write(typeof chunk === 'string' ? chunk : chunk);
+        }
+        catch {
+            // Disk full / fd revoked — drop silently. Mirroring is best-effort.
+        }
+    });
 }
 function handleLine(connection, line) {
     let parsed;

package/dist/core/mcp/registry.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import { z } from 'zod';
@@ -38,6 +38,13 @@ import { getMcpTrust } from './trust.js';
 const mcpFileSchema = z.object({
     servers: z.record(mcpServerConfigSchema).default({}),
 });
+/**
+ * L13: workspace-relative path for per-server log files. Surfaces in
+ * `pugi mcp logs <name>` and is mkdir -p'd before the first connect.
+ */
+export function mcpLogPath(workspaceRoot, serverName) {
+    return resolve(workspaceRoot, '.pugi/logs', `mcp-${serverName}.log`);
+}
 /**
  * Load and (optionally) connect every approved MCP server defined in the
  * workspace + user configs. Pending and denied servers stay in the
@@ -45,6 +52,7 @@ const mcpFileSchema = z.object({
  */
 export async function loadMcpRegistry(workspaceRoot, options = {}) {
     const shouldConnect = options.connect !== false;
+    const handshakeTimeoutMs = options.handshakeTimeoutMs ?? 5_000;
     const userConfig = readMcpFile(resolve(userHomeDir(), 'mcp.json'));
     const workspaceConfig = readMcpFile(resolve(workspaceRoot, '.pugi/mcp.json'));
     const merged = new Map();
@@ -52,6 +60,17 @@ export async function loadMcpRegistry(workspaceRoot, options = {}) {
         merged.set(name, config);
     for (const [name, config] of Object.entries(workspaceConfig))
         merged.set(name, config);
+    // L13: ensure the log dir exists once per session so per-server log
+    // streams can `append` without each one having to mkdir -p.
+    if (shouldConnect && merged.size > 0) {
+        try {
+            mkdirSync(resolve(workspaceRoot, '.pugi/logs'), { recursive: true });
+        }
+        catch {
+            // Workspace may be read-only (CI sandbox). Log routing degrades
+            // silently in that case — see `client.ts::connect`.
+        }
+    }
     const servers = new Map();
     for (const [name, config] of merged) {
         const ledgerTrust = await getMcpTrust(name);
@@ -70,7 +89,10 @@ export async function loadMcpRegistry(workspaceRoot, options = {}) {
         };
         if (shouldConnect && trust === 'trusted') {
             try {
-                const connection = await connect(name, config);
+                const connection = await connect(name, config, {
+                    timeoutMs: handshakeTimeoutMs,
+                    logFile: mcpLogPath(workspaceRoot, name),
+                });
                 state.connection = connection;
                 state.surfacedTools = await listTools(connection);
             }

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