@brutalsystems/muster 1.2.2 → 3.0.0

package/README.md

@@ -64,10 +64,10 @@ models; behaviour against real ones is verified by hand and recorded in
 npm install -g --allow-scripts=@brutalsystems/muster,node-pty @brutalsystems/muster
 
 # A session: an agent you can reach, addressed once it is genuinely alive.
-muster run claude --prompt 'Review this project' --cwd . --level work
+muster run claude --prompt 'Review this project' --cwd .
 
 # A task: runs once, captures output, advertises nothing.
-muster run codex --kind task --prompt 'Summarise the failing tests' --level read
+muster run codex --kind task --prompt 'Summarise the failing tests' --read-only
 muster output <id>
 
 # What is running, and stopping it.
@@ -75,15 +75,26 @@ muster list --format human
 muster stop <id>
 ```
 
-`--level` names a containment pair. `read` can look but not change; `work` can
-edit its working directory, except muster's own home (`~/.muster`); `open`
-removes the sandbox and needs `allow_dangerous_flags` in config.
+**A Claude launch with no containment flag opens exactly as you would open it
+by hand** in that profile and folder. It gets your rules and CLAUDE.md, your
+permissions, hooks, status line, plugins, MCP servers and settings `env`.
+Muster adds nothing and replaces nothing. The one thing it refuses is a profile
+whose default permission mode is bypass. Codex and OpenCode stay read-only by
+default.
 
-| Level  | The agent asks before acting | What it may touch           |
-| ------ | ---------------------------- | --------------------------- |
-| `read` | always                       | nothing on disk             |
-| `work` | no                           | its cwd, except `~/.muster` |
-| `open` | no                           | everything                  |
+When you want muster's guarantee instead, **seal** the launch. A sealed launch
+runs on muster's own settings in place of the profile's, so it loads no rules
+or CLAUDE.md:
+
+| Flag             | The agent asks before acting | What it may touch           |
+| ---------------- | ---------------------------- | --------------------------- |
+| `--read-only`    | always                       | nothing on disk             |
+| `--write-here`   | no                           | its cwd, except `~/.muster` |
+| `--unrestricted` | no                           | everything                  |
+
+`--unrestricted` removes the sandbox and needs `allow_dangerous_flags` in
+config. `--level read|work|open` is the older spelling of the same three and
+still works.
 
 Claude asks to trust a directory the first time. That is a one-time review you
 do yourself — or `--options auto-approve-path`, which records it for you after
@@ -114,6 +125,35 @@ What that verification covers is in [Verification](docs/verification.md).
 | [MCP servers and plugins](docs/mcp.md)               | tools for launched agents, and Muster's own MCP server |
 | [Verification](docs/verification.md)                 | what is tested, what is checked by hand                |
 
+## Use with Claude Code
+
+1. **Install the plugin.** Its `muster` skill teaches a Claude session to use
+   Muster well: choosing a kind and level, reaching and stopping what it
+   launched, and the traps. It is versioned with Muster, so it describes the
+   release it came from.
+
+   ```sh
+   claude plugin marketplace add BrutalSystems/muster
+   claude plugin install muster@muster
+   ```
+
+   Or, inside a session, `/plugin marketplace add BrutalSystems/muster` and
+   then `/plugin install muster@muster`.
+
+2. **Register the MCP server** for the current Claude profile:
+
+   ```sh
+   muster mcp install
+   ```
+
+   It is read-only by default (`list`, `output`), so registering it at user
+   scope grants no launch authority. `muster mcp install --allow-launch` adds
+   `run`, `stop` and `title`, and every session in that profile can then
+   launch and stop sessions. `muster mcp status` shows which you have.
+   Details: [MCP installation](docs/mcp.md#mcp-installation).
+
+3. **Restart Claude Code** (or start a new session) to load it.
+
 ## Keeping it up to date
 
 Publishing a release does not touch an installed copy: `muster --version` keeps

package/dist/config.js

@@ -10,8 +10,13 @@ import { identityNameSchema } from "./identity-store.js";
 import { authoritySchema, subjectSchema } from "./requester.js";
 import { RequesterConfigError } from "./requester-policy.js";
 /**
- * What a remote requester is permitted here. Every default is the narrowest
- * value, so the shortest profile is the most restrictive one.
+ * What a remote requester is permitted here.
+ *
+ * `level` defaults to `normal`: an enrolled remote caller gets a launch like
+ * the operator's own, as a local one does (Mike, 2026-10-14). Naming `read` or
+ * `work` is how a profile caps it. `min_enforcement` follows the level it is
+ * written beside — `none` for a normal profile, which muster does not enforce,
+ * and `kernel` for a capped one — unless the profile names it.
  *
  * `allowed_roots` is the one key with no safe default: the global
  * `allowed_roots` defaults to empty, which `assertAllowedWorkspace` reads as
@@ -29,8 +34,8 @@ import { RequesterConfigError } from "./requester-policy.js";
 export const requesterProfileSchema = z
     .object({
     allowed_roots: z.array(z.string().min(1)).min(1),
-    level: z.enum(["read", "work"]).default("read"),
-    min_enforcement: z.enum(["kernel", "tool-policy"]).default("kernel"),
+    level: z.enum(["read", "work", "normal"]).default("normal"),
+    min_enforcement: z.enum(["kernel", "tool-policy", "none"]).optional(),
     env_allow: z.array(z.string().min(1)).default([]),
     /**
      * Baseline overrides, e.g. a PATH that does not depend on the accepting
@@ -42,7 +47,18 @@ export const requesterProfileSchema = z
     /** Which identities this requester may launch under. Empty refuses any. */
     identities: z.array(identityNameSchema).default([]),
 })
-    .strict();
+    .strict()
+    .transform((p) => ({
+    ...p,
+    min_enforcement: p.min_enforcement ?? (p.level === "normal" ? "none" : "kernel"),
+}))
+    // A normal launch is the profile's own settings with nothing of muster's on
+    // top, so its enforcement grade is `none`. A profile that grants it and keeps
+    // a stricter floor would refuse every launch at its own default level, which
+    // is a configuration error worth reporting at load rather than at launch.
+    .refine((p) => p.level !== "normal" || p.min_enforcement === "none", {
+    message: 'level = "normal" hands the launch to the agent\'s own settings, which muster does not enforce; set min_enforcement = "none" alongside it',
+});
 /** Binding an authenticated `(authority, subject)` to a profile. The grant. */
 export const requesterEnrolmentSchema = z
     .object({
@@ -90,7 +106,10 @@ export const configSchema = z
     projects: z
         .record(z.string().regex(/^[a-zA-Z0-9_-]+$/), z.string().min(1))
         .default({}),
-    permissions: z.enum(["auto", "deny", "bypass"]).default("deny"),
+    // No defaults: naming neither is how a Claude launch knows to open as a
+    // person would open it. `resolvePermissions` supplies deny/read-only for
+    // everything else.
+    permissions: z.enum(["auto", "deny", "bypass"]).optional(),
     sandbox: z
         .enum([
         "read-only",
@@ -98,7 +117,7 @@ export const configSchema = z
         "full-access",
         "danger-full-access",
     ])
-        .default("read-only"),
+        .optional(),
     default_mcp: z.array(mcpName).default([]),
     mcp_servers: z.record(mcpName, mcpServerSchema).default({}),
     default_plugins: z.array(pluginName).default([]),
@@ -164,7 +183,7 @@ export async function loadConfig(home = musterHome()) {
             throw new RequesterConfigError(`Duplicate requester enrolment for ${e.authority}/${e.subject}`);
         seen.add(key);
     }
-    if ((["danger-full-access", "full-access"].includes(result.sandbox) ||
+    if ((["danger-full-access", "full-access"].includes(result.sandbox ?? "") ||
         result.permissions === "bypass") &&
         !result.allow_dangerous_flags)
         throw new Error("full-access or bypass requires allow_dangerous_flags in config.toml");

package/dist/enforcement.js

@@ -1,6 +1,7 @@
 import { AGENTS } from "./agents.js";
 export function enforcementGrade(runtime, resolved) {
-    if (resolved.sandbox === "full-access")
+    // Normal: the agent's own settings decide, and muster imposes nothing.
+    if (resolved.sandbox === "full-access" || resolved.sandbox === "normal")
         return "none";
     return AGENTS[runtime].enforcement;
 }

package/dist/format.js

@@ -54,10 +54,16 @@ function recordHuman(record, color) {
     lines.push(field("Directory", clean(record.cwd)));
     if (record.identity)
         lines.push(field("Identity", clean(record.identity)));
-    if (record.permissions)
-        lines.push(field("Permissions", clean(record.permissions)));
-    if (record.sandbox)
-        lines.push(field("Sandbox", clean(record.sandbox)));
+    // A normal launch has no permissions or sandbox of muster's to report; one
+    // line saying whose settings apply reads better than "normal" twice.
+    if (record.permissions === "normal")
+        lines.push(field("Settings", "the profile's own, as if opened by hand"));
+    else {
+        if (record.permissions)
+            lines.push(field("Permissions", clean(record.permissions)));
+        if (record.sandbox)
+            lines.push(field("Sandbox", clean(record.sandbox)));
+    }
     // Only when known: a null means the child chose its own model, and "-" in a
     // human listing would read as a value rather than an absence. The source is
     // shown because "pinned by the caller" and "fell back to the configured

package/dist/guard.js

@@ -48,7 +48,7 @@ export const runSchema = z
         .regex(/^[a-zA-Z0-9_-]+$/)
         .optional(),
     requestKey: z.string().min(1).max(200).optional(),
-    level: z.enum(["read", "work", "open"]).optional(),
+    level: z.enum(["read", "work", "normal", "open"]).optional(),
     /**
      * Named things muster does on the caller's behalf. Closed set, unlike the
      * pass-through after `--`: see src/options.ts.
@@ -59,15 +59,32 @@ export const runSchema = z
     .strict();
 /**
  * A level is a spelling of a legal `permissions` + `sandbox` pair, not a second
- * policy path — `test/level.test.ts` asserts the equivalence for all three.
+ * policy path — `test/level.test.ts` asserts the equivalence for every level.
  * The two legal combinations no level names, `deny` + `workspace-write` and
  * `deny` + `full-access`, stay reachable through the flags.
+ *
+ * The CLI spells them `--read-only`, `--write-here` and `--unrestricted`;
+ * `normal` has no flag because it is what a Claude launch naming none gets.
  */
 export const LEVELS = {
     read: { permissions: "deny", sandbox: "read-only" },
     work: { permissions: "auto", sandbox: "workspace-write" },
+    normal: { permissions: "normal", sandbox: "normal" },
     open: { permissions: "bypass", sandbox: "full-access" },
 };
+/** The CLI's flag for each level, for messages that tell a caller what to type. */
+export const LEVEL_FLAGS = {
+    read: "--read-only",
+    work: "--write-here",
+    open: "--unrestricted",
+};
+/** Only Claude has a launch muster can leave entirely to the profile so far. */
+function assertNormalSupported(runtime) {
+    if (runtime !== "claude")
+        throw new Error(`a normal launch (the agent's own settings, as if opened by hand) is ` +
+            `supported for claude only; for ${runtime} pass --read-only, ` +
+            `--write-here or --unrestricted`);
+}
 /**
  * Checked against raw input before parsing, like `project` and `cwd`: once
  * defaults have been applied a caller's value is indistinguishable from one
@@ -83,14 +100,26 @@ export function assertLevelExclusive(input) {
 }
 export function resolvePermissions(req, config) {
     if (req.level) {
+        if (req.level === "normal")
+            assertNormalSupported(req.runtime);
         const pair = { ...LEVELS[req.level] };
         if ((pair.permissions === "bypass" || pair.sandbox === "full-access") &&
             !config.allow_dangerous_flags)
             throw new Error("bypass or full-access requires allow_dangerous_flags=true in config.toml");
         return pair;
     }
-    const permissions = req.permissions ?? config.permissions;
-    const configuredSandbox = req.sandbox ?? config.sandbox;
+    // Nothing named anywhere: a Claude launch opens as a person would open it.
+    // The other runtimes keep the sealed read-only default until they have a
+    // normal launch of their own. A config that names either key is an
+    // operator's explicit default and is honoured as before.
+    if (req.permissions === undefined &&
+        req.sandbox === undefined &&
+        config.permissions === undefined &&
+        config.sandbox === undefined &&
+        req.runtime === "claude")
+        return { ...LEVELS.normal };
+    const permissions = req.permissions ?? config.permissions ?? "deny";
+    const configuredSandbox = req.sandbox ?? config.sandbox ?? "read-only";
     const sandbox = configuredSandbox === "danger-full-access"
         ? "full-access"
         : configuredSandbox;
@@ -187,7 +216,7 @@ export function assertMusterHomeProtectable(runtime, cwd, policy, home) {
             `is inside muster's own home (${home}), which holds the config every ` +
             `later launch obeys. OpenCode's permissions are tool policy and cannot ` +
             `keep its shell out of one folder, so launch it in a folder that does ` +
-            `not contain muster's home, or at --level read.`);
+            `not contain muster's home, or with --read-only.`);
 }
 /** Whether `inner` is `outer` or below it, by path segments, not characters. */
 function contains(outer, inner) {
@@ -530,6 +559,12 @@ musterHome = defaultMusterHome(env)) {
     // builders, which carry the model in their config overlay.
     const model = resolved ? ["--model", resolved.model] : [];
     const policy = resolvePermissions(req, config);
+    if (policy.permissions === "normal") {
+        // `resolvePermissions` refuses this outside claude; restated so the codex
+        // branch below can never read `normal` as one of its own modes.
+        assertNormalSupported(req.runtime);
+        return normalClaudeArgs(req, mcp, bridgePath, env, model, extra);
+    }
     if (req.runtime === "codex")
         return [
             "codex",
@@ -658,6 +693,68 @@ musterHome = defaultMusterHome(env)) {
         req.prompt,
     ];
 }
