ADR-020: Compiled Tool Mediation via cllama

[mostlydev]

Summary

https://github.com/mostlydev/clawdapus/blob/60438186e1a42d7fe3fb50922aa27157eb018ebf/docs/decisions/020-cllama-compiled-tool-mediation.md

• Defines how cllama mediates tool execution between LLM providers and pod services
• Uses MCP-shaped tool schemas delivered through provider-native tool calling (not MCP runtime)
• Two delivery modes: mediated (cllama owns tool loop, zero runner changes) and native (runner owns loop, future steady state contingent on audit parity)
• Extends credential starvation to service tools — agents never see service URLs or credentials
• Follows the existing feed pipeline pattern: declare → compile → inject

Review context

Reviewed across four rounds by three independent models (Codex, Gemini, Claude). Key design decisions:

• Single executor per response — mixed runner-local + pod-shared tool_calls in mediated mode refuse execution (no fabricated results)
• Three-layer authority — topology (surfaces), verb authority (tools:), credential scope (principals) are independent
• No tools by default — explicit opt-in required even when the service descriptor declares tools
• MCP as schema vocabulary, not runtime — transitional compatibility layer, MCP transport is Phase 4

Test plan

• Team review of architectural direction
• Validate descriptor v2 shape against existing claw.describe v1 compatibility
• Confirm tools: / tools-defaults: grammar fits pod-defaults machinery

🤖 Generated with Claude Code