Die Claude-Agent-SDK-Integration

Der Agent-Host-Prozess #

Claude läuft über den Agent-Host, ein kleines TypeScript-Programm in desktop/agent-host, das @anthropic-ai/claude-agent-sdk verwendet. Der Desktop startet ihn mit Node und übergibt den Pfad der mitgelieferten Claude-Programmdatei als einziges Argument. Ein Entwicklungs-Build führt node aus dem PATH mit agent-host/dist/src/entry.js aus. Eine paketierte App führt ihr mitgeliefertes node mit claude/host/entry.mjs aus ihren Ressourcen aus. Der macOS-Build und die Windows-Builds liefern diese Laufzeit mit.

Beide Seiten tauschen über stdin und stdout ein JSON-Objekt pro Zeile aus. Eine Anfrage trägt eine id mit 1 bis 200 Zeichen, und ihre Antwort trägt dieselbe id mit einem Ergebnis oder einem Fehler. Eine Zeile ohne id ist ein Event. Der Host prüft jede Anfrage gegen ein striktes Schema, daher schlägt ein unbekanntes Feld fehl. Der Desktop gibt jeder Anfrage 35 Sekunden. Eine Anfrage, die bis dahin keine Antwort hat, schlägt mit „Claude host request timed out“ fehl.

Jeder Run bekommt einen neuen Host, und der Host überlebt seinen Run nie. Wenn der Run endet, sendet der Desktop close und wartet höchstens 3 Sekunden auf die Antwort. Dann schließt er stdin und gibt dem Host 10 Sekunden zum Beenden, danach beendet er den Host und jeden Prozess, den der Host gestartet hat: unter macOS die Prozessgruppe, unter Windows den Prozessbaum mit taskkill. Lesevorgänge, die keine offene Unterhaltung brauchen, etwa der Modellkatalog oder ein Titel, laufen in einem eigenen Einmal-Host. Vor dem Start entfernt der Desktop neun Umgebungsmarker, die eine übergeordnete Claude-Code-Session ihren Kindern gibt, darunter CLAUDECODE, CLAUDE_CODE_CHILD_SESSION, CLAUDE_CODE_SESSION_ID und CLAUDE_PID. Ein Desktop, den Sie aus Claude Code heraus starten, würde seine Sessions sonst als Kind-Sessions ausführen, und Claude speichert deren Transkripte nicht.

Eine Anfrage, die am Schema scheitert, bekommt eine Fehlerantwort mit ihrer id. Eine Zeile, die der Host nicht als JSON lesen kann, bekommt eine Antwort mit der id null, und der Desktop ignoriert sie. Der Desktop puffert höchstens 256 Events eines Hosts. Wenn stdout des Hosts schließt oder eine Zeile kein JSON ist, lässt der Desktop jede wartende Anfrage fehlschlagen und erzeugt selbst ein failed-Event. Die Standardfehlerausgabe des Hosts geht in das Debug-Log des Desktops.

• Einstellungen und Prompt: Die Abfrage lädt die Einstellungen user, project und local und nutzt den System-Prompt claude_code. Der Host hängt die instructions von open daran an. Für jeden Run schreibt agents/session_rules.rs diesen Text in dieser Reihenfolge: die Fragenregel, die Regel für Session-Nachrichten, die Regel für Anweisungen und den Text des Antwortstils. Die Fragenregel sagt, dass Claude den Nutzer mit AskUserQuestion fragt und dass der Aufruf nicht wartet: Der Nutzer antwortet in einer späteren Nachricht. Die Regel für Session-Nachrichten sagt, dass Claude eine andere HB-Code-Session nur mit den hbcode-Tools send_session_message und maintain_sessions erreicht, weil SendMessage und ListAgents nur Claude-Code-Sessions außerhalb von HB Code erreichen. Die Regel für Anweisungen sagt Claude, eine ausdrückliche Anweisung ganz auszuführen, eine Frage zu stellen oder mit Belegen zu widersprechen. Simplified Technical English fügt seinen Antworttext zuletzt hinzu, Default fügt keinen Text hinzu. Der App-Tool-Text steht nicht in diesem Text: Er ist die instructions des MCP-Servers hbcode.
• Stream: includePartialMessages liefert die Live-Deltas, und forwardSubagentText sendet jeden Subagent-Turn vollständig. persistSession speichert das Transkript.
• Tools: Die Query bekommt den MCP-Server hbcode und dessen allowedTools. Ein PreToolUse-Hook beantwortet jeden AskUserQuestion-Aufruf sofort. allowDangerouslySkipPermissions ist nur für bypassPermissions gesetzt.
• Run-Ende: Der Host schaltet Claudes Session-Zustands-Events mit einer Umgebungsvariable ein, weil ein Turn, der Subagents im Hintergrund startet, vor ihnen endet. Nur der Zustand idle sagt dem Host, dass der ganze Run vorbei ist.
• Eingabe: Die Query liest ihre Nachrichten aus einem Stream, der für den ganzen Run offen bleibt. Der Host schreibt jedes send sofort hinein, auch während ein Turn läuft.

