m3tam3re
321a3f91b8
Erstes Plugin im neuen Sammel-Repos opencode-plugins: Baseline-Import der Solo-Datei von der lokalen Linux-Kiste (SHA-256-verifiziert identisch) plus README mit Zweck, Env-Variablen, Audit-Log-Anzeige und Neustart-Hinweis. Repo-Struktur: ein Ordner pro Plugin, pro-Plugin-Tags <name>/v<version>.
84 lines
3.5 KiB
Markdown
84 lines
3.5 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 | `~/.local/state/opencode/explain-permissions.jsonl` |
|
|
|
|
## Audit-Log ansehen
|
|
|
|
```bash
|
|
tail -f ~/.local/state/opencode/explain-permissions.jsonl | jq .
|
|
```
|
|
|
|
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.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.
|