+/**
+ * A Claude launch exactly as a person would start it in this profile and
+ * directory: every setting source (so rules, CLAUDE.md, the env and autoMode
+ * blocks, permissions, hooks, the status line, plugins and the profile's own
+ * MCP servers), no permission mode of muster's, no sandbox of muster's.
+ *
+ * Muster adds only what the caller named: `--mcp` servers ride alongside the
+ * profile's (not instead of them — no `--strict-mcp-config`), and configured
+ * `default_mcp` is not applied because the profile already brings its own.
+ *
+ * The one thing it refuses is a profile or project that makes bypass the
+ * default: a muster launch never starts in bypass unless `--unrestricted`
+ * asked for it.
+ */
+function normalClaudeArgs(req, mcp, bridgePath, env, model, extra) {
+    assertNoDefaultBypass(claudeConfigDir(env), req.cwd);
+    return [
+        "claude",
+        ...(req.kind === "task" ? ["-p"] : []),
+        ...(mcp.length
+            ? ["--mcp-config", JSON.stringify(claudeMcpConfig(mcp, bridgePath))]
+            : []),
+        ...model,
+        ...extra,
+        "--",
+        req.prompt,
+    ];
+}
+/**
+ * The setting files a hand launch reads for `permissions.defaultMode`, lowest
+ * precedence first. Managed policy is above all three and is the operator's
+ * organisation's to set, so it is not second-guessed here.
+ */
+export function claudeSettingFiles(configDir, cwd) {
+    return [
+        join(configDir, "settings.json"),
+        join(cwd, ".claude", "settings.json"),
+        join(cwd, ".claude", "settings.local.json"),
+    ];
+}
+/** Refuses a normal launch whose effective default mode is bypassPermissions. */
+export function assertNoDefaultBypass(configDir, cwd) {
+    let mode, from;
+    for (const file of claudeSettingFiles(configDir, cwd)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            // Missing or unreadable: Claude skips it too.
+            continue;
+        }
+        const value = parsed
+            ?.permissions?.defaultMode;
+        if (value !== undefined)
+            [mode, from] = [value, file];
+    }
+    if (mode === "bypassPermissions")
+        throw new Error(`${from} sets permissions.defaultMode to bypassPermissions; muster ` +
+            `will not start a launch in bypass by default. Pass --unrestricted ` +
+            `to ask for it.`);
+}
 /** A path as given and as resolved, once each. An unresolvable path (it does
  *  not exist yet) is denied as given — nothing can be written through a
  *  missing directory anyway. */