Die title-Anfrage ist eine eigene Query. Sie verwendet das Modell haiku ohne Tools, mit einem Turn, ohne Einstellungen und ohne gespeicherte Session, und ihr System-Prompt verbietet Claude, auf die Nachricht hin zu handeln. Der Desktop fragt nach send einen Titel an, in einem Einmal-Host mit dem aktiven Konto.

HB-Code-Tools über den Host #

Codex und Claude bekommen dieselben HB-Code-Tools aus einem Katalog in services/agent_tools. Für Claude baut der Desktop die Liste für jeden Run und sendet sie in open.appCapabilities: einen instructions-Text und für jedes Tool Name, Beschreibung, Eingabeschema und Freigabeklasse. Der Host macht aus der Liste einen SDK-MCP-Server im selben Prozess mit dem Namen hbcode, sodass Claude jedes Tool als mcp__hbcode__<name> sieht. Ein doppelter Name oder ein Eingabeschema, das kein Objekt ist, lässt open fehlschlagen.

Die Liste hängt von den Einstellungen ab. send_mobile_notification ist nur dabei, solange Benachrichtigungen eingeschaltet sind, und synthesize_speech, create_explainer_video und extract_video_context nur mit einem Gemini-Schlüssel.

Wenn Claude ein Tool aufruft, prüft der SDK-Handler die Argumente gegen das vollständige Schema, erzeugt eine neue requestId und sendet toolCall. Dann wartet der Handler. Das Event kann sein Ziel nicht wählen. Der Desktop weist ein toolCall mit einem anderen Feld als requestId, toolUseId, tool und arguments zurück und leitet den Aufruf über die Session und den Run weiter, denen dieser Host gehört. Ein zurückgewiesenes Event oder ein zweiter Aufruf mit derselben requestId lässt den Run fehlschlagen.

Jeder Aufruf läuft in einem eigenen Task neben der Run-Schleife. Ein langsames Tool kann daher weder Stop noch Freigaben, Timeline-Zeilen oder das Ergebnis eines anderen Tools blockieren. Der Task führt den gemeinsamen Tool-Handler mit Claudes Tool-Use-id als Aufruf-id aus und sendet toolResult dann selbst. Ein Tool, das fehlschlägt, liefert ein Ergebnis mit success false, und Claude sieht einen Tool-Fehler. Wenn die toolResult-Anfrage fehlschlägt, schlägt der Run fehl.

Wenn das SDK einen Aufruf abbricht oder der Run stoppt, antwortet der Host dem Handler mit „Run stopped.“ und sendet toolCancel, und der Desktop bricht diesen Task ab. Ein Ergebnis, das den Abbruch kreuzt, wird ignoriert. Am Ende des Runs stoppt der Desktop jeden verbliebenen Task. In der Timeline erzeugt der Desktop den Titel einer HB-Code-Tool-Zeile aus ihrer Anfrage, zum Beispiel „Create session“ oder „Revise explainer video“.

Verlauf und die gemeinsamen Timeline-Zeilen #

