Agent Tracker

Hook Claude Code pour l'observabilité des sous-agents. Émet des événements structurés lors de chaque délégation (spawn, done, error) et les écrit dans un fichier de trace JSONL.

Fonctionnement

Le hook intercepte les appels à l'outil Agent (via le hook event PostToolUse) et émet :

• spawn — quand un sous-agent est lancé (capte le type, le modèle, la description)
• done — quand un sous-agent termine (capte la durée, le statut, les tokens)
• error — quand un sous-agent échoue

Trace JSONL

Les événements sont écrits dans ~/.arcterm/agent-trace.jsonl au format JSON Lines :

{"id":"abc-123","type":"spawn","timestamp":"2026-03-25T10:00:00.000Z","provider":"claude-code","agentType":"executor","model":"sonnet","promptDescription":"Implémenter le module auth","schemaVersion":1}
{"id":"abc-123","type":"done","timestamp":"2026-03-25T10:00:45.000Z","provider":"claude-code","agentType":"executor","durationMs":45000,"status":"completed","schemaVersion":1}

Corrélation spawn↔done

Le tracker utilise des fichiers de corrélation temporaires (~/.arcterm/corr-*.json) pour relier les événements spawn et done d'un même agent. Les fichiers de corrélation ont un TTL de 60 minutes et sont nettoyés automatiquement.

Rotation

Le fichier de trace est limité à 1 MB. Quand la limite est atteinte, le fichier actuel est renommé en .jsonl.bak et un nouveau fichier est créé.

Schema

Champ	Type	Description
id	string	Identifiant unique de l'événement
type	spawn | done | error	Type d'événement
timestamp	string (ISO 8601)	Horodatage
provider	claude-code | opencode	Plateforme d'exécution
agentType	string	Type d'agent (executor, architect, etc.)
model	string | null	Modèle utilisé
promptDescription	string | null	Description du prompt (max 500 chars)
tokenUsage	object | null	{ input, output } — tokens consommés
durationMs	number | null	Durée en millisecondes
status	string | null	Statut final
parentId	string | null	ID de l'agent parent
schemaVersion	number	Version du schéma (actuellement 1)

Library TypeScript

Le module src/agent-event.ts exporte les types et constantes partagées entre le hook et les tests :

import type { AgentEvent, AgentEventType, AgentProvider } from "shingan/agent-event"
import { SCHEMA_VERSION, TRACE_FILENAME, TRACE_DIR_NAME, MAX_PROMPT_LENGTH } from "shingan/agent-event"

Configuration

Le hook est déclaré dans .claude/settings.json :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Agent",
        "command": "node .claude/hooks/agent-tracker.js"
      }
    ]
  }
}

Sécurité

• Validation stricte des entrées JSON
• Safe parsing avec try/catch sur toutes les opérations I/O
• Troncature des champs texte (promptDescription à 500 chars, status à 200 chars)
• Pas de données sensibles dans la trace (pas de contenu de prompt complet)