Présentation

Le agent-usage-guard est un module pour Claude Code (versions v2.1.287 et supérieures) qui intervient avant chaque appel d’agent. Il lit en temps réel les compteurs d’utilisation du plan (fenêtre de 5 heures et pourcentage hebdomadaire) et bloque les scénarios susceptibles d’épuiser la fenêtre de quota.

Fonctionnement technique

Le mod s’insère dans le pipeline d’exécution : avant le lancement d’un sous‑agent, d’un appel d’outil ou d’une boucle de retry, il déclenche un hook qui compare le nombre d’agents actifs, la taille du contexte et le taux de consommation avec des seuils configurés. Si un dépassement potentiel est détecté, le guard interrompt le processus et affiche une boîte de dialogue native de Claude Code, demandant à l’utilisateur d’approuver ou de refuser l’opération. Les paramètres d’autorisation sont temporaires : un accord lève la restriction pendant la durée du plan ou jusqu’à l’expiration du contexte (maximum une heure), tandis qu’un refus impose un blocage de 10 minutes (AGENT_GUARD_WINDOW_SECONDS). En cas de défaillance d’un hook, le guard passe en mode « fails open », laissant l’événement se dérouler pour ne pas interrompre la session.

/plugin marketplace add rbartoli/agent-usage-guard
/plugin install agent-usage-guard@agent-usage-guard
/reload-plugins
/agent-guard

Analyse d’impact et limites

Sur un test réel, un prompt intensif a généré 394 sous‑agents, 341 en parallèle, et a consommé 84 M de tokens en dix minutes, entraînant immédiatement le blocage « Claude usage limit reached ». Sur une période de 60 jours, l’auteur a enregistré 12 verrouillages et 166 fenêtres de dix minutes, démontrant la fréquence du problème. Le guard a ainsi évité plus de 12 verrouillages supplémentaires, économisant potentiellement plusieurs dizaines de dollars de facturation selon le tarif du plan. Le module fonctionne sans connexion réseau et ne stocke que des compteurs agrégés, préservant la confidentialité des prompts et des réponses. Cependant, il peut empêcher des charges de travail légitimes qui nécessitent un grand contexte ou un parallélisme important, obligeant l’utilisateur à ré‑approuver manuellement chaque burst. De plus, la granularité des seuils (par ex. 10 minutes pour les agents) est fixe et ne s’adapte pas automatiquement aux variations de la taille du plan.