# ToolRouter

Policy-gated execution boundary for Stripe, Gmail, sandbox, and external tool actions.

Status: implemented
Version: latest
Review: source-backed

## Side-effect boundary

ToolRouter routes tool actions through replay, demo, sandbox, sensitive-action, spend, outbound, and content-firewall policies before adapters execute. It is the point where agent intent becomes a governed external operation.

| Stage | Check | Evidence |
| --- | --- | --- |
| Normalize | Provider, operation, account, project, run, idempotency key | ToolCall input summary |
| Policy | Live mode flags, account caps, outbound/send/spend rules | Allowed or denied policy result |
| Approval | Required approval exists and matches action | ApprovalRequest and ApprovalEvent |
| Readiness | Provider credentials, alias, webhook, sandbox, or runtime status | Integration readiness metadata |
| Execute | Adapter call with redacted payload | ToolCall status and provider result summary |
| Audit | Record outcome, denial reason, hashes, and linked refs | AuditEvent, RunEvent, ledger/proof entry |

## Provider families

| Provider family | Example operations | Default posture |
| --- | --- | --- |
| Stripe | Create checkout session, guarded spend/provisioning | Revenue allowed when configured; spend approval-gated |
| Gmail | Create draft, send, reply, alias check | Draft/readiness gated; live send blocked without approval |
| Hermes | Submit runtime task, inspect status | Scoped context only, no raw secrets |
| NVIDIA | Model decision, scoring, safety review | Structured route and schema required |
| Sandbox/NemoClaw posture | Dry-run external action or network posture | Used for proof and safe previews |

ToolRouter records ToolCall, AuditEvent, RunEvent, and sandbox proof for allowed and denied paths. Live spend and send actions require explicit account policy and durable approvals.


Source paths:
- `lib/autonomous_agency/tools/tool_router.ex`
- `test/autonomous_agency/tools`