google / google/adk-python-community
feat(plugins): add AuthorityRoutingPlugin — pre-execution authority posture (ADVISE/EXECUTE/DEFER/STOP)
- Langage dominant
- Python
- Étoiles
- 182
- Forks
- 75
- Métriques de merge des PR
- Aucune PR mergée en 30 j
Description
## Problem
Tool schemas and permissions govern *access* — which tools exist and who may call them. They do not govern *authorization*: whether the agent was allowed to act **at all** for a given request, and within what scope. That gap is where three recurring agent failures live:
- **advice becomes action** — the user asked for a recommendation and the agent executed anyway;
- **scope expansion** — one bounded edit ballooned into a dependent workflow;
- **missing approval** — an approval was clearly required and the agent proceeded.
`AgentGovernancePlugin` (policy-as-code allow/deny) and the HITL approval gateway answer *"is this tool call permitted by policy?"*. Neither answers *"was the agent authorized to act at all, and within what scope?"* — and both require external infrastructure (a policy engine / an approval service).
## Proposal
Add `AuthorityRoutingPlugin`, a self-contained `BasePlugin` that assigns an **authority posture** to every tool call before it runs:
| Posture | Meaning |
| --- | --- |
| ADVISE | Recommendations only; no tool side effects. |
| EXECUTE | Act, within an explicitly bounded scope. |
| DEFER | Pause and request authorization when scope/approval is unclear. |
| STOP | Refuse when the work is not allowed. |
Two stages produce the final posture:
1. **Posture router** (optional, caller-supplied callable — typically a model call) returning a validated verdict with a scope statement.
2. **Deterministic guard** — an irreversibility keyword tripwire + an approval-state check — composed with the router under **most-restrictive-wins**: plain code can only make a posture *stricter*, never looser.
Design properties:
- **Fail-closed** — an unparseable or raised router verdict defaults to DEFER.
- **Guard-only mode** (no router) is fully deterministic and needs no model and no extra dependency.
- Complements, rather than duplicates, the existing governance plugins.
## Scope
- `src/google/adk_community/plugins/authority_routing_plugin.py` + export
- `tests/plugins/test_authority_routing_plugin.py` (deterministic, no credentials)
- `contributing/samples/authority_routing/` (runnable sample with live output)
Happy to adjust the API surface or placement to match maintainer preferences. I have an implementation ready and will open a PR referencing this issue.
Guide de contribution
Ouvrir le guide de contribution
Piste de recherche
Commencez par lire le comportement existant de BasePlugin et du plugin de gouvernance, puis examinez les chemins proposés dans src/google/adk_community/plugins/authority_routing_plugin.py et tests/plugins/test_authority_routing_plugin.py. Ajoutez des tests déterministes pour le routage de posture, la gestion fail-closed, le garde-fou d'irréversibilité, les vérifications d'approbation et le comportement selon lequel la règle la plus restrictive l'emporte, ainsi que l'exemple exécutable sous contributing/samples/authority_routing/. La tâche est terminée lorsque le plugin est exporté et que l'exemple produit une sortie en direct sans identifiants.
Rédigé par le modèle d'indexation à partir du texte de l'issue.
Évaluation
- Stack technique
- python
- Domaine
- security
- Type d'issue
- Fonctionnalité
- Difficulté
- 5/5
- Temps estimé
- Plus d'une semaine
- Activité
- Calme
- Clarté
- Plutôt claire
- Accessibilité débutants
- 45/100