hook

Der Riegel: blockiert Dateiänderungen im Repo, solange kein eigener Task auf In Progress steht. Läuft als PreToolUse-Hook, liest das Hook-JSON von stdin und antwortet mit deny oder gar nicht.

Gezählt wird je Agenten-Sitzung. Wer seinen Task nicht selbst gestartet hat, kommt nicht durch, auch wenn nebenan ein anderer Agent an seinem Ticket arbeitet. Steht der eigene Task auf Testing oder On Hold, nennt die Ablehnung workban task start <nr>.

Was geprüft wird

• Edit, Write und das PowerShell-Tool unter Windows: das Ziel der Änderung.
• apply_patch von Codex: die Dateien aus den Zeilen *** Add File:, *** Update File:, *** Delete File: und *** Move to:. Ein Patch ohne solche Zeilen zählt wie eine Änderung im Verzeichnis, in dem er läuft.
• Bash: der Befehlstext auf Umleitungen in Dateien, sed -i, mv, cp, rm, git apply, Paketinstallationen und Skripte, die Dateien schreiben.
• Geprüft wird nur Code. Heredoc-Inhalte zählen nur, wenn ein Interpreter sie liest (python, node, bash …). Commit-Nachrichten, Beschreibungen per Heredoc und Zeichenketten in Anführungszeichen (Task-Titel, -m "…") werden vorher entfernt.

Was frei ist

• Ziele außerhalb des Repos: /tmp, /dev/null, $TMPDIR, ~/…, das Scratchpad. Relative Ziele löst der Riegel gegen das Arbeitsverzeichnis des Befehls und jedes cd darin auf, dazu ${VAR:-fallback}, $(mktemp …) und $(dirname …).
• Ein Skript (python open(…, "w"), node writeFileSync, Path(…).write_text), wenn jedes Schreibziel als absoluter Pfad außerhalb des Repos erkennbar ist. Relative Pfade oder unbekannte Variablen sperren.
• Branch-Arbeit wie git merge, rebase oder cherry-pick, sie integriert nur schon committete Änderungen.
• Ein Bash-Befehl, der vor dem ersten Schreibzugriff selbst workban task start, claim oder create --start aufruft.

Zwischenspeicher

Der Riegel merkt sich „ein Task läuft" 20 Sekunden lang je Repo und Instanz ($TMPDIR/workban/), damit nicht jeder Tool-Aufruf die API fragt. Eine Blockade wird nie gemerkt, und task start, claim, move und done vergessen den Eintrag sofort. So schließt ein Task auf Testing den Riegel ohne Verzögerung.

Läuft als SessionStart-Hook und gibt Projekt, laufende Tasks und Backlog auf stdout aus. Claude Code liest das als Kontext für die Sitzung.

Danach hält der Hook Repo und CLI aktuell (Automatisches Update): Entsprechen Regel, Skill oder Hooks im Repo nicht dem Stand der installierten CLI, schreibt er sie neu und nennt die geänderten Dateien, sofern die CLI mindestens die Version des Servers hat; sonst oder mit auto_update = false steht dort nur ein Hinweis. Kennt die CLI eine neuere Version, startet er workban update im Hintergrund (beim Binary) oder nennt sie (npm). Was davon er getan hat, steht im Kontext der Sitzung. Teile, die das Repo nie hatte (eingerichtet mit --no-agents), zählen nicht als veraltet. Eigene Tasks, die seit Tagen auf On Hold stehen, nennt der Hook in einem eigenen Block. Der kommt, wenn sich dort etwas ändert, sonst höchstens einmal in der Woche.

Läuft nach jeder Runde (Stop) und am Ende der Sitzung (SessionEnd). Liegt das Arbeitsverzeichnis in einem Repo mit .workban.toml, startet er workban usage report für die Sitzung im Hintergrund, mit dem Protokoll aus transcript_path, und endet sofort. Außerhalb eines Workban-Repos tut er nichts: Was dort geschieht, meldet Workban nicht. Der Eintrag endet mit || true, damit eine CLI, die den Hook noch nicht kennt, keine Fehlermeldung in jede Runde des Agenten trägt.

Läuft bei UserPromptSubmit (arbeitet), PermissionRequest (braucht Freigabe) und, nur bei Claude Code, StopFailure (abgebrochen). Er merkt sich den Zustand der Sitzung und meldet ihn im Hintergrund an Workban, aber nur, wenn er sich geändert hat; „arbeitet" außerdem alle fünf Minuten wieder. Das Board zeigt den Zustand auf der laufenden Karte, siehe Agent-Zustand. Der Riegel meldet ebenso „arbeitet", workban hook usage „wartet" nach jeder Runde und „beendet" am Ende der Sitzung. Bei PermissionRequest entscheidet der Hook nichts, die Rückfrage läuft wie ohne ihn.

Sendet den Zustand einer Sitzung an Workban, mit den Tasks, die sie gestartet hat; der Server nimmt davon den laufenden. Die Hooks starten den Befehl im Hintergrund, von Hand braucht ihn niemand. Ohne Anmeldung oder außerhalb eines Workban-Repos tut er nichts.

In .codex/hooks.json rufen die Hooks --agent codex auf. Dann nennt die Ablehnung workban task start <nr> --agent codex, und der Session-Hook verweist auf den Abschnitt in AGENTS.md statt auf die Regel für Claude Code. Der Riegel greift auf apply_patch und Bash.

Codex führt Hooks aus dem Repo erst aus, wenn du sie freigegeben hast: beim nächsten Start unter „Hooks need review“, später mit /hooks. Ändert sich ein Eintrag, fragt Codex erneut, und bis dahin läuft kein Riegel. workban doctor zeigt, ob die Freigabe da ist. Einzelheiten: Hooks für Codex.