claude-multiacc 2.0.60 → 2.0.61

package/README.md

@@ -571,7 +571,12 @@ claude-accounts mcp apply                        # re-apply now (repair drift)
   config dir outside the pool is plain passthrough. Global options in front of `mcp` are
   looked past the way the real parser does (`alias claude='claude
   --dangerously-skip-permissions'` puts one before every typed `claude mcp add`; until
-  2026-10-22 that kept motionsites in 2 of 11 accounts).
+  2026-10-22 that kept motionsites in 2 of 11 accounts). Mirroring is limited to the server
+  named by the command, including its project approvals: a concurrent runner update to
+  another server cannot become a synced override or tombstone. An unrecognized command
+  option leaves the native command intact and warns that its change was not mirrored.
+  Claude's desktop bulk import mirrors changes except names and retirements belonging to
+  another machine-local overlay owner; an explicit named command can still override one.
 - **Adoption**: whatever reached an account by another route — the real binary run
   directly, a hand edit, another tool's installer — is adopted by the next reconcile: a
   server (user scope or a project entry) or a project's `.mcp.json` approval that no section

package/bin/claude

@@ -224,15 +224,26 @@ mcp_mutation_argv() {
   i="$(cli_positional_at "$@")" || return 1
   [ "${!i}" = "mcp" ] || return 1
   j=$((i + 1))
-  case "${!j:-}" in add|add-json|add-from-claude-desktop|remove) return 0 ;; esac
+  case "${!j:-}" in add|add-json|add-from-claude-desktop|remove) MCP_MUTATION_AT="$j"; return 0 ;; esac
   return 1
 }
 
 mcp_mirror_run() { # $1 acct dir, then the user's argv — exits when it handled the run
-  local d="$1" snap="" rc
+  local d="$1" snap="" rc parse_rc name="" mirror_args=()
   shift
   mcp_mutation_argv "$@" || return 1
   [ "${CLAUDE_MULTIACC_MCP:-1}" != "0" ] && [ -f "$MCP_PY" ] || return 1
+  if [ "${!MCP_MUTATION_AT}" != add-from-claude-desktop ]; then
+    if name="$(. "$SELF_DIR/../lib/mcp_mirror.sh" && mcp_mutation_name claude "${@:$MCP_MUTATION_AT}")"; then
+      mirror_args=("--name=$name")
+    else
+      parse_rc=$?
+      "$REAL" "$@"; rc=$?
+      [ "$rc" -ne 0 ] || [ "$parse_rc" = 2 ] \
+        || printf 'claude-multiacc: could not identify the MCP target; change not mirrored\n' >&2
+      exit "$rc"
+    fi
+  fi
   mcp_ensure "$d"
   snap="$(mktemp "${TMPDIR:-/tmp}/claude-mcp-snap.XXXXXX" 2>/dev/null)" || snap=""
   if [ -n "$snap" ] && ! "$MCP_PYBIN" "$MCP_PY" --root "$ACC_ROOT" --provider claude snapshot \
@@ -243,7 +254,7 @@ mcp_mirror_run() { # $1 acct dir, then the user's argv — exits when it handled
   rc=$?
   if [ "$rc" -eq 0 ] && [ -n "$snap" ]; then
     "$MCP_PYBIN" "$MCP_PY" --root "$ACC_ROOT" --provider claude learn --account-dir "$d" \
-      --before "$snap" --project "$(pwd -P 2>/dev/null || pwd)" </dev/null \
+      --before "$snap" --project "$(pwd -P 2>/dev/null || pwd)" ${mirror_args[@]+"${mirror_args[@]}"} </dev/null \
       || printf 'claude-multiacc: could not mirror the MCP change to the other accounts — run: claude-accounts mcp apply\n' >&2
   elif [ "$rc" -eq 0 ]; then
     printf 'claude-multiacc: could not mirror the MCP change to the other accounts — run: claude-accounts mcp apply\n' >&2

package/bin/codex

@@ -165,15 +165,24 @@ mcp_mutation_argv() {
       *) break ;;
     esac
   done
-  case "${!j:-}" in add|remove) return 0 ;; esac
+  case "${!j:-}" in add|remove) MCP_MUTATION_AT="$j"; return 0 ;; esac
   return 1
 }
 
 mcp_mirror_run() { # $1 acct dir, then the user's argv — exits when it handled the run
-  local d="$1" snap="" rc
+  local d="$1" snap="" rc parse_rc name=""
   shift
   mcp_mutation_argv "$@" || return 1
   [ "${CODEX_MULTIACC_MCP:-1}" != "0" ] && [ -f "$MCP_PY" ] || return 1
+  if name="$(. "$SELF_DIR/../lib/mcp_mirror.sh" && mcp_mutation_name codex "${@:$MCP_MUTATION_AT}")"; then
+    :
+  else
+    parse_rc=$?
+    "$REAL" "$@"; rc=$?
+    [ "$rc" -ne 0 ] || [ "$parse_rc" = 2 ] \
+      || printf 'codex-multiacc: could not identify the MCP target; change not mirrored\n' >&2
+    exit "$rc"
+  fi
   mcp_ensure "$d"
   snap="$(mktemp "${TMPDIR:-/tmp}/codex-mcp-snap.XXXXXX" 2>/dev/null)" || snap=""
   if [ -n "$snap" ] && ! "$MCP_PYBIN" "$MCP_PY" --root "$ACC_ROOT" --provider codex snapshot \
@@ -184,7 +193,7 @@ mcp_mirror_run() { # $1 acct dir, then the user's argv — exits when it handled
   rc=$?
   if [ "$rc" -eq 0 ] && [ -n "$snap" ]; then
     "$MCP_PYBIN" "$MCP_PY" --root "$ACC_ROOT" --provider codex learn --account-dir "$d" \
-      --before "$snap" </dev/null \
+      --before "$snap" "--name=$name" </dev/null \
       || printf 'codex-multiacc: could not mirror the MCP change to the other accounts — run: codex-accounts mcp apply\n' >&2
   elif [ "$rc" -eq 0 ]; then
     printf 'codex-multiacc: could not mirror the MCP change to the other accounts — run: codex-accounts mcp apply\n' >&2

package/lib/mcp_mirror.py

@@ -0,0 +1,49 @@
+"""Keep stock MCP mutations scoped to the server the command actually named."""
+
+import copy
+
+
+def _external_names(overlay, target_owner):
+    """Bulk imports cannot promote another local owner's machine-specific entries."""
+    user, everywhere, projects = set(), set(), {}
+    for owner, section in overlay.get("owners", {}).items():
+        if owner == target_owner:
+            continue
+        everywhere.update(section.get("retired") or [])
+        user.update(section.get("mcpServers") or {})
+        user.update(section.get("retiredUser") or [])
+        for path, entry in (section.get("projects") or {}).items():
+            names = projects.setdefault(path, set())
+            names.update(entry.get("mcpServers") or {})
+            names.update(entry.get("retired") or [])
+            names.update(entry.get("enabledMcpjsonServers") or [])
+    return user | everywhere, everywhere, projects
+
+
+def _filtered_snapshot(snapshot, keep_user, keep_project):
+    result = copy.deepcopy(snapshot)
+    result["user"] = {name: block for name, block in (result.get("user") or {}).items()
+                      if keep_user(name)}
+    for path, entry in (result.get("projects") or {}).items():
+        entry["mcpServers"] = {name: block for name, block in (entry.get("mcpServers") or {}).items()
+                               if keep_project(path, name)}
+        for key in ("enabledMcpjsonServers", "disabledMcpjsonServers"):
+            entry[key] = [name for name in (entry.get(key) or []) if keep_project(path, name)]
+    return result
+
+
+def scoped_snapshots(before, after, name, overlay, target_owner=None):
+    """Named commands mirror only their target, including project approvals.
+
+    Without a name (desktop bulk import), externally owned names are excluded even
+    if a delayed reconcile writes an older generation than the current overlay.
+    """
+    if name is not None:
+        keep_user = lambda candidate: candidate == name
+        keep_project = lambda _path, candidate: candidate == name
+    else:
+        user, everywhere, projects = _external_names(overlay, target_owner)
+        keep_user = lambda candidate: candidate not in user
+        keep_project = lambda path, candidate: candidate not in everywhere | projects.get(path, set())
+    return (_filtered_snapshot(before, keep_user, keep_project),
+            _filtered_snapshot(after, keep_user, keep_project))

package/lib/mcp_mirror.sh

@@ -0,0 +1,47 @@
+# Target of a stock MCP mutation. Global CLI options are already skipped by the shim.
+# Unknown options fail closed: the native command still runs, but is not mirrored.
+# Status 2 is a help request before the target; pass it through without a warning.
+mcp_mutation_name() { # provider, verb, then the verb's argv -> server name
+  local provider="$1" verb="$2" values="" variadic="" flags=" " a opt attached
+  shift 2
+  case "$provider:$verb" in
+    claude:add)
+      values=" -s --scope -t --transport --callback-port --client-id "
+      variadic=" -e --env -H --header "; flags="$flags--client-secret " ;;
+    claude:add-json) values=" -s --scope "; flags="$flags--client-secret " ;;
+    claude:remove) values=" -s --scope " ;;
+    codex:add)
+      values=" -c --config --env --enable --disable --url --bearer-token-env-var \
+--oauth-client-id --oauth-client-secret --oauth-client-registration --oauth-resource " ;;
+    codex:remove) values=" -c --config --enable --disable " ;;
+    *) return 1 ;;
+  esac
+  while [ "$#" -gt 0 ]; do
+    a="$1"; shift
+    case "$a" in
+      --) [ "$#" -gt 0 ] || return 1; printf '%s\n' "$1"; return 0 ;;
+      -h|--help) return 2 ;;
+      -?*) ;;
+      *) printf '%s\n' "$a"; return 0 ;;
+    esac
+    opt="$a"; attached=0
+    case "$a" in
+      --*=*) opt="${a%%=*}"; attached=1 ;;
+      --*) ;;
+      -?*) opt="${a:0:2}"; [ "${#a}" -le 2 ] || attached=1 ;;
+    esac
+    case "$values" in
+      *" $opt "*)
+        if [ "$attached" = 0 ]; then [ "$#" -gt 0 ] || return 1; shift; fi
+        continue ;;
+    esac
+    case "$variadic" in
+      *" $opt "*)
+        while [ "$#" -gt 0 ]; do case "$1" in -*) break ;; esac; shift; done
+        continue ;;
+    esac
+    case "$flags" in *" $opt "*) [ "$attached" = 0 ] || return 1; continue ;; esac
+    return 1
+  done
+  return 1
+}

