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

package/dist/core/permissions/state.js

@@ -0,0 +1,160 @@
+/**
+ * Per-workspace permission-mode session state — Leak L6.
+ *
+ * State lives in `.pugi/session.json` under the workspace root. The
+ * file is read on first `getCurrentMode()` call (cached for the
+ * process lifetime) and written atomically via tmp+rename on
+ * `setCurrentMode()` so a kill mid-write does not corrupt the JSON.
+ *
+ * Resolution order for the effective mode on a fresh process:
+ *   1. CLI flag (`pugi --mode plan`) — passed via `resolveMode` arg;
+ *      not read from disk here.
+ *   2. Workspace session state — `<root>/.pugi/session.json` field
+ *      `permissionMode`.
+ *   3. Global config — `~/.pugi/config.json` field
+ *      `defaultPermissionMode`.
+ *   4. Hard default `ask`.
+ *
+ * This module owns layers 2 + 3. The CLI arg parser owns layer 1; both
+ * funnel into `resolveMode()` which performs the merge.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { z } from 'zod';
+import { DEFAULT_PERMISSION_MODE, isPermissionMode, parsePermissionMode, } from './mode.js';
+const permissionModeEnum = z.enum(['plan', 'ask', 'allow', 'bypass']);
+const sessionStateSchema = z
+    .object({
+    permissionMode: permissionModeEnum.optional(),
+})
+    .partial()
+    .passthrough();
+const globalConfigSchema = z
+    .object({
+    defaultPermissionMode: permissionModeEnum.optional(),
+})
+    .partial()
+    .passthrough();
+const SESSION_FILE = '.pugi/session.json';
+/**
+ * Return the path to the workspace session-state file.
+ */
+export function sessionStatePath(workspaceRoot) {
+    return resolve(workspaceRoot, SESSION_FILE);
+}
+/**
+ * Return the path to the user-global config file. Uses HOME env when
+ * present (test fixtures, CI) so we never accidentally hit the real
+ * user-global file in spec runs.
+ */
+export function globalConfigPath(homeDir = homedir()) {
+    return resolve(homeDir, '.pugi/config.json');
+}
+/**
+ * Read the workspace's saved permission mode. Returns null when the
+ * file is absent OR the field is unset; the caller layers in CLI + env
+ * + global config defaults to produce the effective mode.
+ *
+ * Never throws on JSON parse / schema errors — a malformed session
+ * file should not break the gate. The defensive `try/catch` returns
+ * null and lets the caller fall through to the next layer.
+ */
+export function getCurrentMode(workspaceRoot) {
+    const path = sessionStatePath(workspaceRoot);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = sessionStateSchema.parse(JSON.parse(raw));
+        return isPermissionMode(parsed.permissionMode) ? parsed.permissionMode : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist the workspace's permission mode. Creates the `.pugi/` dir
+ * when missing; preserves any unrelated keys in the file (passthrough
+ * schema). Atomic tmp+rename so a kill mid-write does not corrupt the
+ * JSON.
+ */
+export function setCurrentMode(workspaceRoot, mode) {
+    const path = sessionStatePath(workspaceRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    const existing = existsSync(path)
+        ? safeParseObject(readFileSync(path, 'utf8'))
+        : {};
+    const next = { ...existing, permissionMode: mode };
+    const tmpPath = `${path}.tmp`;
+    writeFileSync(tmpPath, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmpPath, path);
+}
+/**
+ * Read `~/.pugi/config.json::defaultPermissionMode`. Returns null when
+ * the file is absent / the field is unset; same defensive behaviour
+ * as `getCurrentMode` — a malformed global config never breaks the gate.
+ */
+export function getGlobalDefaultMode(homeDir = homedir()) {
+    const path = globalConfigPath(homeDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = globalConfigSchema.parse(JSON.parse(raw));
+        return isPermissionMode(parsed.defaultPermissionMode) ? parsed.defaultPermissionMode : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist `~/.pugi/config.json::defaultPermissionMode`. Used by the
+ * `/permissions <mode> --persist` flow so a future fresh session
+ * defaults to the same mode without an explicit `--mode` flag.
+ */
+export function setGlobalDefaultMode(mode, homeDir = homedir()) {
+    const path = globalConfigPath(homeDir);
+    mkdirSync(dirname(path), { recursive: true });
+    const existing = existsSync(path)
+        ? safeParseObject(readFileSync(path, 'utf8'))
+        : {};
+    const next = { ...existing, defaultPermissionMode: mode };
+    const tmpPath = `${path}.tmp`;
+    writeFileSync(tmpPath, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(tmpPath, path);
+}
+export function resolveMode(options) {
+    if (options.cliFlag) {
+        const flag = parsePermissionMode(options.cliFlag);
+        if (flag)
+            return flag;
+    }
+    const workspace = getCurrentMode(options.workspaceRoot);
+    if (workspace)
+        return workspace;
+    const global = getGlobalDefaultMode(options.homeDir);
+    if (global)
+        return global;
+    return DEFAULT_PERMISSION_MODE;
+}
+/**
+ * Defensive helper — parse JSON to an object; non-object payload (top-
+ * level array, primitive) collapses to an empty object so the merge
+ * doesn't surface a TypeError. The `setCurrentMode` / `setGlobalDefaultMode`
+ * helpers only write objects, so a non-object existing file is corrupted
+ * and we explicitly reset it rather than appending into a non-object.
+ */
+function safeParseObject(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+//# sourceMappingURL=state.js.map

package/dist/core/permissions/tool-class.js

@@ -0,0 +1,93 @@
+/**
+ * Tool side-effect classification — Leak L6.
+ *
+ * Three classes drive the canonical 4-mode permission gate:
+ *
+ *   - `read`     — observe-only. Plan mode allows; ask still prompts;
+ *                  allow + bypass execute silently. Examples: read,
+ *                  grep, glob, web_fetch, web_search, skills_list.
+ *   - `write`    — mutates workspace, journal, or operator screen with
+ *                  visible side effects. Plan mode refuses; ask prompts;
+ *                  allow + bypass execute. Examples: write, edit, bash,
+ *                  multi_edit, task_*. `ask_user_question` is also
+ *                  classed as `write` because it interrupts the
+ *                  dispatcher's flow control and demands operator
+ *                  attention — plan mode should not prompt operators.
+ *   - `dispatch` — spawns a child subagent or off-tree task. Plan mode
+ *                  refuses (a write-capable child violates plan-mode's
+ *                  read-only contract); ask prompts; allow + bypass
+ *                  execute. Example: `agent`.
+ *
+ * Unknown tool names default to `write` — deny-first safety. A stale
+ * schema entry that the gate has not been told about should not silently
+ * pass in plan mode just because the gate doesn't recognise it.
+ */
+/**
+ * Closed map of every built-in tool name -> side-effect class. The
+ * source of truth for the four standard modes; mirrored against the
+ * `WIRED_TOOLS` set in `core/engine/tool-bridge.ts` so an unrecognised
+ * tool surfaces as the safe deny-first `write` default.
+ *
+ * MCP tools follow the `mcp__<server>__<tool>` namespace and are
+ * uniformly classed via `getToolClass` because per-tool annotations are
+ * not yet a part of the MCP spec — treating them as `write` is the
+ * conservative default until server-side metadata is trustworthy.
+ */
+const BUILT_IN_TOOL_CLASSES = Object.freeze({
+    // Read-only observations.
+    read: 'read',
+    grep: 'read',
+    glob: 'read',
+    ls: 'read',
+    search: 'read',
+    web_fetch: 'read',
+    web_search: 'read',
+    file_cache_check: 'read',
+    skills_list: 'read',
+    skill: 'read',
+    task_get: 'read',
+    task_list: 'read',
+    // Mutating actions.
+    write: 'write',
+    edit: 'write',
+    multi_edit: 'write',
+    bash: 'write',
+    task_create: 'write',
+    task_update: 'write',
+    todo_write: 'write',
+    // `ask_user_question` halts the loop and demands operator attention.
+    // Plan mode should not interrupt — class as write so the gate refuses
+    // it in plan mode but ask + allow + bypass execute normally.
+    ask_user_question: 'write',
+    // Dispatch — spawn a child agent. Refused in plan mode regardless of
+    // the child's role tier (the engine adapter applies role-based
+    // capability filtering, but the gate refuses dispatch up front so a
+    // plan-mode session cannot leak a writeable child).
+    agent: 'dispatch',
+    pugi_delegate: 'dispatch',
+    sub_agent_spawn: 'dispatch',
+});
+const MCP_TOOL_PREFIX = 'mcp__';
+/**
+ * Resolve the class for a tool name. Unknown names default to `write`
+ * (deny-first). MCP tools (any name prefixed with `mcp__`) default to
+ * `write` for the same conservative reason — the MCP spec lacks
+ * per-tool annotations today.
+ */
+export function getToolClass(toolName) {
+    const builtIn = BUILT_IN_TOOL_CLASSES[toolName];
+    if (builtIn)
+        return builtIn;
+    if (toolName.startsWith(MCP_TOOL_PREFIX))
+        return 'write';
+    return 'write';
+}
+/**
+ * Expose the built-in class map for diagnostic surfaces (`pugi doctor`,
+ * test fixtures). Caller MUST NOT mutate — the object is already frozen
+ * so any attempt throws in strict mode.
+ */
+export function listBuiltInToolClasses() {
+    return BUILT_IN_TOOL_CLASSES;
+}
+//# sourceMappingURL=tool-class.js.map

package/dist/core/repl/session.js

@@ -34,6 +34,9 @@ import { parseSlashCommand } from './slash-commands.js';
 import { webFetchTool } from '../../tools/web-fetch.js';
 import { loadSettings } from '../settings.js';
 import { getJobRegistry } from '../jobs/registry.js';
+import { applyCompactMask } from '../compact/buffer-rewriter.js';
+import { evaluateAutoCompact } from '../compact/auto-trigger.js';
+import { estimateTokensInMany } from '../compact/token-counter.js';
 import { extractAskTags, extractPlanReviewTags, signatureForAsk, } from './ask.js';
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
@@ -638,7 +641,7 @@ export class ReplSession {
                 return verdict;
             }
             case 'status': {
-                this.dispatchStatus();
+                await this.dispatchStatus();
                 return verdict;
             }
             case 'consensus': {
@@ -799,12 +802,89 @@ export class ReplSession {
                 }
                 return verdict;
             }
+            case 'permissions': {
+                // Leak L6: handle the `/permissions [mode] [--persist]` flow.
+                // The session module forwards to the runtime helper so the
+                // workspace + global-config writes share one code path with
+                // the CLI's top-level `--mode` resolution. The dynamic import
+                // keeps the dispatcher free of a session.ts -> runtime/cli.ts
+                // cycle.
+                try {
+                    const { runPermissionsCommand } = await import('../../runtime/commands/permissions.js');
+                    const lines = [];
+                    await runPermissionsCommand(verdict, {
+                        workspaceRoot: process.cwd(),
+                        writeOutput: (line) => {
+                            const trimmed = line.replace(/\n+$/u, '');
+                            if (trimmed.length > 0)
+                                lines.push(trimmed);
+                        },
+                    });
+                    for (const line of lines)
+                        this.appendSystemLine(line);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    this.appendSystemLine(`/permissions failed: ${message}`);
+                }
+                return verdict;
+            }
+            case 'compact': {
+                // Leak L8 (2026-05-27): /compact summarises older turns and
+                // appends a boundary marker. We forward to the same runner the
+                // top-level `pugi compact` command uses so the surface stays
+                // single-sourced. The session module owns the in-memory
+                // transcript echo (system line + banner row) so the operator
+                // sees the marker land without a fresh REPL bootstrap.
+                await this.dispatchCompact('manual');
+                return verdict;
+            }
             case 'stub': {
                 this.appendSystemLine(verdict.message);
                 return verdict;
             }
         }
     }
+    /**
+     * Leak L8 (2026-05-27): drive the `/compact` flow from inside the
+     * REPL. Reuses the standalone runner so the wire shape + reason
+     * codes stay single-sourced. The result is echoed into the
+     * transcript as a system line; on success the operator sees the
+     * banner sentinel on next render.
+     *
+     * `trigger='manual'` for explicit `/compact` invocations;
+     * `trigger='auto'` for the threshold gate. The runner records the
+     * trigger in the marker payload so the banner can distinguish them.
+     */
+    async dispatchCompact(trigger) {
+        if (!this.store || !this.localSessionId) {
+            this.appendSystemLine('Local session store is disabled — /compact is unavailable.');
+            return;
+        }
+        try {
+            const { runCompactCommand } = await import('../../runtime/commands/compact.js');
+            const result = await runCompactCommand([], {
+                workspaceRoot: process.cwd(),
+                sessionId: this.localSessionId,
+                store: this.store,
+                trigger,
+                writeOutput: (_payload, text) => {
+                    if (text.length > 0)
+                        this.appendSystemLine(text);
+                },
+            });
+            if (result.status === 'compacted') {
+                // Echo a visible separator into the transcript so the operator
+                // immediately sees where the compaction landed. The Ink banner
+                // renders the row when the session reloads / resumes.
+                this.appendSystemLine(`─── context compacted (${result.turnsBefore} turns → 1 summary, ${trigger}) ───`);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.appendSystemLine(`/compact failed: ${message}`);
+        }
+    }
     /**
      * In-REPL `/privacy` - alpha 6.13. Prints the full 3-mode contract
      * doc + the current mode banner inline. The current mode is fetched
@@ -1172,13 +1252,70 @@ export class ReplSession {
             clearTimeout(timer);
         }
     }
-    dispatchStatus() {
-        const sessionId = this.state.sessionId ?? '(unbound)';
-        const reach = this.state.connection;
-        this.appendSystemLine(`Backend: ${this.options.apiUrl} (${reach}).`);
-        this.appendSystemLine(`Session: ${sessionId}.`);
-        this.appendSystemLine(`Workspace: ${this.state.workspaceLabel}.`);
-        this.appendSystemLine(`CLI: pugi ${this.state.cliVersion}.`);
+    /**
+     * In-REPL `/status` — Leak L34 (2026-05-27). Surfaces the full
+     * session snapshot (id + age, cwd, permission mode, CLI version,
+     * tokens, dispatches, last cmd, compact boundaries, auth identity,
+     * connection) by delegating к the same `runStatusCommand` the
+     * top-level `pugi status` shell uses. Live REPL state (session
+     * id, token totals, last operator command) flows in through the
+     * context so the slash variant shows MORE than the shell path.
+     *
+     * The renderer routes к the system pane via `appendSystemLine`
+     * so the snapshot lands as a single contiguous block в the
+     * conversation transcript. Migrating к the Ink `<StatusTable>`
+     * mounted directly в the REPL frame is a follow-up sprint —
+     * keeping the line-buffered path here avoids cycling the
+     * conversation pane's render model mid-α7.
+     */
+    async dispatchStatus() {
+        try {
+            const { runStatusCommand, defaultStatusHome } = await import('../../runtime/commands/status.js');
+            // Find the most-recent operator transcript row + its timestamp
+            // so the snapshot's `Last cmd` field has real content в REPL
+            // mode. Walking от newest end is O(transcript) worst case but
+            // bounded by MAX_TRANSCRIPT_ROWS so this stays cheap.
+            let lastCommand = null;
+            let lastCommandAtEpochMs = null;
+            for (let i = this.state.transcript.length - 1; i >= 0; i -= 1) {
+                const row = this.state.transcript[i];
+                if (row.source === 'operator') {
+                    lastCommand = row.text;
+                    lastCommandAtEpochMs = row.timestampEpochMs;
+                    break;
+                }
+            }
+            const liveTokens = this.state.sessionTokensIn + this.state.sessionTokensOut;
+            const lines = [];
+            await runStatusCommand({
+                cwd: process.cwd(),
+                home: defaultStatusHome(),
+                env: process.env,
+                json: false,
+                liveSessionId: this.state.sessionId ?? null,
+                sessionStartedAtEpochMs: this.state.sessionStartedAtEpochMs,
+                liveTokensUsed: liveTokens >= 0 ? liveTokens : 0,
+                lastCommand,
+                lastCommandAtEpochMs,
+                writeOutput: (_payload, text) => {
+                    for (const line of text.split('\n')) {
+                        const trimmed = line.replace(/\s+$/u, '');
+                        if (trimmed.length > 0)
+                            lines.push(trimmed);
+                    }
+                },
+            });
+            if (lines.length === 0) {
+                this.appendSystemLine('/status: no output.');
+                return;
+            }
+            for (const line of lines)
+                this.appendSystemLine(line);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.appendSystemLine(`/status failed: ${message}`);
+        }
     }
     /**
      * α6.5 `/context` slash handler. Surfaces the three-tier context
@@ -2242,6 +2379,62 @@ export class ReplSession {
         //   persona  -> 'persona'
         //   system   -> 'system'
         this.persistRow(row);
+        // Leak L8 (2026-05-27): evaluate the auto-compact gate after
+        // every appendRow that produces a transcript turn. Wrapped in a
+        // setImmediate so the gate never blocks the input-handling fast
+        // path; if the threshold is tripped, the auto-trigger dispatches
+        // `/compact` in the background while the operator keeps typing.
+        if (row.source === 'operator' || row.source === 'persona') {
+            this.maybeAutoCompact();
+        }
+    }
+    /**
+     * Auto-compact gate. Cheap: builds an in-memory token estimate from
+     * the current transcript and consults `evaluateAutoCompact`. When the
+     * gate fires AND a compaction is not already in flight, we dispatch
+     * `/compact` with `trigger='auto'`. The fire-and-forget shape means
+     * the input box stays responsive while the background round-trip
+     * runs.
+     *
+     * Hysteresis: `compactionInFlight` blocks re-entry. The gate is
+     * cleared when the dispatch promise resolves regardless of outcome
+     * so a transient transport failure does not permanently disable the
+     * auto-trigger.
+     */
+    compactionInFlight = false;
+    maybeAutoCompact() {
+        if (this.compactionInFlight)
+            return;
+        if (!this.store || !this.localSessionId)
+            return;
+        if (process.env['PUGI_AUTOCOMPACT_DISABLED'] === '1')
+            return;
+        // Token estimate from the in-memory transcript. The estimate is a
+        // lower bound on actual context pressure (server-side system
+        // prompts add overhead) but the 4-char/token heuristic plus the
+        // 0.75 default threshold gives generous headroom.
+        const texts = this.state.transcript.map((r) => r.text);
+        const tokenCount = estimateTokensInMany(texts);
+        // Conservative default: assume the smallest commonly-used window
+        // (32k tokens for deepseek-v3.1). Resolving the live model slug
+        // through DispatchFSM + admin-api adds latency on a hot path; the
+        // 0.75 threshold + smallest-window assumption errs toward
+        // EARLY trigger which is the safe direction.
+        const verdict = evaluateAutoCompact({
+            tokenCount,
+            windowSize: 32_000,
+        });
+        if (verdict.kind !== 'fire')
+            return;
+        this.compactionInFlight = true;
+        void (async () => {
+            try {
+                await this.dispatchCompact('auto');
+            }
+            finally {
+                this.compactionInFlight = false;
+            }
+        })();
     }
     /**
      * Best-effort write of one transcript row into the local
@@ -2292,8 +2485,14 @@ export class ReplSession {
      * write the restored events.
      */
     restoreTranscript(events) {
+        // Leak L8 (2026-05-27): apply compact-boundary masking BEFORE the
+        // row conversion. Events strictly before the latest marker are
+        // condensed into the boundary's `keptTailTurns + marker` slice so
+        // the post-resume transcript starts at the most-recent context
+        // floor rather than re-playing the full pre-compaction history.
+        const masked = applyCompactMask(events);
         const rows = [];
-        for (const event of events) {
+        for (const event of masked) {
             const row = eventToTranscriptRow(event);
             if (row)
                 rows.push(row);
@@ -2481,6 +2680,25 @@ function eventToTranscriptRow(event) {
             timestampEpochMs: event.t,
         };
     }
+    if (event.kind === 'compaction') {
+        // Leak L8: render the marker as a system separator line on
+        // replay. The full summary text is intentionally NOT inlined here
+        // (a 2k-token summary in the transcript would defeat the purpose
+        // of compacting); the operator sees the "context compacted"
+        // banner and can run `/context` to inspect the marker payload
+        // when they want the details.
+        const compactionPayload = (event.payload ?? null);
+        const trigger = compactionPayload?.trigger === 'auto' ? 'auto' : 'manual';
+        const turns = typeof compactionPayload?.summaryTurnsBefore === 'number'
+            ? compactionPayload.summaryTurnsBefore
+            : 0;
+        return {
+            id: randomUUID(),
+            source: 'system',
+            text: `─── context compacted (${turns} turns → 1 summary, ${trigger}) ───`,
+            timestampEpochMs: event.t,
+        };
+    }
     return null;
 }
 /**

package/dist/core/repl/slash-commands.js

@@ -38,7 +38,10 @@ import { listRoles } from '../agents/registry.js';
  * silently appear here with empty placeholders.
  */
 export const SLASH_STUB_MESSAGES = Object.freeze({
-    compact: 'Manual context compaction lands in α6.5b.',
+    // Leak L8 (2026-05-27): /compact graduated from stub. The session
+    // module now owns the summariser round-trip + boundary marker append
+    // via `dispatchCompact`. Keep the type record exhaustive so a future
+    // stub addition cannot silently overlap the wired set.
     memory: 'Session memory editor lands in α6.5b.',
     config: 'Run `pugi config list` from a fresh shell for the full surface; in-REPL editor lands in α6.5.',
     // alpha 6.13: /privacy graduated from stub; nothing reads this at
@@ -62,7 +65,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'clear', args: '', gloss: 'Clear conversation pane', group: 'Session' },
     { name: 'resume', args: '', gloss: 'Pick a stored session to restore', group: 'Session' },
     { name: 'context', args: '', gloss: 'Show three-tier context summary (Tier 0 skeleton + Tier 1 working set)', group: 'Session' },
-    { name: 'compact', args: '', gloss: 'Manual context compaction  (α6.5b)', group: 'Session', stub: true },
+    { name: 'compact', args: '', gloss: 'Summarise older turns into a boundary marker (leak L8)', group: 'Session' },
     { name: 'memory', args: '', gloss: 'Session memory editor  (α6.5b)', group: 'Session', stub: true },
     { name: 'init', args: '', gloss: 'Scaffold .pugi/ in the current workspace (β1 Sl11)', group: 'Session' },
     // Pugi tools
@@ -70,11 +73,12 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     { name: 'diff', args: '', gloss: 'Show pending diff', group: 'Pugi tools' },
     { name: 'cost', args: '', gloss: 'Session token + USD totals + last 5 turn breakdown', group: 'Pugi tools' },
     { name: 'quota', args: '', gloss: 'Plan tier + monthly usage caps (sync / review / engine)', group: 'Pugi tools' },
-    { name: 'status', args: '', gloss: 'Backend + tenant status', group: 'Pugi tools' },
+    { name: 'status', args: '', gloss: 'Session snapshot — id · cwd · mode · tokens · dispatches · auth', group: 'Pugi tools' },
     { name: 'consensus', args: '[ref]', gloss: '3-model consensus review (codex · claude · deepseek)', group: 'Pugi tools' },
     // Settings
     { name: 'config', args: '', gloss: 'Show config', group: 'Settings', stub: true },
     { name: 'privacy', args: '', gloss: 'Show privacy mode + contract', group: 'Settings' },
+    { name: 'permissions', args: '[mode] [--persist]', gloss: 'Show or flip permission mode (plan / ask / allow / bypass)', group: 'Settings' },
     { name: 'budget', args: '', gloss: 'Show usage budget', group: 'Settings', stub: true },
     { name: 'mcp', args: '[sub]', gloss: 'MCP servers — list / trust / deny / install / serve / perms', group: 'Settings' },
     { name: 'undo', args: '', gloss: 'Undo last write', group: 'Settings', stub: true },
@@ -257,6 +261,49 @@ export function parseSlashCommand(input) {
             // device flow + audit identity are wired correctly).
             return { kind: 'privacy' };
         }
+        case 'permissions':
+        case 'perms': {
+            // Leak L6: `/permissions [mode] [--persist] [--confirm]`.
+            //
+            // Argument grammar (single line, no quoting):
+            //   /permissions                   -> show current mode + table
+            //   /permissions plan|ask|allow    -> flip mode
+            //   /permissions bypass --confirm  -> flip to bypass (refused
+            //                                     without --confirm — safety)
+            //   /permissions <mode> --persist  -> also write to ~/.pugi/config.json
+            //
+            // Anything else returns an `error` result so the runtime can
+            // render the usage hint inline.
+            const tokens = tail.length === 0 ? [] : tail.split(/\s+/).filter((s) => s.length > 0);
+            if (tokens.length === 0) {
+                return { kind: 'permissions', persist: false, confirmBypass: false };
+            }
+            const head0 = tokens[0]?.toLowerCase();
+            if (head0 !== 'plan' && head0 !== 'ask' && head0 !== 'allow' && head0 !== 'bypass') {
+                return {
+                    kind: 'error',
+                    message: `Usage: /permissions [plan|ask|allow|bypass] [--persist] [--confirm]; unknown mode '${tokens[0] ?? ''}'`,
+                };
+            }
+            const flags = tokens.slice(1);
+            let persist = false;
+            let confirmBypass = false;
+            for (const flag of flags) {
+                if (flag === '--persist') {
+                    persist = true;
+                }
+                else if (flag === '--confirm') {
+                    confirmBypass = true;
+                }
+                else {
+                    return {
+                        kind: 'error',
+                        message: `/permissions: unknown flag '${flag}' (allowed: --persist, --confirm)`,
+                    };
+                }
+            }
+            return { kind: 'permissions', mode: head0, persist, confirmBypass };
+        }
         case 'init': {
             // β1 Sl11: surface the init flow inside the REPL. Tail args
             // are ignored — the init handler is parameterless today; `pugi
@@ -280,7 +327,14 @@ export function parseSlashCommand(input) {
             // shell surface, not the slash one).
             return { kind: 'doctor' };
         }
-        case 'compact':
+        case 'compact': {
+            // Leak L8 (2026-05-27): graduated from stub. The session module
+            // owns the summariser round-trip; tail args are ignored today
+            // because the surface is parameterless. Operators wanting a
+            // per-session compact run `pugi compact --session <id>` from a
+            // fresh shell.
+            return { kind: 'compact' };
+        }
         case 'memory':
         case 'config':
         case 'budget':