Files

T

m3tam3re 321a3f91b8 feat: explain-permissions v1.1.0 — kanonische Quelle im Sammel-Repos (az-fleet-imn)

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

2026-09-17 15:15:21 +02:00

explain-permissions.js

feat: explain-permissions v1.1.0 — kanonische Quelle im Sammel-Repos (az-fleet-imn)

2026-09-17 15:15:21 +02:00

README.md

feat: explain-permissions v1.1.0 — kanonische Quelle im Sammel-Repos (az-fleet-imn)

2026-09-17 15:15:21 +02:00

README.md

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 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:

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.
Schickt eine Desktop-Notification, wenn der Freigabe-Dialog erscheint — mit der deutschen Erklärung des Modells, Fallback: der Roh-Befehl.
Schreibt ein JSONL-Audit-Log: jeden Freigabe-Request (ask), die abgegebene Erklärung (ask.explained) und die Entscheidung (replied).
Erzwingt optional (Default: aus), dass Erklärungen VOR dem Call kommen — sonst wirft der Call einen Fehler.

Installation

Lokale Kiste (Checkout + Symlink)

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

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.