package/lib/mcp_registry.py

@@ -1413,14 +1413,18 @@ def cmd_snapshot(args):
 
 
 def cmd_learn(args):
+    from mcp_mirror import scoped_snapshots
+
     try:
         with open(args.before, encoding="utf-8") as handle:
             before = json.load(handle)
     except (OSError, ValueError) as exc:
         raise RegistryError(f"snapshot {args.before}: {exc}") from exc
-    after = snapshot(args.provider, args.account_dir)
     with _Lock(args.root):
+        after = snapshot(args.provider, args.account_dir)
         target = _Target(args.root)
+        before, after = scoped_snapshots(before, after, args.name, load_overlay(args.root),
+                                         "local" if target.replica else None)
         changes = _learn_into(target.section, before, after)
         if changes:
             target.save()
@@ -1519,7 +1523,8 @@ def build_parser():
     p = modes.add_parser("learn")
     p.add_argument("--account-dir", required=True)
     p.add_argument("--before", required=True)
-    p.add_argument("--project", help="accepted for the shim's sake; every changed project is mirrored")
+    p.add_argument("--name", help="mirror only this stock command's server, including project approvals")
+    p.add_argument("--project", help="accepted for the shim; --name applies across project entries")
 
     p = modes.add_parser("import-local")
     p.add_argument("--owner", required=True)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multiacc",
