m3ta-chiron
53b3eb651b
- notify() mit Plattform-Zweigen: Linux notify-send (unverändert), macOS osascript, Windows PowerShell-Toast via WinRT + PowerShell-AUMID (keine App-Registrierung nötig); Titel/Text über env des Child-Prozesses (injektionssicher), XML-Escape via SecurityElement - fail-soft Spawn in Node UND Bun (try/catch + error-Listener decken beide ENOENT-Semantiken ab) — fehlendes Binary/headless = stiller No-Op - Log-Pfad-Entscheidung: Windows %LOCALAPPDATA%\opencode\ (idiomatisch, roamt nicht, Fallback ~\AppData\Local), sonst XDG-State unverändert; dokumentiert im README - Live verifiziert: Linux permission.asked -> ask/ask.explained/replied im Audit-Log + Toast; Fail-Soft win32/darwin-Zweige in node+bun ohne Crash
116 lines
5.3 KiB
Markdown
116 lines
5.3 KiB
Markdown
# explain-permissions — opencode-Plugin für laienverständliche Tool-Call-Erklärungen
|
|
|
|
Dieses Verzeichnis ist die **kanonische Quelle** für das opencode-Plugin
|
|
`explain-permissions`. Es lebt im Sammel-Repos
|
|
[`opencode-plugins`](../README.md) und besteht aus genau einer Plugin-Datei
|
|
(`explain-permissions.js`) plus dieser Doku. Wer das Plugin nutzt, bezieht es
|
|
von hier — es gibt bewusst keine zweiten Solo-Kopien.
|
|
|
|
Konsumenten:
|
|
|
|
| Konsument | Bezug |
|
|
|---|---|
|
|
| Lokale Linux-Kiste (m3tam3re) | Repo-Checkout + Symlink in `~/.config/opencode/plugins/` |
|
|
| Fleet (`az-fleet`) | später per Repo-Pin (anonym lesbar, kein Token für Pulls) |
|
|
|
|
## Zweck
|
|
|
|
Jeden berechtigungspflichtigen Tool-Call laienverständlich erklären — für
|
|
Menschen ohne Computer-Kenntnisse. Das Plugin:
|
|
|
|
1. **Injiziert die Freigabe-Regel in den System-Prompt** (Was / Welche Folgen /
|
|
Wie riskant, auf Deutsch, vor jedem freigabepflichtigen Call) — inklusive
|
|
der konkreten ask-/allow-Muster aus der opencode-Konfiguration.
|
|
2. **Schickt eine Desktop-Notification**, wenn der Freigabe-Dialog erscheint —
|
|
mit der deutschen Erklärung des Modells, Fallback: der Roh-Befehl.
|
|
3. **Schreibt ein JSONL-Audit-Log**: jeden Freigabe-Request (`ask`), die
|
|
abgegebene Erklärung (`ask.explained`) und die Entscheidung (`replied`).
|
|
4. **Erzwingt optional** (Default: aus), dass Erklärungen VOR dem Call kommen
|
|
— sonst wirft der Call einen Fehler.
|
|
|
|
## Installation
|
|
|
|
### Lokale Kiste (Checkout + Symlink)
|
|
|
|
```bash
|
|
git clone https://git.az-gruppe.com/AZ-Intec-GmbH/opencode-plugins.git ~/p/AZ/opencode-plugins
|
|
ln -sf ~/p/AZ/opencode-plugins/explain-permissions/explain-permissions.js ~/.config/opencode/plugins/explain-permissions.js
|
|
```
|
|
|
|
Danach opencode neu starten (siehe unten). Wichtig: nur EINE Datei dieses
|
|
Namens im Plugin-Ordner — sonst lädt opencode das Plugin doppelt.
|
|
|
|
### Fleet
|
|
|
|
Pin auf ein Tag (z. B. `explain-permissions/v1.1.0`) oder `main`; anonymes
|
|
`git clone` über HTTPS reicht, kein Token nötig.
|
|
|
|
## Konfiguration via Environment-Variablen
|
|
|
|
| Variable | Wirkung | Default |
|
|
|---|---|---|
|
|
| `OPENCODE_EXPLAIN_NOTIFY=0` | Desktop-Notifications abschalten | an |
|
|
| `OPENCODE_EXPLAIN_LOG=0` | Audit-Log abschalten | an |
|
|
| `OPENCODE_EXPLAIN_INJECT=0` | System-Prompt-Regel abschalten | an |
|
|
| `OPENCODE_EXPLAIN_ENFORCE=1` | Hartes Erzwingen der Erklärung aktivieren (Call ohne vorherige Erklärung → Fehler) | aus |
|
|
| `OPENCODE_EXPLAIN_DEBUG=1` | Permission-Events ins Log schreiben | aus |
|
|
| `OPENCODE_EXPLAIN_LOG_PATH=…` | Anderer Log-Pfad | plattformabhängig (siehe unten) |
|
|
|
|
## Notifications je Plattform (v1.2.0)
|
|
|
|
| Plattform | Mechanismus | Anmerkung |
|
|
|---|---|---|
|
|
| Linux | `notify-send` (libnotify) | wie bisher |
|
|
| macOS | `osascript display notification` | Boardmittel, keine Abhängigkeit |
|
|
| Windows | PowerShell-Toast (WinRT) via `-EncodedCommand` | AppUserModelID = PowerShell-AUMID — **keine App-Registrierung nötig**; Titel/Text laufen über env-Variablen des Child-Prozesses (injektionssicher), XML-Escaping in PowerShell |
|
|
|
|
Alle Zweige sind **fail-soft**: fehlendes Binary, headless Session oder
|
|
Spawn-Fehler sind stille No-Ops — kein Crash, kein Log-Müll. Node und Bun
|
|
behandeln ENOENT beim Spawn unterschiedlich (asynchrones `error`-Event vs.
|
|
synchroner Wurf); das Plugin deckt beide Semantiken ab (try/catch plus
|
|
error-Listener) und läuft damit in beiden Runtime-Welten.
|
|
|
|
## Log-Pfad-Entscheidung (v1.2.0)
|
|
|
|
| Plattform | Default-Pfad | Begründung |
|
|
|---|---|---|
|
|
| Windows | `%LOCALAPPDATA%\opencode\explain-permissions.jsonl` | idiomatisch, roamt nicht, liegt neben anderen App-States; Fallback `~\AppData\Local\…`, falls `LOCALAPPDATA` nicht gesetzt |
|
|
| Linux/macOS | `~/.local/state/opencode/explain-permissions.jsonl` | XDG-State-Konvention (unverändert seit v1.1.0) |
|
|
|
|
`~/.local/state` würde zwar überall funktionieren (auch auf Windows), aber
|
|
`%LOCALAPPDATA%` ist auf Windows der etablierte Ort für pro-Nutzer-State —
|
|
Pilotnutzer-Support findet Dateien dort, wo Windows sie erwartet.
|
|
|
|
## Audit-Log ansehen
|
|
|
|
```bash
|
|
# Linux/macOS
|
|
tail -f ~/.local/state/opencode/explain-permissions.jsonl | jq .
|
|
# Windows (PowerShell)
|
|
Get-Content "$env:LOCALAPPDATA\opencode\explain-permissions.jsonl" -Wait
|
|
```
|
|
|
|
Relevante Events:
|
|
|
|
- `plugin-loaded` — mit `version`: welche Plugin-Version wann geladen wurde
|
|
- `ask` — Freigabe-Request (Roh-Call, Muster, Session)
|
|
- `ask.explained` — die Erklärung, die das Modell vor dem Call abgegeben hat
|
|
- `replied` — die Entscheidung (`once` / `always` / `reject`)
|
|
|
|
## Wichtig: Neustart
|
|
|
|
**Plugin-Änderungen greifen erst nach Neustart von opencode** — eine neue
|
|
Chat-Session im laufenden Prozess reicht nicht. Der Audit-Log-Eintrag
|
|
`plugin-loaded` (mit Version) zeigt an, welche Version wann geladen wurde.
|
|
|
|
## Versionierung
|
|
|
|
- `explain-permissions/v1.2.0` — Cross-Platform-Notifications (Linux
|
|
notify-send / macOS osascript / Windows PowerShell-Toast mit PowerShell-AUMID,
|
|
keine App-Registrierung), fail-soft Spawn in Node- und Bun-Runtimes,
|
|
Windows-Log-Pfad `%LOCALAPPDATA%\opencode\` (Entscheidung siehe oben).
|
|
- `explain-permissions/v1.1.0` — Baseline, exakt der Stand der lokalen
|
|
Solo-Datei vom 17.09.2026 (Inhaltsgleichheit per SHA-256 verifiziert).
|
|
- Fortlaufende Versionsnummer in `PLUGIN_VERSION` im Dateikopf; Änderungen
|
|
bekommen ein Tag `explain-permissions/v<version>` in diesem Repo.
|