m3ta-chiron
cbc1cb739f
Plugin.define({id: "az.explain-permissions", setup}) als Default-Export;
Hooks via ctx.permission.hook("evaluate"), ctx.session.hook("context"),
ctx.tool.hook("execute.before"); Event-Stream permission.v2.asked/replied;
Config-Lesung per fs mit V1+V2-Parser (JSONC-tolerant) statt hooks.config;
Action-Renames bash→shell/task→subagent, lsp/doom_loop verworfen.
KEIN V1-Export mehr (V2-only-Cut) — V1-Fleet bleibt gepinnt auf v1.3.0.
Verifikation: Mock-ctx-Tests 21/21 grün (Config-Parsing beider Formen,
System-Regel, evaluate/ask-Pfad, Hook↔Event-Dedup, replied, ENFORCE);
E2E vm-test folgt laut Issue.
185 lines
10 KiB
Markdown
185 lines
10 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. Seit v1.3.0
|
|
mit festem Ausgabeformat: Zitat-Block (`>`) mit fetten Labels, jeder Punkt
|
|
auf eigener Zeile. TUI und OpenCode Desktop rendern das als abgesetzten
|
|
Kasten mit farbigem Balken — die Erklärung hebt sich damit klar vom restlichen
|
|
Chatverlauf ab, und die drei Punkte bleiben sauber untereinander lesbar.
|
|
Desktop-Notifications bekommen reinen Text (Markdown-Marker werden entfernt).
|
|
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.
|
|
|
|
### opencode V2 (ab v2.0.0 — V2-only)
|
|
|
|
Die Datei exportiert `Plugin.define({id: "az.explain-permissions", setup})`
|
|
als Default-Export und wird in `opencode.json(c)` unter dem V2-Schlüssel
|
|
`plugins` referenziert (Einzel-Datei-Eintrag, absolute `file:///`-URL):
|
|
|
|
```jsonc
|
|
{
|
|
"plugins": [{ "package": "file:///C:/ProgramData/opencode/plugins/explain-permissions.js" }]
|
|
}
|
|
```
|
|
|
|
Alternativ läuft die Datei auch unverändert als Datei-Plugin in
|
|
`~/.config/opencode/plugins/` bzw. `.opencode/plugins/` (dort wird sie
|
|
automatisch entdeckt, kein Config-Eintrag nötig). Benötigt opencode V2
|
|
(Core 2.0.x); V1 (1.18.x) lädt sie bewusst NICHT (V2-only-Cut) — die V1-Fleet
|
|
bleibt auf der gepinnten v1.3.0.
|
|
|
|
### Fleet
|
|
|
|
Pin auf ein Tag (z. B. `explain-permissions/v2.0.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.
|
|
Unter V2 gilt zusätzlich: Der Background-Service besitzt und cachet die
|
|
Konfiguration — Config-/Plugin-Änderungen wirken erst nach
|
|
`opencode service restart`; Änderungen an beobachteten Plugin-Verzeichnissen
|
|
laden automatisch neu.
|
|
|
|
## V2-Migrationsmappe (v2.0.0, az-fleet-7x8)
|
|
|
|
| V1 (1.18.x) | V2 (2.0.x) |
|
|
|---|---|
|
|
| `export const ExplainPermissionsPlugin = async ({client}) => …` (Hooks-Objekt) | `export default Plugin.define({id: "az.explain-permissions", async setup(ctx)})`, Hooks via `ctx.*.hook()` registriert |
|
|
| Config-Schlüssel `"plugin": ["file:///…"]` | `"plugins": [{"package": "file:///…"}]` (Einzel-Datei-Einträge unterstützt) |
|
|
| `hooks.config` (liest permission-Sektion) | entfallen — Config-Dateien direkt per `fs` gelesen (Managed-Verzeichnis, Global, Projekt, `OPENCODE_CONFIG`), **beide** Formate: V1-`permission`-Map + V2-`permissions`-Array; Action-Renames bash→shell, task→subagent, write/patch→edit; `lsp`/`doom_loop` sind in V2 tote Actions und werden verworfen |
|
|
| `permission.ask`-Hook + `permission.asked/updated`-Events | `ctx.permission.hook("evaluate")` — feuert für allow UND ask nach Regel-Evaluation, vor Dialog/Ausführung (explizites deny ruft den Hook nicht); Effect `ask` → `recordAsk` + `explainAndNotify` |
|
|
| `permission.replied`-Event | `permission.v2.replied` im öffentlichen Event-Stream (`ctx.event.subscribe`), Payload `{sessionID, requestID, reply}` |
|
|
| `experimental.chat.system.transform` | `ctx.session.hook("context")` → `event.system.push({type: "text", text})` — Agent-Loop inkl. Tool-Continuations |
|
|
| `tool.execute.before` (ENFORCE) | `ctx.tool.hook("execute.before")` — Event `{tool, sessionID, callID, input}` |
|
|
| `client.session.messages({path:{id}})` | `ctx.session.context({sessionID})` — Tool-Parts tragen die Call-ID als `id` (matcht `source.id` der Permission-Evaluation) |
|
|
| `plugin-loaded`-Audit-Eintrag beim Laden | in `setup()` (jetzt mit Plugin-ID, opencode-Version, Location) |
|
|
|
|
Unverändert übernommen: Notification-Logik je Plattform (PowerShell-WinRT-AUMID,
|
|
injektionssicher), JSONL-Audit-Log samt Env-Flags, fail-soft-Muster, das
|
|
Erklär-Format (Zitat-Block) und die ENFORCE-Semantik (greift nur auf Calls,
|
|
die durch einen Freigabe-Dialog gegangen sind).
|
|
|
|
Der `@opencode/plugin`-Import ist bewusst dynamisch mit Fallback auf die
|
|
Rohestform `{id, setup}`: Schlägt die Paketauflösung fehl (Einzel-Datei-Package
|
|
außerhalb eines npm-Kontexts), bleibt der Fleet-Load fail-soft und das Plugin
|
|
trotzdem aktiv, statt beim Laden der ganzen Datei zu werfen.
|
|
|
|
## Versionierung
|
|
|
|
- `explain-permissions/v2.0.0` — V2-only-Port auf die V2-Plugin-API (Core
|
|
2.0.x, az-fleet-7x8): `Plugin.define`-Default-Export, Hooks via
|
|
`ctx.permission.hook("evaluate")` / `ctx.session.hook("context")` /
|
|
`ctx.tool.hook("execute.before")`, Event-Stream `permission.v2.asked` /
|
|
`permission.v2.replied`, Config-Lesung per `fs` mit V1+V2-Parser
|
|
(JSONC-tolerant) statt `hooks.config`, Action-Namen auf V2
|
|
(bash→shell, task→subagent; lsp/doom_loop verworfen). KEIN V1-Export mehr
|
|
(V2-only-Cut, Entscheidung 25.09.) — V1-Fleet bleibt gepinnt auf v1.3.0.
|
|
Verifikation: Mock-ctx-Tests 21/21 grün (Config-Parsing beider Formen,
|
|
System-Regel-Injektion, evaluate/ask-Pfad, Hook↔Event-Dedup, replied-Audit,
|
|
ENFORCE); E2E auf vm-test laut Issue az-fleet-7x8.
|
|
- `explain-permissions/v1.3.0` — Erklärungs-Format überarbeitet: Zitat-Block
|
|
(`>`) mit fetten Labels (`**WAS passiert:**` usw.), jeder Punkt auf eigener
|
|
Zeile — bessere Lesbarkeit und visuelle Hervorhebung in TUI und Desktop
|
|
(beide rendern Blockquotes mit farbigem Balken; verifiziert gegen opencode
|
|
1.18.30, das keinen Anzeige-Transform-Hook bietet — `experimental.chat.messages.transform`
|
|
wirkt nur modellseitig). Desktop-Notifications erhalten reinen Text ohne
|
|
Markdown-Marker; `EXPLAIN_FIRST_ERROR` verweist auf das neue Format.
|
|
- `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.
|