-  "version": "2.0.60",
+  "version": "2.0.61",
   "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {
@@ -58,7 +58,7 @@
     "test": "npm run test:core && npm run test:seeding && npm run test:commands",
     "test:core": "bash tests/run-tests.sh && npm run test:selector && python3 tests/test_shim_path.py",
     "test:selector": "python3 -m unittest discover -s tests -p 'test_selector*.py'",
-    "test:seeding": "python3 tests/test_account_seeding.py && python3 tests/test_claude_pool_prepare.py && python3 tests/test_mcp_registry.py && python3 tests/test_mcp_oauth.py && npm run test:codex-settings",
+    "test:seeding": "python3 tests/test_account_seeding.py && python3 tests/test_claude_pool_prepare.py && python3 -m unittest discover -s tests -p 'test_mcp_*.py' && npm run test:codex-settings",
     "test:codex-settings": "python3 tests/test_codex_config_edit.py && python3 tests/test_codex_settings.py",
     "test:commands": "python3 tests/test_packaged_commands.py"
   },

package/tests/run-tests.sh

@@ -10251,7 +10251,9 @@ fi
 # reconciles with whatever `python3` is on PATH, and a runner Mac's is /usr/bin/python3.
 # Skipped silently where that interpreter is absent or already 3.11+ (CI is ubuntu).
 if [ -x /usr/bin/python3 ] && /usr/bin/python3 -c 'import sys; sys.exit(0 if sys.version_info < (3, 11) else 1)' 2>/dev/null; then
