# 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.