adr_approve blocks subagents permanently — MCP permission prompt only surfaceable in main thread

[le-dawg]

Summary

When adr_approve is called from a subagent (e.g. via Claude Code's Agent tool), the MCP tool invocation triggers a permission prompt that only the human operator can approve in the main thread UI. Subagents run in isolated contexts with no UI surface — the permission prompt is never shown, the call hangs or is auto-rejected, and the subagent is permanently stuck with no recovery path.

Environment

• Claude Code with MCP adr-kit server
• adr-kit v0.2.7 (solution8-com/AIRStack-ADRKit fork, also reproducible on upstream)
• Triggered when dispatching implementation agents that need to create + approve ADRs as part of their task

Reproduction

1. Dispatch a subagent via Claude Code's Agent tool
2. Subagent calls mcp__adr-kit__adr_create — succeeds (no permission prompt required)
3. Subagent calls mcp__adr-kit__adr_approve — triggers Claude Code permission prompt
4. Permission prompt appears only in main thread UI, not visible to subagent or its operator context
5. Subagent waits indefinitely or receives auto-rejection with no actionable error message
6. Human operator in main thread cannot see the pending prompt — it is silently consumed

Root Cause

adr_approve modifies files on the filesystem (ADR markdown files + adr-index.json). Claude Code treats MCP tool calls that write to the repository as potentially destructive and gates them with a human approval prompt. This is by design in Claude Code's permission model.

adr_create does the same filesystem writes but apparently does not trigger the prompt in practice — the difference may be that approve mutates an existing file (status change) whereas create is additive.

Impact

• Subagent-driven development workflows (dispatching fresh agents per task) cannot use adr_approve at all
• Any automated or agentic workflow that needs to create + approve ADRs in one pass is blocked
• No CLI fallback: adr-kit approve is not a CLI subcommand — approval is MCP-only

Note: this is separate from issue #24 (parallel approval rejections). This issue occurs even with a single sequential adr_approve call inside a subagent.

Suggested Mitigations

Option A — Document the constraint (minimal)

Add a note to README / MCP tool description that adr_approve must be called from the main thread only, never from a subagent. Subagents can call adr_create; the human or main-thread agent handles approval.

Option B — Non-interactive approve mode (preferred)

Add a --no-confirm / auto_approve parameter to adr_approve that skips the permission-gated filesystem write and instead writes directly. This would let subagents approve ADRs in contexts where the calling agent has already been granted trust (e.g. an agent explicitly told "approve all ADRs you create").

Option C — Split into two operations

Expose a adr_set_status tool that only updates the YAML status field without triggering a permission prompt. adr_approve would call adr_set_status + emit the human-approval event separately. Subagents use adr_set_status directly.

Related

• Issue adr_approve parallel MCP calls cause silent rejections in Claude Code #24 — parallel approval rejections (different failure mode, same adr_approve function)
• Issue adr_approve: approval_notes insertion corrupts YAML frontmatter when last field has no trailing newline #26 — YAML corruption in approval_notes insertion
• Upstream fix for setup-claude creates wrong config filename (.claude-mcp-config.json instead of .mcp.json) #23/adr_approve: approval_notes insertion corrupts YAML frontmatter when last field has no trailing newline #26 merged in solution8-com/AIRStack-ADRKit PR Add agent-driven task and git workflows #1