-  if /usr/bin/python3 "$REPO_DIR/tests/test_mcp_registry.py" >/dev/null 2>&1; then
+  # Only this unit suite's disposable pools opt back in; legacy sections stay protected.
+  if CLAUDE_MULTIACC_MCP_ADOPT=1 CODEX_MULTIACC_MCP_ADOPT=1 \
+       /usr/bin/python3 "$REPO_DIR/tests/test_mcp_registry.py" >/dev/null 2>&1; then
     t_ok "MCP registry unit suite on stock python $(/usr/bin/python3 -c 'import sys;print("%d.%d"%sys.version_info[:2])')"
   else
     t_fail "MCP registry unit suite on stock python" "/usr/bin/python3 tests/test_mcp_registry.py failed"

package/tests/test_mcp_mirror.py

@@ -0,0 +1,148 @@
+#!/usr/bin/env python3
+"""Stock mutations must not promote concurrent runner publications into the registry."""
+
+import json
+from pathlib import Path
+import unittest
+from unittest.mock import patch
+
+from test_mcp_registry import HAS_TOMLLIB, HTTP, R, RegistryCase, STDIO
+
+APP = "appinspire-mcp"
+MOTION = "motionsites"
+V1 = {"type": "stdio", "command": "/releases/1000249/python", "args": ["launcher.pyc"], "env": {}}
+V2 = {"type": "stdio", "command": "/releases/1000250/python", "args": ["launcher.pyc"], "env": {}}
+V3 = {"type": "stdio", "command": "/bin/sh", "args": ["-p", "-c", "exec node server.mjs"], "env": {}}
+
+
+class MirrorCases:
+    def setUp(self):
+        super().setUp()
+        if self.provider == "codex" and not HAS_TOMLLIB:
+            self.skipTest("Codex requires tomllib")
+        if self.replica:
+            (self.root / "sync-role").write_text("replica\n")
+
+    def publish(self, servers):
+        rc, _, err = self.run_cli(self.provider, "import-local", "--owner", "app-robot",
+                                 stdin=json.dumps({"mcpServers": servers}))
+        self.assertEqual(rc, 0, err)
+
+    def write_account(self, servers, projects=None):
+        if self.provider == "claude":
+            R._claude_save(self.acct(), {"mcpServers": servers, "projects": projects or {}})
+        else:
+            eff = R.Effective()
+            eff.servers = servers
+            text, notes = R.reconcile_codex_text("", eff)
+            self.assertFalse(notes)
+            (Path(self.acct()) / "config.toml").write_text(text)
+
+    def before(self):
+        rc, snapshot, err = self.run_cli(self.provider, "snapshot", "--account-dir", self.acct())
+        self.assertEqual(rc, 0, err)
+        path = self.root / "before.json"
+        path.write_text(snapshot)
+        return str(path)
+
+    def learn(self, before, name):
+        scope = ["--name", name] if name is not None else []
+        rc, _, err = self.run_cli(self.provider, "learn", "--account-dir", self.acct(),
+                                 "--before", before, *scope)
+        self.assertEqual(rc, 0, err)
+        return R._Target(str(self.root)).section
+
+    def test_named_add_ignores_delayed_runner_generation(self):
+        self.publish({APP: V1})
+        before = self.before()
+        self.publish({APP: V2})
+        # import-local commits G3 under the lock, then applies accounts outside it.
+        # Pause before apply: the client still sees G2, which differs from current G3.
+        with patch.object(R, "_apply_all", return_value=0):
+            self.publish({APP: V3})
+        self.write_account({APP: V2, MOTION: HTTP})
+        section = self.learn(before, MOTION)
+        self.assertEqual(set(section["mcpServers"]), {MOTION})
+        self.assertEqual(section["retired"] + section["retiredUser"], [])
+        self.assertEqual(self.overlay()["owners"]["app-robot"]["mcpServers"], {APP: V3})
+        for account in ("acct-01", "acct-02"):
+            snapshot = R.snapshot(self.provider, self.acct(account))
+            self.assertEqual(snapshot["user"][APP]["command"], "/bin/sh")
+            self.assertEqual(snapshot["user"][MOTION]["url"], HTTP["url"])
+
+    def test_named_remove_does_not_promote_runner_retirement(self):
+        self.publish({APP: V1})
+        self.run_cli(self.provider, "add-json", MOTION, json.dumps(HTTP))
+        before = self.before()
+        self.publish({})
+        self.write_account({})
+        section = self.learn(before, MOTION)
+        self.assertEqual(section["mcpServers"], {})
+        self.assertEqual(section["retiredUser"], [MOTION])
+        self.assertEqual(section["retired"], [])
+        self.assertEqual(self.overlay()["owners"]["app-robot"]["retired"], [APP])
+
+    def test_explicit_owner_override_and_removal_still_mirror(self):
+        self.publish({APP: V1})
+        before = self.before()
+        self.write_account({APP: HTTP})
+        section = self.learn(before, APP)
+        self.assertEqual(section["mcpServers"][APP]["url"], HTTP["url"])
+        self.assertEqual(self.overlay()["owners"]["app-robot"]["mcpServers"], {APP: V1})
+        before = self.before()
+        self.write_account({})
+        section = self.learn(before, APP)
+        self.assertEqual(section["mcpServers"], {})
+        self.assertEqual(section["retiredUser"], [APP])
+        self.assertEqual(section["retired"], [])
+
+    def test_bulk_import_excludes_external_updates_and_retirements(self):
+        self.publish({APP: V1, "old-runner-tool": STDIO})
+        self.run_cli(self.provider, "import-local", "--owner", "local",
+                     stdin=json.dumps({"mcpServers": {"local-tool": V1}}))
+        before = self.before()
+        self.publish({APP: V2})
+        with patch.object(R, "_apply_all", return_value=0):
+            self.publish({APP: V3})
+        self.write_account({APP: V2, MOTION: HTTP, "local-tool": HTTP})
+        section = self.learn(before, None)
+        self.assertEqual(set(section["mcpServers"]), {MOTION, "local-tool"} if self.replica else {MOTION})
+        local = self.overlay()["owners"]["local"]["mcpServers"]["local-tool"]
+        self.assertEqual(local.get("url") if self.replica else local, HTTP["url"] if self.replica else V1)
+        self.assertEqual(section["retired"] + section["retiredUser"], [])
+
+    def test_named_project_changes_and_approvals_stay_scoped(self):
+        if self.provider != "claude":
+            self.skipTest("project MCP entries are Claude-only")
+        for name in (MOTION, "other"):
+            self.run_cli("claude", "add-json", name, json.dumps(STDIO), "--scope", "project",
+                         "--project", "/project")
+        before = self.before()
+        self.write_account({}, {"/project": {"mcpServers": {MOTION: HTTP, "other": HTTP},
+                                             "enabledMcpjsonServers": [MOTION, "other"]}})
+        section = self.learn(before, MOTION)
+        project = section["projects"]["/project"]
+        self.assertEqual(project["mcpServers"], {MOTION: HTTP, "other": STDIO})
+        self.assertEqual(project["enabledMcpjsonServers"], [MOTION])
+        other = self.claude_doc("acct-02")["projects"]["/project"]
+        self.assertEqual(other["enabledMcpjsonServers"], [MOTION])
+
+
+class ClaudeSourceTests(MirrorCases, RegistryCase):
+    provider, replica = "claude", False
+
+
+class ClaudeReplicaTests(MirrorCases, RegistryCase):
+    provider, replica = "claude", True
+
+
+class CodexSourceTests(MirrorCases, RegistryCase):
+    provider, replica = "codex", False
+
+
+class CodexReplicaTests(MirrorCases, RegistryCase):
+    provider, replica = "codex", True
+
+
+if __name__ == "__main__":
+    unittest.main()