Der Desktop liest Claudes Transkriptdateien nie selbst. Der Host liest sie mit getSessionMessages und gibt Seiten mit höchstens 100 vollständigen Nachrichten zurück. Er fügt benachbarte Assistant-Umschläge mit derselben API-Nachrichten-id zusammen und verwirft Nachrichten, die nichts zu zeigen haben. Eine Seitengrenze ist eine Nachrichten-uuid, und wenn diese Nachricht fehlt, bittet die Antwort den Desktop, neu zu laden. Eine Unterhaltung ohne Transkript lädt als leer. Das SDK liefert eine komprimierte Unterhaltung erst ab ihrer letzten Komprimierung, deshalb erscheinen ältere Turns einer solchen Unterhaltung nicht in HB Code. Die vollständige Ausgabe eines Befehls wird bei Bedarf über toolOutput gelesen, auch für einen Subagent, so wie eine Codex-Protokollausgabe.

Der Cursor für ältere Seiten ist ein JSON-Objekt mit session, before, anchor und revision und höchstens 4096 Zeichen lang. Der Desktop prüft ihn gegen die Unterhaltung oder den Subagent, durch den er blättert. Ein Cursor für ein anderes Ziel schlägt mit einem Konflikt fehl, der Sie bittet, die Unterhaltung neu zu laden.

Lesevorgänge sind nicht billig. Jeder Transkript-Lesevorgang startet einen Einmal-Host, und getSessionMessages liest das ganze Transkript, weil der SDK-Aufruf keinen Bereich kennt. Ein Timeline-Ladevorgang lässt zwei Hosts nebeneinander laufen: einen für die Seite und einen für die Subagent-Liste. Ein Zustellnachweis ist ein einziger messageSaved-Lesevorgang. Während eines Runs beantwortet ihn der Host des Runs. Nach dem Run beantwortet ihn ein Einmal-Host.

Der Claude-Adapter projiziert jede Nachricht in dieselben Timeline-Zeilen, die Codex verwendet. Eine Zeile nimmt ihre Identität nur aus stabilen Daten, daher ersetzt die gespeicherte Zeile die Live-Zeile an derselben Stelle.

Das SDK sendet für jeden Inhaltsblock einen abschließenden Umschlag. Ein solcher Umschlag ersetzt sein eigenes Textfragment, daher wird ein Delta nie doppelt angefügt. Gespeicherte Zeilen sortieren nach ihrer Position im Transkript, Live-Zeilen nach ihrer Ankunft. Eine Live-Ansicht sendet auch die Zeilen, die sie vorher gezeigt hat und nicht mehr zeigt, sodass jeder Client sie entfernt. Eine Live-Prompt-Zeile gibt es nur für eine Nachricht, die HB Code gesendet hat. Ihre Zeile zeigt den Anzeigetext und die Anhänge aus claude_operations. Der Text, den Claude bekommt, ist länger, weil der Desktop den Skills-Kontext und die Pfade der Anhänge hinzufügt. Jeder andere Prompt erscheint aus dem gespeicherten Transkript.

Eine gespeicherte Unterhaltung finden und fortsetzen #

Um eine bestehende Claude-Code-Unterhaltung fortzusetzen, listet der Desktop die gespeicherten Unterhaltungen genau dieses Workspace-Ordners auf, die neueste zuerst. Der Host ruft listSessions mit includeWorktrees false und includeProgrammatic false auf. Eine Unterhaltung aus einem anderen Checkout oder Worktree kann in diesem Ordner nicht fortgesetzt werden, daher wird sie nicht aufgelistet. Eine Seite enthält standardmäßig 25 Unterhaltungen und höchstens 100, und ihr Cursor ist ein Offset in Claudes eigener sortierter Liste. Jede Zeile trägt linkedAppSessionId, wenn eine HB-Code-Session die Unterhaltung bereits besitzt. Ein Titel erscheint nur, wenn er mehr sagt als der erste Prompt.

Eine Vorschau liest eine Seite des Transkripts. Sie bindet nichts, schreibt nichts und hat keine älteren Seiten.

