@bike4mind/cli 0.18.5 → 0.20.0

package/LICENSE

@@ -9,7 +9,7 @@ Parameters
 
 Licensor:             Bike4Mind, Inc.
 
-Licensed Work:        Bike4Mind (the lumina5 repository and the components
+Licensed Work:        Bike4Mind (this repository and the components
                       distributed under this License).
                       The Licensed Work is (c) 2026 Bike4Mind, Inc.
 

package/README.md

@@ -70,26 +70,74 @@ The CLI will prompt you to authenticate with your Bike4Mind account on first run
 ### CLI Flags
 
 ```bash
-b4m [options]
+b4m [options] ["initial prompt"]
 ```
 
-**Available flags:**
-- `--dev` - Point the CLI at the local dev server (`http://localhost:3001`) and remember it
-- `--prod` - Point the CLI at Bike4Mind production and remember it
-- `--verbose`, `-v` - Show debug logs in console (useful for troubleshooting)
-- `--help`, `-h` - Show help information
-- `--version`, `-V` - Show CLI version
+A bare positional argument seeds **and** submits the first turn while keeping the interactive UI open (e.g. `b4m "summarize the git log"`).
+
+**Environment / API** (see [API Configuration](#api-configuration)):
+
+| Flag | Effect |
+| --- | --- |
+| `--dev` | Point the CLI at the local dev server (`http://localhost:3001`) and remember it. Aliases: `--local`, single-dash forms. |
+| `--prod` | Point the CLI at Bike4Mind production and remember it. Alias: `--production`. |
+| `--api-url <url>` | Point the CLI at **any** instance — a self-hosted stack, an AWS deployment, `http://localhost:3000`, etc. Clears cached auth (bound to the old origin) and exits; run `b4m` again to sign in. |
+| `--reset-api` | Reset the API URL to the built-in default and clear auth, then exit. |
+
+**Session / behavior:**
+
+| Flag | Effect |
+| --- | --- |
+| `--verbose`, `-v` | Show debug logs in the console (also always written to file — see [Debug Logs](#debug-logs)). |
+| `--debug-stream` | Ultra-verbose: log every SSE event (stream-parser debugging). Implies `--verbose`. |
+| `--no-project-config` | Skip loading project-specific config (`.bike4mind/`). |
+| `--add-dir <dir>` | Grant file access to an additional directory. Repeatable. |
+| `--ollama-host <url>` | Add a local Ollama endpoint's models to the picker (e.g. `http://localhost:11434`). |
+| `--no-remote-skills` | Skip fetching remote B4M-web skills for this run (local files only). |
+
+**Headless / non-interactive** (for scripts and CI):
+
+| Flag | Effect |
+| --- | --- |
+| `-p`, `--prompt <query>` | Run a single query non-interactively and exit. |
+| `--output-format <fmt>` | Output when using `-p`: `text` (default), `json`, or `stream-json` (NDJSON of thoughts/actions/observations). |
+| `--dangerously-skip-permissions` | With `-p`, auto-allow all tool permission prompts. Use with caution in CI/CD. |
+
+**Info:**
+
+| Flag | Effect |
+| --- | --- |
+| `--help`, `-h` | Show help. |
+| `--version`, `-V` | Show CLI version. |
+
+> **Host / `claude`-drop-in flags** (`--mcp-config`, `--strict-mcp-config`, `--append-system-prompt`, `--allowedTools`, `--settings`, `--session-id`, `--resume`) are documented under [Running as a `claude` engine inside a host app](#running-as-a-claude-engine-inside-a-host-app).
 
 **Examples:**
 ```bash
+# Point at a self-hosted stack, then sign in
+b4m --api-url http://localhost:3000
+b4m
+
+# One-shot headless query, JSON output
+b4m -p "What is 2+2?" --output-format json
+
 # Run with debug logs visible
 b4m --verbose
 
-# Check version
-b4m --version
+# Seed and submit the first turn, stay interactive
+b4m "review the recent changes"
+```
 
-# Show help
-b4m --help
+### Subcommands
+
+```bash
+b4m mcp list                              # List configured MCP servers
+b4m mcp add <name> -- <command...>        # Add an MCP server
+b4m mcp remove <name>                     # Remove an MCP server
+b4m mcp enable <name> | disable <name>    # Toggle a server on/off
+b4m mcp serve [--http] [--port <n>]       # Expose Bike4Mind itself as an MCP server
+b4m update                                # Check for and install CLI updates
+b4m doctor                                # Diagnose the CLI installation (Node, registry, ripgrep, native modules)
 ```
 
 ### Switching environments (`--dev` / `--prod`)
@@ -116,31 +164,64 @@ shown in the startup banner (`🌍 API Environment: …`).
 
 ## Commands
 
-While in interactive mode:
+While in interactive mode. This mirrors the registry in `src/config/commands.ts` — run `/help` in a session for the live list (which also includes any custom and project commands).
 
 **Authentication:**
 - `/login` - Authenticate with your B4M account
 - `/logout` - Clear authentication and sign out
 - `/whoami` - Show current authenticated user
 
-**Session Management:**
+**Session management:**
 - `/save <name>` - Save current session
-- `/resume` - List and resume saved sessions
-
-**API Configuration:**
-- `/set-api <url>` - Connect to self-hosted Bike4Mind instance
-- `/reset-api` - Reset to Bike4Mind main service
+- `/resume` (alias `/sessions`) - List and resume saved sessions
+- `/clear` (alias `/new`) - Start a new session
+- `/compact [instructions]` - Compact the conversation into a new session
+- `/context` - Show context-window usage
+- `/usage` - Show credit usage and balance
+
+**API configuration:**
+- `/set-api <url>` - Connect to a self-hosted / custom Bike4Mind instance
+- `/reset-api` - Reset to the Bike4Mind main service
 - `/api-info` - Show current API configuration
 
-**Tool Permissions:**
-- `/trust <tool-name>` - Trust a tool (won't ask permission again)
-- `/untrust <tool-name>` - Remove tool from trusted list
-- `/trusted` - List all trusted tools
+**Files & checkpoints:**
+- `/add-dir <path>` / `/remove-dir <path>` / `/dirs` - Manage accessible directories
+- `/undo` - Undo the last file change
+- `/checkpoints` - List file restore points
+- `/restore <number>` - Restore files to a checkpoint
+- `/diff [number]` - Diff current state against a checkpoint
+- `/rewind` - Rewind the conversation to a previous point
+
+**Tool permissions:**
+- `/trust <tool-name>` / `/untrust <tool-name>` / `/trusted` - Manage auto-approved tools
+
+**Sandbox** (OS-level isolation for `bash`):
+- `/sandbox` - Show sandbox status and configuration
+- `/sandbox:enable` / `/sandbox:disable` - Toggle the sandbox
+- `/sandbox:mode <auto-allow|permissions>` - Set enforcement mode
+- `/sandbox:trust-domain <domain> [...]` / `/sandbox:domains` - Manage the network allowlist
+- `/sandbox:violations [count]` / `/sandbox:violations:clear` - Inspect / clear violations
+
+**MCP & agents:**
+- `/mcp` (alias `/mcp:list`) - Show MCP server status and connected tools
+- `/agents` (alias `/agents:list`) - List available agents
+- `/agents:new <name>` / `/agents:reload` - Create / reload agent definitions
+
+**Custom commands:**
+- `/commands` - List all custom commands
+- `/commands:new <name>` / `/commands:reload` - Create / reload custom commands
+
+**Durable workflow** (cross-session continuity):
+- `/workflow [decisions|blockers|handoff|review-gates]` - Workflow overview or a section
+- `/decisions` / `/blockers` / `/review-gates` - Shortcuts for the sections above
+- `/handoff [generate|--local]` - Show or generate a session handoff (`--local` = LLM-free snapshot)
 
 **General:**
 - `/help` - Show help
-- `/exit` - Exit CLI
-- `/config` - Show configuration
+- `/config` - Open the interactive configuration editor
+- `/project-config` - Show merged project configuration
+- `/terminal-setup` - Configure Shift+Enter for multi-line input
+- `/exit` (alias `/quit`) - Exit the CLI
 
 ## Configuration
 
@@ -164,31 +245,43 @@ The default is baked in at build time from the hosted build environment — ther
 fallback in source** (open-core, #9306/#9392), so a fresh clone ships empty. A fork publishes its
 own CLI by setting `B4M_DEFAULT_API_URL` when building — see `tsdown.config.ts`.
 
+Because that default is injected only at build time, the endpoint is resolved like this:
+
+1. A **custom URL** you set (`--api-url` / `--dev` / `--prod` / `/set-api`) always wins.
+2. Otherwise, the **build-time default** baked into a published binary.
+3. Otherwise, when running **from source** (a `pnpm link --global` checkout, `pnpm dev` — no
+   `dist/` built), the CLI defaults to the local dev server `http://localhost:3001`. Use
+   `--prod` / `--api-url` to point it elsewhere.
+4. Otherwise (a published, unbranded fork with no baked default), the first `b4m` **prompts you
+   to choose a backend**.
+
 **Quick switch between local dev and production:** use the `b4m --dev` / `b4m --prod`
 launch flags (see [Switching environments](#switching-environments---dev----prod)).
 They persist your choice and cache auth per-environment. The `/set-api`, `/reset-api`,
 and `/api-info` commands below operate on the same setting from inside a session.
 
-**For Self-Hosted Instances:**
-
-If your organization runs a self-hosted Bike4Mind instance, connect to it using:
+**For self-hosted / custom instances:**
 
-```bash
-/set-api https://app.your-instance.example.com
-```
+The CLI can point at **any** Bike4Mind deployment — a self-hosted Docker stack, an AWS deployment, or `http://localhost:3000` — because auth (the OAuth device flow) and the chat API ship in the open core and are served by that instance directly.
 
-To return to the main Bike4Mind service:
+From the launch line (clears auth, then exit — run `b4m` again to sign in):
 
 ```bash
-/reset-api
+b4m --api-url http://localhost:3000              # local self-host Docker stack
+b4m --api-url https://app.your-instance.example.com
+b4m --reset-api                                  # back to the built-in default
 ```
 
-Check your current API configuration:
+Or from inside a session:
 
 ```bash
-/api-info
+/set-api https://app.your-instance.example.com
+/reset-api    # return to the default service
+/api-info     # show the current API configuration
 ```
 
+Auth tokens are cached **per environment**, so switching between hosted and self-host does not force a re-login. For an end-to-end walkthrough (hosted **and** self-host, sign-in, credits, troubleshooting), see the top-level [**BIKE4MIND_CLI.md**](../../BIKE4MIND_CLI.md).
+
 ### Tool API Keys
 
 Some built-in tools require API keys to function. Add them to `~/.bike4mind/config.json`:
@@ -297,6 +390,77 @@ You can also run any MCP server via npx or custom executables:
 
 **Note:** Internal MCP servers must be built and available in the `b4m-core/packages/mcp/dist/src/` directory. The CLI will automatically find them if you're running from the monorepo. For Docker-based servers, ensure Docker is installed and the image is accessible.
 
+#### Serve Bike4Mind itself as an MCP server (`b4m mcp serve`)
+
+The reverse of adding a server: `b4m mcp serve` exposes your Bike4Mind backend to any MCP client (Claude Desktop, editors, other agents). It advertises eight tools (`list_notebooks`, `get_notebook`, `create_notebook`, `send_message`, `search_knowledge_base`, `list_files`, `get_file`, `generate_sound_effect`) plus four resource templates (`b4m://notebook/{id}`, `b4m://file/{id}`, `b4m://project/{id}`, `b4m://artifact/{id}`), each listable and readable as JSON, and `b4m://agent-quest` - the credential-free manifest for The Open Door, the onboarding quest for agents.
+
+```bash
+b4m mcp serve                        # stdio (default) - for local clients that spawn the process
+b4m mcp serve --http --port 7000     # stateless streamable HTTP at http://127.0.0.1:7000/mcp
+```
+
+Auth precedence is `--api-key` > `B4M_API_KEY` > the stored login; the endpoint is `B4M_API_URL` > `--api-url` > the configured backend. Tool *listing* needs no credentials; tool *calls* authenticate. Prefer `B4M_API_KEY` over `--api-key` (a flag value shows up in process listings). HTTP mode binds loopback only (`127.0.0.1`, `/mcp` path) and has no per-request auth, so do not expose it off-host. The advertised scopes are the recommended key configuration, not per-route hard gates. See [Serve Bike4Mind as an MCP server](../../BIKE4MIND_CLI.md#serve-bike4mind-as-an-mcp-server-b4m-mcp-serve) for the Claude Desktop config and details.
+
+## Plugins
+
+The CLI can load external feature modules at runtime. A plugin is an npm package that adds tools, a system-prompt section, slash commands, and (optionally) WebSocket handlers to the interactive session, without any change to the CLI itself.
+
+```bash
+b4m plugin add @someone/b4m-plugin-foo     # install from npm
+b4m plugin add github:user/b4m-plugin-foo  # install from GitHub
+b4m plugin add file:/path/to/local/plugin  # install a local directory (development/QA)
+b4m plugin list                            # show installed plugins and their state
+b4m plugin remove foo                      # uninstall and disable
+```
+
+Plugins install to `~/.bike4mind/plugins/` and are gated by a `features` toggle in your config: `add` enables it for you, and every installed plugin also shows up automatically in the `/config` editor. A newly installed plugin loads the next time you start `b4m`; toggling an already-installed plugin in `/config` hot-reloads it in place.
+
+### Writing a plugin
+
+A plugin declares itself with a `b4m-plugin` field in its `package.json`:
+
+```json
+{
+  "name": "@someone/b4m-plugin-foo",
+  "type": "module",
+  "b4m-plugin": { "entry": "./dist/index.js", "configKey": "foo" }
+}
+```
+
+`entry` (required) is the module the CLI imports, resolved inside the package. `configKey` (optional, defaults to the package name) is the `features` key that gates the plugin.
+
+The entry default-exports a factory. It receives a context (currently `{ logger }`, with `debug/info/warn/error` methods that write to the CLI debug log) and returns the module object:
+
+```js
+export default ctx => ({
+  name: 'foo',                       // unique module name
+  description: 'What this plugin does',
+  getTools: () => [
+    {
+      toolFn: async args => 'result',   // invoked when the agent calls the tool
+      toolSchema: {
+        name: 'foo_tool',
+        description: 'What the tool does',
+        parameters: { type: 'object', properties: {} },  // JSON Schema
+      },
+    },
+  ],
+  getSystemPromptSection: () => 'Extra system-prompt text (or an empty string)',
+  getCommands: () => [{ name: 'foo', description: '...', execute: args => {} }],  // optional
+  registerWsHandlers: wsManager => {},  // optional
+  dispose: () => {},                    // optional, runs on exit/disable
+});
+```
+
+Tool objects are written out structurally as shown - plugin packages cannot import `@bike4mind/*` packages at runtime (those are bundled into the CLI binary and are not on npm in a compatible form). See `test/fixtures/b4m-plugin-example/` in this package for a complete working plugin.
+
+### Limitations and trust
+
+- **Plugins run in-process with your privileges.** Installing one runs its npm install scripts, and enabling it executes its code inside the CLI, same as configuring an MCP server command. Only install plugins you trust.
+- **Interactive mode only.** Headless (`b4m -p`) and ACP sessions do not load feature modules or plugins today.
+- **Downgrade caveat:** CLI versions without plugin support strip plugin keys from the config `features` map on their next save; re-enable after upgrading again.
+- A plugin that fails to load (bad manifest, import error, malformed tools) is skipped with a warning at startup - it never blocks the CLI. `b4m plugin list` shows the reason.
+
 ## Git-Aware Code Search
 
 The CLI includes a `recent_changes` tool that uses git history to find recently modified files. This significantly speeds up debugging by narrowing the search space to recently changed code.
@@ -459,6 +623,11 @@ b4m --version
 
 After step 4, running `b4m` anywhere on your system executes this working tree. Re-run `pnpm link --global` if you move or rename the repo.
 
+> **Which backend does a linked checkout talk to?** A source/linked run has no build-time
+> default baked in, so `b4m` defaults to the local dev server (`http://localhost:3001`) — start
+> your local stack, or point it elsewhere with `b4m --prod` / `b4m --api-url <url>`. See
+> [API Configuration](#api-configuration) for the full resolution order.
+
 ### Editing CLI source (`packages/cli/src/`)
 
 Just run `b4m`. The bin's `tsx` fallback picks up your edits on the next invocation — no build step needed.
@@ -547,7 +716,7 @@ packages/cli/
 │   │   └── ConfigStore.ts
 │   └── index.tsx         # Main entry point
 └── bin/
-    └── bike4mind-cli.js  # Executable
+    └── bike4mind-cli.mjs  # Executable (source/dist auto-detect + flag parsing)
 ```
 
 ## Dependencies

package/bin/bike4mind-cli.mjs

@@ -1,19 +1,15 @@
 #!/usr/bin/env node
  
 
-// This is the executable entry point for the CLI
-// In development, it will use tsx to run the TypeScript directly
-// In production, it will run the compiled JavaScript
+// Executable entry point for the CLI: tsx runs the TypeScript source in dev,
+// the compiled JavaScript in production.
 
-// Suppress punycode deprecation warning from dependencies
-// This is a known issue with older npm packages using Node's built-in punycode
+// Suppress punycode deprecation warning from older deps using Node's built-in punycode.
 process.removeAllListeners('warning');
 process.on('warning', (warning) => {
-  // Only suppress punycode deprecation warnings
   if (warning.name === 'DeprecationWarning' && warning.message.includes('punycode')) {
     return;
   }
-  // Show all other warnings
   console.warn(warning);
 });
 
@@ -37,7 +33,7 @@ const { version: cliVersion } = require('../package.json');
 // Intercept these BEFORE yargs parses argv. They're accepted with either a
 // single or double dash (e.g. `b4m -prod` and `b4m --prod` both work), but
 // single-dash multi-char tokens would otherwise be split into clustered short
-// flags by yargs (`-prod` → `-p -r -o -d`, colliding with -p/--prompt). We pull
+// flags by yargs (`-prod` -> `-p -r -o -d`, colliding with -p/--prompt). We pull
 // them out here, record the target, and strip them so yargs sees a clean argv.
 const ENV_FLAG_MAP = {
   '--dev': 'dev', '-dev': 'dev', '--local': 'dev', '-local': 'dev',
@@ -57,14 +53,13 @@ let envTarget = null;
   process.argv = [process.argv[0], process.argv[1], ...cleaned];
 }
 
-// Parse CLI arguments
 const argv = await yargs(hideBin(process.argv))
   // --dev / --prod are declared here ONLY so they appear in `--help`. The actual
-  // handling is the pre-yargs argv interception above — these yargs-side values
+  // handling is the pre-yargs argv interception above - these yargs-side values
   // (`argv.dev` / `argv.prod`) are never read.
   .option('dev', {
     type: 'boolean',
-    description: 'Point the CLI at the local dev server (http://localhost:3001) and remember it',
+    description: 'Point the CLI at the local dev server (http://localhost:3000) and remember it',
   })
   .option('prod', {
     type: 'boolean',
@@ -107,13 +102,17 @@ const argv = await yargs(hideBin(process.argv))
     description: 'When using -p, auto-allow all tool permission prompts (use with caution in CI/CD)',
     default: false,
   })
+  .option('permission-policy', {
+    type: 'string',
+    description: 'When using -p, path to a JSON permission policy for unattended runs (allow/deny/risk rules)',
+  })
   .option('ollama-host', {
     type: 'string',
     description: 'Add local Ollama models to the model picker (e.g. http://localhost:11434)',
   })
-  // ─── claude-compatible flags (host drop-in masquerade) ──────────────────────
-  // Declared so a host's claude launch flags parse into named options instead of
-  // leaking into the positional `argv._` task. See packages/cli README "host app".
+  // claude-compatible flags (host drop-in masquerade). Declared so a host's
+  // claude launch flags parse into named options instead of leaking into the
+  // positional `argv._` task. See packages/cli README "host app".
   .option('mcp-config', {
     type: 'string',
     description: 'Path to a JSON file of MCP servers to inject ({ "mcpServers": {...} })',
@@ -198,10 +197,62 @@ const argv = await yargs(hideBin(process.argv))
       }, async () => {
         // Handled by external command handler
       })
-      .demandCommand(1, 'You must provide a subcommand (list, add, remove, enable, disable)');
+      .command('serve', 'Run Bike4Mind as an MCP server (stdio by default, or --http)', (yargs) => {
+        return yargs
+          .option('http', {
+            type: 'boolean',
+            description: 'Serve over streamable HTTP instead of stdio',
+            default: false,
+          })
+          .option('port', {
+            type: 'number',
+            description: 'Port for --http mode',
+            default: 7000,
+          })
+          .option('api-key', {
+            type: 'string',
+            description: 'Bike4Mind API key (overrides B4M_API_KEY and the stored login). Visible in process listings; prefer B4M_API_KEY',
+          })
+          .option('api-url', {
+            type: 'string',
+            description: 'Bike4Mind API URL (overrides B4M_API_URL and the configured backend)',
+          })
+          .example('b4m mcp serve', 'Serve over stdio for Claude Desktop and other local clients')
+          .example('b4m mcp serve --http --port 7000', 'Serve over streamable HTTP on port 7000');
+      }, async () => {
+        // Handled by external command handler
+      })
+      .demandCommand(1, 'You must provide a subcommand (list, add, remove, enable, disable, serve)');
+  })
+  .command('plugin', 'Manage B4M feature-module plugins', (yargs) => {
+    return yargs
+      .command('list', 'List installed plugins', {}, async () => {
+        // Handled by external command handler
+      })
+      .command('add <spec>', 'Install a plugin package', (yargs) => {
+        return yargs
+          .positional('spec', {
+            type: 'string',
+            describe: 'npm package, @scope/package, github:user/repo, or file:<path>',
+          })
+          .example('b4m plugin add @someone/b4m-plugin-foo', 'Install from npm')
+          .example('b4m plugin add github:user/b4m-plugin-foo', 'Install from GitHub');
+      }, async () => {
+        // Handled by external command handler
+      })
+      .command('remove <name>', 'Uninstall a plugin', (yargs) => {
+        return yargs.positional('name', {
+          type: 'string',
+          describe: 'Plugin name (config key, package name, or short name)',
+        });
+      }, async () => {
+        // Handled by external command handler
+      })
+      .demandCommand(1, 'You must provide a subcommand (list, add, remove)');
   })
   .command('update', 'Check for and install CLI updates')
   .command('doctor', 'Run diagnostic checks on CLI installation')
+  .command('acp', 'Run as an Agent Client Protocol (ACP) stdio server for editors like Zed')
   .help()
   .alias('help', 'h')
   .version(cliVersion)
@@ -238,8 +289,8 @@ if (argv['no-remote-skills']) {
   process.env.B4M_NO_REMOTE_SKILLS = '1';
 }
 
-// ─── claude-compatible flags → B4M_* env (read by src/index.tsx init) ─────────
-// Mirrors the established bin→env→init channel (cf. --add-dir → B4M_ADDITIONAL_DIRS).
+// claude-compatible flags -> B4M_* env (read by src/index.tsx init).
+// Mirrors the established bin->env->init channel (cf. --add-dir -> B4M_ADDITIONAL_DIRS).
 if (argv['mcp-config']) {
   process.env.B4M_MCP_CONFIG_FILE = resolve(argv['mcp-config']);
 }
@@ -266,7 +317,7 @@ if (argv.resume) {
 }
 // Positional task (claude `<prompt>` form): seeds AND submits turn 1, stays interactive.
 // Only when it's not a known subcommand and headless -p wasn't used.
-const KNOWN_SUBCOMMANDS = new Set(['mcp', 'update', 'doctor']);
+const KNOWN_SUBCOMMANDS = new Set(['mcp', 'plugin', 'update', 'doctor', 'acp']);
 if (argv.prompt === undefined && argv._.length > 0 && !KNOWN_SUBCOMMANDS.has(String(argv._[0]))) {
   process.env.B4M_INITIAL_PROMPT = String(argv._[0]);
 }
@@ -284,10 +335,21 @@ const hasDist = existsSync(distPath);
 const isDev = process.env.NODE_ENV === 'development' ||
               (!hasDist && hasSource);
 
+// Signal source mode to the app so endpoint resolution can default an
+// otherwise-unconfigured run to the local dev server (build-time brand
+// defaults are never injected into a source run). Set before any command
+// dispatch below so --reset-api messaging and the app both observe it.
+// See resolveApiEndpoint() / isSourceMode() in src/utils/apiUrl.ts.
+if (isDev) {
+  process.env.B4M_SOURCE_MODE = '1';
+}
+
 // Handle --api-url / --reset-api flags
 // These mutate ~/.bike4mind/config.json and exit before any auth flow runs,
 // so devs can recover from a misconfigured customUrl without editing JSON.
-if (argv['reset-api'] || argv['api-url'] !== undefined) {
+// `mcp serve` has its own ephemeral --api-url (points that one server at a
+// backend without touching config), so skip the mutate-and-exit path for it.
+if ((argv['reset-api'] || argv['api-url'] !== undefined) && argv._[0] !== 'mcp') {
   try {
     let handleApiCommand;
 
@@ -360,6 +422,7 @@ if (argv.prompt !== undefined) {
       dangerouslySkipPermissions: argv['dangerously-skip-permissions'] || false,
       verbose: argv.verbose || false,
       addDirs: rawAddDirs.map(d => resolve(d)),
+      permissionPolicyPath: argv['permission-policy'] ? resolve(argv['permission-policy']) : undefined,
     });
     // handleHeadlessCommand calls process.exit internally, but handle the case it doesn't
     process.exit(0);
@@ -397,6 +460,31 @@ if (argv._[0] === 'mcp') {
   }
 }
 
+// Handle plugin subcommands (external commands)
+if (argv._[0] === 'plugin') {
+  const pluginSubcommand = argv._[1];
+
+  try {
+    let handlePluginCommand;
+
+    if (isDev) {
+      const { register } = require('tsx/esm/api');
+      register();
+      const module = await import('../src/commands/pluginCommand.ts');
+      handlePluginCommand = module.handlePluginCommand;
+    } else {
+      const module = await import('../dist/commands/pluginCommand.mjs');
+      handlePluginCommand = module.handlePluginCommand;
+    }
+
+    await handlePluginCommand(pluginSubcommand, argv);
+    process.exit(0);
+  } catch (error) {
+    console.error('Error:', error.message);
+    process.exit(1);
+  }
+}
+
 // Handle update command (external command)
 if (argv._[0] === 'update') {
   try {
@@ -420,6 +508,31 @@ if (argv._[0] === 'update') {
   }
 }
 
+// Handle ACP server command (external command)
+// stdio is the JSON-RPC transport, so this never returns until the client
+// disconnects. Errors go to stderr to keep stdout as a clean protocol stream.
+if (argv._[0] === 'acp') {
+  try {
+    let handleAcpCommand;
+
+    if (isDev) {
+      const { register } = require('tsx/esm/api');
+      register();
+      const module = await import('../src/commands/acpCommand.ts');
+      handleAcpCommand = module.handleAcpCommand;
+    } else {
+      const module = await import('../dist/commands/acpCommand.mjs');
+      handleAcpCommand = module.handleAcpCommand;
+    }
+
+    await handleAcpCommand({ verbose: argv.verbose || false, version: cliVersion });
+    process.exit(0);
+  } catch (error) {
+    process.stderr.write(`Error: ${error.message}\n`);
+    process.exit(1);
+  }
+}
+
 // Handle doctor command (external command)
 if (argv._[0] === 'doctor') {
   try {
@@ -444,14 +557,14 @@ if (argv._[0] === 'doctor') {
 }
 
 if (isDev) {
-  // Show dev mode indicator for developers
-  console.log('🔧 Running in development mode (using TypeScript source)\n');
+  // Note: this is about *how the CLI runs* (unbuilt TypeScript source), which is
+  // distinct from the `--dev` flag (which selects the local dev *backend*).
+  console.log('🔧 Running from TypeScript source (no dist build)\n');
   // Development: use tsx to run TypeScript
   try {
     const { register } = require('tsx/esm/api');
     register();
 
-    // Import and run the main app
     await import(join(__dirname, '../src/index.tsx'));
   } catch (error) {
     console.error('Failed to start CLI in development mode:', error);
@@ -463,7 +576,7 @@ if (isDev) {
   try {
     // Auto-update on launch (consent-first): when a newer version is available
     // on a writable global prefix, install + re-exec into it BEFORE importing
-    // the code-split app — running an install while dist/index.mjs is loaded
+    // the code-split app - running an install while dist/index.mjs is loaded
     // would crash it. On the default 'ask' preference this prompts the user
     // (Update once / Always / Skip / Never); 'auto' installs silently, 'never'
     // does nothing. Wrapped so the updater can never block launching the CLI.
@@ -471,7 +584,7 @@ if (isDev) {
       const { maybeAutoUpdateOnLaunch } = await import('../dist/commands/updateCommand.mjs');
       await maybeAutoUpdateOnLaunch();
     } catch {
-      // Updater is best-effort — fall through to the current version.
+      // Updater is best-effort - fall through to the current version.
     }
 
     await import(join(__dirname, '../dist/index.mjs'));