feat(sidecar): govern Composio tool execution

[veeso]

Why

The personal assistant reaches Gmail and Google Calendar through Composio, which means every one of those actions leaves the agent over the same two hostnames and the same handful of web addresses. Looking at the address alone cannot tell reading an inbox apart from emptying it, so none of those actions could be governed by policy. Closes FIR-435. Slack and Notion are out of scope here and tracked in FIR-458.

What Changed

• The Sidecar now reads Composio requests and works out which tool was actually asked for, then runs that tool through the normal permission and policy checks before anything leaves the machine.
• Reviewed catalogs for Gmail (63 tools) and Google Calendar (49) are shipped with the Sidecar. All 112 tools were classified by hand, and a tool that is not in a catalog is refused. That includes every Slack and Notion tool until FIR-458 lands reviewed catalogs for them.
• Linking, changing, or removing a connected account or auth configuration is treated as a permission change and goes through the same checks, so an agent cannot quietly widen which accounts it can reach. Read-only listing still passes through.
• Policies and the audit log now name a tool in a way that does not depend on how the request was sent, and they can also match on the toolkit, the account selector, the session, and the position of a tool inside a batch.
• A request that asks for several tools at once is all or nothing. Every tool in it is checked and recorded, and if any one of them is refused, nothing is sent upstream at all.
• Google Calendar needed four new permission categories, so reading, creating, changing, and deleting events can be granted separately.
• Anything the Sidecar cannot understand is refused rather than let through: unknown addresses, unreadable payloads, custom tools, raw pass-through calls, and remote shell or workbench tools. In monitor mode those requests are forwarded and recorded instead of blocked, so observe-only stays observe-only.
• If the configuration names the Composio hostnames but leaves them uninspected, the Sidecar says so at startup instead of silently losing visibility.

How to Review

This change cannot be usefully split. The parts depend on each other in a straight line, so any smaller pull request would land code on main that nothing calls yet, which is the exact problem this branch was written to avoid. Instead, here is the short path through it.

Most of the added snapshot lines are machine-generated tool snapshots that nobody needs to read. They are marked as generated in .gitattributes, so GitHub already collapses them. The real reading is the Rust, in five sittings, in this order.

1. The shared code path, about 25 lines. crates/firma-core/src/envelope.rs adds policy_resource_display(), and it replaces resource_display() at 12 call sites, one in crates/firma-sidecar/src/enforcement/capability_validation.rs, four in crates/firma-sidecar/src/enforcement/constraint_enforcement.rs, and seven in crates/firma-sidecar/src/pipeline.rs. This is the only part of the branch that runs for traffic that has nothing to do with Composio, so it deserves the most attention per line. What to confirm: with no policy_resource key present, the new method returns exactly what the old one did, which makes every one of those call sites a no-op for existing traffic.

2. The trust boundary, about 800 lines. crates/firma-sidecar/src/composio.rs is where attacker-controlled bytes are interpreted. Read it asking two questions. Does every shape the decoder does not recognise end in a refusal rather than a fallthrough? Do any tool arguments survive into an envelope, a resource, or a log line? There is a custom JSON parser at the bottom of the file, and the reason it exists is that the Sidecar decides on a parse of the body but forwards the original bytes, so a duplicate key that this parser and Composio's parser resolve differently would be an authorisation bypass. The account lifecycle handling is new in this revision: writes to the connected-account and auth-configuration routes become governed permission changes instead of passing through.

3. The all-or-nothing rule, about 600 lines. enforce_composite in crates/firma-sidecar/src/pipeline.rs and the handle_composio_* functions in crates/firma-sidecar/src/handler.rs. One thing matters here: the upstream request is sent at most once when everything is allowed, and exactly zero times when anything is refused. Monitor mode is the awkward case, because it has to forward the request while still recording what would have been blocked, and it now does that for undecodable requests and protocol upgrades too, not only for policy refusals.

4. The classifications, two files, no code. The .mapping.json files under crates/firma-sidecar/config/composio/. Each line assigns one Composio tool to one permission category. This is judgement, not correctness, and it is the part most likely to be wrong in a way tests cannot catch. The known judgement calls, such as the vacation auto-responder counting as sending mail, are written down in docs/architecture/composio-enforcement.md.

5. Everything else can be skimmed. The Cedar policy context is built in insert_composio_context in crates/firma-sidecar/src/enforcement/constraint_enforcement.rs and declared in crates/firma-core/firma.cedarschema. Catalog loading and validation is crates/firma-sidecar/src/composio/catalog.rs. The refresh tool is scripts/composio_catalog.py. Tests mostly enumerate refusal cases, and one drives a refusal through the real proxy and certificate interception path end to end.

Risks / Notes

• The classification of each tool is a judgement call and is the most useful thing to review. The judgement calls with side effects, like mail filters that can forward messages elsewhere and calendar invitations that email arbitrary people, are documented for policy authors.
• Both Composio hostnames must be intercepted rather than passed through untouched. If they are passed through, the tool name is hidden and nothing can be governed. The Sidecar now warns at startup when a configuration that references those hostnames leaves them uninspected, bypassed, or without strict interception.
• The catalogs are built into the Sidecar, so adding newly released Composio tools means refreshing a catalog, classifying the new tools, and rebuilding. That is deliberate: a Composio release cannot quietly widen what an agent is allowed to do. Version pinning is strict for direct execution; the session routes carry no version, and that limit is documented.
• No change to the shared audit format. A tool is identified by its category and its name in the audit record. Credentials, tool arguments, and provider responses are never recorded.

AI Assistance

Claude Opus 5 (claude-opus-5); review fixes with Claude Fable 5 (claude-fable-5).

https://claude.ai/code/session_01NRAaNueJjd9Z7rJsSjBW3e

[veeso]

prevents duplicate object keys