package/tests/test_mcp_mirror_args.py

@@ -0,0 +1,129 @@
+#!/usr/bin/env python3
+"""MCP target parsing uses native verb options, without reading command payloads."""
+
+from pathlib import Path
+import subprocess
+import tempfile
+import unittest
+
+from test_mcp_registry import R
+
+HELPER = Path(__file__).resolve().parents[1] / "lib" / "mcp_mirror.sh"
+
+
+class MutationNameTests(unittest.TestCase):
+    def parse(self, *args):
+        return subprocess.run(["/bin/bash", "-uc", '. "$1"; shift; mcp_mutation_name "$@"',
+                               "mcp-target-test", str(HELPER), *args], capture_output=True, text=True)
+
+    def test_native_options_before_name(self):
+        cases = [
+            ("claude", "add", "-s", "user", "-t", "http", "motionsites", "https://example.test"),
+            ("claude", "add", "-suser", "-thttp", "motionsites", "https://example.test"),
+            ("claude", "add", "--scope=user", "--callback-port", "1234", "--client-id", "cid",
+             "--client-secret", "motionsites", "https://example.test"),
+            ("claude", "add", "-e", "A=1", "B=2", "-H", "X: 1", "Y: 2", "--", "motionsites", "echo"),
+            ("claude", "add", "-eA=1", "B=2", "--scope=user", "motionsites", "--", "echo", "--unknown"),
+            ("claude", "add-json", "-suser", "--client-secret", "motionsites", '{"command":"echo"}'),
+            ("claude", "remove", "--scope=user", "motionsites"),
+            ("codex", "add", "-c", "x=1", "--env", "A=1", "--url=https://example.test", "motionsites"),
+            ("codex", "add", "--enable", "x", "--disable=y", "--bearer-token-env-var", "MCP_TOKEN",
+             "--oauth-client-id", "cid", "--oauth-client-secret", "dummy", "--oauth-resource", "r",
+             "--oauth-client-registration", "dynamic", "motionsites"),
+            ("codex", "remove", "-cx=1", "--enable=x", "--disable", "y", "motionsites"),
+            ("codex", "add", "motionsites", "--", "node", "--env", "appinspire-mcp"),
+            ("claude", "add", "motionsites", "--", "node", "--help"),
+            ("codex", "add", "motionsites", "--help"),
+            ("claude", "remove", "motionsites", "-h"),
+            ("claude", "add", "--client-id", "--help", "motionsites", "https://example.test"),
+        ]
+        for args in cases:
+            with self.subTest(args=args):
+                result = self.parse(*args)
+                self.assertEqual((result.returncode, result.stdout, result.stderr), (0, "motionsites\n", ""))
+
+    def test_unknown_or_incomplete_options_never_become_a_broad_mirror(self):
+        cases = [
+            ("claude", "add", "--future-value", "appinspire-mcp", "motionsites"),
+            ("claude", "remove", "--scope"),
+            ("claude", "add", "-e", "A=1", "motionsites", "echo"),
+            ("claude", "add-json", "--client-secret=unexpected", "motionsites", "{}"),
+            ("codex", "add", "--unknown=value", "motionsites"),
+            ("codex", "remove", "--config"),
+            ("codex", "add", "--"),
+            ("claude", "add-from-claude-desktop"),
+        ]
+        for args in cases:
+            with self.subTest(args=args):
+                result = self.parse(*args)
+                self.assertNotEqual(result.returncode, 0)
+                self.assertEqual(result.stdout, "")
+
+    def test_help_without_a_target_has_a_distinct_quiet_status(self):
+        for provider in ("claude", "codex"):
+            for flag in ("-h", "--help"):
+                result = self.parse(provider, "add", flag)
+                self.assertEqual((result.returncode, result.stdout, result.stderr), (2, "", ""))
+
+    def run_shim(self, provider, args, native_exit=0):
+        with tempfile.TemporaryDirectory() as work:
+            root = Path(work)
+            pool, fakebin = root / "pool", root / "bin"
+            (pool / "acct-01").mkdir(parents=True)
+            fakebin.mkdir()
+            (pool / "accounts.json").write_text('{"version":1,"accounts":[{"id":"acct-01"}]}')
+            native = fakebin / provider
+            native.write_text('#!/bin/sh\nprintf "NATIVE\\n"\nprintf "%s\\n" "$@"\nexit "$FAKE_EXIT"\n')
+            native.chmod(0o755)
+            logger = fakebin / "mcp-python"
+            logger.write_text('#!/bin/sh\nprintf "%s\\n" "$@" >> "$MCP_TEST_LOG"\n'
+                              'case "$*" in *" snapshot "*) printf "{}\\n" ;; esac\n')
+            logger.chmod(0o755)
+            log = root / "mirror.log"
+            env = {"PATH": f"{fakebin}:/usr/bin:/bin", "HOME": work, "USER": "test", "LOGNAME": "test",
+                   "TMPDIR": work, "FAKE_EXIT": str(native_exit), "MCP_TEST_LOG": str(log),
+                   "CLAUDE_MULTIACC_PYTHON": str(logger), f"{provider.upper()}_ACCOUNTS_ROOT": str(pool),
+                   f"{provider.upper()}_SHIM_ACTIVE": "1",
+                   "CLAUDE_CONFIG_DIR" if provider == "claude" else "CODEX_HOME": str(pool / "acct-01")}
+            result = subprocess.run([str(HELPER.parents[1] / "bin" / provider), *args], env=env,
+                                    capture_output=True, text=True, timeout=10)
+            return result, log.read_text() if log.exists() else ""
+
+    def test_literal_help_global_value_still_mirrors(self):
+        args = ["--system-prompt", "--help", "mcp", "add-json", "--scope", "user", "motionsites",
+                '{"command":"echo","args":[]}']
+        result, log = self.run_shim("claude", args)
+        self.assertEqual((result.returncode, result.stderr), (0, ""))
+        self.assertEqual(result.stdout.splitlines(), ["NATIVE", *args])
+        self.assertIn("\nlearn\n", log)
+        self.assertIn("\n--name=motionsites\n", log)
+
+    def test_leading_dash_name_reaches_the_registry_parser(self):
+        args = ["mcp", "add", "--", "-probe-name", "echo"]
+        for provider in ("claude", "codex"):
+            result, log = self.run_shim(provider, args)
+            self.assertEqual((result.returncode, result.stderr), (0, ""))
+            self.assertEqual(result.stdout.splitlines(), ["NATIVE", *args])
+            words = log.splitlines()
+            tail = words[words.index("learn") + 1:]
+            parsed = R.build_parser().parse_args(["--root", "unused", "--provider", provider, "learn", *tail])
+            self.assertEqual(parsed.name, "-probe-name")
+
+    def test_help_is_quiet_native_passthrough(self):
+        for provider in ("claude", "codex"):
+            result, log = self.run_shim(provider, ["mcp", "add", "--help"])
+            self.assertEqual((result.returncode, result.stderr, log), (0, "", ""))
+            self.assertEqual(result.stdout.splitlines(), ["NATIVE", "mcp", "add", "--help"])
+
+    def test_unknown_options_keep_native_argv_and_exit_without_mirroring(self):
+        args = ["mcp", "add", "--future-value", "appinspire-mcp", "motionsites"]
+        for provider in ("claude", "codex"):
+            for native_exit in (0, 7):
+                result, log = self.run_shim(provider, args, native_exit)
+                self.assertEqual((result.returncode, log), (native_exit, ""))
+                self.assertEqual(result.stdout.splitlines(), ["NATIVE", *args])
+                self.assertEqual("change not mirrored" in result.stderr, native_exit == 0)
+
+
+if __name__ == "__main__":
+    unittest.main()