ki-grok/05-subagents-und-parallelitaet.md

Kapitel 5

Subagents und Parallelität

Kern in einem Satz: Subagents sind Kind-Sessions mit eigenem Kontext: Du delegierst Research, Implementierung oder Review parallel – der Parent bleibt schlank und bekommt Zusammenfassungen statt den ganzen Trace.

---

5.1 Das Problem, das Subagents lösen

Alltagsschmerz: Eine Session erforscht Auth, liest 40 Dateien, startet dann den Fix – und am Ende ist der Kontext voller toter Enden. /compact rettet Tokens, verliert aber Nuancen. Neue Session vergisst den Faden.

Subagents als Kontext-Ventil: Der Parent spawnt ein Kind, das selbst liest und sucht. Zurück kommt ein Summary (plus Artefakte/Pfade), nicht der komplette Scrollback des Kindes. Der Parent orchestriert; die Kinder schuften.

{width=90%}

Subagents sind default an. Abschalten:

export GROK_SUBAGENTS=0

# ~/.grok/config.toml
[subagents]
enabled = false

---

5.2 Agents vs. Personas (nicht verwechseln)

	Agents	Personas
Was	Ganze Session: Modell, Tools, Prompt, Skills	Verhaltens-Overlay auf Subagent-Prompt
Scope	Primary oder Subagent	nur Subagents
Wo	.grok/agents/, ~/.grok/agents/, Modal	config.toml [subagents.personas], .grok/personas/*.toml
Beispiele	grok-build, explore, plan, Custom	researcher, concise

Merksatz: Ein Agent definiert wer die Session ist. Eine Persona formt wie ein Subagent innerhalb einer Session auftritt. Ein Kind läuft immer als Agent-Typ (z. B. general-purpose); die Resolution kann eine Persona darüberlegen.

Verwalten: /config-agents (Alias /agents) – Tabs Agents und Personas. Personas-Tab direkt: /personas.

---

5.3 Built-in-Typen

subagent_type	Rolle	Datei-Edits
general-purpose	Default, volle Fähigkeiten	ja (voller Toolset)
explore	Research: lesen, greppen, Shell	nein
plan	Strukturierter Implementierungsplan	nein

Custom-Agents können Typen ergänzen oder Built-ins per Name überschatten.

Wann welcher Typ:

Aufgabe	Typ
„Wo wird Rate-Limit gesetzt? Nur finden.“	explore
„Skizziere einen Ansatz für Feature X.“	plan (oder Parent-Plan-Mode, Kapitel 4)
„Implementiere den freigegebenen Fix + Tests.“	general-purpose
Unklar / gemischt	general-purpose + enger Prompt, oder erst explore

Default: general-purpose nur, wenn Writes wirklich nötig sind – sonst explore/plan und Kontext sparen.

---

5.4 Wie Spawning funktioniert

Der Parent ruft intern spawn_subagent auf. Für dich als Nutzer zählt: Du formulierst Delegation klar – und reviewst das Summary.

Wichtige Parameter (Konzept – der Agent setzt sie; du steuerst über Prompt und Config):

Parameter	Bedeutung
prompt	Vollständiger Auftrag an das Kind
description	Kurzes Label (3–5 Wörter) für UI/Tasks
subagent_type	s. oben
background	true: sofort zurück mit ID; Ergebnis später holen
capability_mode	Grober Tool-Filter (s. 5.5)
isolation	none (Default, shared Workspace) oder worktree (Kapitel 6)
cwd	Anderes Working Directory (nicht mit worktree kombinieren)
resume_from	Abgeschlossenes Kind fortsetzen (gleicher Typ, gleiche Session)

Background-Kinder: Output/Status über get_command_or_subagent_output; abbrechen mit kill_command_or_subagent. Mehrere Tasks: warten mit dem Tool wait_commands_or_subagents und Parameter mode = wait_any oder wait_all (max. 20 Tasks). In der TUI: Tasks-Pane Ctrl+G – laufende/fertige Subagents und Background-Commands.

Nesting-Tiefe 1: Nur die Top-Level-Session spawnt Subagents. Ein Kind kann keine eigenen Subagents spawnen (spawn_subagent → Depth-Limit-Fehler). Der Agent-Baum bleibt flach – Orchestrierung bleibt beim Parent.

---

5.5 Capability Modes

Optionaler Filter zusätzlich zum Agent-Typ:

Mode	Read	Write	Shell/Execute
read-only	ja	nein	nein (auch kein Shell; Web/LSP-Lesen je nach Toolset)
read-write	ja	ja	nein
execute	ja	nein	ja
all	ja	ja	ja

Ohne capability_mode gilt das Toolset des Typs: explore/plan lesen+suchen+Shell, aber keine File-Edits; general-purpose = voll.

Praxis: Für „nur recherchieren, Parent plant danach“ → explore oder read-only. Für „Tests laufen lassen, Code nicht anfassen“ → execute. Für parallele Feature-Arbeit → general-purpose + idealerweise isolation: worktree (Kapitel 6).

---

5.6 Personas in der Praxis

Persona = named instructions als <system-reminder>-Schicht: Ton, Output-Format, Fokus – ohne Agent-Typ/Tools zwingend zu ändern (Model/Effort können über Persona greifen).

# ~/.grok/config.toml oder Projekt-Config
[subagents.personas.researcher]
instructions = "Du bist gründlich. Nenne immer konkrete Dateipfade und Zitate (Funktion/Zeile)."
description = "Deep investigator."

Oder Datei .grok/personas/researcher.toml (Dateiname = Name). Priorität: Inline-Config > Projekt-Dateien > User-Dateien > Bundled (read-only).

Nützliche Felder:

Feld	Nutzen
instructions / instructions_file	Verhalten
description	Katalog
inputs / outputs	IO-Contracts für Ketten (Datei rein/raus)
model, reasoning_effort	Overrides
default_isolation	none oder worktree

Resolution (Modell/Effort), grob höchste Priorität zuerst: Spawn-Override → Role-Default → Persona → Parent.
Isolation: ähnliche Kette, Default aber none (erbt nicht automatisch Worktree vom Parent).

Personas greifen über Resolution/Roles – der Parent übergibt typischerweise keinen Persona-Namen als freien spawn_subagent-Parameter. Model/Effort wechseln nur, wenn Persona oder Role sie setzen; sonst erbt das Kind den Parent. Du gestaltest Personas und Roles so, dass die Resolution den richtigen Overlay wählt; Details im Agents-Modal und in der Config (Kapitel 14).

---

5.7 resume_from und MCP-Vererbung

Multi-Stage:

1. Explore-Kind: Ursachen finden.
2. Neues Kind mit resume_from=<id>: implementiert auf Basis des vollen Kind-Transcripts (nicht nur Summary an Parent).

Voraussetzungen: Quelle completed, gleiche Session, gleicher subagent_type.

MCP: Kinder erben default die bereits verbundenen MCP-Server des Parents (search_tool / use_tool wie der Parent). Steuerung per Agent-Frontmatter mcpInheritance: all | none | named: […] | except: […]. Plugin-Agents: keine eigenen mcpServers/Hooks im Frontmatter; kein permissionMode: bypassPermissions im Plugin-Agent.

---

5.8 Parallelität ohne Chaos – Spielregeln

Regel	Warum
Klare Nicht-Überlappung der Dateien	Sonst Merge-Konflikt im Kopf und auf Disk
Research parallel, Writes serial oder in Worktrees	Shared Workspace + zwei Writer = Reibung
Jedes Kind bekommt Definition of Done	Sonst Summary ohne Beleg
Parent orchestriert Verify	„Beide sagen grün“ ≠ Integration grün
Tasks-Pane beobachten (Ctrl+G)	Du siehst hängende Kinder

Gute Parallel-Splits:

• Explore A: Call-Sites von legacyPay()
• Explore B: bestehende Retry-Utils
• Danach ein general-purpose: Fix

Schlechte Parallel-Splits:

• Zwei general-purpose schreiben beide an auth/middleware.ts im selben Tree

---

5.9 Config-Hebel (kurz)

Toggle, Models und Roles greifen in der Resolution, bevor der Parent spawnt – das spart Prompt-Yoga und erzwingt Team-Defaults (z. B. Research nur read-only).

[subagents.toggle]
explore = true
plan = false                 # plan-Subagent aus, wenn ihr nur Parent-Plan-Mode wollt

[subagents.models]
explore = "grok-build"       # Modell-Override pro Typ

[subagents.roles.researcher]
description = "Deep research agent"
default_capability_mode = "read-only"
model = "grok-build"
# prompt_file = ".grok/prompts/researcher.md"

Roles/Personas auch als Dateien unter .grok/roles/*.toml und .grok/personas/*.toml.

---

5.10 Praxis-Sessions

Session 1 – Explore als Ventil

Untersuche, wo Refresh-Tokens validiert werden.
Spawne dafür einen explore-Subagenten (read-only, keine Edits).
Liefere mir: Dateipfade, Sequenz, und 2 Risiken.
Parent: noch nichts implementieren.

Erfolg: Parent-Kontext bleibt klein; du hast Pfade und Risiken; kein Diff.

Session 2 – Plan-Subagent vs. Plan Mode

Spawne einen plan-Subagenten:
Implementierungsplan für CSV-Export der Invoices.
Constraints: bestehender Streaming-Helper, kein neues Framework.
Parent bleibt in Normal Mode und wartet auf den Plan-Text.

Vergleich zu Kapitel 4: Parent-Plan Mode hat Edit-Gate + Approval-UI. Der plan-Subagent liefert einen Plan ins Kind/Summary – ohne dass der Parent zwingend in Plan Mode ist. Für teamfähiges Approve-UI: Parent-Plan-Mode. Für schnelle Skizze parallel zu anderer Arbeit: plan-Subagent.

Session 3 – Implement + Test parallel (mit Vorsicht)

Zwei Tracks:
1) general-purpose: minimaler Fix für Bug B-123 in payments/retry.ts + Unit-Test.
2) explore (parallel): alle Call-Sites von retryPayment dokumentieren.
Keine weiteren Module anfassen. Am Ende Parent: Summary mergen und pytest tests/payments.

Wenn beide schreiben müssten: Track 1 im Worktree (Kapitel 6).

Session 4 – Background und Tasks-Pane

Starte die volle Testsuite im Hintergrund und
parallel einen explore-Subagenten zu flaky test_timeout.
Zeig Status in der Tasks-Pane; warte auf beide Results.

In der TUI: Ctrl+G, bei hängenden Jobs killen statt ewig warten. Foreground-Shell → Background: Ctrl+B.

Session 5 – resume_from (Zwei-Stufen)

1) explore: root cause für Memory-Leak im Worker.
2) Danach general-purpose mit resume_from auf dieses Kind:
   minimaler Fix + Regressionstest. Kein Refactor außerhalb.

---

5.11 Prompt-Muster für Delegation

Schwach:

Mach das mit Subagents irgendwie parallel.

Stark:

Delegiere so:
- explore „find cache writers“: alle Writes auf Redis-Keys mit Prefix order:
  Liste path:line, kurze Notiz. Keine Edits.
- explore „find readers“: analog für Reads.
- Parent: nach beiden Summaries einen gemeinsamen Fix-Vorschlag in 5 Bullets.
  Noch nicht implementieren.

Warum stark: typisiert, scoped, Output-Contract, Parent-Rolle klar.

---

5.12 Jetzt selbst machen: Subagent-Parcours (30 Minuten)

Jetzt selbst machen

1. Subagents enabled lassen (GROK_SUBAGENTS nicht 0).
2. Session 1 (explore only) – Tasks-Pane einmal öffnen.
3. Session 2 (plan-Subagent) – Plan-Text reviewen, nicht blind bauen.
4. Session 3 – paralleles Explore + ein Writer; Dateiüberlappung vermeiden.
5. Optional: /agents öffnen und Built-ins ansehen.
6. Notiere: Wann würdest du Parent-Plan-Mode statt plan-Subagent wählen?

---

5.13 Häufige Fehler

Symptom	Ursache	Fix
Parent-Kontext trotzdem voll	Zu viel im Parent selbst gelesen	Explizit „nur Subagent exploriert“
Kind schreibt im Plan-Parent	general-purpose ohne Gate (Parent-Plan ≠ Kind-Gate, Kap. 4)	explore/plan oder read-only
Zwei Writer, Chaos-Diff	Shared isolation	Worktrees / serialisieren
Resume schlägt fehl	Anderer Typ / noch running	completed + same type
Persona „wirkt nicht“	Resolution/Name	Modal, Config-Priorität, instructions prüfen
MCP im Kind fehlt	nicht connected / mcpInheritance	Parent-Server zuerst; Inheritance

---

5.14 Checkliste Subagents

• Auftrag hat klaren Typ (explore / plan / general-purpose)
• DoD und Out-of-scope im Kind-Prompt
• Nesting-Tiefe 1: Orchestrierung nur im Parent
• Keine unnötige Dateiüberlappung bei Parallel-Writes
• Parent macht Integration-Verify
• Tasks-Pane im Blick bei Background
• Plan Mode Parent ≠ automatische Kind-Sperre verstanden

---

Was du jetzt kannst

• Subagents als Kontext-Ventil erklären und Agents von Personas trennen
• Built-in-Typen und Capability Modes gezielt wählen
• 2–4 parallele bzw. gestufte Sessions orchestrieren und im Tasks-Pane verfolgen
• Typische Parallelitäts-Fallen (Writes, Plan-Parent, Resume) vermeiden

Nächste Schritte

→ Kapitel 06 – Worktrees und isolierte Arbeit: git-isolierte Copies, damit parallele Agenten sich nicht gegenseitig die Working Tree zerschießen.