@pugi/cli 0.1.0-beta.35 → 0.1.0-beta.37

package/dist/core/permissions/mode.js

@@ -1,102 +1,174 @@
 /**
- * Permission modes — canonical 4-mode taxonomy (Leak L6).
+ * Permission modes — Wave 7 canonical 6-mode taxonomy (Claude Code parity).
  *
- * 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:
+ * 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.
  *
- *   - `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.
+ * Canonical 6 modes (Wave 7):
  *
- * 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.
+ *   - `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 — useful for input validation and slash-command help.
+ * 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',
-    'ask',
-    'allow',
-    'bypass',
+    'auto',
+    'dontAsk',
+    'bypassPermissions',
 ]);
 /**
  * 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.
+ * 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 = 'ask';
+export const DEFAULT_PERMISSION_MODE = 'default';
 /**
- * Type guard for arbitrary string input (CLI flag, session.json
+ * 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.
+ * 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 for invalid input so the
+ * 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 lower = value.trim().toLowerCase();
-    return isPermissionMode(lower) ? lower : null;
+    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;
 }
 /**
- * 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)
+ * 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 is in
- * one place.
+ * 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 'ask':
-            return 'ask';
-        case 'allow':
+        case 'auto':
             return 'auto';
-        case 'bypass':
+        case 'dontAsk':
+            return 'dontAsk';
+        case 'bypassPermissions':
             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.
+ * 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({
-    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.',
+    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

package/dist/core/permissions/state.js

@@ -22,8 +22,27 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from '
 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']);
+import { DEFAULT_PERMISSION_MODE, parsePermissionMode, } from './mode.js';
+/**
+ * Wave 7: zod enum for the canonical 6-mode taxonomy. Includes α6
+ * aliases (`ask`, `allow`, `bypass`) as accepted input — Zod parses
+ * them, the helpers below remap к canonical names before returning к
+ * the caller. Persistence always writes the canonical name so the file
+ * migrates forward on next save.
+ */
+const permissionModeEnum = z.enum([
+    // Canonical Wave 7 names.
+    'default',
+    'acceptEdits',
+    'plan',
+    'auto',
+    'dontAsk',
+    'bypassPermissions',
+    // α6 backwards-compat aliases — resolved via parsePermissionMode.
+    'ask',
+    'allow',
+    'bypass',
+]);
 const sessionStateSchema = z
     .object({
     permissionMode: permissionModeEnum.optional(),
@@ -74,7 +93,12 @@ export function getCurrentMode(workspaceRoot) {
     try {
         const raw = readFileSync(path, 'utf8');
         const parsed = sessionStateSchema.parse(JSON.parse(raw));
-        return isPermissionMode(parsed.permissionMode) ? parsed.permissionMode : null;
+        if (typeof parsed.permissionMode !== 'string')
+            return null;
+        // Wave 7: parsePermissionMode resolves α6 aliases (`ask`, `allow`,
+        // `bypass`) to their canonical Wave 7 names. A session file written
+        // by α6.x is silently upgraded on read.
+        return parsePermissionMode(parsed.permissionMode);
     }
     catch {
         return null;
@@ -112,9 +136,9 @@ export function getPreviousMode(workspaceRoot) {
     try {
         const raw = readFileSync(path, 'utf8');
         const parsed = sessionStateSchema.parse(JSON.parse(raw));
-        return isPermissionMode(parsed.previousPermissionMode)
-            ? parsed.previousPermissionMode
-            : null;
+        if (typeof parsed.previousPermissionMode !== 'string')
+            return null;
+        return parsePermissionMode(parsed.previousPermissionMode);
     }
     catch {
         return null;
@@ -157,7 +181,9 @@ export function getGlobalDefaultMode(homeDir = homedir()) {
     try {
         const raw = readFileSync(path, 'utf8');
         const parsed = globalConfigSchema.parse(JSON.parse(raw));
-        return isPermissionMode(parsed.defaultPermissionMode) ? parsed.defaultPermissionMode : null;
+        if (typeof parsed.defaultPermissionMode !== 'string')
+            return null;
+        return parsePermissionMode(parsed.defaultPermissionMode);
     }
     catch {
         return null;

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

@@ -29,6 +29,7 @@
  * `/quit` confirmation and `/help` footer - never inline.
  */
 import { listRoles } from '../agents/registry.js';
+import { PERMISSION_MODES, parsePermissionMode, } from '../permissions/index.js';
 /**
  * Deterministic stub copy returned by the Tier 3 commands. Spec'd
  * inline so the unit test can pin the exact text without poking at
@@ -86,7 +87,7 @@ export const SLASH_COMMAND_HELP = Object.freeze([
     // 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)  (also: /plan)', group: 'Settings' },
+    { name: 'permissions', args: '[mode] [--persist]', gloss: 'Show or flip permission mode (default / acceptEdits / plan / auto / dontAsk / bypassPermissions)  (also: /plan, Shift+Tab cycle)', group: 'Settings' },
     { name: 'plan', args: '[--back | --persist] [<prompt>]', gloss: 'Switch to plan mode (read-only). Same as /permissions plan, slicker UX.', group: 'Settings' },
     { name: 'model', args: '[<slug>]', gloss: 'Show or select the active model. Bare /model lists tier-gated options', group: 'Settings' },
     { name: 'budget', args: '', gloss: 'Show usage budget', group: 'Settings', stub: true },
@@ -332,26 +333,29 @@ export function parseSlashCommand(input) {
         }
         case 'permissions':
         case 'perms': {
-            // Leak L6: `/permissions [mode] [--persist] [--confirm]`.
+            // Wave 7: `/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                                        -> show + table
+            //   /permissions default|acceptEdits|plan|auto|dontAsk  -> flip mode
+            //   /permissions bypassPermissions --confirm            -> flip to
+            //                                     bypassPermissions (refused
+            //                                     без --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.
+            // α6 aliases (`ask`, `allow`, `bypass`) are accepted и mapped to
+            // their Wave 7 canonical names via `parsePermissionMode`.
             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') {
+            const headRaw = tokens[0] ?? '';
+            const mode = parsePermissionMode(headRaw);
+            if (!mode) {
+                const modeList = [...PERMISSION_MODES].join('|');
                 return {
                     kind: 'error',
-                    message: `Usage: /permissions [plan|ask|allow|bypass] [--persist] [--confirm]; unknown mode '${tokens[0] ?? ''}'`,
+                    message: `Usage: /permissions [${modeList}] [--persist] [--confirm]; unknown mode '${headRaw}'`,
                 };
             }
             const flags = tokens.slice(1);
@@ -371,7 +375,7 @@ export function parseSlashCommand(input) {
                     };
                 }
             }
-            return { kind: 'permissions', mode: head0, persist, confirmBypass };
+            return { kind: 'permissions', mode, persist, confirmBypass };
         }
         case 'init': {
             // β1 Sl11: surface the init flow inside the REPL. Tail args

package/dist/core/session.js

@@ -62,6 +62,54 @@ export async function fireSessionStartMvp(session) {
         return 0;
     }
 }
+/**
+ * Wave 7 P1 — fire the v2 `SessionStart` event from `~/.pugi/hooks.json`
+ * (global) + `<workspaceRoot>/.pugi/hooks.json` (project). Companion to
+ * `fireSessionStartMvp`; both surfaces run because they read different
+ * config files.
+ *
+ * Headless by default (no trust prompt) — the v2 trust ledger gates
+ * first-run executions. Operators with no prior trust decision will see
+ * the SessionStart hook skipped with a `denied by trust ledger` stderr
+ * note; running `pugi hooks trust allow <command>` enrolls it.
+ *
+ * Returns the number of hooks that ran (excluding trust-denied skips).
+ * Never throws.
+ */
+export async function fireSessionStartV2(session) {
+    try {
+        const { fireSessionStart } = await import('./hooks/v2/index.js');
+        const outcome = await fireSessionStart({
+            sessionId: session.id,
+            workspaceRoot: session.root,
+            transcriptPath: session.eventsPath,
+            permissionMode: 'ask',
+        });
+        return outcome.results.filter((r) => r.exitCode !== -1).length;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Wave 7 P1 — fire the v2 `SessionEnd` event. Called by the REPL
+ * teardown path. Companion to `fireSessionStartV2`.
+ */
+export async function fireSessionEndV2(session) {
+    try {
+        const { fireSessionEnd } = await import('./hooks/v2/index.js');
+        const outcome = await fireSessionEnd({
+            sessionId: session.id,
+            workspaceRoot: session.root,
+            transcriptPath: session.eventsPath,
+            permissionMode: 'ask',
+        });
+        return outcome.results.filter((r) => r.exitCode !== -1).length;
+    }
+    catch {
+        return 0;
+    }
+}
 export function recordCommandStarted(session, command) {
     if (!session.enabled)
         return;

package/dist/runtime/cli.js

@@ -755,7 +755,7 @@ async function dispatchRewind(args, flags, _session) {
 async function dispatchPermissions(args, flags, _session) {
     const head = args[0];
     if (head && parsePermissionMode(head) === null) {
-        writeOutput(flags, { error: 'unknown_mode', mode: head }, `Unknown mode '${head}'. Allowed: plan, ask, allow, bypass.`);
+        writeOutput(flags, { error: 'unknown_mode', mode: head }, `Unknown mode '${head}'. Allowed: default, acceptEdits, plan, auto, dontAsk, bypassPermissions (α6 aliases ask/allow/bypass accepted).`);
         process.exitCode = 1;
         return;
     }
@@ -780,8 +780,8 @@ async function dispatchPermissions(args, flags, _session) {
             await runPermissionsCommand({
                 mode: chosen,
                 persist: Boolean(flags.persist),
-                // The picker selection IS the confirm gesture for `bypass`.
-                confirmBypass: chosen === 'bypass' ? true : Boolean(flags.confirm),
+                // The picker selection IS the confirm gesture for `bypassPermissions`.
+                confirmBypass: chosen === 'bypassPermissions' ? true : Boolean(flags.confirm),
             }, {
                 workspaceRoot: process.cwd(),
                 writeOutput: (text) => writeOutput(flags, { text }, text),
@@ -1524,7 +1524,7 @@ function parseArgs(argv) {
         else if (arg === '--mode') {
             const next = argv[index + 1];
             if (!next || next.startsWith('--')) {
-                throw new Error('--mode requires plan|ask|allow|bypass');
+                throw new Error('--mode requires default|acceptEdits|plan|auto|dontAsk|bypassPermissions (α6 aliases ask|allow|bypass accepted)');
             }
             flags.mode = next;
             index += 1;

package/dist/runtime/commands/mcp.js

@@ -10,7 +10,9 @@ import { loadMcpRegistry, mcpLogPath } from '../../core/mcp/registry.js';
 import { listMcpTrust, setMcpTrust } from '../../core/mcp/trust.js';
 import { createPugiMcpServer, serveStdio } from '../../core/mcp/server.js';
 import { buildPugiMcpTools } from '../../core/mcp/server-tools.js';
+import { buildOrchestratorTools } from '../../core/mcp/orchestrator-tools.js';
 import { serveHttp } from '../../core/mcp/http-server.js';
+import { resolveActiveCredential, DEFAULT_API_URL } from '../../core/credentials.js';
 import { listMcpPermissions, clearMcpPermission, } from '../../core/mcp/permission.js';
 export async function runMcpCommand(args, ctx) {
     const sub = args[0] ?? 'list';
@@ -74,6 +76,15 @@ const USAGE_LINES = [
     '    --allow-write               Expose edit/write (default off — explicit opt-in).',
     '    --allow-bash                Expose the bash tool (default off — explicit opt-in).',
     '    --no-bash                   Deprecated alias (bash is already off by default).',
+    '    --orchestrator              Expose pugi.run / pugi.read / pugi.write /',
+    '                                pugi.dispatch / pugi.publish / pugi.deploy instead of',
+    '                                the engine surface. Designed for external Claude Code',
+    '                                / Cursor sessions driving fix-publish-test loops.',
+    '                                Each tool family is gated by an env switch:',
+    '                                  PUGI_MCP_EXEC_ENABLED=1     enables pugi.run',
+    '                                  PUGI_MCP_PUBLISH_ENABLED=1  enables pugi.publish',
+    '                                  PUGI_MCP_DEPLOY_ENABLED=1   enables pugi.deploy',
+    '                                  PUGI_MCP_WORKSPACE_ROOT=... overrides cwd for path validation',
     '  perms list                    Show cached per-(server, tool) decisions',
     '  perms reset <server>:<tool>   Forget one cached decision',
 ];
@@ -536,16 +547,23 @@ async function runMcpServe(args, ctx) {
     const readOnly = flags.readOnly === true;
     const writeAllowed = !readOnly && flags.writeAllowed;
     const bashAllowed = !readOnly && flags.bashAllowed;
-    const tools = buildPugiMcpTools(toolCtx, {
-        bashAllowed,
-        // Keep the legacy contract: `readOnly` for the tool-builder means
-        // "do not advertise edit/write tools". Bash advertisement is gated
-        // by the independent `bashAllowed` knob. So the builder sees
-        // `readOnly = true` whenever the operator did not opt into write
-        // explicitly, which preserves the deny-by-default surface for
-        // edit/write but no longer accidentally suppresses bash.
-        readOnly: readOnly || !writeAllowed,
-    });
+    // Wave 7 P1 — when `--orchestrator` is set the surface swaps to the
+    // CLI-orchestrator family (pugi.run / pugi.read / pugi.write /
+    // pugi.dispatch / pugi.publish / pugi.deploy). The engine surface is
+    // intentionally dropped — the two are mutually exclusive on the wire
+    // to keep tool-name resolution unambiguous on the consumer side.
+    const tools = flags.orchestrator
+        ? buildOrchestratorTools(buildOrchestratorContext(ctx.workspaceRoot))
+        : buildPugiMcpTools(toolCtx, {
+            bashAllowed,
+            // Keep the legacy contract: `readOnly` for the tool-builder means
+            // "do not advertise edit/write tools". Bash advertisement is gated
+            // by the independent `bashAllowed` knob. So the builder sees
+            // `readOnly = true` whenever the operator did not opt into write
+            // explicitly, which preserves the deny-by-default surface for
+            // edit/write but no longer accidentally suppresses bash.
+            readOnly: readOnly || !writeAllowed,
+        });
     // β4 r1 P1 #2 — deny-by-default permissionGate. The MCP cache + FSM
     // are consulted on every dispatch; allow_always-cached entries pass
     // silently, allow_once entries pass and self-clear, deny entries
@@ -604,6 +622,7 @@ async function runMcpServe(args, ctx) {
             command: 'mcp.serve',
             transport: 'http',
             url: handle.url,
+            surface: flags.orchestrator ? 'orchestrator' : 'engine',
             bearerTokenSource: handle.bearerTokenAutoGenerated
                 ? 'auto-generated (see stderr)'
                 : explicitToken === envToken
@@ -649,7 +668,7 @@ async function runMcpServe(args, ctx) {
     // the wire; nothing is printed unless the parent agent sends a
     // request that returns a response. Operator sees one info line on
     // stderr so they know the server is up.
-    process.stderr.write(`pugi-mcp (stdio): ${tools.length} tool(s) — ${tools.map((t) => t.name).join(', ')}\n`);
+    process.stderr.write(`pugi-mcp (stdio, ${flags.orchestrator ? 'orchestrator' : 'engine'}): ${tools.length} tool(s) — ${tools.map((t) => t.name).join(', ')}\n`);
     await serveStdio({
         server,
         stdin: ctx.stdin ?? process.stdin,
@@ -665,6 +684,7 @@ function parseServeFlags(args) {
         readOnly: false,
         writeAllowed: false,
         bashAllowed: false,
+        orchestrator: false,
     };
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i] ?? '';
@@ -722,6 +742,9 @@ function parseServeFlags(args) {
             // so existing operator scripts do not error.
             flags.bashAllowed = false;
         }
+        else if (arg === '--orchestrator') {
+            flags.orchestrator = true;
+        }
         else if (arg === '--help') {
             // Caller renders USAGE_LINES. We surface the same via top-level
             // dispatch — nothing to do here, just don't error.
@@ -755,9 +778,41 @@ function buildServePermissionGate(opts) {
             return false;
         if (tool.permission === 'edit' && !opts.writeAllowed)
             return false;
+        // `network` is the permission class used by orchestrator tools
+        // (pugi.dispatch / pugi.publish / pugi.deploy). The env capability
+        // gates inside each tool's `execute` body provide the per-family
+        // kill switch, so the serve-time gate is permissive here. The
+        // server's overall `permissionGate` is already deny-most-other —
+        // adding a third boolean knob (`networkAllowed`) would create more
+        // ways to misconfigure than to protect. Wave 7 P1 (2026-05-28).
         return true;
     };
 }
+/**
+ * Build the OrchestratorToolContext for `pugi mcp serve --orchestrator`.
+ * Reads from process.env + the credentials store. Encapsulated so tests
+ * never need to mock the resolveActiveCredential path — they call
+ * `buildOrchestratorTools` directly with a hand-rolled context.
+ *
+ * Wave 7 P1 (2026-05-28).
+ */
+function buildOrchestratorContext(workspaceRoot) {
+    const envRoot = process.env.PUGI_MCP_WORKSPACE_ROOT;
+    const root = envRoot && envRoot.length > 0 ? resolve(envRoot) : workspaceRoot;
+    const credential = resolveActiveCredential();
+    return {
+        workspaceRoot: root,
+        pugiBin: process.env.PUGI_MCP_PUGI_BIN ?? 'pugi',
+        apiUrl: credential?.apiUrl ?? DEFAULT_API_URL,
+        apiKey: credential?.apiKey ?? null,
+        capabilities: {
+            exec: process.env.PUGI_MCP_EXEC_ENABLED === '1',
+            publish: process.env.PUGI_MCP_PUBLISH_ENABLED === '1',
+            deploy: process.env.PUGI_MCP_DEPLOY_ENABLED === '1',
+        },
+        sshAlias: process.env.PUGI_MCP_SSH_ALIAS ?? 'codeforge',
+    };
+}
 function parseHttpBinding(input) {
     // Accept `:7100`, `7100`, or `host:7100`.
     let host = '127.0.0.1';

package/dist/runtime/commands/permissions.js

@@ -29,9 +29,10 @@ export async function runPermissionsCommand(command, ctx) {
         renderModeTable(ctx);
         return;
     }
-    if (command.mode === 'bypass' && !command.confirmBypass) {
-        ctx.writeOutput('Bypass mode disables policy hooks (skill steering, denial tracking).');
-        ctx.writeOutput('Run `/permissions bypass --confirm` to acknowledge before flipping.');
+    if (command.mode === 'bypassPermissions' && !command.confirmBypass) {
+        ctx.writeOutput('bypassPermissions disables policy hooks (skill steering, denial tracking) AND skips the deny-list.');
+        ctx.writeOutput('Catastrophic patterns (rm -rf /, fork bomb, dd if=/) still trip the circuit-breaker, но that is the only guardrail left.');
+        ctx.writeOutput('Run `/permissions bypassPermissions --confirm` to acknowledge before flipping.');
         return;
     }
     setCurrentMode(ctx.workspaceRoot, command.mode);
@@ -42,8 +43,8 @@ export async function runPermissionsCommand(command, ctx) {
         ? ' Persisted to ~/.pugi/config.json for future sessions.'
         : '';
     ctx.writeOutput(`Permission mode set to '${command.mode}'.${persistedHint} ${PERMISSION_MODE_GLOSS[command.mode]}`);
-    if (command.mode === 'bypass') {
-        ctx.writeOutput('BYPASS MODE — all tools execute without prompts AND policy hooks disabled. Switch back with /permissions allow.');
+    if (command.mode === 'bypassPermissions') {
+        ctx.writeOutput('bypassPermissions — all tools execute without prompts AND policy hooks disabled (circuit-breaker still trips on rm -rf /). Switch back with /permissions dontAsk.');
     }
 }
 /**
@@ -68,12 +69,13 @@ function renderCurrentMode(ctx) {
  */
 function renderModeTable(ctx) {
     ctx.writeOutput('');
-    ctx.writeOutput('Permission modes:');
+    ctx.writeOutput('Permission modes (Shift+Tab cycles in REPL):');
     for (const mode of PERMISSION_MODES) {
-        ctx.writeOutput(`  ${mode.padEnd(7)}  ${PERMISSION_MODE_GLOSS[mode]}`);
+        // Wave 7: longest canonical name is `bypassPermissions` (17 chars).
+        ctx.writeOutput(`  ${mode.padEnd(18)}  ${PERMISSION_MODE_GLOSS[mode]}`);
     }
     ctx.writeOutput('');
-    ctx.writeOutput('Switch with `/permissions <mode> [--persist]`. Bypass requires `--confirm`.');
+    ctx.writeOutput('Switch with `/permissions <mode> [--persist]`. bypassPermissions requires `--confirm`.');
 }
 /**
  * Render the one-shot banner shown on session boot when the effective
@@ -82,7 +84,7 @@ function renderModeTable(ctx) {
  * but the caller is responsible for the once-only semantics.
  */
 export function renderBypassBanner(writeOutput) {
-    writeOutput('BYPASS MODE — all tools execute without prompts AND policy hooks disabled. Switch back with /permissions allow.');
+    writeOutput('bypassPermissions — all tools execute without prompts AND policy hooks disabled (circuit-breaker still trips on rm -rf /). Switch back with /permissions dontAsk.');
 }
 /**
  * Resolve the effective mode + the layered source label used by the