Wenn Sie fortsetzen, muss inspect das Transkript in genau diesem Ordner finden. Die neue Session übernimmt Claudes eigenen Namen für die Unterhaltung, den benutzerdefinierten Titel oder sonst die Zusammenfassung. Die Tabelle claude_sessions bindet dann die beiden ids. Sie hat eine Zeile pro Session, und native_session_id ist eindeutig. Eine Unterhaltung gehört daher zu höchstens einer HB-Code-Session, und wer sie erneut wählt, öffnet diese Session statt einer zweiten. Wenn diese Session zu einem anderen Ordner gehört, schlägt die Anfrage mit einem Konflikt fehl, der die Session nennt. Eine Kopie einer Session bekommt eine neue Unterhaltungs-id. Transkript-Lesevorgänge brauchen keine Anmeldung und laufen immer mit dem Ordner des Standardkontos.

Modelle und Effort #

Die Modellliste kommt aus einem Einmal-Host für catalog, ein Lesevorgang pro Konto und Workspace-Ordner. Der Desktop behält eine Liste 10 Minuten lang und verwirft alle Listen bei einer Anmeldung, einer Abmeldung, einem Kontowechsel und beim Entfernen eines Kontos. Claude listet Aliasse wie default und opus neben festen Modell-ids auf. Der Desktop behält eine Zeile pro aufgelöster Modell-id, und der Alias default markiert nur das Modell, das das Konto empfiehlt.

Der Standard-Effort eines Modells ist high, wenn das Modell ihn anbietet, und sonst seine erste Stufe. Ein Modell ohne Effort-Stufen bekommt den Effort default, und open trägt dann kein effort-Feld. Eine neue Unterhaltung startet mit dem empfohlenen Modell. Eine fortgesetzte Unterhaltung startet mit dem Modell, das zuletzt geantwortet hat, wenn der Katalog es noch enthält.

Live-Runs, Zustellnachweis und Freigaben #

agents/dispatch sendet eine Nachricht aus der Warteschlange an den Adapter des Agenten der Session. Eine Claude-Session kann den letzten Turn nicht ersetzen und keinen Geschwindigkeitsmodus nutzen. Einen laufenden Turn kann sie steuern. Eine Session hat jeweils einen aktiven Claude-Run. Die Registry RUNS hält einen Run pro App-Session, und ein zweiter Run schlägt mit „The Claude session already has an active run.“ fehl.

Der Run öffnet den Host mit Modell, Effort und Berechtigungsmodus der Session, speichert die Operation und sendet dann den Text. Der Eintrag ist eine Zeile in claude_operations mit einer neuen UUID für die Nachricht. Das Insert behält eine vorhandene Zeile, daher behält ein erneuter Versuch derselben Operation die erste UUID. Ein erneuter Versuch mit anderem Text oder anderen Anhängen schlägt als Konflikt fehl. Ein erneuter Versuch aus einem anderen Run liest zuerst das Transkript. Hat das Transkript die Nachricht, sendet der Run nichts, und die Operation gilt als gesendet. Hat es sie nicht, wechselt die Operation zum neuen Run und geht mit derselben UUID hinaus. Der Host des früheren Runs ist beendet, daher kann Claude die Nachricht nicht mehr von ihm bekommen.

Eine Nachricht, die Sie senden, während der Run aktiv ist, ist eine Steuerung. Die Run-Schleife besitzt jeden Schreibvorgang zum Host, daher geht die Steuerung an die Schleife. Die Schleife speichert die Operation mit einer eigenen UUID und sendet sie. Claude liest die Nachricht nach seinem aktuellen Schritt, zwischen zwei Tool-Runden. Endet der Turn zuerst, startet die Nachricht den nächsten Turn desselben Runs. Der Outbox-Eintrag bleibt sending, mit einer Annahme, die den Run nennt, die Claude-Session-ID als Thread und die Claude-ID der Nachricht, die den Run gestartet hat, als Turn. Eine Steuerung, die keinen aktiven Run findet oder einen anderen Run als den genannten, wird aufgeschoben, und die Nachricht bleibt in der Warteschlange.

Stop and send now holt eine hinzugekommene Nachricht zurück. Die Schleife sendet cancel an den Host. Hat Claude die Nachricht noch nicht begonnen, stoppt der Desktop den Run und sendet dieselbe Operation als neuen Run. Hat Claude die Nachricht schon, wird nichts erneut gesendet.

