# 0015 — Aggregate the copilot "Pendientes" feed through the tool registry

- **Status:** accepted
- **Date:** 2026-06-15
- **Deciders:** Core team
- **Tags:** copilot, agents, modules, rbac

## Context

The IA redesign (Fase 2, `docs/technical/copilot/ia-redesign-plan.md`)
adds a read-only **Pendientes** feed to the copilot drawer: open work the
caller can act on — overdue recalls, budgets awaiting a response, etc.
The data lives in other modules (`recalls`, `budget`, …). Copilot keeps
`manifest.depends = []` and must not import another module's service
(ADR 0001/0003). The question the roadmap flagged: **how does copilot
aggregate cross-module signals for this feed?**

Three mechanisms were on the table: call the modules' agent **tools**
through the registry; import their **read services** directly; or react to
**events** and maintain a copilot-owned projection table.

## Decision

The Pendientes feed aggregates by calling the **existing agent tools**
through the global `tool_registry`, with an `AgentContext` whose
permissions are `get_role_permissions(caller_role)` — the exact same path
the chat turn and the morning digest already use. No new tables, no
cross-module imports.

Clarifications:

- One reusable per-clinic copilot agent + a single reusable session
  (metadata `surface=copilot_pending`) back the audit context, so a
  drawer open does **not** insert agent/session rows each time.
- RBAC parity is mechanical: the registry enforces each tool's
  `permissions` against the caller's role, so the feed can never surface
  anything the caller couldn't see in the owning module.
- A tool whose module is uninstalled is simply absent from
  `tool_registry.list()` and its section is omitted.

## Consequences

### Good

- `depends = []` holds — copilot stays cleanly removable.
- RBAC parity for free; no second authorization path to keep in sync.
- Consistent with chat + digest — one aggregation pattern in the module.
- Read tool calls land in `agent_audit_logs`, so they show up in the
  `GET /metrics` dashboard like any other usage.

### Bad / accepted trade-offs

- The feed is limited to what tools expose; a new pending source needs a
  tool (which is the right place for it anyway).
- Each pending fetch executes N tool calls inline (currently 2). Bounded
  and fast; if it grows, batch or cache behind the reusable session.
- Sources without a tool yet (cash mismatch, the "Hecho"/done timeline
  filter) are deferred until the relevant tool exists.

## Alternatives considered

- **Import module read services directly** — rejected: breaks the
  `depends = []` contract and duplicates the RBAC checks the tools
  already encapsulate.
- **Event-driven projection table** — rejected for the live feed:
  eventual-consistency and a copilot-owned copy of other modules' state
  add bug surface for a read that the registry serves synchronously.
  (Events remain the right tool for *nudges*, ADR 0014 — a one-shot
  reaction, not a live aggregate.)

## How to verify the rule still holds

- `tests/test_copilot_pending.py` — the endpoint runs and reuses a single
  session across calls.
- `tests/test_module_isolation.py` — copilot declares no `depends` and
  imports no sibling module.
- grep: `PendingService` calls only `tool_registry`, never
  `from app.modules.<other>` .

## References

- `backend/app/modules/copilot/service.py` (`PendingService`)
- `backend/app/modules/copilot/router.py` (`GET /pending`)
- ADR 0001 (modular contract), ADR 0003 (event bus over imports),
  ADR 0014 (proactivity / nudges)
- `docs/technical/copilot/ia-redesign-plan.md` (Fase 2)