claude-code - 💡(How to fix) Fix Sub-agent attempts `exit_plan_mode` as Bash command, fails with Exit code 127

Summary

A custom sub-agent dispatched via the Task tool attempted to execute exit_plan_mode as a Bash command. The command failed with Exit code 127 (command not found) because exit_plan_mode is not a shell command — it appears to be an internal Claude Code mechanism that should not be invoked via the Bash tool.

Environment

• Claude Code surface: VS Code extension (Windows)
• OS: Windows 11 Pro 10.0.26200
• Shell: PowerShell 7+ (pwsh) and Git Bash both available
• Sub-agent type: Custom user-defined agent declared in .claude/agents/code.md (tools: Read, Write, Bash, Glob, Grep)
• Date observed: 2026-05-06 (Pacific Europe / EEST)

Reproduction (observed once)

1. A pipeline orchestrator (custom slash command /feature-request) dispatched the custom Code Agent via the Task tool.
2. The Code Agent ran in plan mode at some point during its execution.
3. After plan acceptance, the sub-agent attempted to exit plan mode by calling exit_plan_mode via the Bash tool (not as an ExitPlanMode tool invocation).
4. The Bash tool executed exit_plan_mode against the system shell, which returned Exit code 127 (command not found).

The agent definition file (.claude/agents/code.md) was reviewed exhaustively and contains no instruction advising exit_plan_mode as a shell command. The string exit_plan_mode does not appear in the agent definition. The issue is therefore not in user-authored guidance — it appears to originate either from the model's own interpretation of plan-mode-exit semantics in a sub-agent context, or from harness behaviour that issued the command via the Bash tool.

Expected behaviour

Plan-mode exit should occur via the dedicated ExitPlanMode tool (a built-in Claude Code tool), not via Bash(exit_plan_mode). The transition from plan mode to non-plan mode after plan acceptance should be handled internally by the Claude Code runtime without the sub-agent attempting to spawn a shell command.

Actual behaviour

The sub-agent invoked the Bash tool with the literal command exit_plan_mode. The shell returned Exit code 127. The plan-mode exit did not complete via the failed Bash invocation; the agent continued execution but the failure was visible in the chat log as a tool error.

Frequency

Observed once during a pipeline run (STORY-T03 backend feature implementation, 2026-05-06). Did not recur in a subsequent pipeline run on 2026-05-07 (Process Rules Batch 2). Filing this issue proactively because the failure mode is unambiguously a harness or model bug — there is no user-side mitigation possible — and to record the observation in case the bug recurs for other users.

Workaround

Not applicable. The Bash invocation of exit_plan_mode fails benignly (Exit code 127, no side effects), and the sub-agent typically continues execution. A user-side workaround would be to add Bash(exit_plan_mode) to the project's permission allowlist to suppress any prompts that the failed command triggers, but this does not fix the underlying issue.

Suggestion

Investigate why the model or harness emits exit_plan_mode as a Bash command in custom-sub-agent contexts. Either:

1. Document explicitly that custom sub-agents should never attempt exit_plan_mode as a shell command, and document the correct plan-mode exit mechanism for sub-agents (ExitPlanMode tool, or auto-exit on plan acceptance).
2. Patch the harness so that any Bash(exit_plan_mode) call from a sub-agent is intercepted and treated as an ExitPlanMode invocation (or a no-op if plan-mode has already exited).

Thank you for the great tool — happy to provide additional logs or context if helpful.