Claudes Live-Stream wiederholt den Prompt nie, und ein Schreibvorgang auf stdin oder ein Delta ist nie ein Zustellnachweis. Claude speichert die Nachricht, die einen Run startet, bevor es das Modell aufruft. Deshalb startet der erste message-Frame nach send einen Transkript-Lesevorgang. Nach einem Lesevorgang ohne Fund startet jeder Frame, der die Nachricht nennt, einen weiteren. Ein Frame nennt eine Nachricht in user_message_uuid oder user_message_uuids, oder als command_lifecycle-Frame mit dem Zustand started oder completed. Der Thinking-Zähler und der idle-Frame starten keinen. Eine hinzugekommene Nachricht speichert Claude später, mit seiner nächsten Antwort. Deshalb startet der Frame, der sagt, dass Claude die Nachricht begonnen hat, einen Lesevorgang, und jede der nächsten 3 Antworten der Unterhaltung startet einen weiteren. Findet ein Lesevorgang eine Nachricht, erscheint zuerst die gespeicherte Zeile, und danach verschwindet die Outbox-Zeile. Am Ende des Runs ist ein weiterer Lesevorgang für jede Nachricht ohne Nachweis der endgültige Nachweis, auch für einen gestoppten oder fehlgeschlagenen Run. Eine Nachricht, die den Run gestartet hat und die kein Lesevorgang findet, wird nie automatisch erneut gesendet. Eine hinzugekommene Nachricht, die kein Lesevorgang findet, kehrt in die Warteschlange zurück.

Wenn Claude ein Tool verwenden will, hält der Host das canUseTool-Promise des SDK und sendet ein permission-Event. Der Desktop zeigt dieselbe Freigabekarte wie für Codex, mit Accept und Decline und keiner anderen Entscheidung. Ein Bash-Aufruf ist eine Befehlsfreigabe, und jedes andere Tool ist eine Berechtigungsfreigabe. Ein Telefon antwortet über run.chatResolveApproval, und der Dispatch lässt den Claude-Adapter zuerst antworten, wenn er diese Anfrage-id hält.

• Begründungstext: Für ExitPlanMode zeigt die Karte „Claude wants to carry out this plan:“ und den Plan. Für Bash zeigt sie Claudes eigene Beschreibung des Befehls. Für ein anderes Tool zeigt sie die Beschreibung, sonst den Tool-Namen mit seinem Dateipfad oder seiner URL, sonst den Tool-Namen mit seiner Eingabe als JSON.
• Subagents: Die Anfrage eines Subagents beginnt mit „Requested by“ und dem Namen, den die Agentenliste zeigt.
• Antwort: Der Adapter prüft den Thread, den Turn, das Item und die Entscheidung. Wenn kein Run die Anfrage mehr hält, schlägt die Antwort mit „The Claude run has ended.“ fehl.
• Ablehnung: Claude bekommt „The user declined this action.“, und die Tool-Zeile wird zu Tool declined.
• Stop: Der Host lehnt jede offene Anfrage ab und stoppt jeden offenen HB-Code-Tool-Aufruf mit „Run stopped.“ Das Ende des Runs markiert die übrigen Karten als abgebrochen.
• Fragen: Eine Frage hält den Run nie an. Ein PreToolUse-Hook im Host beantwortet AskUserQuestion sofort, in jedem Berechtigungsmodus, und Claude bekommt den Hinweis, dass die Frage angezeigt wird und die Antwort als spätere Nachricht kommt. Die Timeline zeigt den Aufruf als Zeile „Question for you“, ihre Optionen legen eine Antwort in den Composer, und Telefone bekommen eine Benachrichtigung. Es öffnet sich keine Karte.
• Duplikate: Der Host lehnt eine zweite Anfrage mit einer Anfrage-id ab, die noch offen ist.

Die Run-Schleife, Fehler und Stop #

Nach send gehört der Run einer einzigen Schleife. Sie wartet gleichzeitig auf sieben Eingänge und behandelt den, der zuerst bereit ist.

