fix: MCP tools unavailable in spawned subagents (GH #31, v0.21.1)

Phase 84. MCP stdio connections don't propagate across subprocess
boundaries, so spawning rn-tester/rn-debugger via Task tool fails.

Multi-part fix (validated via multi-review):
- Removed mcp__*cdp__* from agents/rn-tester.md + rn-debugger.md tools
  frontmatter (runtime gate — spawned subagents fail fast)
- Removed agent: directive from test-feature/debug-screen/build-and-test
  commands; protocol now executes inline in parent session using skills
- Added PARENT-SESSION-ONLY label + body blockquote warnings to agents
- Updated using-rn-dev-agent meta-skill: Agent Map splits into
  "spawnable (read-only)" vs "parent-session-only (protocol playbooks)"
- Fixed docs-site agents/index.mdx to reflect the split
- Fixed stale "rn-tester agent cannot verify" in rn-code-reviewer.md
- Fixed build-and-test.md bash invocations missing <platform> arg
- Added README troubleshooting entry

Convention D609: agents split by invocation pattern — MCP-bound ones
are protocol playbooks for parent session, read-only ones are safe
to spawn via Task tool.

Author: Lykhoyda

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "rn-dev-agent",
       "description": "AI agent that fully tests React Native features on simulator/emulator — navigates the app, verifies UI, walks user flows, and confirms internal state.",
-      "version": "0.21.0",
+      "version": "0.21.1",
       "source": "./",
       "category": "mobile-development",
       "homepage": "https://github.com/Lykhoyda/rn-dev-agent"

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rn-dev-agent",
-  "version": "0.21.0",
+  "version": "0.21.1",
   "description": "AI agent that fully tests React Native features on simulator/emulator — navigates the app, verifies UI, walks user flows, and confirms internal state.",
   "author": {
     "name": "Anton Lykhoyda",

README.md

@@ -150,6 +150,7 @@ Claude Code
 | Zustand store error | Add `global.__ZUSTAND_STORES__` ([setup](https://lykhoyda.github.io/rn-dev-agent/getting-started/#zustand-stores-one-line)) |
 | Plugin not detected | `/plugin install rn-dev-agent@Lykhoyda-rn-dev-agent` then `/reload-plugins` |
 | Tools fail after upgrade | Restart Claude Code ([why](https://lykhoyda.github.io/rn-dev-agent/troubleshooting/)) |
+| Spawned subagent says "MCP tools unavailable" | Never spawn `rn-tester` / `rn-debugger` via Task tool — MCP stdio doesn't propagate to subprocesses (GH #31). Use `/rn-dev-agent:test-feature` or `/rn-dev-agent:debug-screen` instead; protocols run inline in the parent session. |
 
 [Full troubleshooting guide](https://lykhoyda.github.io/rn-dev-agent/troubleshooting/)
 

agents/rn-code-reviewer.md

@@ -64,7 +64,8 @@ Rate each potential issue 0–100:
 
 - **testID coverage** (Critical): Every `Pressable`, `TouchableOpacity`, `Button`,
   `TextInput`, and scrollable container must have a `testID`. Without testIDs,
-  the rn-tester agent cannot verify the feature via `cdp_component_tree` or Maestro.
+  the rn-tester protocol (run via `/rn-dev-agent:test-feature`) cannot verify
+  the feature via `cdp_component_tree` or Maestro.
 - **`__DEV__` guards** (Critical): All dev-only code must be wrapped in `if (__DEV__)`.
   This includes `global.__ZUSTAND_STORES__`, network mocks, debug logging, and
   dev menu setup. Shipping dev code to production is a security risk.

agents/rn-debugger.md

@@ -4,6 +4,8 @@ description: |
   Diagnoses broken or unexpected behavior in a React Native app running
   on simulator/emulator. Gathers parallel evidence (component tree, logs,
   network, store), narrows root cause, applies a fix, and verifies recovery.
+  PARENT-SESSION-ONLY: requires MCP tools (cdp_*, device_*, collect_logs) —
+  do NOT spawn via Task tool, run protocol inline in parent session (GH #31).
   Triggers: "something is broken", "debug this", "why isn't this working",
   "the screen is blank", "I see an error", "fix the crash"
 
@@ -33,7 +35,7 @@ description: |
   Frozen app could be paused debugger, blocked JS thread, or native crash — needs structured diagnosis.
   </commentary>
   </example>
-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__*cdp__*
+tools: Bash, Read, Write, Edit, Glob, Grep
 model: opus
 memory: true
 color: red
@@ -44,6 +46,20 @@ You are a React Native debugging agent. You diagnose broken UI, crashes,
 and unexpected behavior by gathering structured evidence from all available
 layers, then applying targeted fixes.
 
+> **CRITICAL — Invocation Constraint (GH #31):**
+> This agent uses MCP tools (`cdp_*`, `device_*`, `collect_logs`) which only
+> work when invoked in the **parent Claude Code session**, not when spawned
+> as a subagent via the Task tool. MCP stdio connections do not propagate
+> across subprocess boundaries.
+>
+> - **DO** invoke this agent's protocol inline from `/rn-dev-agent:debug-screen`
+>   or from the parent session directly
+> - **DO NOT** spawn this agent via `Task(subagent_type='rn-dev-agent:rn-debugger')`
+>   — the spawned subagent will not have access to `cdp_*` / `device_*` tools
+>
+> If you are reading this as a spawned subagent and notice you cannot call
+> CDP/device tools, **stop immediately**. Return control to the parent session.
+
 ## Safety Constraints
 
 - **NEVER change git state**: Do not run `git checkout`, `git stash`, `git reset`,

agents/rn-tester.md

@@ -4,6 +4,8 @@ description: |
   Tests React Native features on simulator/emulator. Verifies UI renders
   correctly, user flows work, and internal state matches expectations.
   Use when a feature has been implemented and needs verification.
+  PARENT-SESSION-ONLY: requires MCP tools (cdp_*, device_*) — do NOT spawn
+  via Task tool, run protocol inline in parent session (GH #31).
   Triggers: "test this feature", "verify it works", "check the implementation",
   "test on simulator", "run on device", "does it work"
 
@@ -33,7 +35,7 @@ description: |
   User is asking whether a feature works correctly, which requires live device testing.
   </commentary>
   </example>
-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__*cdp__*
+tools: Bash, Read, Write, Edit, Glob, Grep
 model: sonnet
 memory: true
 color: cyan
@@ -43,6 +45,21 @@ skills: rn-device-control, rn-testing, rn-debugging
 You are a React Native feature testing agent. After a feature is
 implemented, you verify it works correctly on a real simulator/emulator.
 
+> **CRITICAL — Invocation Constraint (GH #31):**
+> This agent uses MCP tools (`cdp_*`, `device_*`) which only work when invoked
+> in the **parent Claude Code session**, not when spawned as a subagent via
+> the Task tool. MCP stdio connections do not propagate across subprocess
+> boundaries.
+>
+> - **DO** invoke this agent's protocol inline from a slash command
+>   (`/rn-dev-agent:test-feature`) or from the parent session directly
+> - **DO NOT** spawn this agent via `Task(subagent_type='rn-dev-agent:rn-tester')`
+>   — the spawned subagent will not have access to `cdp_*` / `device_*` tools
+>
+> If you are reading this as a spawned subagent and notice you cannot call
+> CDP/device tools, **stop immediately**. Return control to the parent session
+> and ask it to run the testing protocol directly.
+
 ## Your Testing Protocol
 
 ### Step 0: Environment Check

commands/build-and-test.md

@@ -3,17 +3,46 @@ command: build-and-test
 description: Build the Expo/React Native app (local or EAS), install on simulator/emulator, start Metro, then test the specified feature end-to-end.
 argument-hint: [--eas profile] [feature-description]
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__*cdp__*
-agent: rn-tester
 ---
 
 Build the app and test this feature: $ARGUMENTS
 
-## Usage
+## Run the build + test protocol INLINE (parent session)
 
-```
-/rn-dev-agent:build-and-test <description>
-/rn-dev-agent:build-and-test --eas [profile] <description>
-```
+> **Important (GH #31):** Do NOT spawn the `rn-tester` agent via the Task tool.
+> MCP tools (`cdp_*`, `device_*`) are not available in spawned subagents.
+> Execute the build + test protocol directly in this parent session.
+
+Phase A — Build pre-flight (run in this session):
+
+1. **Detect platform** — check booted devices via `device_list` or `xcrun simctl
+   list devices booted` / `adb devices`. Record the result as `<platform>` =
+   `ios` or `android` — every script below needs it as argument 1.
+2. **Check if app is already running** — call `cdp_status`. If `cdp.connected
+   == true` AND `app.dev == true`, skip to Phase B.
+3. **Build / install** (substitute `<platform>` with `ios` or `android`):
+   - **No `--eas` flag:** run `bash $CLAUDE_PLUGIN_ROOT/scripts/expo_ensure_running.sh <platform>`
+     which triggers `npx expo run:ios` or `npx expo run:android` (local build).
+   - **With `--eas` flag:** run `bash $CLAUDE_PLUGIN_ROOT/scripts/eas_resolve_artifact.sh <platform> <profile>`
+     to find the artifact, then `bash $CLAUDE_PLUGIN_ROOT/scripts/expo_ensure_running.sh <platform> --artifact <path>`
+     to install.
+4. **Start Metro** if not running (`npx expo start` in background, or instruct
+   user to start it).
+5. **Confirm CDP** — call `cdp_status` again, must return `ok:true`.
+
+Phase B — Run the rn-tester 7-step protocol (load `rn-testing` skill):
+
+Follow the same protocol as `/rn-dev-agent:test-feature` — environment check,
+understand the feature, plan, navigate, execute+verify, edge cases, generate
+persistent test.
+
+## Verification (mandatory before declaring complete)
+
+- [ ] `cdp_status` returns `ok:true` with `cdp.connected: true` after Phase A
+- [ ] Every test assertion has concrete Evidence
+- [ ] At least one `device_screenshot` saved
+- [ ] `flows/<feature-name>.yaml` written
+- [ ] `cdp_error_log` shows 0 new errors at end
 
 ## Examples
 
@@ -23,18 +52,6 @@ Build the app and test this feature: $ARGUMENTS
 /rn-dev-agent:build-and-test --eas preview payment flow -- test a specific EAS profile
 ```
 
-## What This Does
-
-Extends the standard `rn-tester` 7-step protocol with a build pre-flight:
-
-1. **Detect platform** — checks for booted iOS simulator or Android emulator
-2. **Check if app is running** — calls `cdp_status` to see if Metro + Hermes are connected
-3. **Build/install if needed**:
-   - **No `--eas` flag**: runs `expo_ensure_running.sh` which triggers `npx expo run:ios` or `npx expo run:android` (local build, blocks until done)
-   - **With `--eas` flag**: runs `eas_resolve_artifact.sh` to find the artifact (cache → EAS servers), then `expo_ensure_running.sh --artifact <path>` to install
-4. **Start Metro** if not already running
-5. **Run the standard 7-step test protocol** (environment check, understand feature, plan test, navigate, execute+verify, edge cases, generate test file)
-
 ## Build Modes
 
 | Mode | When | Command |

commands/debug-screen.md

@@ -2,27 +2,42 @@
 command: debug-screen
 description: Diagnose why the current screen is broken, showing unexpected content, or crashing. Gathers parallel evidence from all layers and applies a targeted fix.
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__*cdp__*
-agent: rn-debugger
 ---
 
 Diagnose and fix the current screen state on the simulator/emulator.
 
-## Usage
-
-```
-/rn-dev-agent:debug-screen
-```
-
-## What This Does
-
-Invokes the `rn-debugger` agent, which runs a structured diagnostic flow:
-
-1. **Screenshot** -- captures current screen state immediately
-2. **Parallel evidence gathering** -- simultaneously reads error log, console, network log, and component tree
-3. **Error type identification** -- routes to the right investigation path (JS error vs native crash vs data mismatch vs navigation issue)
-4. **Root cause narrowing** -- reads source files, checks store state, inspects native logs if CDP shows nothing
-5. **Fix** -- applies minimal targeted fix, waits for Fast Refresh
-6. **Verify recovery** -- confirms error is gone, re-runs the failing action
+## Run the rn-debugger protocol INLINE (parent session)
+
+> **Important (GH #31):** Do NOT spawn the `rn-debugger` agent via the Task tool.
+> MCP tools (`cdp_*`, `device_*`, `collect_logs`) are not available in spawned
+> subagents. Execute the debugger protocol directly in this parent session
+> using the `rn-debugging` and `rn-device-control` skills as your reference.
+
+Load the `rn-debugging` skill and follow this diagnostic flow in this session:
+
+1. **Screenshot** — `device_screenshot` to capture the broken state immediately.
+2. **Parallel evidence gathering** — call these in parallel:
+   - `cdp_error_log` (JS errors)
+   - `cdp_console_log` (console output)
+   - `cdp_network_log` (recent requests)
+   - `cdp_component_tree(filter=...)` (rendered fiber)
+   - `collect_logs(sources=["native_ios"])` or `["native_android"]` for native crashes
+3. **Error type identification** — classify: JS error vs native crash vs data
+   mismatch vs navigation issue vs blank screen.
+4. **Root cause narrowing** — read source files flagged by stack traces, check
+   `cdp_store_state(path=...)`, inspect native logs if CDP shows nothing.
+5. **Fix** — apply the minimal targeted fix, save, wait for Fast Refresh
+   (or `cdp_reload(full=true)` for native changes).
+6. **Verify recovery** — reproduce the failing action AGAIN, confirm the bug
+   no longer reproduces, capture a "fixed" `device_screenshot`.
+
+## Verification (mandatory before declaring "fixed")
+
+- [ ] Root cause stated (not just symptom)
+- [ ] Reproduction steps executed AGAIN after the fix → bug gone
+- [ ] `cdp_error_log` shows 0 new errors after fix
+- [ ] "Before" and "after" screenshots both saved
+- [ ] No adjacent files refactored ("while I'm here")
 
 ## When to Use
 
@@ -35,6 +50,6 @@ Invokes the `rn-debugger` agent, which runs a structured diagnostic flow:
 
 ## What You Don't Need to Do
 
-You don't need to describe the problem in detail. The agent gathers its own
-evidence from the running app. Just run the command while the broken state
-is visible on the simulator.
+You don't need to describe the problem in detail. The MCP tools gather their
+own evidence from the running app. Just run the command while the broken
+state is visible on the simulator.

commands/test-feature.md

@@ -3,16 +3,42 @@ command: test-feature
 description: Test a React Native feature on the running simulator/emulator. Verifies UI, user flows, and internal state. Generates a persistent Maestro test file.
 argument-hint: [feature-description]
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, mcp__*cdp__*
-agent: rn-tester
 ---
 
 Test this React Native feature: $ARGUMENTS
 
-## Usage
-
-```
-/rn-dev-agent:test-feature <description>
-```
+## Run the rn-tester protocol INLINE (parent session)
+
+> **Important (GH #31):** Do NOT spawn the `rn-tester` agent via the Task tool.
+> MCP tools (`cdp_*`, `device_*`) are not available in spawned subagents.
+> Execute the rn-tester protocol directly in this parent session using the
+> `rn-testing` and `rn-device-control` skills as your reference.
+
+Load the `rn-testing` skill and follow this 7-step protocol in this session:
+
+1. **Environment check** — call `cdp_status`. If it fails, stop and tell the
+   user to run `/rn-dev-agent:setup`.
+2. **Understand the feature** — read implementation files, find testIDs, routes,
+   store slices.
+3. **Plan the test** — write test steps and expected outcomes BEFORE executing.
+4. **Navigate to start** — use `cdp_navigate` or `device_deeplink` to reach the
+   starting screen.
+5. **Execute and verify** — for each step:
+   - Act (`device_press`, `device_fill`, `device_find`)
+   - Wait (`assertVisible` or 1-2s settle)
+   - Verify UI (`cdp_component_tree(filter=...)`)
+   - Verify data (`cdp_store_state(path=...)` + `cdp_network_log`)
+6. **Edge cases** — test empty state, error state, back navigation, rapid taps.
+7. **Generate persistent test** — write `flows/<feature-name>.yaml` for CI.
+
+## Verification (mandatory before declaring "tested")
+
+- [ ] `cdp_status` returned `ok:true` with `cdp.connected: true`
+- [ ] Every assertion has concrete Evidence (not "looks fine")
+- [ ] At least one `device_screenshot` saved
+- [ ] `flows/<feature-name>.yaml` written
+- [ ] `cdp_error_log` shows 0 new errors at end of flow
+- [ ] Cross-platform check via `cross_platform_verify` (or single-platform noted)
 
 ## Examples
 
@@ -22,23 +48,11 @@ Test this React Native feature: $ARGUMENTS
 /rn-dev-agent:test-feature profile screen -- edit name, upload photo, save
 ```
 
-## What This Does
-
-Invokes the `rn-tester` agent, which runs a 7-step verification protocol:
-
-1. **Environment check** -- confirms Metro running, CDP connected, no RedBox
-2. **Understand the feature** -- reads implementation files, finds testIDs, routes, store slices
-3. **Plan the test** -- writes test steps and expected outcomes before executing
-4. **Navigate to start** -- uses deep links or Maestro to reach the starting screen
-5. **Execute and verify** -- for each step: act (Maestro), wait (assertVisible), verify UI (cdp_component_tree), verify data (cdp_store_state + cdp_network_log)
-6. **Edge cases** -- tests empty state, error state, back navigation, rapid interactions
-7. **Generate persistent test** -- writes `flows/<feature-name>.yaml` for CI
-
 ## Prerequisites
 
 - iOS Simulator or Android Emulator running with the app loaded
 - Metro dev server running (`npx expo start` or `npx react-native start`)
-- Maestro or maestro-runner installed (`brew install maestro`)
+- Maestro or maestro-runner installed
 - For Zustand apps: `if (__DEV__) global.__ZUSTAND_STORES__ = { ... }` in app entry
 
 ## Output

docs-site/src/content/docs/agents/index.mdx

@@ -1,26 +1,38 @@
 ---
 title: Agents
-description: 5 specialized agents for testing, debugging, architecture, exploration, and code review.
+description: 5 specialized agents — 3 spawnable for parallel codebase analysis, 2 parent-session-only for live device testing and debugging.
 ---
 
-Agents are autonomous sub-agents that Claude Code spawns to handle specific tasks. Each agent has its own model, tools, and protocol.
+The plugin has **5 agents** split into two categories based on what tools they need.
+
+## Spawnable agents (read-only)
+
+These use only `Glob, Grep, LS, Read` — safe to spawn via the Task tool, typically in parallel.
 
 | Agent | Model | Purpose |
 |-------|-------|---------|
-| [`rn-tester`](/rn-dev-agent/agents/rn-tester/) | Sonnet | 7-step test verification protocol |
-| [`rn-debugger`](/rn-dev-agent/agents/rn-debugger/) | — | Parallel evidence gathering + targeted fix |
 | [`rn-code-explorer`](/rn-dev-agent/agents/rn-code-explorer/) | Sonnet | Codebase mapping: screens, store, navigation, testIDs |
 | [`rn-code-architect`](/rn-dev-agent/agents/rn-code-architect/) | Opus | Architecture design with E2E proof flow |
-| [`rn-code-reviewer`](/rn-dev-agent/agents/rn-code-reviewer/) | — | Correctness, RN conventions, project patterns |
+| [`rn-code-reviewer`](/rn-dev-agent/agents/rn-code-reviewer/) | Sonnet | Correctness, RN conventions, project patterns |
+
+## Parent-session-only agents (protocol playbooks)
+
+These agents' protocols require `cdp_*` / `device_*` MCP tools. **Do NOT spawn them via the Task tool** — MCP stdio connections don't propagate across subprocess boundaries (see [GitHub #31](https://github.com/Lykhoyda/rn-dev-agent/issues/31)). The agent files are **protocol playbooks** the parent session reads and executes inline.
+
+| Agent | Model | Purpose | How to invoke |
+|-------|-------|---------|---------------|
+| [`rn-tester`](/rn-dev-agent/agents/rn-tester/) | Sonnet | 7-step test verification protocol | `/rn-dev-agent:test-feature` — runs inline |
+| [`rn-debugger`](/rn-dev-agent/agents/rn-debugger/) | Opus | Parallel evidence gathering + targeted fix | `/rn-dev-agent:debug-screen` — runs inline |
 
 ## When agents are used
 
 In the `rn-feature-dev` pipeline:
-- **Phase 2 (Exploration):** 2-3 `rn-code-explorer` agents run in parallel
-- **Phase 4 (Architecture):** `rn-code-architect` designs the blueprint
-- **Phase 5.5 (Verification):** `rn-tester` verifies live on simulator
-- **Phase 6 (Review):** 3 `rn-code-reviewer` agents check different aspects
+- **Phase 2 (Exploration):** 2-3 `rn-code-explorer` agents spawned in parallel
+- **Phase 4 (Architecture):** `rn-code-architect` spawned for blueprint design
+- **Phase 5.5 (Verification):** Verification runs inline in parent session (MCP tools)
+- **Phase 6 (Review):** 2-3 `rn-code-reviewer` agents spawned in parallel
+- **Phase 8 (E2E Proof):** Proof flow runs inline in parent session (MCP tools)
 
 Standalone:
-- `/debug-screen` spawns `rn-debugger`
-- `/test-feature` spawns `rn-tester`
+- `/rn-dev-agent:debug-screen` — runs the `rn-debugger` protocol inline
+- `/rn-dev-agent:test-feature` — runs the `rn-tester` protocol inline