@pugi/cli 0.1.0-beta.5 → 0.1.0-beta.51

package/dist/core/permissions/gate.js

@@ -0,0 +1,278 @@
+/**
+ * Permission gate — Wave 7 canonical 6-mode enforcement (CC parity).
+ *
+ * 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
+ *   default             |  ask   |  ask        |  ask
+ *   acceptEdits         |  allow |  allow*     |  ask
+ *   plan                |  allow |  deny       |  deny
+ *   auto                |  ask†  |  ask†       |  ask†
+ *   dontAsk             |  allow |  allow      |  allow
+ *   bypassPermissions   |  allow |  allow      |  allow   (hooks bypassed)
+ *
+ *   * acceptEdits allows file-write tools (write/edit/multi_edit) only;
+ *     bash and other write-class tools still ask.
+ *   † auto-mode consults the classifier (`auto-classifier.ts`): safe
+ *     regex allowlist → allow; destructive regex denylist → deny;
+ *     anything else → ask.
+ *
+ * Protected paths (`.git`, `~/.ssh`, `.pugi/settings.json`, …) NEVER
+ * auto-approve regardless of mode — the gate refuses them even in
+ * `dontAsk` and `bypassPermissions`. The bypassPermissions circuit-
+ * breaker fires on rm -rf / fork-bomb / dd if=/ patterns против root /
+ * home / workspace.
+ *
+ * Ask-mode session cache (`AskAlwaysCache`) survives — `default` and
+ * `auto` consult it; `plan` ignores it (structural contract); the
+ * permissive modes already allow / refuse без the cache.
+ */
+import { classifyAutoMode } from './auto-classifier.js';
+import { evaluateCircuitBreaker } from './circuit-breaker.js';
+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 так cache stays в 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 для the same tool name внутри 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` };
+    }
+}
+/**
+ * Tools that `acceptEdits` mode auto-allows. Restricted к file-edit
+ * surfaces — bash / dispatch / etc fall through к the ask branch so
+ * the operator stays in control of "execute arbitrary command" and
+ * "spawn child agent" actions.
+ */
+const ACCEPT_EDITS_AUTO_ALLOW = new Set([
+    'write',
+    'edit',
+    'multi_edit',
+]);
+/**
+ * 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 в 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 в console output.
+     */
+    reason;
+    constructor(toolName, toolClass, mode, reason) {
+        // The base Error.message is the canonical sentinel так 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 к the model.
+     * The string format stable так a parent agent / E2E spec can
+     * pattern-match `PERMISSION_DENIED: <tool> blocked in <mode> mode.`
+     * verbatim. Equivalent to `this.message`; kept как method так
+     * 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. The gate inspects `args.command`
+ *     when present (bash tool) for the circuit-breaker + auto-mode
+ *     classifier. Other tools pass through unused — the contract is
+ *     stable on purpose.
+ *   - `ctx` carries mode + session-scoped state.
+ */
+export function gate(toolName, args, ctx) {
+    const toolClass = getToolClass(toolName);
+    const cache = ctx.alwaysCache;
+    const command = extractCommand(args, ctx.commandPreview);
+    // Bypass-mode circuit breaker: catastrophic patterns refuse FIRST,
+    // before any other routing. Same rule applies when the operator
+    // wired `dontAsk` and a destructive command sneaks through — defence
+    // in depth.
+    if ((ctx.permissionMode === 'bypassPermissions' || ctx.permissionMode === 'dontAsk')
+        && command) {
+        const breaker = evaluateCircuitBreaker(command);
+        if (breaker.tripped) {
+            return {
+                decision: 'deny',
+                reason: `Circuit-breaker tripped: ${breaker.reason}. Refused в ${ctx.permissionMode} mode regardless of policy.`,
+                circuitBreakerReason: breaker.reason,
+            };
+        }
+    }
+    // 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`,
+        };
+    }
+    // "Always-allow" в ask-style modes 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.
+    // `bypassPermissions` / `dontAsk` already allow so the cache is moot.
+    // `acceptEdits` and `auto` honour the cache like `default` does.
+    if (cache?.alwaysAllowed.has(toolName)
+        && (ctx.permissionMode === 'default'
+            || ctx.permissionMode === 'acceptEdits'
+            || ctx.permissionMode === 'auto')) {
+        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 dontAsk.`,
+            };
+        }
+        case 'default': {
+            return askDecision(toolName, toolClass, ctx.target, 'default');
+        }
+        case 'acceptEdits': {
+            // File-edit surfaces auto-execute; everything else asks.
+            if (toolClass === 'read') {
+                return { decision: 'allow', reason: `acceptEdits: read allowed (${toolName})` };
+            }
+            if (toolClass === 'write' && ACCEPT_EDITS_AUTO_ALLOW.has(toolName)) {
+                return {
+                    decision: 'allow',
+                    reason: `acceptEdits: file-edit auto-allowed (${toolName})`,
+                };
+            }
+            return askDecision(toolName, toolClass, ctx.target, 'acceptEdits');
+        }
+        case 'auto': {
+            // Phase 1 classifier — regex allowlist / denylist для bash;
+            // other tools always fall back to ask. The classifier surfaces
+            // an explicit verdict so the spec layer can assert per-pattern.
+            if (toolName === 'bash' && command) {
+                const verdict = classifyAutoMode(command);
+                if (verdict.verdict === 'allow') {
+                    return {
+                        decision: 'allow',
+                        reason: `auto-mode: ${verdict.reason}`,
+                    };
+                }
+                if (verdict.verdict === 'deny') {
+                    return {
+                        decision: 'deny',
+                        reason: `auto-mode: ${verdict.reason}. Switch with /permissions default to override.`,
+                    };
+                }
+                // verdict === 'ask' — fall through.
+            }
+            return askDecision(toolName, toolClass, ctx.target, 'auto');
+        }
+        case 'dontAsk': {
+            return {
+                decision: 'allow',
+                reason: `dontAsk mode: ${toolName} executed (deny-list still applies)`,
+            };
+        }
+        case 'bypassPermissions': {
+            return {
+                decision: 'allow',
+                reason: `bypassPermissions: ${toolName} executed (policy hooks skipped)`,
+                hooksBypassed: true,
+            };
+        }
+    }
+}
+function askDecision(toolName, toolClass, target, mode) {
+    return {
+        decision: 'ask',
+        reason: `${mode} mode: prompt before ${toolName}`,
+        question: buildAskQuestion(toolName, toolClass, target),
+        options: ASK_OPTIONS,
+        toolClass,
+    };
+}
+/**
+ * Best-effort extract of the bash command string from the raw tool
+ * args. Returns `null` when the shape doesn't match — auto-mode and
+ * the circuit-breaker treat null как "no preview available" and fall
+ * back to safe defaults (ask / no-trip).
+ */
+function extractCommand(args, fallback) {
+    if (typeof fallback === 'string' && fallback.length > 0)
+        return fallback;
+    if (args && typeof args === 'object') {
+        const maybe = args.command;
+        if (typeof maybe === 'string' && maybe.length > 0)
+            return maybe;
+    }
+    return null;
+}
+/**
+ * Build the operator-facing question string for an ask-mode prompt.
+ * Kept в one place так 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,20 @@
+/**
+ * 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, nextPermissionMode, parsePermissionMode, toLegacyMode, } from './mode.js';
+export { classifyAutoMode, listAutoAllowPatterns, listAutoDenyPatterns, } from './auto-classifier.js';
+export { evaluateCircuitBreaker, listCircuitBreakerPatterns, } from './circuit-breaker.js';
+export { getToolClass, listBuiltInToolClasses, } from './tool-class.js';
+export { ASK_OPTIONS, PermissionDenied, applyAskAnswer, createAskAlwaysCache, gate, } from './gate.js';
+export { getCurrentMode, getGlobalDefaultMode, getPreviousMode, globalConfigPath, resolveMode, sessionStatePath, setCurrentMode, setGlobalDefaultMode, setPreviousMode, } from './state.js';
+//# sourceMappingURL=index.js.map

package/dist/core/permissions/mode.js

@@ -0,0 +1,174 @@
+/**
+ * Permission modes — Wave 7 canonical 6-mode taxonomy (Claude Code parity).
+ *
+ * Pugi α6 shipped a 4-mode taxonomy (`plan | ask | allow | bypass`) that
+ * proved fine для daily use but diverged from Claude Code's 6-mode
+ * surface (`default | acceptEdits | plan | auto | dontAsk |
+ * bypassPermissions`). Wave 7 Sprint 1 epic #2 closes the parity gap so
+ * operators coming from Claude Code see the same mode names + same
+ * Shift+Tab cycle.
+ *
+ * Canonical 6 modes (Wave 7):
+ *
+ *   - `default`            — every tool call asks the operator. Safe
+ *                            ground state, replaces α6 `ask`.
+ *   - `acceptEdits`        — auto-allow write/edit on workspace files,
+ *                            ask for everything else (bash, dispatch).
+ *                            Matches CC's "trust file edits только".
+ *   - `plan`               — read-only proposal mode. Write/dispatch
+ *                            refused with deterministic sentinel; the
+ *                            model surfaces a plan, не executes.
+ *   - `auto`               — classifier decides per-call. Phase 1
+ *                            (this PR) ships regex allowlist (safe
+ *                            commands) + regex denylist (destructive).
+ *                            Anything else falls back to ask.
+ *   - `dontAsk`            — auto-allow everything except `permissions.deny`
+ *                            list. Replaces α6 `allow`.
+ *   - `bypassPermissions`  — skip ALL checks including deny list +
+ *                            policy hooks. Has a circuit-breaker for
+ *                            catastrophic patterns (rm -rf /, fork bomb,
+ *                            dd if=/) that refuses regardless of mode.
+ *                            Replaces α6 `bypass`.
+ *
+ * Backwards-compat aliases: the α6 short names (`ask`, `allow`, `bypass`)
+ * map to the new canonical names via `MODE_ALIASES`. `parsePermissionMode`
+ * resolves aliases so existing session.json files keep working.
+ *
+ * Rename mapping (α6 → α7):
+ *   ask     → default
+ *   allow   → dontAsk
+ *   bypass  → bypassPermissions
+ *   (plan, acceptEdits, auto unchanged / new)
+ */
+/**
+ * Closed list — used by Shift+Tab cycle (in order), input validation,
+ * and slash-command help. Order matches Claude Code's documented
+ * Shift+Tab progression: default → acceptEdits → plan → auto → dontAsk
+ * → bypassPermissions → wrap к default.
+ */
+export const PERMISSION_MODES = Object.freeze([
+    'default',
+    'acceptEdits',
+    'plan',
+    'auto',
+    'dontAsk',
+    'bypassPermissions',
+]);
+/**
+ * Default mode applied when no `--mode` flag, no per-workspace session
+ * state, and no `defaultPermissionMode` в `~/.pugi/config.json`. We
+ * default cautious (`default` mode = prompt every call) — 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 = 'default';
+/**
+ * Backwards-compat aliases: α6 short names map to α7 canonical names.
+ * `parsePermissionMode` consults this table так existing session.json
+ * files + scripts that pass `--mode ask` keep working without breaking.
+ *
+ * Aliases are one-way: persistence writes the canonical name, so a
+ * session that started on `ask` is migrated to `default` on next save.
+ */
+const MODE_ALIASES = Object.freeze({
+    ask: 'default',
+    allow: 'dontAsk',
+    bypass: 'bypassPermissions',
+});
+/**
+ * Type guard для arbitrary string input (CLI flag, session.json
+ * deserialization). Returns false for casing variants — caller is
+ * expected to lowercase before testing. Aliases are NOT accepted by
+ * this predicate; use `parsePermissionMode` for alias resolution.
+ */
+export function isPermissionMode(value) {
+    return typeof value === 'string' && PERMISSION_MODES.includes(value);
+}
+/**
+ * Parse + validate a mode string. Returns null для invalid input so the
+ * caller can surface a typed error (`unknown mode: <value>`) instead of
+ * throwing from a parse helper.
+ *
+ * Resolves α6 aliases (`ask` → `default`, `allow` → `dontAsk`,
+ * `bypass` → `bypassPermissions`) for backwards compatibility.
+ *
+ * Case-handling: lowercases for canonical names but matches camelCase
+ * names case-insensitively too (так `acceptedits` resolves to
+ * `acceptEdits`). The aliases table covers the legacy lowercase tokens.
+ */
+export function parsePermissionMode(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return null;
+    // Direct canonical match first (preserves camelCase capitalisation).
+    if (isPermissionMode(trimmed))
+        return trimmed;
+    // Case-insensitive canonical match — operator typed `acceptedits`.
+    const lower = trimmed.toLowerCase();
+    const canonical = PERMISSION_MODES.find((m) => m.toLowerCase() === lower);
+    if (canonical)
+        return canonical;
+    // α6 alias fallthrough.
+    const aliased = MODE_ALIASES[lower];
+    if (aliased)
+        return aliased;
+    return null;
+}
+/**
+ * Wave 7 Shift+Tab cycle — advance to the next mode in the canonical
+ * order, wrapping from the last back to the first. Pure helper so the
+ * TUI binding can call it without re-implementing the cycle logic.
+ */
+export function nextPermissionMode(current) {
+    const idx = PERMISSION_MODES.indexOf(current);
+    if (idx === -1)
+        return DEFAULT_PERMISSION_MODE;
+    const next = PERMISSION_MODES[(idx + 1) % PERMISSION_MODES.length];
+    return next ?? DEFAULT_PERMISSION_MODE;
+}
+/**
+ * Map the canonical 6-mode taxonomy to the legacy SDK enum used by
+ * `@pugi/sdk::permissionModeSchema`. The SDK enum already contains all
+ * 6 names so the map is identity для the modes that align; the two
+ * α6-only legacy names (`ask`, `allow`) are not part of the canonical
+ * set anymore — `default` and `dontAsk` are их replacements.
+ *
+ * Callers that need the legacy enum (existing bash classifier, settings
+ * persistence) should funnel through this helper so the mapping stays
+ * в one place.
+ */
+export function toLegacyMode(mode) {
+    switch (mode) {
+        case 'default':
+            // SDK enum doesn't carry `default`; the closest legacy semantic is
+            // `ask` (prompt-every-call). Persistence layers that round-trip
+            // через the SDK enum get back `ask`, which `parsePermissionMode`
+            // re-maps to `default` via the alias table. Round-trip safe.
+            return 'ask';
+        case 'acceptEdits':
+            return 'acceptEdits';
+        case 'plan':
+            return 'plan';
+        case 'auto':
+            return 'auto';
+        case 'dontAsk':
+            return 'dontAsk';
+        case 'bypassPermissions':
+            return 'bypassPermissions';
+    }
+}
+/**
+ * One-line human-readable summary surfaced by the `/permissions` table,
+ * the Ink picker, and `pugi --help` text. Each line carries a safety
+ * hint ("safe-by-default" / "use carefully" / "power-user only") so an
+ * operator скимming the picker knows the risk profile at a glance.
+ */
+export const PERMISSION_MODE_GLOSS = Object.freeze({
+    default: 'Prompt before every tool call. Safe-by-default for new operators.',
+    acceptEdits: 'Auto-allow file edit/write; ask for bash + dispatch. Safe-by-default.',
+    plan: 'Read-only — propose, never execute. Write + dispatch refused.',
+    auto: 'Classifier decides per call (safe regex allowlist; falls back к ask). Use carefully.',
+    dontAsk: 'Execute tools without prompts; deny-list still applies. Use carefully.',
+    bypassPermissions: 'Skip ALL checks AND policy hooks; circuit-breaker on catastrophic patterns. Power-user only.',
+});
+//# sourceMappingURL=mode.js.map