Zwei message-Frames werden besonders behandelt. Der result-Frame hält den Erfolg oder den Fehler des Turns fest, und die Schleife läuft weiter. Der Zustand idle beendet die Schleife, mit einer Ausnahme. Claude kann melden, dass es ruht, kurz bevor es eine Nachricht liest, die in diesem Moment angekommen ist, und startet dann einen Turn für diese Nachricht. Wartet also noch eine hinzugekommene Nachricht auf Claude und hat der Run keinen Fehler, läuft die Schleife weiter und wartet 10 Sekunden auf den nächsten Frame.

Die Reihenfolge beim Beenden ist fest, egal was die Schleife beendet hat.

1. Der Desktop schließt den Event-Kanal und stoppt jeden Tool-Task, der noch übrig ist.
2. Er fährt den Host herunter: close, 3 Sekunden, stdin geschlossen, 10 Sekunden, Kill.
3. Er markiert jede offene Freigabekarte als abgebrochen.
4. Er schließt jede noch offene Subagent-Ansicht ab: als abgebrochen nach einem Stop oder einem Fehler, sonst als abgeschlossen.
5. Er führt die Endprüfungen aus: zuerst für jede hinzugekommene Nachricht ohne Nachweis, dann für die Nachricht, die den Run gestartet hat.
6. Er sendet das Endereignis des Runs: abgebrochen, fehlgeschlagen mit dem Grund oder abgeschlossen.
7. Er gibt jede hinzugekommene Nachricht, die das Transkript nicht hat, in die Warteschlange zurück.

Dann verwirft der Desktop die Nutzungsmessung des Kontos, beendet den Run in der Run-Registry und entfernt ihn aus RUNS. Die Grenze bei send entscheidet, was ein Fehler bedeutet. ProvenUnadmitted sagt, dass Claude die Nachricht nicht bekommen hat. AdmissionUncertain sagt, dass Claude sie haben kann, daher muss vor einem erneuten Versuch der gespeicherte Verlauf entscheiden.

Der Grund eines fehlgeschlagenen Ergebnisses stammt aus Claudes errors-Liste oder, bei API-Fehlern wie einer fehlenden Anmeldung, aus seinem result-Text. Ein fehlgeschlagener Run behält seinen Grund im Fehlerprotokoll des Desktops unter claude_run, mit den ids von Session, Run und Operation. Paketierte Apps verwerfen die Standardfehlerausgabe, daher ginge die Logzeile allein verloren.

Ein Abbruch antwortet nur für die genaue Run-id. Er setzt das Stop-Flag und wartet, bis der Run meldet, dass er fertig ist, was erst nach dem Ende des Hosts geschieht. Wenn der Task des Runs gestorben ist und nichts mehr melden kann, fährt der Abbruch selbst diesen Host herunter, beendet den Run und entfernt ihn aus RUNS.

Die gemeinsame Run-Registry holt einen Run als veraltet zurück, wenn er 45 Sekunden lang keine Aktivität zeigt. Ein Claude-Host kann länger brauchen, um eine Unterhaltung zu öffnen, und der erste Heartbeat kommt erst aus der Schleife. Deshalb fragt die Registry zuerst den Claude-Adapter, und ein Run, dessen genauer Host-Prozess lebt, wird nie zurückgeholt.

Subagents als Kind-Threads #

Claude-Subagents verwenden dieselben Listen-, Timeline- und Live-Pfade wie Codex-Kind-Threads. Während eines Runs meldet Claude jeden Subagent über Task-Events und leitet seine Turns mit der id des startenden Tool-Aufrufs weiter. Nur ein task_started-Event mit dem Task-Typ local_agent erzeugt einen Subagent. Der Adapter schickt die weitergeleiteten Turns in die eigene Ansicht des Subagents. Der Aufruf, der den Subagent gestartet hat, und sein Ergebnis verlassen die Ansicht des Elternteils, daher steht keine Zeile für den Subagent. Ein Subagent, den die Unterhaltung gestartet hat, hat die Tiefe 1, und jede Verschachtelung addiert 1. Ein Live-Subagent trägt keine Eltern-id, daher ist die Tiefe eines verschachtelten Subagents nur aus seinem gespeicherten Transkript bekannt.