package/dist/help.js

@@ -51,16 +51,28 @@ export const COMMANDS = [
                 "--terminal APP",
                 "deprecated, removed in v2: pass the app to --open instead",
             ],
+            [
+                "--read-only",
+                "sealed: muster's own settings replace the profile's, and the agent can change nothing",
+            ],
+            [
+                "--write-here",
+                "sealed: muster's own settings replace the profile's, and the agent can write only inside the launch folder, never muster's own home",
+            ],
+            [
+                "--unrestricted",
+                "no sandbox and no permission checks; needs allow_dangerous_flags in config.toml",
+            ],
             [
                 "--level LEVEL",
-                "read, work, or open: a legal permissions and sandbox pair; work writes the launch folder except muster's own home",
+                "older spelling: read, work or open are the three flags above; normal is the claude default",
             ],
-            ["--permissions MODE", "auto, deny, or bypass"],
-            ["--sandbox MODE", "read-only, workspace-write, or full-access"],
+            ["--permissions MODE", "auto, deny, or bypass (sealed)"],
+            ["--sandbox MODE", "read-only, workspace-write, or full-access (sealed)"],
             ["--mcp NAME", "repeatable; replaces configured defaults"],
             [
                 "--options NAME",
-                "repeatable; muster-side launch options — auto-approve-path records the launch directory as trusted so its one-time dialog does not block the launch (claude and codex only, and refused if the directory ships hooks or MCP servers); accept-bypass-warning accepts Claude's one-time Bypass Permissions warning so a --level open launch can start (claude with bypass permissions only)",
+                "repeatable; muster-side launch options — auto-approve-path records the launch directory as trusted so its one-time dialog does not block the launch (claude and codex only, and refused if the directory ships hooks or MCP servers); accept-bypass-warning accepts Claude's one-time Bypass Permissions warning so an --unrestricted launch can start (claude with bypass permissions only)",
             ],
             ["--no-mcp", "launch with no MCP servers"],
             ["--plugin NAME", "repeatable; replaces configured defaults (OpenCode)"],
