codex-subagent

星标12

分支0

更新时间2026年7月22日 08:39

Dieser Skill sollte verwendet werden, wenn Nutzer „GPT-Subagent“, „starte GPT-Agents“, „lass GPT reviewen“, „zweite Meinung“, „frag Codex“ oder „delegiere an GPT/Codex“ sagen. Standard ist der native Agent-Typ `gpt`. Der CLI-Spezialpfad gilt nur bei explizitem `--cli`/`whisperm8 agent` oder Codex-only-Anforderungen wie detachten, App-sichtbaren Jobs, Browser-QA mit Playwright-State, `image_gen`, Jobverwaltung oder ausdrücklich gewünschten CLI-Steps in Dynamic Workflows.

安装

用 Codex 或 Claude 帮你安装复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。

来源

RankM8

RankM8/WhisperM8

打开 GitHub 仓库查看创作者相关仓库

下载

GPT-Subagents: nativ (Standard) oder Codex-CLI (explizit)

Es gibt ZWEI Wege zu GPT-Subagents. Standard ist der native Weg über den Claude-Code-Agent-Typ gpt — schnell, in-session, volles Tool-Set. Das whisperm8-CLI ist die Spezial-Variante für alles, was nur Codex kann.

Wegweiser — welcher Weg wann

Anlass	Weg
Standard: "GPT-Subagent", zweite Meinung, Review, parallele Teilaufgabe	NATIV (`subagent_type: "gpt"`)
Bilder generieren (codex-natives `image_gen`)	CLI — immer; nativ gibt es kein image_gen
User sagt explizit "CLI", "whisperm8 agent", "Job" — oder `--cli` als Skill-Argument	CLI
Detachte Langläufer: Sidebar-Sichtbarkeit in der App, überleben App-Neustart	CLI
Browser-QA (Playwright-storageState), 1Password-Flows	CLI
Steps in Claude Dynamic Workflows	NATIV: `agent(prompt, {agentType: "gpt", schema})` — inkl. Structured Output E2E-validiert (2026-07-18). Der ausgelieferte Workflow `codex-verify` ist native-only und fällt nie auf CLI/`codex-runner` zurück.

Skill-Argumente: /codex-subagent <aufgabe> → nativ. /codex-subagent --cli <aufgabe> → CLI erzwingen. Bild-Aufträge gehen unabhängig vom Argument immer über die CLI.

Nativer Weg (Standard): Agent-Typ `gpt`

Das WhisperM8-GPT-Backend verwaltet eine Agent-Definition (<config-dir>/agents/gpt.md, Frontmatter model: gpt-5.6-sol — bei aktivem Fast-Modus, dem Default, model: gpt-5.6-sol-fast = Priority-Tier, 2,5× ChatGPT-Credits) für das Main-Profil UND jedes Account-Profil; alle Requests laufen über den lokalen Mix-Router. Nutzung: normales Agent-Tool mit subagent_type: "gpt" — ein Spawn pro Teilaufgabe, parallele Fan-outs ausdrücklich erwünscht. Effort ist per Env immer aktiv (high thinking gemäß Session-Einstellung).

