Summary

Two doc-only changes anticipating the broader cleanup tracked in #2618:

1. ICED banner on docs/concepts/exec-approvals-architecture.md — the architecture described is not currently implemented. The gateway handlers for exec.approval.{request,waitDecision,resolve} were deleted by PR gut: delete 8 zero-caller EXCLUDE-STUB files in src/gateway/ #2375 (2026-04-16); the macOS-mediated path is broken (verified by the audit in PR docs(audit): exec.approval.* (singular) wire-path broken — #2606 #2609 — see docs/refactor/exec-approval-singular-audit-2606.md). Status changed: Accepted → Iced. Doc preserved for historical context only; will be replaced when the new approach ships. Banner links to Audit: exec-approvals request/decision/resolve subsystem registration survives a gut — wire-path or unregister #2606 (audit), Cleanup: gut singular exec.approval.* stranded surface (#2606 follow-up) #2618 (cleanup), AgentRuntime: route per-call tool approval requests to messaging channels #2616 (the new AgentRuntime tool-approval routing direction).

2. docs/concepts/middleware-architecture.md § The Middleware Boundary Principle table gains a row clarifying the boundary for tool-approval routing:

   • LEFT (RemoteClaw): AgentRuntime tool-approval routing (capture and surface to channels)
   • RIGHT (Agent): Tool-execution decisions and the actual invocation post-approval

   Plus a clarifying paragraph: routing is RemoteClaw's because the user is reachable only via RemoteClaw's channel adapters (the "requires RemoteClaw infrastructure?" test is satisfied); tool execution itself remains the agent CLI's responsibility. Paragraph links to AgentRuntime: route per-call tool approval requests to messaging channels #2616 for implementation tracking.

Why now

The broader code cleanup (gut 4 stranded callers + protocol declarations + tests) is in #2618 and will land separately. The doc updates land here because:

• They're independent of the code surgery (no schema changes, no code changes — just docs)
• They're worth getting in front of any contributor reading the docs today, who would otherwise be misled about the singular exec.approval.* path being functional
• The boundary-table refinement signals the architectural commitment ahead of the implementation work in AgentRuntime: route per-call tool approval requests to messaging channels #2616

Test plan

• pnpm check clean (format:check, tsgo, lint, lint:tmp:no-random-messaging, lint:no-remoteclaw-ai, lint:ui:no-css-class-drift) — ran via pre-commit hook
• Doc-only changes; no source/schema/test changes
• All issue/PR references in the new content resolve to existing remoteclaw issues (gut: delete 8 zero-caller EXCLUDE-STUB files in src/gateway/ #2375, Audit: exec-approvals request/decision/resolve subsystem registration survives a gut — wire-path or unregister #2606, docs(audit): exec.approval.* (singular) wire-path broken — #2606 #2609, AgentRuntime: route per-call tool approval requests to messaging channels #2616, Cleanup: gut singular exec.approval.* stranded surface (#2606 follow-up) #2618)

🤖 Generated with Claude Code