Ein Workflow ist ein Skript, das die Unterhaltung mit einem Aufruf des Tools Workflow startet, und das Skript startet Subagents in Phasen. Der laufende Turn verfolgt einen Workflow als einen Task: ein task_started-Event mit dem Task-Typ local_workflow, das die ID des startenden Tool-Aufrufs, den Workflow-Namen und eine Zusammenfassung liefert. Die späteren Task-Events dieses Tasks ändern seinen Status, wie die Tabelle oben zeigt. Claude leitet die Turns der Subagents eines Workflows nicht weiter, und kein Task-Event nennt sie. Sie erscheinen in der Liste nur durch ihre gespeicherten Dateien.

Die gespeicherten Dateien sind die Quelle für jeden Subagent, den der laufende Turn nicht meldet, und nach dem Run sind sie die einzige Quelle. Das SDK liefert die Liste der Subagent-IDs und jedes Transkript. Der Host liest außerdem selbst drei Arten von Claude-Dateien, weil das SDK keine davon bereitstellt.

Claude benennt einen Projektordner nach einer eigenen Regel aus dem Arbeitsverzeichnis. Deshalb sucht der Host in jedem Ordner unter projects in CLAUDE_CONFIG_DIR, oder unter ~/.claude/projects, nach einem Ordner mit der Session-ID, der einen Ordner subagents mit Einträgen hat. Jeder Leser liefert nichts, wenn eine Datei fehlt oder eine andere Form hat, und die Liste zeigt dann weniger Angaben.

Eine subagents-Anfrage liest all das in einem Einmal-Host. Das Lesen eines Transkripts kostet die ganze Datei, daher nennt der Desktop, was er schon hält, und der Host liest nur den Rest. Der Desktop behält diese Angaben pro Unterhaltung, bis er beendet wird.

Der Host bestimmt outcome in dieser Reihenfolge. Der Datensatz des Runs ergibt completed für den Zustand done und failed für den Zustand error. Sonst ist eine letzte Nachricht mit dem Modell <synthetic> ein API-Fehler und bedeutet failed. Sonst bedeutet eine letzte Assistant-Nachricht mit stop_reason end_turn, mit Text und ohne Tool-Aufruf completed. Text, der im selben Turn vor einem Tool-Aufruf steht, beendet den Subagent nicht. Sonst gilt ein Subagent eines Runs mit Datensatz als stopped, weil der Run vor dem Subagent endete. Jeder andere Subagent hat outcome null.

Ein Workflow-Run nimmt Name, Zusammenfassung, Phasen, Status, Start und Dauer aus seinem Datensatz. Ein Run ohne Datensatz ist noch offen. Dann verbindet die Zeile „Run ID:“ im Ergebnis seines Workflow-Aufrufs den Run mit diesem Aufruf, und die Zeile „Summary:“ liefert seine Zusammenfassung. Sein Name und die Titel seiner Phasen kommen aus der meta-Anweisung seines Skripts.

Ein Workflow gibt jedem Subagent seine Aufgabe in einem Rahmen. Ein Rahmen ist eine Zeile, die mit „[Workflow harness — user request]“ oder „[Workflow harness — computed task]“ beginnt, und der Text folgt mit zwei Leerzeichen Einzug in jeder Zeile. Der Host entfernt die Rahmenzeile und den Einzug für das Feld task. subagentHistory liefert die berechnete Aufgabe ohne ihren Rahmen und lässt die gerahmte Benutzeranfrage weg, weil die Unterhaltung diese Anfrage schon zeigt.

Der Desktop gibt dann jedem Subagent einen Status. Die erste Regel, die zutrifft, gilt.

1. Der laufende Turn dieser Session meldet den Subagent als Task: der Status dieses Tasks.
2. Die Dateien liefern ein outcome: completed wird Completed, failed wird Errored, und stopped wird Interrupted.
3. Der Subagent gehört zu einem Workflow, den der laufende Turn als laufend meldet: Running.
4. Die letzte Transkript-Nachricht ist weniger als 10 Minuten alt, und sie ist später als das Ende des letzten Runs dieser Session in diesem Desktop-Lauf: Running. Eine andere Claude-App kann dieselbe Unterhaltung ausführen, daher ist neue Aktivität das einzige Zeichen.
5. Sonst: Interrupted.

