Abgleich mit dem Vault-Stand 7f484f9

38 Datei(en) geändert.
Erzeugt von .vault-tools/auto-push/werkzeuge_spiegel.py.

.vault-tools/shell-wache/docs/code/shell_wache.md

@@ -0,0 +1,50 @@
+---
+type: resource
+title: "shell_wache.py"
+status: active
+summary: "Codedoku zum PreToolUse-Hook, der im Befehl des Bash-Werkzeugs vier Windows-Shell-Fallen erkennt und einen Hinweis in den Kontext gibt, ohne je abzulehnen."
+tags: [vault-tools, codedoku]
+created: 2026-10-30
+updated: 2026-10-30
+---
+
+Werkzeug: [ENTWURF.md](../../ENTWURF.md)
+
+# shell_wache.py
+
+## Wofür
+
+- Warnt vor `python -I` ohne `-X utf8`, `python3`, `bash` ohne Pfad aus cmd, PowerShell oder Python und `pkill -f`, bevor das Bash-Werkzeug den Befehl ausführt.
+
+## Ablauf
+
+1. Claude Code startet das Skript vor jedem Aufruf des Bash-Werkzeugs, eingetragen in `.claude/settings.json` unter `PreToolUse`, Matcher `Bash`, als `python -I -X utf8`, Zeitlimit 10 s.
+2. `lies_eingabe()` liest stdin als Bytes und holt `tool_input.command`. Kaputte Eingabe ergibt den Grund für `[eingabe]`, ein leerer Befehl bleibt still.
+3. Die vier Detektoren in `DETEKTOREN` laufen je in eigenem `try`. Ein Absturz darin wird `[intern]`, die übrigen laufen weiter.
+4. `baue_text()` setzt Kopfzeile und je getroffenem Schlüssel eine Zeile aus `HINWEISE` zusammen.
+5. `melde()` schreibt genau ein JSON-Objekt mit `hookSpecificOutput.additionalContext`. Ohne Befund schreibt das Skript nichts.
+6. Das Skript endet immer mit Exit 0.
+
+```bash
+# Regressionstreiber: Grundlinie, dann alle Fälle, je Fall ein eigener Prozess
+python -I -X utf8 .vault-tools/shell-wache/faelle_shell_wache.py
+# Gegen eine mutierte Kopie: Pfad zum Hook als erstes Argument
+python -I -X utf8 .vault-tools/shell-wache/faelle_shell_wache.py /pfad/zur/kopie/shell_wache.py
+```
+
+## Annahmen
+
+- Claude Code liefert die Hook-Eingabe als JSON mit `tool_name` und `tool_input.command`. Belegt am 2026-10-30 in einer frischen Sitzung mit Claude Code 2.1.309: Im Transkript stehen `hook_success` und `hook_additional_context` für `PreToolUse:Bash`.
+- `additionalContext` bei PreToolUse erreicht das Modell. Belegt in derselben Probe: Das Modell gab den Hinweis wörtlich wieder.
+- Das Bash-Werkzeug ist die Git-Bash. Ein `bash` auf oberster Ebene ist dort `/usr/bin/bash` (`type -a bash`, 2026-10-30) und bleibt still.
+- Eine geänderte `settings.json` wirkt in laufenden Sitzungen sofort. Am 2026-10-30 schlug der Hook in der Sitzung, die ihn eingetragen hat, beim nächsten Bash-Aufruf an.
+
+## Was beim Anfassen weh tut
+
+- **Nie Exit 2 und nie `permissionDecision`.** Exit 2 lehnt den Befehl ab, `allow` überspringt die Berechtigungsabfrage. Beides fängt der Treiber, die letzte Schranke in `__main__` hält Exit 0 auch bei Absturz.
+- **Keine Importe aus dem eigenen Ordner.** `python -I` nimmt den Skriptordner aus `sys.path`.
+- **Erwähnungen schlagen an.** Ein Befehl, der `pkill -f` nur als Text enthält, löst den Hinweis aus. Das ist eine benannte Lücke, kein Fehler. Wer sie schließen will, braucht eine Shell-Grammatik, keinen weiteren regulären Ausdruck.
+- **Die Linux-Weiche gilt für den ganzen Befehl.** Wer sie auf Zeilen einschränkt, macht `ssh h python - <<'EOF'` mit `["bash"` im Heredoc laut.
+- **Zwei Mutanten sind wirkungslos:** `-c` nicht als Ende der Python-Optionen zu werten und einen leeren Befehl an die Detektoren zu geben. In beiden Fällen ändert sich keine Ausgabe, deshalb fängt sie kein Fall.
+- **Ein neues Muster braucht einen Treffer- und einen Gegenfall im Treiber, je am Anfang und am Ende des Befehls,** und einen Rotlauf mit gelöschtem Detektor.
+- **Probe-Eingaben mit Backslash legst du mit dem Write-Werkzeug an.** Ein `printf` mit `\\` in einem Bash-Aufruf kam am 2026-10-30 als einzelnes `\` an, und der Hook meldete richtig „kein JSON“.