@@ -89,12 +101,15 @@ export const COMMANDS = [
             ["-- RUNTIME_OPTIONS", "everything after -- is passed to the runtime"],
         ],
         notes: [
-            "Naming both --level and --permissions or --sandbox is an error rather than a precedence rule.",
+            "With none of --read-only, --write-here or --unrestricted, claude opens exactly as you would open it by hand in that folder: your profile's rules, CLAUDE.md, permissions, hooks, plugins, MCP servers and env. Muster refuses only a profile whose default mode is bypass. codex and opencode stay read-only by default.",
+            "A sealed launch does not read your profile's or the project's settings, so it also loads no rules or CLAUDE.md.",
+            "Use one of the three flags, --level, or --permissions/--sandbox; naming two is an error rather than a precedence rule.",
             "A pty launch keeps this process running and Ctrl-C stops it; a tmux launch survives this process exiting.",
         ],
         examples: [
             "muster run claude --prompt 'Review this project' --cwd .",
-            "muster run codex --identity work --level work --prompt 'Ship it'",
+            "muster run claude --read-only --prompt 'Audit this' --cwd .",
+            "muster run codex --identity work --write-here --prompt 'Ship it'",
         ],
     },
     {
@@ -176,13 +191,22 @@ export const COMMANDS = [
     },
     {
         name: "mcp",
-        summary: "start the MCP server on stdio",
-        synopsis: "muster mcp",
-        options: [],
+        summary: "serve MCP on stdio, or register it with Claude Code",
+        synopsis: "muster mcp [--allow-launch] | mcp install|uninstall|status",
+        options: [
+            ["--allow-launch", "also expose run, stop and title (launch authority)"],
+            ["--force", "install: replace a different existing registration"],
+        ],
         notes: [
-            "Exposes run, list, stop and output. No arguments does the same when stdin is not a terminal, which is what an MCP client provides.",
+            "Read-only by default: exposes list and output only. --allow-launch is the deliberate grant. No arguments starts the read-only server when stdin is not a terminal, which is what an MCP client provides.",
+            "install registers the server with Claude Code at user scope for the current profile (CLAUDE_CONFIG_DIR) via `claude mcp add`. Without --allow-launch it asks at a terminal, defaulting to no; without a terminal it does not grant. Restart Claude Code afterwards.",
+        ],
+        examples: [
+            "muster mcp",
+            "muster mcp install",
+            "muster mcp install --allow-launch --force",
+            "muster mcp status",
         ],
-        examples: ["muster mcp"],
     },
 ];
 export function topLevelHelp() {
@@ -204,7 +228,7 @@ export function topLevelHelp() {
         // Kept here rather than moved to the README: this is a safety statement
         // about who gets launch authority, not reference detail, and it is only
         // load-bearing where someone is about to install.
-        ...wrap("MCP: install deliberately in the one authorized session, never at user scope.", WIDTH),
+        ...wrap("MCP: `muster mcp install` registers a read-only server with Claude Code. Launch authority is granted only by --allow-launch.", WIDTH),
     ];
     return lines.join("\n") + "\n";
 }

package/dist/mcp-bridge.js

@@ -6,13 +6,14 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { mcpServerSchema, mcpName, mcpTransport } from "./mcp.js";
+import { mcpServerSchema, mcpName, mcpTransport, toolGate } from "./mcp.js";
 async function main() {
     const [path, name] = process.argv.slice(2);
     if (!path || !name || !mcpName.safeParse(name).success)
         throw new Error("Invalid MCP bridge arguments");
     const definitions = JSON.parse(await readFile(path, "utf8"));
     const config = mcpServerSchema.parse(definitions[name]);
+    const gate = toolGate(config.tools);
     const client = new Client({ name: "muster-tool-bridge", version: "1" }, { capabilities: {} });
     const server = new Server({ name: `muster-${name}`, version: "1" }, { capabilities: { tools: {} } });
     let shutdown;
@@ -59,13 +60,13 @@ async function main() {
         let cursor;
         do {
             const page = await client.listTools(cursor ? { cursor } : {});
-            tools.push(...page.tools.filter((t) => config.tools.includes(t.name)));
+            tools.push(...gate.expose(page.tools));
             cursor = page.nextCursor;
         } while (cursor);
         return { tools };
     });
     server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
