From 25fb62abe6324dd06b87c778b8850b18eaf10b97 Mon Sep 17 00:00:00 2001
From: viettranx <viettranx@gmail.com>
Date: Fri, 24 Apr 2026 21:04:53 +0700
Subject: [PATCH] docs: document shellDenyGroups runtime config and 2026-04-24
 changelog

- docs/03-tools-system.md: new "Shell Deny-Groups (Runtime Config)"
  section covering the merge precedence (per-agent context wins per-key
  over global), live-reload via TopicConfigChanged, and the full registry
  of 15 deny-group classes from internal/tools/shell_deny_groups.go.
- docs/project-changelog.md: add 2026-04-24 entry for the three commits
  (shellDenyGroups feature, credential wording fix, read_audio routing fix).
---
 docs/03-tools-system.md   | 32 ++++++++++++++++++++++++++++++++
 docs/project-changelog.md | 21 +++++++++++++++++++++
 2 files changed, 53 insertions(+)

diff --git a/docs/03-tools-system.md b/docs/03-tools-system.md
index 7f11ab60..ea7a5d2d 100644
--- a/docs/03-tools-system.md
+++ b/docs/03-tools-system.md
@@ -396,6 +396,38 @@ Never put credentials in the settings JSON blob — backend does not validate th
 
 Current adopters: `web_search`, `web_fetch`, `tts`, `create_image`, `read_image`, `create_audio`, `read_audio`, `knowledge_graph_search`.
 
+### Shell Deny-Groups (Runtime Config)
+
+**Global shell deny-groups** are controlled via `config.tools.shellDenyGroups` (map[string]bool). Operators can toggle deny-group classes (e.g. `package_install`, `env_dump`) at runtime from the /config Web UI without restarting the gateway.
+
+**Merge semantics:**
+- Global config serves as base (`config.tools.shellDenyGroups`)
+- Per-agent overrides in `agents.other_config.shell_deny_groups` (if set)
+- Per-key: agent value takes precedence over global value
+- Multi-tenant invariant: each tenant's config is isolated
+
+**Live reload:** Changes to `config.tools.shellDenyGroups` propagate via `bus.TopicConfigChanged` pub/sub. Next agent turn automatically applies new toggles.
+
+**Deny-group classes** (from `internal/tools/shell_deny_groups.go` — all denied by default):
+
+| Class | Blocks |
+|---|---|
+| `destructive_ops` | rm -rf, dd, mkfs, shutdown, fork bombs |
+| `data_exfiltration` | curl/wget piped to shell, curl POST, DNS tools, /dev/tcp |
+| `reverse_shell` | nc, bash -i, sh -i, reverse-shell payloads |
+| `code_injection` | eval/exec on untrusted input, dynamic code loaders |
+| `privilege_escalation` | sudo, su, setuid abuse |
+| `dangerous_paths` | writes to /etc, /root, system dirs |
+| `env_injection` | export of sensitive env, LD_PRELOAD tricks |
+| `container_escape` | mount, nsenter, capability changes |
+| `crypto_mining` | xmrig and other miners |
+| `filter_bypass` | encoding/quoting tricks to evade pattern matching |
+| `network_recon` | nmap, masscan and similar scanners |
+| `package_install` | apt, yum, brew, pip, npm install (separately routes to approval) |
+| `persistence` | cron edits, systemd unit writes, rc.local |
+| `process_control` | kill -9 of arbitrary PIDs, killall |
+| `env_dump` | env, printenv (full-environment dumps) |
+
 ---
 
 ## 10. MCP Integration
diff --git a/docs/project-changelog.md b/docs/project-changelog.md
index 36e559d4..0d527788 100644
--- a/docs/project-changelog.md
+++ b/docs/project-changelog.md
@@ -4,6 +4,27 @@ Significant changes, features, and fixes in reverse chronological order.
 
 ---
 
+## 2026-04-24
+
+### Tools: Config-driven shell deny-groups + read_audio routing fixes
+
+**Features**
+
+- **`shellDenyGroups` runtime config:** `config.tools.shellDenyGroups` (map[string]bool) allows operators to toggle shell deny-groups (e.g. `package_install`, `env_dump`) from the /config Web UI without restarting. Merged with per-agent overrides with per-key agent precedence; multi-tenant invariant preserved. Subscribed to `bus.TopicConfigChanged` for live reload.
+
+**Fixes**
+
+- **Credentialed CLI wording scope:** "operation requires admin approval" error wording now scoped to `[CREDENTIALED EXEC]` marker only — was over-applied to generic shell failures, causing unjustified LLM pre-refusals.
+- **read_audio transcription routing:** Fixed silent fallback on missing API credentials for transcription/gemini/openai paths — now hard-errors with clear message. Fixed openai_compat providers (e.g. DashScope) not reaching `/v1/audio/transcriptions` endpoint; moved transcription model check above provider type switch.
+
+**Tests**
+
+- 6 unit tests for shell deny-groups merge/defensive-copy semantics.
+- 3 pub/sub dispatch tests for config reload lifecycle.
+- 3 regression tests for read_audio fail-fast paths.
+
+---
+
 ## 2026-04-22
 
 ### Providers: Native image generation for Codex + OpenAI-compat