Die 10 Minuten kommen von Claudes längster normaler Stille, einem Shell-Befehl, den Claude nach höchstens 10 Minuten stoppt. Ein Workflow-Run nimmt das outcome seines Datensatzes, sonst den Status seines Tasks im laufenden Turn, sonst Regel 4 mit der neuesten Aktivität seiner Subagents. Ein Subagent, den der Turn meldet und der noch kein Transkript hat, kommt aus seinem Task-Event in die Liste. Subagents, die am Ende eines Runs noch offen sind, enden mit ihm, daher zählt Aktivität vor diesem Ende nicht.

Das Listenergebnis nutzt den Agent-Thread-Vertrag, den auch Codex-Kind-Threads nutzen. Claude füllt Felder, die Codex leer lässt.

Keine Timeline-Zeile steht für einen Subagent oder einen Workflow. Der Aufruf, der einen startet, und sein Ergebnis verlassen die Ansicht, und die Agentenliste zeigt die Subagents und die Workflow-Runs. Ein Task-Event, das die Liste ändert, und das Ende eines Runs mit offenen Subagents senden das Signal agent-threads. Jeder Client lädt die Liste dann neu. Auf dem Desktop gruppiert die Agentenliste Workflow-Subagents unter ihrem Workflow und ihrer Phase und zeigt Modell, Effort, Tokens, Tool-Aufrufe und Dauer.

Konten und Nutzung #

Das Standardkonto ist die Claude-Anmeldung dieses Computers und läuft mit Claudes eigenem Ordner. Dieser Ordner ist ~/.claude oder der Ordner im eigenen CLAUDE_CONFIG_DIR des Desktops. Jedes hinzugefügte Konto ist ein Ordner claude/accounts/<uuid> in den lokalen Anwendungsdaten von HB Code. Es behält seine eigene Anmeldung und verlinkt jeden anderen Eintrag auf den Hauptordner. Alle Konten lesen und fortsetzen daher dieselben Sessions mit denselben Einstellungen, und ein Wechsel ändert nur, wer für einen Turn bezahlt.

Die Einstellung agent.chat.claude_account_id nennt das aktive Konto, und kein Wert bedeutet das Standardkonto. Der nächste Turn läuft mit dem aktiven Konto, und ein entferntes Konto lässt das Standardkonto aktiv. Der Desktop legt die Links vor jedem Start eines Claude-Prozesses an. Er erstellt projects zuerst im Hauptordner, damit ein hinzugefügtes Konto nie einen eigenen Transkriptspeicher beginnt. Ein projects-Link, der fehlschlägt, stoppt den Start. Jeder andere Link, der fehlschlägt, wird nur protokolliert. Unter macOS ist jeder Link ein symbolischer Link. Unter Windows bekommt ein Ordner eine Verzeichnisverbindung (Junction), und eine Datei bekommt einen symbolischen Link oder einen Hardlink, wenn Windows den symbolischen Link verweigert. Der Entwicklermodus ist dafür nicht nötig.

HB Code führt Claudes eigene Anmeldebefehle für einen Kontoordner aus. Es liest nie ein Token und führt keinen eigenen Autorisierungsablauf aus.

Die Nutzung kommt aus dem SDK: das rollierende Fünf-Stunden-Fenster und die Wochenfenster. Das Wochenfenster für Drittanbieter-Apps bleibt außen vor. Ein Konto mit API-Schlüssel hat keine Plan-Fenster. Der Host für usage lädt keine Einstellungen und überspringt den Scan der lokalen Transkripte. Die Nutzung wird nur für ein angemeldetes Konto gelesen, und ein Lesevorgang, der fehlschlägt, erscheint als Fehlertext an diesem Konto, während die Liste trotzdem lädt. Bei den Wochenfenstern pro Modell kommen die eigenen Labels des Servers zuerst, und die festen Felder für Opus und Sonnet ergänzen ein Modell, das er nicht aufgelistet hat. Reset-Zeiten werden auf die nächste Minute gerundet, und jede Messung geht in den Nutzungsverlauf. Die Seitenleiste, die Einstellungsseite und die Telefone teilen sich eine Messung pro Konto und Minute, und ein beendeter Run verwirft die Messung dieses Kontos.