Docs · Internals
Où s'arrête Claude Code, où commence n'importe quel agent
Le SDK nexus a commencé comme un client Claude Code. Ce schéma trace la ligne entre ce que tout agent doit fournir et ce qui appartient à Claude Code, et montre le faux CLI qui rend le contrat exécutable.
Ce que ça fait
Tout agent fournit des tours, du texte et du raisonnement, des appels d'outils et leurs résultats, un flux de jetons, un résultat avec coût et usage, des demandes de permission, des interruptions et des sous-agents imbriqués.
Claude Code ajoute sa propre ligne de commande, un protocole stream-json, un canal de contrôle avec une poignée de main initialize, et des hooks.
Le contrat d'agent neutre et les providers sont construits au-dessus de cette surface : un nouvel agent n'a pas à imiter le protocole de Claude.
Le schéma
Fais glisser pour te déplacer. Pince, Ctrl + molette ou les touches + et - pour zoomer ; flèches pour bouger ; 0 ou double-clic pour ajuster. Choisis un nœud pour allumer ses liens.
Description textuelle du schéma
Schéma de flux. Le backend importe la surface publique du SDK : clients, types et trait Transport. Les types portent la partie générique. Le Transport mène à la partie propre à Claude : la ligne de commande, le routage de stdout entre messages de contrôle et messages de conversation, le protocole de contrôle et les hooks, qui parlent au processus claude. Le trait Transport est la couture : presque générique, il laisse fuir des détails du protocole, et il n'est utilisé avec un faux transport qu'en test. Un exécutable fake_claude simule le processus claude et spécifie le contrat. La partie générique et la couture pointent vers le module agent et les providers construits au-dessus.
Lecture guidée
Étape 1. La surface publique
Le backend voit des clients (comme InteractiveClient), des types (Message, ContentBlock, PermissionMode et d'autres) et le trait Transport avec ses implémentations sous-processus et factice.
Étape 2. La partie générique
Tour utilisateur, texte et raisonnement, appel d'outil et résultat, flux de jetons, résultat avec coût et usage, demande et réponse de permission, interruption, sous-agents imbriqués. C'est ce que le contrat neutre généralise.
Étape 3. La ligne de commande de Claude Code
Le SDK construit la commande claude avec des entrées et sorties stream-json, un mode de permission, une configuration MCP en ligne et la reprise. Il trouve le binaire et vérifie sa version, ce qui ne fait qu'avertir.
Étape 4. Router ce que le processus écrit
Les lignes de stdout sont routées : les messages de contrôle vont au canal de contrôle, tout le reste à l'analyseur de messages.
Étape 5. Protocole de contrôle et hooks
Le canal de contrôle porte la poignée de main initialize, can_use_tool, hook_callback, set_permission_mode et set_model. Les hooks sont PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop et PreCompact.
Étape 6. La couture
Le trait Transport est presque générique mais laisse fuir le protocole : messages de contrôle JSON bruts, un émetteur stdin brut, un identifiant de processus enfant. En production il n'est utilisé qu'avec un seul transport ; un second n'existe qu'en test.
Étape 7. Le faux CLI
fake_claude est piloté par des variables d'environnement et des directives (emit, reply_control, wait_eof et d'autres). Les tests du crate l'utilisent pour exécuter le vrai protocole sans le vrai CLI.
Pourquoi c'est conçu ainsi
Une spécification exécutable
Le faux CLI est la partie du contrat qui s'exécute. Un nouveau provider en livre un d'abord, avant le code de transport.
Nommer les fuites
Le diagramme note où la couture générique dépend encore de détails de Claude : les refermer est une tâche visible plutôt qu'une surprise.
Une évolution additive
Rien de public n'est retiré tant que le backend en dépend. Le module neutre grandit à côté de l'ancien client, et les anciens types sont enveloppés plutôt que remplacés.
Ce qui n'est pas établi
- Dettes connues lors de la dernière vérification du diagramme (2026-10-05) : deux formes filaires de la requête d'interruption coexistent, et la ligne de commande claude est construite à cinq endroits à travers le SDK et le crate d'API.
Sources publiques
Où vérifier chaque affirmation, dans les dépôts publics.