Wenn der Spawn fehlschlägt („Agent type 'gpt' not found"):

Die Registry lädt beim Session-Start — Sessions, die älter sind als die Agent-Definition, kennen den Typ nicht (nur PROJEKT-Level-Definitionen unter .claude/agents/ laden mid-session nach). Abhilfe: neue Session starten und den User informieren; nicht automatisch auf CLI wechseln.
GPT-Backend deaktiviert? env | grep ANTHROPIC_BASE_URL muss auf http://127.0.0.1:<router-port> zeigen; sonst Settings → „GPT-Backend" prüfen. Der native-only Workflow codex-verify bricht in diesem Fall klar ab; nur ein ausdrücklich angeforderter CLI-Auftrag darf auf den CLI-Weg wechseln.

Gotchas (QA-verifiziert 2026-07-18):

Selbstauskunft ist wertlos: GPT-Subagents halten sich laut System-Prompt für Claude/Opus. Modell-Beweis liefern nur die "model"-Felder im Session-JSONL (~/.claude*/projects/<cwd>/…jsonl).
Der model-Parameter des Agent-Tools hat eine Alias-Whitelist (sonnet/opus/haiku/fable) und lehnt GPT-Slugs ab — GPT geht NUR über den Agent-TYP, nie über den Parameter.
Instruiere Subagents, ihr Ergebnis IMMER in der finalen Antwort zu melden — sonst enden sie teils mit bloßer Idle-Meldung ohne Inhalt.

Verbindliche Modell-Deklaration bei jedem Subagent

Jeder Spawn muss das Modell technisch und explizit deklarieren, damit Claude Codes Agents-Ansicht den echten Modell-Chip ([gpt-5.6-sol], die zugehörige -fast-Variante oder Terra) zeigt:

Standard-Aufruf: immer subagent_type: "gpt"; in Workflows ausnahmslos agentType: "gpt". Den Agent-Typ niemals weglassen und nie nur im Prompt behaupten, dass GPT verwendet werde.
Ein spezialisierter Custom Agent darf seinen eigenen subagent_type bzw. agentType behalten, wenn dessen Definition im Frontmatter explizit model: gpt-5.6-sol oder model: gpt-5.6-terra setzt. Vor dem Spawn prüfen; Custom-Prompt und Tool-Grenzen dürfen nicht durch gpt ersetzt werden.
Zulässige Subagent-Modelle sind ausschließlich GPT-5.6 Sol (Standard) oder GPT-5.6 Terra. Niemals Haiku verwenden. Ist keine explizite Terra- Definition verfügbar, auf den verwalteten gpt-Typ (Sol) zurückfallen — nicht auf ein implizit geerbtes Modell.
Bei Custom-Agent-Definitionen muss model: im Frontmatter gesetzt sein; keine Definition mit impliziter Vererbung starten. Name/Label beschreibt die Aufgabe, nicht das Modell — den Modell-Chip rendert Claude Code aus der tatsächlich aufgelösten Definition.
CLI-Jobs deklarieren das Modell weiterhin zwingend über --model gpt-5.6-sol oder ein ausdrücklich gewünschtes --model gpt-5.6-terra.
Die sichtbare Deklaration ist ein Kontrollsignal, aber der verbindliche Nachweis bleibt das "model"-Feld im Agent-Transcript.

CLI-Weg (explizit): Codex-Subagents via `whisperm8 agent`

Was das System ist

Die OpenAI Codex CLI hat kein Background-Konzept (kein Pendant zu claude --bg/attach). WhisperM8 schließt die Lücke: das whisperm8-CLI ist der Supervisor. whisperm8 agent run startet einen headless codex exec-Lauf, ein detachter Supervisor-Prozess protokolliert Events und Zustand in ein Job-Verzeichnis, und die WhisperM8-App zeigt jeden Job live in der Sidebar (eingerückt unter der Claude-Session, die ihn gespawnt hat).

Wichtige Eigenschaften:

Jeder Job ist eine echte Codex-Session (persistiert in ~/.codex/sessions/). Folge-Turns via agent send nutzen codex exec resume — der Kontext bleibt erhalten.
Ein Turn = ein Prozess. Zwischen Turns läuft nichts; Jobs überleben Neustarts. Ein Job durchläuft: spawning → running → done | failed | stopped (+ takenOver, wenn der User ihn in der App als interaktiven Chat übernimmt — danach ist send dauerhaft gesperrt).
Approvals gibt es nicht (headless = never); Sicherheit kommt aus der Sandbox: workspace-write (Default, kein Netzwerk) oder read-only.
Der User sieht alles in der WhisperM8-App und kann eingreifen — erwähne bei gespawnten Jobs die Job-ID, damit er sie zuordnen kann.

Befehle (vollständig)

whisperm8 agent run  [optionen] "<prompt>"       # Job starten
whisperm8 agent send <id> [--wait] [--json] "<prompt>"   # Folge-Turn (resume)
whisperm8 agent list [--json]                    # alle Jobs, neueste zuerst
whisperm8 agent status <id> [--json]             # Zustand + Report + Metriken
whisperm8 agent wait <id> [--json]               # auf Turn-Ende warten / nach Timeout wieder anhängen
whisperm8 agent logs <id> [--tail N]             # letzte N Event-Zeilen (Default 50, rohe JSONL)
whisperm8 agent stop <id>                        # laufenden Turn abbrechen (SIGTERM)
whisperm8 agent rm <id>                          # Job-Verzeichnis entfernen (Codex-Session bleibt)
whisperm8 agent help                             # Hilfetext

run-Optionen

Flag	Wirkung
`--wait`	Synchron: blockiert bis Turn-Ende, Ergebnis auf stdout. Ohne `--wait`: detacht, gibt sofort `{"shortId":"…","state":"spawning"}` aus.
`--json`	Maschinenlesbares Ergebnis-Objekt auf stdout (immer setzen, wenn du das Ergebnis parst).
`--cd <dir>`	Working Directory des Jobs. Default: aktuelles Verzeichnis.
`--sandbox <m>`	`read-only` oder `workspace-write` (Default). read-only für reine Analyse/Reviews.
`--worktree`	Job arbeitet in einem frischen Git-Worktree (Branch `subagent/<id>`, liegt im Job-Verzeichnis). Pflicht-Empfehlung, wenn du selbst gerade im selben Checkout editierst.
`--allow-network`	Netzwerk in der Sandbox (u.a. `git push`, Paketinstallationen). Default aus — vorher den User fragen.
`--config <key=value>`	Generischer Codex-Config-Override, wiederholbar — wird 1:1 als `-c` an codex exec durchgereicht und gilt auch für Folge-Turns (`send`). Kommt NACH den eingebauten Configs, übersteuert sie also (z.B. `--config tools.web_search=true`). Werte mit führendem `-` werden abgelehnt (Exit 1) — codex läse sie als Flag.
`--playwright-storage-state <path>`	Browser-QA: startet den Playwright-MCP im Codex-Subagent isoliert mit dieser storageState-Datei (`--isolated --storage-state`). Relative Pfade werden relativ zu `--cd`/CWD aufgelöst; fehlt die Datei, bricht `run` sofort mit Exit 1 ab. Browser-Traffic braucht KEIN `--allow-network`.
`--model <name>`	Codex-Modell-Override. IMMER explizit `--model gpt-5.6-sol` setzen (Frontier-Modell, Stand codex 0.144.0) — NIEMALS `gpt-5.5` oder älter, und nie weglassen (ohne Flag gilt die `~/.codex/config.toml`, deren Effort-Default niedrig ist). Freier String, keine Whitelist — neue Modelle funktionieren sofort.
`--effort <level>`	`model_reasoning_effort`-Override: minimal/low/medium/high/xhigh/max/ultra — modellabhängig (bis `ultra` nur gpt-5.6-sol/terra; gpt-5.6-luna bis `max`; ältere Modelle bis `xhigh`). IMMER explizit setzen, Standard `high` (ohne Flag greift der config.toml-Default `low`); für die härtesten Verifikationen `xhigh`+. Verfügbare Level pro Modell: `~/.codex/models_cache.json`.
`--parent <session-id>`	Claude-Session-ID des spawnenden Chats — nur nötig, wenn du eine echte ID kennst. OHNE das Flag ordnet WhisperM8 den Job automatisch über den Prozessbaum dem Chat zu, in dem du läufst (`$CLAUDE_SESSION_ID` existiert NICHT als Env-Variable — nicht verwenden).

Exit-Codes (verbindlich — kein Text-Parsing nötig)

Code	Bedeutung	Typische Reaktion
0	ok / Job done (Report-status success oder partial)	Report auswerten
1	Usage-Fehler (Flag/Argument falsch)	Aufruf korrigieren
2	Job failed (turn.failed, Prozessfehler, oder Report meldet `status: failure`)	`status`/`logs` lesen, ggf. `send` mit Korrektur
3	Zustandskonflikt (Turn läuft schon; Job wurde übernommen; keine Thread-ID)	Warten bzw. Job neu starten
4	Umgebungsproblem (codex fehlt/zu alt, Job-ID unbekannt, Worktree dirty bei rm)	Meldung auf stderr lesen, User informieren

Ausgabe-Formen (`--json`)

run ohne --wait (detacht):

{"shortId":"a3f81c2e","state":"spawning"}

run --wait, send --wait und status liefern das volle Job-Objekt (Auszug; Felder können null sein):

{
  "shortId": "a3f81c2e",
  "state": "done",
  "intent": "…erster Prompt…",
  "cwd": "/pfad/zum/repo",
  "codexThreadID": "019f2f13-…",
  "parentSessionID": "…",
  "turns": 2,
  "sandbox": "workspace-write",
  "worktree": {"path": "…", "branch": "subagent/a3f81c2e"},
  "metrics": {"lastTurnSeconds": 42.1, "diffChangedFiles": 3, "diffAdded": 120, "diffDeleted": 8},
  "failureReason": null,
  "report": {
    "status": "success",
    "summary": "…was getan wurde…",
    "filesChanged": ["…"],
    "commits": [{"sha": "9c2e1af", "message": "feat(...): …"}],
    "testsRun": {"command": "swift test --filter Foo", "passed": true},
    "openQuestions": ["…"]
  }
}

report ist schema-erzwungen (--output-schema). Ist es trotzdem null, steht der Rohtext in rawLastMessage.
metrics misst der Supervisor selbst (verlässlich); report sagt das Modell (plausibel, aber verifizierbar — Commits ggf. per git prüfen).
list --json liefert ein Array dieser Job-Objekte (ohne report).

Arbeitsregeln

Modellwahl ist festgelegt, nicht deine Entscheidung: jeder run bekommt --model gpt-5.6-sol --effort high (das beste verfügbare Modell). NIEMALS gpt-5.5 oder ein anderes älteres Modell wählen und die Flags NIE weglassen — ohne sie zieht die ~/.codex/config.toml mit Effort low. Härteste Verifikationen/Adjudikationen: --effort xhigh bis ultra. Vom Sol-Default nur auf ausdrücklichen User-Wunsch zu gpt-5.6-terra wechseln; andere Modellfamilien und ältere GPT-Generationen bleiben ausgeschlossen.
Parent-Zuordnung ist automatisch: Läufst du in einem WhisperM8-Chat, erkennt das CLI den spawnenden Chat über den Prozessbaum — kein --parent nötig. ($CLAUDE_SESSION_ID ist als Env-Variable LEER — niemals darauf verlassen.)
Kurz (< ~2 Min erwartet): direkt run --wait --json.
Länger: run --wait --json als Background-Bash-Task starten (run_in_background) — das Harness meldet sich beim Prozessende von selbst. Keine Poll-Schleifen bauen. --wait ist nur Zuschauer: der Job läuft immer detacht; stirbt der wartende Prozess (Bash-Timeout, Ctrl-C, Abbruch), arbeitet der Turn weiter. agent wait <id> hängt sich wieder an (die Short-ID steht als stderr-Breadcrumb sofort im Output, auch bei --json). Turns stoppt ausschließlich agent stop <id>.
Paralleles Schreiben im selben Repo, in dem du selbst editierst: --worktree. Danach: Branch subagent/<id> reviewen (git log/diff <branch>), mergen/cherry-picken oder verwerfen.
Reine Analyse: --sandbox read-only — schneller freigegeben, kein Schreibrisiko.
Nachsteuern statt neu spawnen: agent send <id> "…" behält den Session-Kontext. Exit 3 heißt: Turn läuft noch (mit logs reinschauen) oder Job wurde übernommen.
Zwischenstand: agent logs <id> --tail 20 (rohe JSONL-Events: agent_message-, command_execution-Items etc.).
Committen ja, Pushen nein. Das CLI schaltet bei workspace-write das gemeinsame Git-Verzeichnis automatisch frei (git rev-parse --git-common-dir; Codex' Sandbox behandelt es sonst als read-only) — Commits funktionieren in-place, aus Repo-Unterverzeichnissen und mit --worktree. Push nur nach User-Freigabe via --allow-network. Nebenwirkung: der Override ERSETZT ein etwaiges sandbox_workspace_write.writable_roots aus der eigenen config.toml (TOML ersetzt Arrays) — eigene Roots ggf. per --config mitgeben. Scheitert ein Commit an .git/index.lock: Operation not permitted, läuft ein whisperm8-Binary von vor dem Fix — App neu bauen/starten.
Aufräumen: fertige, ausgewertete Jobs mit agent rm <id> entfernen — aber nicht ungefragt, der User sieht die Jobs auch in der App.
Codex liest Projekt-Konventionen aus AGENTS.md im Ziel-Repo (nicht CLAUDE.md). Fehlt es, gib die 2–3 wichtigsten Konventionen im Prompt mit.
Formuliere Aufträge abschlussorientiert: was tun, wie verifizieren (Test-Befehl!), was committen. Der Abschluss-Report ist erzwungen — gute Prompts machen ihn aussagekräftig.

Browser-/UI-QA mit Playwright-State

Für UI- und Browser-Verifikation ist Playwright-MCP der Standardpfad, nicht der sichtbare Chrome des Users und nicht Computer Use. Authentifizierung wird über Playwright storageState geteilt, z.B. .qa/auth/akquise-admin.storageState.json.

Verbindliche Regeln:

Nie direkt fan-outen. Starte zuerst genau einen Probe-Subagent mit --playwright-storage-state <path>, der eine geschützte Route öffnet und Auth-Indikatoren prüft.
Fan-out nur nach PASS. Wenn der Probe-Subagent Playwright-MCP nicht sieht, auf Login/Auth umgeleitet wird oder den Auth-Indikator nicht findet, keine weiteren Browser-QA-Subagents starten.
State-Dateien sind read-only. Subagents dürfen .qa/auth/* lesen, aber nicht überschreiben. Refresh des Auth-State ist ein eigener, serieller Auftrag.
Isolierte Browser-Kontexte. --playwright-storage-state erzwingt einen isolierten Playwright-MCP-Kontext, damit parallele Subagents keine Browser- Profile teilen.
Eindeutige Artefakte. Jeder QA-Subagent bekommt eigene Pfade: .qa/reports/<task-id>.md, .qa/screenshots/<task-id>/, .qa/traces/<task-id>/.
Keine Fallbacks ohne Freigabe. Wenn Playwright-MCP nicht funktioniert, nicht auf sichtbaren Chrome, Codex Chrome Plugin oder Computer Use ausweichen.
State frisch capturen, direkt vor jedem Batch. storageStates sterben serverseitig binnen ~40 Minuten (App-Session-Rotation), unabhängig von der Cookie-Expiry im JSON. Erzeugung via 1Password-CLI ohne Secret-Sichtkontakt: siehe references/1password-cli.md.
Harte Verbotsregeln in JEDEN Prompt. Codex kennt die Sicherheitsregeln des Haupt-Agenten nicht — ein Agent hat sich bei totem State eigenmächtig mit Seed-Credentials eingeloggt. Pflichtbausteine: nie einloggen/ausloggen/ Passwörter, bei Login-Redirect abbrechen mit VERDICT "NICHT PRUEFBAR", erlaubte Datenänderungen explizit benennen inkl. Rückdreh-Pflicht.
Mutierende Agents brauchen disjunkte Testobjekte (pro Agent ein eigenes Wegwerf-Objekt, namentlich zugewiesen). Fehlende Testdaten vorher selbst headless anlegen, nicht dem Agent überlassen.
Agent-Verdicts sind Evidenz, keine Wahrheit. Überraschende MÄNGEL/ NICHT-PRÜFBAR-Urteile selbst nachmessen (headless Playwright mit demselben State) — Fehlurteil-Muster in references/playwright-browser-qa.md.

Technische Eigenschaften (für korrekte Flags/Prompts):

Der Playwright-MCP läuft außerhalb der Codex-Sandbox — Browser-Traffic (auch localhost/Dev-Server) funktioniert ohne --allow-network. Das Flag nur setzen, wenn der Subagent selbst Netz braucht (z.B. Paketinstallation).
Der MCP ist gepinnt (@playwright/mcp, --browser chrome --ignore-https-errors): nutzt das installierte Chrome und ignoriert TLS-Fehler — gedacht für lokale Test-Umgebungen mit self-signed Zertifikaten.
Jeder Subagent startet eine eigene Chrome-Instanz. Moderat parallelisieren (3–5 Jobs) und größere Ticket-Mengen staffeln — der Engpass sind RAM/CPU der vielen Chrome-Instanzen, kein hartes Limit.
Fehlersignatur user cancelled MCP tool call: Codex hat den Toolcall am MCP-Approval-Gate abgebrochen (nicht-read-only Tools wie browser_resize/browser_tabs/browser_evaluate brauchen headless eine Freigabe). Das CLI setzt diese Freigabe seit 2026-07-05 automatisch (default_tools_approval_mode) — tritt der Fehler trotzdem auf, ist es KEIN Timing-/Parallel-Problem: Logs prüfen und den Job per agent send <id> "…erneut prüfen…" nachsteuern statt neu spawnen — der Session-Kontext (gelesene Tickets etc.) bleibt erhalten.

Probe-Subagent:

whisperm8 agent run --wait --json --cd /pfad/zum/repo \
  --model gpt-5.6-sol --effort high \
  --playwright-storage-state .qa/auth/akquise-admin.storageState.json \
  "Browser-QA Preflight. Öffne https://akquise.test/admin/kunden mit Playwright-MCP. Prüfe: keine Weiterleitung zu /login oder auth.akquise.test, Titel AkquiseAI, sichtbarer Auth-Indikator Admin AkquiseAI oder admin@akquise.ai. Schreibe .qa/reports/preflight.md. Keine App-Daten ändern."

Subagent-Prompt für Browser-QA:

Browser-QA Auftrag.

Base URL: <url>
Auth-State: <storageState>
Report: .qa/reports/<task-id>.md
Screenshots: .qa/screenshots/<task-id>/
Traces bei Fehlern: .qa/traces/<task-id>/

Nutze Playwright-MCP. Nutze nicht den sichtbaren Chrome, nicht Computer Use und
nicht das Codex Chrome Plugin. Überschreibe .qa/auth/* nicht.

HARTE REGELN: NIEMALS einloggen, ausloggen oder Passwörter eingeben — wenn eine
Login-Seite erscheint oder der Auth-State nicht greift, sofort abbrechen und
VERDICT "NICHT PRUEFBAR" dokumentieren. Erlaubte Datenänderungen: <explizit
aufzählen oder "keine">; jede Änderung zurückdrehen und im Report dokumentieren.
Arbeite zügig — der Auth-State altert.

Schreibe VERDICT (BESTANDEN/MAENGEL/NICHT PRUEFBAR), Beobachtung pro
Akzeptanzpunkt (Texte wörtlich zitieren), finale URL, Console-/Network-
Auffälligkeiten und Artefaktpfade — VERDICT zusätzlich in die Abschlussnachricht.

Explizite CLI-Spezialfälle in Claude Dynamic Workflows (`/workflows`)

Der normale Workflow-Weg ist direkt und nativ: agent(prompt, {agentType: "gpt", schema}). Insbesondere .claude/workflows/codex-verify.js enthält ausschließlich diesen Weg. Der Workflow lädt diesen Skill nicht zur Laufzeit — das ist weder möglich noch nötig, weil Agent-Typ und Fehlerverhalten im Skript fest verdrahtet sind.

Nur wenn ein Auftrag ausdrücklich Codex-CLI-Eigenschaften benötigt, etwa einen detachten Job, Browser-QA oder image_gen, darf ein eigener Workflow-Step die CLI verwenden. Das Workflow-Skript kann nicht selbst shellen; jeder solche Codex-Aufruf läuft über den Custom-Agent codex-runner. Dessen Frontmatter setzt das Modell explizit auf gpt-5.6-sol und beschränkt die Tools auf Bash; Haiku, Sonnet oder ein implizit geerbtes Modell sind auch für mechanische Wrapper verboten. Der Runner nutzt run --wait --json, ; echo "EXIT:$?" und reicht das stdout-JSON schemageprüft weiter. Exit-Codes wertet das Skript aus, nicht der Wrapper. status <id> statt list (Kontext-Falle!), shortId durch die Stages reichen für send-Nachsteuerung, Playwright-Jobs auf 3–5 parallel batchen. Prompt-Vorlage, Schema, CLI-Spezialmuster wie detachte Nachsteuer-Ketten und Browser-QA-Fan-out sowie bekannte Grenzen: references/claude-workflows.md.

CLI-Spezialpfad: Kopiervorlagen

# 1) Detachter, in der App sichtbarer Langläufer
whisperm8 agent run --json --sandbox read-only \
  --model gpt-5.6-sol --effort high \
  "Führe eine langlaufende Repository-Inventur durch. Nur Analyse, keine Edits. Fasse Risiken und offene Fragen im Abschluss-Report zusammen."

# 2) Parallele Implementierung, isoliert (als Background-Task starten!)
whisperm8 agent run --wait --json --worktree \
  --model gpt-5.6-sol --effort high \
  "Implementiere <X> in <Datei>. Verifiziere mit 'swift test --filter <Y>'. Committe bei grün (Conventional Commit, deutsche Beschreibung)."

# 3) Fire-and-forget mit späterem Abholen
ID=$(whisperm8 agent run --json --cd /pfad/repo --model gpt-5.6-sol --effort high "…" | sed -E 's/.*"shortId":"([a-f0-9]+)".*/\1/')
# … später:
whisperm8 agent status "$ID" --json

# 4) Nachsteuern
whisperm8 agent send a3f81c2e --wait --json \
  "openQuestions[0] beantworten: ja, Legacy-Modes hart ablehnen. Bitte anpassen und nachcommitten."

Troubleshooting

Shell-Parse-Error beim Inline-Prompt ((eval):N: parse error): Lange deutsche Prompts mit typografischen Anführungszeichen („…") brechen die zsh-Doppelquote-Umklammerung — das gerade Abschlusszeichen " beendet den String. Robustes Muster: Prompt mit Write in eine Datei legen und per whisperm8 agent run … "$(cat /pfad/prompt.txt)" übergeben (gelernt 2026-07-12, Doku-Nachsteuerungs-Job).
Exit 4 „codex nicht gefunden/zu alt": Codex.app installieren oder codex in den PATH; Mindestversion siehe Fehlermeldung.
state: failed mit failureReason: "supervisor died …": der Supervisor-Prozess wurde gekillt (Neustart o.ä.). Der Job ist per send fortsetzbar, sofern codexThreadID gesetzt ist.
stalled im failureReason: 30 Min keine Events — Idle-Watchdog hat abgebrochen. Prompt verkleinern oder Aufgabe zerlegen.
Exit 3 bei send, Job zeigt takenOver: der User hat den Job in WhisperM8 als interaktiven Chat übernommen — nicht mehr anfassen, den User fragen.
Report null trotz done: rawLastMessage nutzen; beim nächsten send explizit an den Report-Vertrag erinnern.
partial + openQuestion „Sandbox blockiert .git/index.lock": das laufende whisperm8-Binary ist älter als der Commit-Fix (writable_roots- Override, 2026-07-08) — App neu bauen/starten. Die Dateiarbeit des Jobs ist trotzdem erledigt: notfalls selbst committen; nach dem Update committet ein send-Folge-Turn auch selbst nach.
Report meldet Commits, aber git log kennt sie nicht als neu: Codex referenziert gern existierende SHAs — Commits IMMER per git verifizieren, besonders bei read-only-Jobs (die können gar nicht committen).

Referenzen

Vertiefendes Betriebswissen (bei Bedarf laden):

references/playwright-browser-qa.md — Browser-QA im Detail: State-Lebensdauer und Frische-Regeln, Parallelitäts-Empirie und Approval-Gate-Historie, Sandbox-Grenzen, Werkzeug-Verfügbarkeits-Fallbacks, Prompt-Pflichtbausteine, Testdaten-Kollisionsvermeidung, Verdict-Kalibrierung (dokumentierte Fehlurteil-Muster), bewährter Batch-Ablauf.
references/1password-cli.md — Auth-States via 1Password-CLI: op run-Muster ohne Secret-Sichtkontakt, capture-state.mjs, Item-Mapping, Setup, Betriebsregeln (Frische, gitignore, read-only für Subagents).
references/claude-workflows.md — explizite Codex-CLI-Jobs als Steps in Claude Dynamic Workflows: Wrapper-Kontrakt (Prompt-Vorlage + Schema), Exit-Code-Mapping im Skript, Parallelitäts- und Budget-Regeln, Browser-QA- Fan-out, App-sichtbare Langläufer und Nachsteuer-Ketten sowie bekannte Grenzen inklusive des verifizierten Commit-Fixes.

name

codex-subagent

description

GPT-Subagents: nativ (Standard) oder Codex-CLI (explizit)

Wegweiser — welcher Weg wann

Anlass	Weg
Standard: "GPT-Subagent", zweite Meinung, Review, parallele Teilaufgabe	NATIV (`subagent_type: "gpt"`)
Bilder generieren (codex-natives `image_gen`)	CLI — immer; nativ gibt es kein image_gen
User sagt explizit "CLI", "whisperm8 agent", "Job" — oder `--cli` als Skill-Argument	CLI
Detachte Langläufer: Sidebar-Sichtbarkeit in der App, überleben App-Neustart	CLI
Browser-QA (Playwright-storageState), 1Password-Flows	CLI
Steps in Claude Dynamic Workflows	NATIV: `agent(prompt, {agentType: "gpt", schema})` — inkl. Structured Output E2E-validiert (2026-07-18). Der ausgelieferte Workflow `codex-verify` ist native-only und fällt nie auf CLI/`codex-runner` zurück.

Skill-Argumente: /codex-subagent <aufgabe> → nativ. /codex-subagent --cli <aufgabe> → CLI erzwingen. Bild-Aufträge gehen unabhängig vom Argument immer über die CLI.

Nativer Weg (Standard): Agent-Typ `gpt`

Wenn der Spawn fehlschlägt („Agent type 'gpt' not found"):

Die Registry lädt beim Session-Start — Sessions, die älter sind als die Agent-Definition, kennen den Typ nicht (nur PROJEKT-Level-Definitionen unter .claude/agents/ laden mid-session nach). Abhilfe: neue Session starten und den User informieren; nicht automatisch auf CLI wechseln.
GPT-Backend deaktiviert? env | grep ANTHROPIC_BASE_URL muss auf http://127.0.0.1:<router-port> zeigen; sonst Settings → „GPT-Backend" prüfen. Der native-only Workflow codex-verify bricht in diesem Fall klar ab; nur ein ausdrücklich angeforderter CLI-Auftrag darf auf den CLI-Weg wechseln.

Gotchas (QA-verifiziert 2026-07-18):

Selbstauskunft ist wertlos: GPT-Subagents halten sich laut System-Prompt für Claude/Opus. Modell-Beweis liefern nur die "model"-Felder im Session-JSONL (~/.claude*/projects/<cwd>/…jsonl).
Der model-Parameter des Agent-Tools hat eine Alias-Whitelist (sonnet/opus/haiku/fable) und lehnt GPT-Slugs ab — GPT geht NUR über den Agent-TYP, nie über den Parameter.
Instruiere Subagents, ihr Ergebnis IMMER in der finalen Antwort zu melden — sonst enden sie teils mit bloßer Idle-Meldung ohne Inhalt.

Verbindliche Modell-Deklaration bei jedem Subagent

Jeder Spawn muss das Modell technisch und explizit deklarieren, damit Claude Codes Agents-Ansicht den echten Modell-Chip ([gpt-5.6-sol], die zugehörige -fast-Variante oder Terra) zeigt:

Standard-Aufruf: immer subagent_type: "gpt"; in Workflows ausnahmslos agentType: "gpt". Den Agent-Typ niemals weglassen und nie nur im Prompt behaupten, dass GPT verwendet werde.
Ein spezialisierter Custom Agent darf seinen eigenen subagent_type bzw. agentType behalten, wenn dessen Definition im Frontmatter explizit model: gpt-5.6-sol oder model: gpt-5.6-terra setzt. Vor dem Spawn prüfen; Custom-Prompt und Tool-Grenzen dürfen nicht durch gpt ersetzt werden.
Zulässige Subagent-Modelle sind ausschließlich GPT-5.6 Sol (Standard) oder GPT-5.6 Terra. Niemals Haiku verwenden. Ist keine explizite Terra- Definition verfügbar, auf den verwalteten gpt-Typ (Sol) zurückfallen — nicht auf ein implizit geerbtes Modell.
Bei Custom-Agent-Definitionen muss model: im Frontmatter gesetzt sein; keine Definition mit impliziter Vererbung starten. Name/Label beschreibt die Aufgabe, nicht das Modell — den Modell-Chip rendert Claude Code aus der tatsächlich aufgelösten Definition.
CLI-Jobs deklarieren das Modell weiterhin zwingend über --model gpt-5.6-sol oder ein ausdrücklich gewünschtes --model gpt-5.6-terra.
Die sichtbare Deklaration ist ein Kontrollsignal, aber der verbindliche Nachweis bleibt das "model"-Feld im Agent-Transcript.

CLI-Weg (explizit): Codex-Subagents via `whisperm8 agent`

Was das System ist

Wichtige Eigenschaften:

Jeder Job ist eine echte Codex-Session (persistiert in ~/.codex/sessions/). Folge-Turns via agent send nutzen codex exec resume — der Kontext bleibt erhalten.
Ein Turn = ein Prozess. Zwischen Turns läuft nichts; Jobs überleben Neustarts. Ein Job durchläuft: spawning → running → done | failed | stopped (+ takenOver, wenn der User ihn in der App als interaktiven Chat übernimmt — danach ist send dauerhaft gesperrt).
Approvals gibt es nicht (headless = never); Sicherheit kommt aus der Sandbox: workspace-write (Default, kein Netzwerk) oder read-only.
Der User sieht alles in der WhisperM8-App und kann eingreifen — erwähne bei gespawnten Jobs die Job-ID, damit er sie zuordnen kann.

Befehle (vollständig)

whisperm8 agent run  [optionen] "<prompt>"       # Job starten
whisperm8 agent send <id> [--wait] [--json] "<prompt>"   # Folge-Turn (resume)
whisperm8 agent list [--json]                    # alle Jobs, neueste zuerst
whisperm8 agent status <id> [--json]             # Zustand + Report + Metriken
whisperm8 agent wait <id> [--json]               # auf Turn-Ende warten / nach Timeout wieder anhängen
whisperm8 agent logs <id> [--tail N]             # letzte N Event-Zeilen (Default 50, rohe JSONL)
whisperm8 agent stop <id>                        # laufenden Turn abbrechen (SIGTERM)
whisperm8 agent rm <id>                          # Job-Verzeichnis entfernen (Codex-Session bleibt)
whisperm8 agent help                             # Hilfetext

run-Optionen

Flag	Wirkung
`--wait`	Synchron: blockiert bis Turn-Ende, Ergebnis auf stdout. Ohne `--wait`: detacht, gibt sofort `{"shortId":"…","state":"spawning"}` aus.
`--json`	Maschinenlesbares Ergebnis-Objekt auf stdout (immer setzen, wenn du das Ergebnis parst).
`--cd <dir>`	Working Directory des Jobs. Default: aktuelles Verzeichnis.
`--sandbox <m>`	`read-only` oder `workspace-write` (Default). read-only für reine Analyse/Reviews.
`--worktree`	Job arbeitet in einem frischen Git-Worktree (Branch `subagent/<id>`, liegt im Job-Verzeichnis). Pflicht-Empfehlung, wenn du selbst gerade im selben Checkout editierst.
`--allow-network`	Netzwerk in der Sandbox (u.a. `git push`, Paketinstallationen). Default aus — vorher den User fragen.
`--config <key=value>`	Generischer Codex-Config-Override, wiederholbar — wird 1:1 als `-c` an codex exec durchgereicht und gilt auch für Folge-Turns (`send`). Kommt NACH den eingebauten Configs, übersteuert sie also (z.B. `--config tools.web_search=true`). Werte mit führendem `-` werden abgelehnt (Exit 1) — codex läse sie als Flag.
`--playwright-storage-state <path>`	Browser-QA: startet den Playwright-MCP im Codex-Subagent isoliert mit dieser storageState-Datei (`--isolated --storage-state`). Relative Pfade werden relativ zu `--cd`/CWD aufgelöst; fehlt die Datei, bricht `run` sofort mit Exit 1 ab. Browser-Traffic braucht KEIN `--allow-network`.
`--model <name>`	Codex-Modell-Override. IMMER explizit `--model gpt-5.6-sol` setzen (Frontier-Modell, Stand codex 0.144.0) — NIEMALS `gpt-5.5` oder älter, und nie weglassen (ohne Flag gilt die `~/.codex/config.toml`, deren Effort-Default niedrig ist). Freier String, keine Whitelist — neue Modelle funktionieren sofort.
`--effort <level>`	`model_reasoning_effort`-Override: minimal/low/medium/high/xhigh/max/ultra — modellabhängig (bis `ultra` nur gpt-5.6-sol/terra; gpt-5.6-luna bis `max`; ältere Modelle bis `xhigh`). IMMER explizit setzen, Standard `high` (ohne Flag greift der config.toml-Default `low`); für die härtesten Verifikationen `xhigh`+. Verfügbare Level pro Modell: `~/.codex/models_cache.json`.
`--parent <session-id>`	Claude-Session-ID des spawnenden Chats — nur nötig, wenn du eine echte ID kennst. OHNE das Flag ordnet WhisperM8 den Job automatisch über den Prozessbaum dem Chat zu, in dem du läufst (`$CLAUDE_SESSION_ID` existiert NICHT als Env-Variable — nicht verwenden).

Exit-Codes (verbindlich — kein Text-Parsing nötig)

Code	Bedeutung	Typische Reaktion
0	ok / Job done (Report-status success oder partial)	Report auswerten
1	Usage-Fehler (Flag/Argument falsch)	Aufruf korrigieren
2	Job failed (turn.failed, Prozessfehler, oder Report meldet `status: failure`)	`status`/`logs` lesen, ggf. `send` mit Korrektur
3	Zustandskonflikt (Turn läuft schon; Job wurde übernommen; keine Thread-ID)	Warten bzw. Job neu starten
4	Umgebungsproblem (codex fehlt/zu alt, Job-ID unbekannt, Worktree dirty bei rm)	Meldung auf stderr lesen, User informieren

Ausgabe-Formen (`--json`)

run ohne --wait (detacht):

{"shortId":"a3f81c2e","state":"spawning"}

run --wait, send --wait und status liefern das volle Job-Objekt (Auszug; Felder können null sein):

{
  "shortId": "a3f81c2e",
  "state": "done",
  "intent": "…erster Prompt…",
  "cwd": "/pfad/zum/repo",
  "codexThreadID": "019f2f13-…",
  "parentSessionID": "…",
  "turns": 2,
  "sandbox": "workspace-write",
  "worktree": {"path": "…", "branch": "subagent/a3f81c2e"},
  "metrics": {"lastTurnSeconds": 42.1, "diffChangedFiles": 3, "diffAdded": 120, "diffDeleted": 8},
  "failureReason": null,
  "report": {
    "status": "success",
    "summary": "…was getan wurde…",
    "filesChanged": ["…"],
    "commits": [{"sha": "9c2e1af", "message": "feat(...): …"}],
    "testsRun": {"command": "swift test --filter Foo", "passed": true},
    "openQuestions": ["…"]
  }
}

report ist schema-erzwungen (--output-schema). Ist es trotzdem null, steht der Rohtext in rawLastMessage.
metrics misst der Supervisor selbst (verlässlich); report sagt das Modell (plausibel, aber verifizierbar — Commits ggf. per git prüfen).
list --json liefert ein Array dieser Job-Objekte (ohne report).

Arbeitsregeln

Modellwahl ist festgelegt, nicht deine Entscheidung: jeder run bekommt --model gpt-5.6-sol --effort high (das beste verfügbare Modell). NIEMALS gpt-5.5 oder ein anderes älteres Modell wählen und die Flags NIE weglassen — ohne sie zieht die ~/.codex/config.toml mit Effort low. Härteste Verifikationen/Adjudikationen: --effort xhigh bis ultra. Vom Sol-Default nur auf ausdrücklichen User-Wunsch zu gpt-5.6-terra wechseln; andere Modellfamilien und ältere GPT-Generationen bleiben ausgeschlossen.
Parent-Zuordnung ist automatisch: Läufst du in einem WhisperM8-Chat, erkennt das CLI den spawnenden Chat über den Prozessbaum — kein --parent nötig. ($CLAUDE_SESSION_ID ist als Env-Variable LEER — niemals darauf verlassen.)
Kurz (< ~2 Min erwartet): direkt run --wait --json.
Länger: run --wait --json als Background-Bash-Task starten (run_in_background) — das Harness meldet sich beim Prozessende von selbst. Keine Poll-Schleifen bauen. --wait ist nur Zuschauer: der Job läuft immer detacht; stirbt der wartende Prozess (Bash-Timeout, Ctrl-C, Abbruch), arbeitet der Turn weiter. agent wait <id> hängt sich wieder an (die Short-ID steht als stderr-Breadcrumb sofort im Output, auch bei --json). Turns stoppt ausschließlich agent stop <id>.
Paralleles Schreiben im selben Repo, in dem du selbst editierst: --worktree. Danach: Branch subagent/<id> reviewen (git log/diff <branch>), mergen/cherry-picken oder verwerfen.
Reine Analyse: --sandbox read-only — schneller freigegeben, kein Schreibrisiko.
Nachsteuern statt neu spawnen: agent send <id> "…" behält den Session-Kontext. Exit 3 heißt: Turn läuft noch (mit logs reinschauen) oder Job wurde übernommen.
Zwischenstand: agent logs <id> --tail 20 (rohe JSONL-Events: agent_message-, command_execution-Items etc.).
Committen ja, Pushen nein. Das CLI schaltet bei workspace-write das gemeinsame Git-Verzeichnis automatisch frei (git rev-parse --git-common-dir; Codex' Sandbox behandelt es sonst als read-only) — Commits funktionieren in-place, aus Repo-Unterverzeichnissen und mit --worktree. Push nur nach User-Freigabe via --allow-network. Nebenwirkung: der Override ERSETZT ein etwaiges sandbox_workspace_write.writable_roots aus der eigenen config.toml (TOML ersetzt Arrays) — eigene Roots ggf. per --config mitgeben. Scheitert ein Commit an .git/index.lock: Operation not permitted, läuft ein whisperm8-Binary von vor dem Fix — App neu bauen/starten.
Aufräumen: fertige, ausgewertete Jobs mit agent rm <id> entfernen — aber nicht ungefragt, der User sieht die Jobs auch in der App.
Codex liest Projekt-Konventionen aus AGENTS.md im Ziel-Repo (nicht CLAUDE.md). Fehlt es, gib die 2–3 wichtigsten Konventionen im Prompt mit.
Formuliere Aufträge abschlussorientiert: was tun, wie verifizieren (Test-Befehl!), was committen. Der Abschluss-Report ist erzwungen — gute Prompts machen ihn aussagekräftig.

Browser-/UI-QA mit Playwright-State

Verbindliche Regeln:

Nie direkt fan-outen. Starte zuerst genau einen Probe-Subagent mit --playwright-storage-state <path>, der eine geschützte Route öffnet und Auth-Indikatoren prüft.
Fan-out nur nach PASS. Wenn der Probe-Subagent Playwright-MCP nicht sieht, auf Login/Auth umgeleitet wird oder den Auth-Indikator nicht findet, keine weiteren Browser-QA-Subagents starten.
State-Dateien sind read-only. Subagents dürfen .qa/auth/* lesen, aber nicht überschreiben. Refresh des Auth-State ist ein eigener, serieller Auftrag.
Isolierte Browser-Kontexte. --playwright-storage-state erzwingt einen isolierten Playwright-MCP-Kontext, damit parallele Subagents keine Browser- Profile teilen.
Eindeutige Artefakte. Jeder QA-Subagent bekommt eigene Pfade: .qa/reports/<task-id>.md, .qa/screenshots/<task-id>/, .qa/traces/<task-id>/.
Keine Fallbacks ohne Freigabe. Wenn Playwright-MCP nicht funktioniert, nicht auf sichtbaren Chrome, Codex Chrome Plugin oder Computer Use ausweichen.
State frisch capturen, direkt vor jedem Batch. storageStates sterben serverseitig binnen ~40 Minuten (App-Session-Rotation), unabhängig von der Cookie-Expiry im JSON. Erzeugung via 1Password-CLI ohne Secret-Sichtkontakt: siehe references/1password-cli.md.
Harte Verbotsregeln in JEDEN Prompt. Codex kennt die Sicherheitsregeln des Haupt-Agenten nicht — ein Agent hat sich bei totem State eigenmächtig mit Seed-Credentials eingeloggt. Pflichtbausteine: nie einloggen/ausloggen/ Passwörter, bei Login-Redirect abbrechen mit VERDICT "NICHT PRUEFBAR", erlaubte Datenänderungen explizit benennen inkl. Rückdreh-Pflicht.
Mutierende Agents brauchen disjunkte Testobjekte (pro Agent ein eigenes Wegwerf-Objekt, namentlich zugewiesen). Fehlende Testdaten vorher selbst headless anlegen, nicht dem Agent überlassen.
Agent-Verdicts sind Evidenz, keine Wahrheit. Überraschende MÄNGEL/ NICHT-PRÜFBAR-Urteile selbst nachmessen (headless Playwright mit demselben State) — Fehlurteil-Muster in references/playwright-browser-qa.md.

Technische Eigenschaften (für korrekte Flags/Prompts):

Der Playwright-MCP läuft außerhalb der Codex-Sandbox — Browser-Traffic (auch localhost/Dev-Server) funktioniert ohne --allow-network. Das Flag nur setzen, wenn der Subagent selbst Netz braucht (z.B. Paketinstallation).
Der MCP ist gepinnt (@playwright/mcp, --browser chrome --ignore-https-errors): nutzt das installierte Chrome und ignoriert TLS-Fehler — gedacht für lokale Test-Umgebungen mit self-signed Zertifikaten.
Jeder Subagent startet eine eigene Chrome-Instanz. Moderat parallelisieren (3–5 Jobs) und größere Ticket-Mengen staffeln — der Engpass sind RAM/CPU der vielen Chrome-Instanzen, kein hartes Limit.
Fehlersignatur user cancelled MCP tool call: Codex hat den Toolcall am MCP-Approval-Gate abgebrochen (nicht-read-only Tools wie browser_resize/browser_tabs/browser_evaluate brauchen headless eine Freigabe). Das CLI setzt diese Freigabe seit 2026-07-05 automatisch (default_tools_approval_mode) — tritt der Fehler trotzdem auf, ist es KEIN Timing-/Parallel-Problem: Logs prüfen und den Job per agent send <id> "…erneut prüfen…" nachsteuern statt neu spawnen — der Session-Kontext (gelesene Tickets etc.) bleibt erhalten.

Probe-Subagent:

whisperm8 agent run --wait --json --cd /pfad/zum/repo \
  --model gpt-5.6-sol --effort high \
  --playwright-storage-state .qa/auth/akquise-admin.storageState.json \
  "Browser-QA Preflight. Öffne https://akquise.test/admin/kunden mit Playwright-MCP. Prüfe: keine Weiterleitung zu /login oder auth.akquise.test, Titel AkquiseAI, sichtbarer Auth-Indikator Admin AkquiseAI oder admin@akquise.ai. Schreibe .qa/reports/preflight.md. Keine App-Daten ändern."

Subagent-Prompt für Browser-QA:

Browser-QA Auftrag.

Base URL: <url>
Auth-State: <storageState>
Report: .qa/reports/<task-id>.md
Screenshots: .qa/screenshots/<task-id>/
Traces bei Fehlern: .qa/traces/<task-id>/

Nutze Playwright-MCP. Nutze nicht den sichtbaren Chrome, nicht Computer Use und
nicht das Codex Chrome Plugin. Überschreibe .qa/auth/* nicht.

HARTE REGELN: NIEMALS einloggen, ausloggen oder Passwörter eingeben — wenn eine
Login-Seite erscheint oder der Auth-State nicht greift, sofort abbrechen und
VERDICT "NICHT PRUEFBAR" dokumentieren. Erlaubte Datenänderungen: <explizit
aufzählen oder "keine">; jede Änderung zurückdrehen und im Report dokumentieren.
Arbeite zügig — der Auth-State altert.

Schreibe VERDICT (BESTANDEN/MAENGEL/NICHT PRUEFBAR), Beobachtung pro
Akzeptanzpunkt (Texte wörtlich zitieren), finale URL, Console-/Network-
Auffälligkeiten und Artefaktpfade — VERDICT zusätzlich in die Abschlussnachricht.

Explizite CLI-Spezialfälle in Claude Dynamic Workflows (`/workflows`)

CLI-Spezialpfad: Kopiervorlagen

# 1) Detachter, in der App sichtbarer Langläufer
whisperm8 agent run --json --sandbox read-only \
  --model gpt-5.6-sol --effort high \
  "Führe eine langlaufende Repository-Inventur durch. Nur Analyse, keine Edits. Fasse Risiken und offene Fragen im Abschluss-Report zusammen."

# 2) Parallele Implementierung, isoliert (als Background-Task starten!)
whisperm8 agent run --wait --json --worktree \
  --model gpt-5.6-sol --effort high \
  "Implementiere <X> in <Datei>. Verifiziere mit 'swift test --filter <Y>'. Committe bei grün (Conventional Commit, deutsche Beschreibung)."

# 3) Fire-and-forget mit späterem Abholen
ID=$(whisperm8 agent run --json --cd /pfad/repo --model gpt-5.6-sol --effort high "…" | sed -E 's/.*"shortId":"([a-f0-9]+)".*/\1/')
# … später:
whisperm8 agent status "$ID" --json

# 4) Nachsteuern
whisperm8 agent send a3f81c2e --wait --json \
  "openQuestions[0] beantworten: ja, Legacy-Modes hart ablehnen. Bitte anpassen und nachcommitten."

Troubleshooting

Shell-Parse-Error beim Inline-Prompt ((eval):N: parse error): Lange deutsche Prompts mit typografischen Anführungszeichen („…") brechen die zsh-Doppelquote-Umklammerung — das gerade Abschlusszeichen " beendet den String. Robustes Muster: Prompt mit Write in eine Datei legen und per whisperm8 agent run … "$(cat /pfad/prompt.txt)" übergeben (gelernt 2026-07-12, Doku-Nachsteuerungs-Job).
Exit 4 „codex nicht gefunden/zu alt": Codex.app installieren oder codex in den PATH; Mindestversion siehe Fehlermeldung.
state: failed mit failureReason: "supervisor died …": der Supervisor-Prozess wurde gekillt (Neustart o.ä.). Der Job ist per send fortsetzbar, sofern codexThreadID gesetzt ist.
stalled im failureReason: 30 Min keine Events — Idle-Watchdog hat abgebrochen. Prompt verkleinern oder Aufgabe zerlegen.
Exit 3 bei send, Job zeigt takenOver: der User hat den Job in WhisperM8 als interaktiven Chat übernommen — nicht mehr anfassen, den User fragen.
Report null trotz done: rawLastMessage nutzen; beim nächsten send explizit an den Report-Vertrag erinnern.
partial + openQuestion „Sandbox blockiert .git/index.lock": das laufende whisperm8-Binary ist älter als der Commit-Fix (writable_roots- Override, 2026-07-08) — App neu bauen/starten. Die Dateiarbeit des Jobs ist trotzdem erledigt: notfalls selbst committen; nach dem Update committet ein send-Folge-Turn auch selbst nach.
Report meldet Commits, aber git log kennt sie nicht als neu: Codex referenziert gern existierende SHAs — Commits IMMER per git verifizieren, besonders bei read-only-Jobs (die können gar nicht committen).

Referenzen

Vertiefendes Betriebswissen (bei Bedarf laden):

references/playwright-browser-qa.md — Browser-QA im Detail: State-Lebensdauer und Frische-Regeln, Parallelitäts-Empirie und Approval-Gate-Historie, Sandbox-Grenzen, Werkzeug-Verfügbarkeits-Fallbacks, Prompt-Pflichtbausteine, Testdaten-Kollisionsvermeidung, Verdict-Kalibrierung (dokumentierte Fehlurteil-Muster), bewährter Batch-Ablauf.
references/1password-cli.md — Auth-States via 1Password-CLI: op run-Muster ohne Secret-Sichtkontakt, capture-state.mjs, Item-Mapping, Setup, Betriebsregeln (Frische, gitignore, read-only für Subagents).
references/claude-workflows.md — explizite Codex-CLI-Jobs als Steps in Claude Dynamic Workflows: Wrapper-Kontrakt (Prompt-Vorlage + Schema), Exit-Code-Mapping im Skript, Parallelitäts- und Budget-Regeln, Browser-QA- Fan-out, App-sichtbare Langläufer und Nachsteuer-Ketten sowie bekannte Grenzen inklusive des verifizierten Commit-Fixes.

codex-subagent

同仓库更多 Skills

同仓库更多 Skills

GPT-Subagents: nativ (Standard) oder Codex-CLI (explizit)

Wegweiser — welcher Weg wann

Nativer Weg (Standard): Agent-Typ gpt

Verbindliche Modell-Deklaration bei jedem Subagent

CLI-Weg (explizit): Codex-Subagents via whisperm8 agent

Was das System ist

Befehle (vollständig)

run-Optionen

Exit-Codes (verbindlich — kein Text-Parsing nötig)

Ausgabe-Formen (--json)

Arbeitsregeln

Browser-/UI-QA mit Playwright-State

Explizite CLI-Spezialfälle in Claude Dynamic Workflows (/workflows)

CLI-Spezialpfad: Kopiervorlagen

Troubleshooting

Referenzen

GPT-Subagents: nativ (Standard) oder Codex-CLI (explizit)

Wegweiser — welcher Weg wann

Nativer Weg (Standard): Agent-Typ gpt

Verbindliche Modell-Deklaration bei jedem Subagent

CLI-Weg (explizit): Codex-Subagents via whisperm8 agent

Was das System ist

Befehle (vollständig)

run-Optionen

Exit-Codes (verbindlich — kein Text-Parsing nötig)

Ausgabe-Formen (--json)

Arbeitsregeln

Browser-/UI-QA mit Playwright-State

Explizite CLI-Spezialfälle in Claude Dynamic Workflows (/workflows)

CLI-Spezialpfad: Kopiervorlagen

Troubleshooting

Referenzen

Nativer Weg (Standard): Agent-Typ `gpt`

CLI-Weg (explizit): Codex-Subagents via `whisperm8 agent`

Ausgabe-Formen (`--json`)

Explizite CLI-Spezialfälle in Claude Dynamic Workflows (`/workflows`)

Nativer Weg (Standard): Agent-Typ `gpt`

CLI-Weg (explizit): Codex-Subagents via `whisperm8 agent`

Ausgabe-Formen (`--json`)

Explizite CLI-Spezialfälle in Claude Dynamic Workflows (`/workflows`)