-        if (!config.tools.includes(params.name))
+        if (!gate.allows(params.name))
             return {
                 isError: true,
                 content: [

package/dist/mcp-install.js

@@ -0,0 +1,207 @@
+/**
+ * `muster mcp install | uninstall | status` — registering Muster's own MCP
+ * server with Claude Code at user scope, for the profile `CLAUDE_CONFIG_DIR`
+ * names (or the default one).
+ *
+ * Every write goes through `claude mcp add` / `claude mcp remove`, so Muster
+ * never edits Claude's configuration itself. Reading is different: the current
+ * definition is read straight from the profile's `.claude.json`, because
+ * `claude mcp get` health-checks a server by starting it and reports whichever
+ * scope wins, where this needs the user-scope entry exactly as written.
+ */
+import { execFile } from "node:child_process";
+import { access, constants, readFile, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { parseArgs } from "node:util";
+import { LAUNCH_TOOLS, mcpToolNames } from "./mcp-tools.js";
+export const SERVER_NAME = "muster";
+export const ALLOW_LAUNCH = "--allow-launch";
+export const LAUNCH_QUESTION = "Let this Claude launch and stop sessions? [y/N] ";
+export const MCP_SUBCOMMANDS = ["install", "uninstall", "status"];
+/** The first executable called `name` on PATH, as PATH spells it. */
+export async function onPath(name, env) {
+    for (const dir of (env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, name);
+        try {
+            await access(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch { }
+    }
+    return undefined;
+}
+/**
+ * The command a client should run to reach this muster. The installed `muster`
+ * bin when the one on PATH is this very script — its PATH spelling, not its
+ * resolved target, so a package-manager link survives an upgrade. Otherwise
+ * (a source checkout, or a different install first on PATH) this node and this
+ * script, absolutely, so the registration runs what the person just ran.
+ */
+export async function selfInvocation(env, script = process.argv[1], node = process.execPath) {
+    const resolved = await realpath(script);
+    const found = await onPath("muster", env);
+    if (found && (await realpath(found).catch(() => undefined)) === resolved)
+        return { command: found, args: [] };
+    return { command: node, args: [resolved] };
+}
+export function claudeConfigFile(env) {
+    return join(env.CLAUDE_CONFIG_DIR || env.HOME || homedir(), ".claude.json");
+}
+/** The user-scope `muster` entry, or undefined when there is none. */
+export async function registered(env) {
+    const file = claudeConfigFile(env);
+    let raw;
+    try {
+        raw = await readFile(file, "utf8");
+    }
+    catch (e) {
+        if (e.code === "ENOENT")
+            return undefined;
+        throw e;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Cannot read ${file}: it is not valid JSON`);
+    }
+    const entry = parsed?.mcpServers?.[SERVER_NAME];
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    return {
+        command: typeof entry.command === "string" ? entry.command : "",
+        args: Array.isArray(entry.args) ? entry.args.map(String) : [],
+    };
+}
+export function desired(self, allowLaunch) {
+    return {
+        command: self.command,
+        args: [...self.args, "mcp", ...(allowLaunch ? [ALLOW_LAUNCH] : [])],
+    };
+}
+const same = (a, b) => a.command === b.command &&
+    a.args.length === b.args.length &&
+    a.args.every((arg, i) => arg === b.args[i]);
+const quote = (s) => /^[\w@%+=:,./-]+$/.test(s) ? s : JSON.stringify(s);
+export const render = (d) => [d.command, ...d.args].map(quote).join(" ");
+const launchAllowed = (d) => d.args.includes(ALLOW_LAUNCH);
+function toolsLine(allowLaunch) {
+    return allowLaunch
+        ? `Tools: ${mcpToolNames(true).join(", ")} — this Claude can launch and stop sessions.`
+        : `Tools: ${mcpToolNames(false).join(", ")} — read-only; it cannot launch or stop anything.`;
+}
+async function defaultRunClaude(binary, args, env) {
+    return new Promise((resolve) => {
+        execFile(binary, args, { env, timeout: 60_000 }, (error, stdout, stderr) => resolve({
+            code: error ? (typeof error.code === "number" ? error.code : 1) : 0,
+            stdout: String(stdout),
+            stderr: String(stderr),
+        }));
+    });
+}
+async function claude(deps) {
+    const binary = await onPath("claude", deps.env);
+    if (!binary)
+        throw new Error("`claude` is not on PATH. Install Claude Code, or put it on PATH, and run this again.");
+    const run = deps.runClaude ?? defaultRunClaude;
+    return async (args, what) => {
+        const result = await run(binary, args, deps.env);
+        if (result.code !== 0)
+            throw new Error(`\`claude ${args.join(" ")}\` failed while ${what}: ${(result.stderr || result.stdout).trim() || `exit ${result.code}`}`);
+        return result;
+    };
+}
+async function install(opts, deps) {
+    const run = await claude(deps);
+    let allowLaunch = opts.allowLaunch;
+    // Default no, and no question at all without a terminal: the grant is made
+    // by a person typing the flag or answering yes, never by a script's silence.
+    if (!allowLaunch && deps.ask)
+        allowLaunch = /^y(es)?$/i.test((await deps.ask(LAUNCH_QUESTION)).trim());
+    const want = desired(await deps.self(), allowLaunch);
+    const file = claudeConfigFile(deps.env);
+    const have = await registered(deps.env);
+    if (have && same(have, want)) {
+        deps.write(`Already registered at user scope in ${file}; nothing changed.\n  ${render(want)}\n${toolsLine(allowLaunch)}\n`);
+        return;
+    }
+    if (have && !opts.force)
+        throw new Error(`A different "${SERVER_NAME}" MCP server is already registered at user scope in ${file}:\n` +
+            `  have: ${render(have)}\n  want: ${render(want)}\n` +
+            `Run again with --force to replace it, or \`muster mcp uninstall\` first.`);
+    if (have)
+        await run(["mcp", "remove", "--scope", "user", SERVER_NAME], "removing the existing definition");
+    await run([
+        "mcp",
+        "add",
+        "--scope",
+        "user",
+        SERVER_NAME,
+        "--",
+        want.command,
+        ...want.args,
+    ], "registering the server");
+    deps.write(`${have ? "Replaced" : "Registered"} the "${SERVER_NAME}" MCP server at user scope in ${file}.\n` +
+        `  ${render(want)}\n${toolsLine(allowLaunch)}\n` +
+        "Restart Claude Code (or start a new session) to load it.\n");
+}
+async function uninstall(deps) {
+    const run = await claude(deps);
+    const file = claudeConfigFile(deps.env);
+    if (!(await registered(deps.env))) {
+        deps.write(`No "${SERVER_NAME}" MCP server at user scope in ${file}; nothing to remove.\n`);
+        return;
+    }
+    await run(["mcp", "remove", "--scope", "user", SERVER_NAME], "removing the server");
+    deps.write(`Removed the "${SERVER_NAME}" MCP server from user scope in ${file}.\n` +
+        "Restart Claude Code (or start a new session) to drop it.\n");
+}
+async function status(deps) {
+    const file = claudeConfigFile(deps.env);
+    const have = await registered(deps.env);
+    if (!have) {
+        deps.write(`Not registered: no "${SERVER_NAME}" MCP server at user scope in ${file}.\n` +
+            "Run `muster mcp install` to add it.\n");
+        return;
+    }
+    const allowed = launchAllowed(have);
+    deps.write(`Registered at user scope in ${file}.\n  ${render(have)}\n` +
+        `Launch allowed: ${allowed ? "yes" : "no"}\n${toolsLine(allowed)}\n`);
+}
+/** `muster mcp <subcommand> ...`, already known to name a subcommand. */
+export async function mcpCommand(argv, deps) {
+    const [sub, ...rest] = argv;
+    const { values, positionals } = parseArgs({
+        args: rest,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            "allow-launch": { type: "boolean" },
+            force: { type: "boolean" },
+        },
+    });
+    if (positionals.length)
+        throw new Error(`mcp ${sub} takes no positional arguments`);
+    if (sub !== "install" && (values["allow-launch"] || values.force))
+        throw new Error(`--allow-launch and --force apply only to mcp install`);
+    if (sub === "install")
+        return install({
+            allowLaunch: Boolean(values["allow-launch"]),
+            force: Boolean(values.force),
+        }, deps);
+    if (sub === "uninstall")
+        return uninstall(deps);
+    if (sub === "status")
+        return status(deps);
+    throw new Error(`Unknown mcp subcommand: ${sub}`);
+}
+/** The refusal for a tool the running server does not expose. */
+export function notEnabled(name) {
+    return LAUNCH_TOOLS.includes(name)
+        ? `Tool ${name} is not enabled: this Muster MCP server is read-only. Start it with \`muster mcp --allow-launch\` (or register it with \`muster mcp install --allow-launch\`) to expose ${LAUNCH_TOOLS.join(", ")}.`
+        : `Unknown tool ${name}`;
+}

package/dist/mcp-tools.js

@@ -44,17 +44,17 @@ export const MCP_TOOLS = [
                 permissions: {
                     type: "string",
                     enum: ["auto", "deny", "bypass"],
-                    description: "Defaults to config (deny). Auto requires workspace-write; bypass requires authorized full-access.",
+                    description: "Seals the launch. Defaults to config, else deny (claude: normal when config names neither). Auto requires workspace-write; bypass requires authorized full-access.",
                 },
                 sandbox: {
                     type: "string",
                     enum: ["read-only", "workspace-write", "full-access"],
-                    description: "Defaults to config (read-only). Full access requires config authorization.",
+                    description: "Seals the launch. Defaults to config, else read-only (claude: normal when config names neither). Full access requires config authorization.",
                 },
                 level: {
                     type: "string",
-                    enum: ["read", "work", "open"],
-                    description: "A spelling of a legal permissions/sandbox pair: read is deny + read-only, work is auto + workspace-write, open is bypass + full-access. Naming a level and either flag is an error.",
+                    enum: ["read", "work", "normal", "open"],
+                    description: "normal (claude's default, claude only) opens the agent exactly as a person would by hand: the profile's rules, CLAUDE.md, permissions, hooks, plugins and MCP servers. read (deny + read-only), work (auto + workspace-write) and open (bypass + full-access) are sealed: muster's settings replace the profile's, so no rules or CLAUDE.md load. Naming a level and permissions or sandbox is an error.",
                 },
                 mcp: {
                     type: "array",
@@ -165,3 +165,20 @@ export const MCP_TOOLS = [
  * callers may not set the field, not a place to park an oversight.
  */
 export const RUN_MCP_OMITTED = [];
+/**
+ * What `muster mcp` serves by default: reading what Muster already owns.
+ * Nothing here can start, stop or change a run, so registering the server
+ * where every Claude session sees it grants no launch authority.
+ */
+export const READ_ONLY_TOOLS = ["list", "output"];
+/**
+ * Added by `muster mcp --allow-launch`, the deliberate grant. `title` is here
+ * rather than above because it changes a running session, and the read-only
+ * set is defined as changing nothing.
+ */
+export const LAUNCH_TOOLS = ["run", "stop", "title"];
+export function mcpToolNames(allowLaunch) {
+    return allowLaunch
+        ? [...READ_ONLY_TOOLS, ...LAUNCH_TOOLS]
+        : [...READ_ONLY_TOOLS];
+}

package/dist/mcp.js

@@ -39,9 +39,29 @@ export const mcpServerSchema = z
             message: "args, env and env_vars require a stdio server",
         });
 });
+/**
+ * One allowlist, applied to both halves of an MCP server: what `tools/list`
+ * advertises and what `tools/call` will dispatch. Used by the Claude bridge
+ * (the operator's selected tools of an upstream server) and by Muster's own
+ * server (read-only unless started with `--allow-launch`). Filtering the
+ * listing alone is not enough — a client can call a name it was never shown —
+ * so every call is checked against the same set.
+ */
+export function toolGate(enabled) {
+    const names = new Set(enabled);
+    return {
+        expose: (tools) => tools.filter((tool) => names.has(tool.name)),
+        allows: (name) => names.has(name),
+    };
+}
 export function selectMcp(req, config) {
-    // Personal defaults apply to sessions, not unattended one-shot tasks.
-    const names = req.mcp ?? (req.kind === "session" ? config.default_mcp : []);
+    // Personal defaults apply to sessions, not unattended one-shot tasks, and not
+    // to a normal launch: the profile already brings its own MCP servers, and a
+    // second copy of one under muster's bridge would register the session twice.
+    const names = req.mcp ??
+        (req.kind === "session" && req.level !== "normal"
+            ? config.default_mcp
+            : []);
     return [...new Set(names)].map((name) => {
         const server = Object.hasOwn(config.mcp_servers, name)
             ? config.mcp_servers[name]

package/dist/muster.js

@@ -12,7 +12,9 @@ import { checkPlugins, npmRegistry } from "./doctor.js";
 import { loadConfig, musterHome } from "./config.js";
 import { describeIdentities, interactiveSetup, setupIdentity, } from "./identity-cli.js";
 import { IdentityError } from "./identity-store.js";
-import { MCP_TOOLS } from "./mcp-tools.js";
+import { MCP_TOOLS, mcpToolNames } from "./mcp-tools.js";
+import { toolGate } from "./mcp.js";
+import { ALLOW_LAUNCH, MCP_SUBCOMMANDS, mcpCommand, notEnabled, selfInvocation, } from "./mcp-install.js";
 import { normalizeOpenFlag, usesTerminalFlag } from "./guard.js";
 import { commandHelp, topLevelHelp } from "./help.js";
 import { promptForMissing, terminalReader } from "./prompt.js";
@@ -75,8 +77,28 @@ async function main() {
     // driven by hand in a terminal to debug it.
     const bareAtTerminal = argv.length === 0 && Boolean(process.stdin.isTTY);
     const mcp = !bareAtTerminal && (argv.length === 0 || argv[0] === "mcp");
-    if (argv[0] === "mcp" && argv.length > 1)
-        throw new Error("mcp takes no arguments");
+    // `muster mcp install|uninstall|status` registers the server with Claude
+    // Code rather than serving it. Handled before Muster.create(): none of them
+    // touches a run.
+    if (argv[0] === "mcp" &&
+        MCP_SUBCOMMANDS.includes(argv[1] ?? "")) {
+        if (argv.includes("--help") || argv.includes("-h")) {
+            process.stdout.write(commandHelp("mcp"));
+            return;
+        }
+        await mcpCommand(argv.slice(1), {
+            env: process.env,
+            write: (s) => process.stdout.write(s),
+            ...(process.stdin.isTTY ? { ask: terminalReader() } : {}),
+            self: () => selfInvocation(process.env),
+        });
+        return;
+    }
+    // Read-only unless launching is granted by the flag. Bare `muster` down a
+    // pipe is the same server, so it is read-only too.
+    const allowLaunch = argv[0] === "mcp" && argv[1] === ALLOW_LAUNCH;
+    if (argv[0] === "mcp" && argv.length > (allowLaunch ? 2 : 1))
+        throw new Error(`mcp takes ${ALLOW_LAUNCH}, or one of ${MCP_SUBCOMMANDS.join(", ")}`);
     const muster = await Muster.create();
     let shutdown;
     const close = () => (shutdown ??= (async () => {
@@ -107,10 +129,16 @@ async function main() {
         });
     if (mcp) {
         const server = new Server({ name: "muster", version }, { capabilities: { tools: {} } });
+        const gate = toolGate(mcpToolNames(allowLaunch));
         server.setRequestHandler(ListToolsRequestSchema, async () => ({
-            tools: MCP_TOOLS,
+            tools: gate.expose(MCP_TOOLS),
         }));
         server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+            if (!gate.allows(params.name))
+                return {
+                    content: [{ type: "text", text: notEnabled(params.name) }],
+                    isError: true,
+                };
             try {
                 const args = params.arguments ?? {};
                 switch (params.name) {
@@ -175,6 +203,9 @@ async function main() {
                 permissions: { type: "string" },
                 sandbox: { type: "string" },
                 level: { type: "string" },
+                "read-only": { type: "boolean" },
+                "write-here": { type: "boolean" },
+                unrestricted: { type: "boolean" },
                 mcp: { type: "string", multiple: true },
                 options: { type: "string", multiple: true },
                 "no-mcp": { type: "boolean" },
@@ -195,7 +226,23 @@ async function main() {
                 interactive: { type: "boolean" },
             },
         });
-        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, "idle-timeout": idleTimeout, socket, home: homeFlag, "stop-now": stopNow, ...values } = parsed;
+        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, "idle-timeout": idleTimeout, socket, home: homeFlag, "stop-now": stopNow, "read-only": readOnly, "write-here": writeHere, unrestricted, ...values } = parsed;
+        // The plain spellings of the three sealed levels. Each is a level, so the
+        // existing exclusivity with --permissions/--sandbox applies unchanged once
+        // it is folded into `values.level`.
+        const levelFlags = [
+            ["--read-only", readOnly, "read"],
+            ["--write-here", writeHere, "work"],
+            ["--unrestricted", unrestricted, "open"],
+        ].filter(([, set]) => set);
+        if (levelFlags.length && command !== "run")
+            throw new Error(`${levelFlags[0][0]} applies only to run`);
+        if (levelFlags.length > 1)
+            throw new Error(`use one of ${levelFlags.map(([name]) => name).join(", ")}, not several`);
+        if (levelFlags.length && values.level !== undefined)
+            throw new Error(`use ${levelFlags[0][0]} or --level, not both`);
+        if (levelFlags.length)
+            values.level = levelFlags[0][2];
         // Guarded like --request-key and --no-mcp below: a flag that applies to one
         // command and is silently ignored elsewhere misleads, and --home silently
         // reading the real registry is the one that would mislead most.

package/dist/options.js

@@ -33,7 +33,7 @@ export function assertOptionsSupported(runtime, options, permissions) {
             throw new Error(`--options accept-bypass-warning is not supported for ${runtime}: only Claude shows a bypass-permissions warning`);
         if (option === "accept-bypass-warning" &&
             permissions.permissions !== "bypass")
-            throw new Error(`--options accept-bypass-warning requires bypass permissions (--level open or --permissions bypass); this launch resolves to ${permissions.permissions}`);
+            throw new Error(`--options accept-bypass-warning requires bypass permissions (--unrestricted or --permissions bypass); this launch resolves to ${permissions.permissions}`);
     }
 }
 /**

package/dist/requester-policy.js

@@ -30,7 +30,7 @@ export class RequesterConfigError extends Error {
     }
 }
 /** Ordered weakest to strongest, so a ceiling is one index comparison. */
-const LEVEL_ORDER = ["read", "work", "open"];
+const LEVEL_ORDER = ["read", "work", "normal", "open"];
 const GRADE_ORDER = ["none", "tool-policy", "kernel"];
 export function resolveRequesterPolicy(requester, config) {
     if (requester.kind === "local")

package/dist/run.js

@@ -188,7 +188,13 @@ export class Muster {
         // defaults. So the profile is the floor here as well as the ceiling. A
         // local requester has no `policy.level`, which leaves this undefined and
         // local behaviour untouched.
-        const level = req.level ?? policy.level;
+        // A profile's normal default applies to claude only, the one runtime with
+        // a normal launch; any other runtime gets the read default it would get
+        // locally, rather than a refusal for a level the caller never named.
+        const level = req.level ??
+            (policy.level === "normal" && req.runtime !== "claude"
+                ? "read"
+                : policy.level);
         if (level)
             assertLevelWithinCeiling(level, policy);
         return { req, policy, level };
@@ -250,7 +256,7 @@ export class Muster {
          * that happens, so there is one: nothing below derives containment from
          * `req`.
          */
-        const effective = level ? { ...req, level } : req;
+        const requested = level ? { ...req, level } : req;
         if (req.kind === "task" && req.host)
             throw new Error("host applies only to session launches");
         if (req.terminal && !req.open)
@@ -260,7 +266,13 @@ export class Muster {
         if (req.open &&
             (req.kind !== "session" || !["auto", "tmux"].includes(requestedHost)))
             throw new Error("--open requires a tmux session on macOS");
-        const permissions = resolvePermissions(effective, this.config);
+        const permissions = resolvePermissions(requested, this.config);
+        // A Claude launch naming nothing resolves to normal without having asked
+        // for it by name; spelled out here so everything below — MCP defaults,
+        // the argv, the record — sees one answer rather than re-deriving it.
+        const effective = permissions.permissions === "normal"
+            ? { ...requested, level: "normal" }
+            : requested;
         // Refused here, with the other checks that cost nothing to fail: an option
         // the runtime cannot honour must not leave a registry entry behind.
         assertOptionsSupported(req.runtime, req.options, permissions);
@@ -292,7 +304,10 @@ export class Muster {
         if (req.open &&
             (!driver?.open || !(await driver.openAvailable?.(terminal))))
             throw new Error(`--open requires the selected terminal (${terminal}) installed on macOS and tmux`);
-        if (req.runtime === "claude")
+        // Managed policy is refused because muster cannot prove its own inline
+        // settings win over it. A normal launch has no settings of muster's to
+        // prove, and obeys managed policy exactly as a hand launch does.
+        if (req.runtime === "claude" && permissions.permissions !== "normal")
             await assertClaudePolicy(this.hostEnv);
         if (req.runtime === "opencode")
             await assertOpenCodeVersion(this.hostEnv, "1.18.31", Date.now() + 4000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "1.2.2",
+  "version": "3.0.0",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {
@@ -21,7 +21,7 @@
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
     "prepack": "npm run build",
     "prepublishOnly": "npm test",
-    "version": "node scripts/stamp-release-notes.mjs && git add RELEASE_NOTES.md",
+    "version": "node scripts/stamp-release-notes.mjs && node scripts/stamp-plugin-version.mjs && git add RELEASE_NOTES.md plugins/claude-code/.claude-plugin/plugin.json",
     "postversion": "git push origin HEAD --follow-tags"
   },
   "dependencies": {