From c17ac79258962f57d47521040d97545ad8ad5ca7 Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Fri, 13 Nov 2026 11:22:49 +0000 Subject: [PATCH] feat(install): deny Edit and Write on the council config and state in every session MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New scripts/council-deny.js holds the deny rules (SPOT) for ~/.claude/agents-council/** and, new, ~/.local/state/agents-council/**, where the skills' scripts keep state only they may change. enable-plugins.js takes them from it for /.claude/settings.local.json as before. The global install now also merges them into ~/.claude/settings.json, the only user-wide settings file, because a settings.local.json binds only sessions rooted in its own repository; the operator no longer edits settings by hand. The writer follows a settings symlink (dangling included), keeps the file mode, writes a 0600 wx temp file and renames it, and refuses invalid JSON or a non-object with exit 1 and the file untouched. Tests: tests/test_dream.py 26 passed (denies once beside existing rules, user settings kept through a symlink with mode, dangling link kept, invalid JSON untouched with exit 1); two independent reviews, round 2 holds. 🎯 Fix: 93 % 💥 Break: 3 % 💸 Cost: 100 % ⏱️ Time: 100 % 🛡️ Security: 100 % 🏆 Score: 90 🚦 Gate: ✅ 90/5, cost and time <= 100, security 100 % Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- scripts/council-deny.js | 67 +++++++++++++++++++++++++++++++++++++++ scripts/enable-plugins.js | 4 +-- scripts/install.sh | 3 ++ tests/test_dream.py | 41 ++++++++++++++++++++++-- 5 files changed, 111 insertions(+), 6 deletions(-) create mode 100644 scripts/council-deny.js diff --git a/README.md b/README.md index 68a2638..339f3be 100644 --- a/README.md +++ b/README.md @@ -454,7 +454,7 @@ Copy the skills into a specific project (`/.agents/skills` and `/.cl make project TARGET=/path/to/repo ``` -Both commands also patch the target's `.claude/settings.local.json` — the machine-local, untracked file, so a project's reviewed `.claude/settings.json` is never rewritten by an install: the caveman and ponytail plugins are enabled so their modes auto-activate on session start, and two reminder hooks are registered — `kvb-dream` points each agent at `/kvb-dream` at most once every twelve hours (stamped per session in `~/.claude/.dream-stamps/`), and `kvb-coach` runs its short form at the first prompt of every full hour, once across all agents (stamped in `~/.claude/.coach-hours/`); the global install also enables the `kvb-dream-notify.timer` systemd user timer, which recommends `/kvb-dream` in a GNOME notification daily at 17:00 local time and catches up once after a missed run. A PreToolUse gate from the `kvb-org-organize` skill blocks edits to files in a git worktree until the session holds a claim (`skills/kvb-org-organize/scripts/council.py`), and its resource watch (`skills/kvb-org-organize/scripts/watch.py`) measures disk, Docker and caches, cleans up low-risk data and blocks new heavy jobs before the disk runs out; it stays inactive until `~/.claude/agents-council/config.json` exists, and because its hooks run that config's commands outside the sandbox, the install adds `Edit(~/.claude/agents-council/**)` to `permissions.deny`, which also covers Write in every permission mode. The `kvb-org-radio` skill registers five hooks: its prompt hook and a PostToolBatch hook deliver the immediate radio (`call`, `broadcast`, `security`, `pan-pan`, `mayday`) mid-turn, a Stop hook delivers the post (`post`, `newsletter` and call receipts) when the turn ends, an `asyncRewake` Stop hook wakes an idle session for the radio, and a PreToolUse hook refuses every writing action while a mayday holds, except those of its sender and of the agents that join it with `radio.py assist`. The PreToolUse hook of the `kvb-org-queue` skill sends heavy commands through `queue.py hold` once the config sets `queue_enforce`, and holds a held command to the settings' Bash deny and ask rules, which see only `queue.py hold`. The global install also installs the MEDUSA security scanner with pipx for `kvb-check-security`, unless `medusa` is already on the PATH. Two hooks of the `kvb-org-perform` skill (`skills/kvb-org-perform/scripts/log.py`) log every Agent spawn with its task class, model and effort, and store the quality feedback a sandboxed session prints, in `~/.local/state/agents-council/subagent-model.jsonl`. Every hook runs `/usr/bin/python3 -I`, so neither the `python3` of a sandbox-writable virtualenv on the `PATH` nor `PYTHONPATH` reaches the hooks, which run outside the sandbox; older bare `python3` hook entries are rewritten. The reminder hooks run `/usr/bin/bash` and pin `PATH=/usr/bin:/bin`, and the council scripts keep only the `PATH` directories this uid cannot write (`skills/kvb-org-organize/scripts/hookpath.py`), so no binary an agent plants on the inherited `PATH` runs outside the sandbox. Existing settings are preserved. +Both commands also patch the target's `.claude/settings.local.json` — the machine-local, untracked file, so a project's reviewed `.claude/settings.json` is never rewritten by an install: the caveman and ponytail plugins are enabled so their modes auto-activate on session start, and two reminder hooks are registered — `kvb-dream` points each agent at `/kvb-dream` at most once every twelve hours (stamped per session in `~/.claude/.dream-stamps/`), and `kvb-coach` runs its short form at the first prompt of every full hour, once across all agents (stamped in `~/.claude/.coach-hours/`); the global install also enables the `kvb-dream-notify.timer` systemd user timer, which recommends `/kvb-dream` in a GNOME notification daily at 17:00 local time and catches up once after a missed run. A PreToolUse gate from the `kvb-org-organize` skill blocks edits to files in a git worktree until the session holds a claim (`skills/kvb-org-organize/scripts/council.py`), and its resource watch (`skills/kvb-org-organize/scripts/watch.py`) measures disk, Docker and caches, cleans up low-risk data and blocks new heavy jobs before the disk runs out; it stays inactive until `~/.claude/agents-council/config.json` exists, and because its hooks run that config's commands outside the sandbox, the install adds `Edit(~/.claude/agents-council/**)` to `permissions.deny`, which also covers Write in every permission mode; `Edit(~/.local/state/agents-council/**)` joins it, so the state the skills' scripts keep there changes only through those scripts. The global install writes both rules into `~/.claude/settings.json` too (`scripts/council-deny.js`), the only user-wide settings file, so they bind sessions in every repository. The `kvb-org-radio` skill registers five hooks: its prompt hook and a PostToolBatch hook deliver the immediate radio (`call`, `broadcast`, `security`, `pan-pan`, `mayday`) mid-turn, a Stop hook delivers the post (`post`, `newsletter` and call receipts) when the turn ends, an `asyncRewake` Stop hook wakes an idle session for the radio, and a PreToolUse hook refuses every writing action while a mayday holds, except those of its sender and of the agents that join it with `radio.py assist`. The PreToolUse hook of the `kvb-org-queue` skill sends heavy commands through `queue.py hold` once the config sets `queue_enforce`, and holds a held command to the settings' Bash deny and ask rules, which see only `queue.py hold`. The global install also installs the MEDUSA security scanner with pipx for `kvb-check-security`, unless `medusa` is already on the PATH. Two hooks of the `kvb-org-perform` skill (`skills/kvb-org-perform/scripts/log.py`) log every Agent spawn with its task class, model and effort, and store the quality feedback a sandboxed session prints, in `~/.local/state/agents-council/subagent-model.jsonl`. Every hook runs `/usr/bin/python3 -I`, so neither the `python3` of a sandbox-writable virtualenv on the `PATH` nor `PYTHONPATH` reaches the hooks, which run outside the sandbox; older bare `python3` hook entries are rewritten. The reminder hooks run `/usr/bin/bash` and pin `PATH=/usr/bin:/bin`, and the council scripts keep only the `PATH` directories this uid cannot write (`skills/kvb-org-organize/scripts/hookpath.py`), so no binary an agent plants on the inherited `PATH` runs outside the sandbox. Existing settings are preserved. The global install also runs the Agent Orchestrator, a local review page in which the operator approves or rejects the agents' staged commits (the `kvb-git-diff` skill): it copies `orchestrator/` to `~/.local/share/kvb-orchestrator`, starts it there with `docker compose up -d --build` (restart `unless-stopped`, bound to `127.0.0.1` only, state in `~/.local/state/kvb-orchestrator`) and registers its MCP server for Claude Code at user scope. Its port is `KVB_ORCHESTRATOR_PORT` in `orchestrator/.env`; the hub page is `http://localhost:/`, the MCP endpoint `/mcp`. Without docker the hub is skipped and the commit skills ask in chat. The hub reads new radio traffic aloud in maritime phraseology and takes push-to-talk input; its image builds both engines from pinned, sha256-verified sources and runs each as a separate process: Piper (`piper-tts`, GPL-3.0-or-later) with the `en_US-libritts-high` voice (904 speakers, trained on LibriTTS, CC BY 4.0, from `rhasspy/piper-voices`) and whisper.cpp (MIT) with the multilingual `ggml-base-q8_0` model (OpenAI Whisper weights, MIT, 82 MB). The operator's own voice is `KVB_ORCHESTRATOR_OPERATOR_VOICE` in `orchestrator/.env`. Its Tree reads only the file `pkgmgr branch tree` writes: the install clones `PKGMGR_REPO` (default the GitHub repository, never the sandbox-writable local checkout), builds the newest `v*` tag a fully trusted GPG key signed into `~/.local/share/kvb-orchestrator/pkgmgr`, and enables the `kvb-orchestrator-tree.timer` user timer, which writes `~/.local/state/pkgmgr/tree/branch-tree.json` a minute after its previous run while the hub page polls, on at most half a core; the hub mounts that directory read-only and starts no git. A signed tag without `branch tree` leaves the timer off. diff --git a/scripts/council-deny.js b/scripts/council-deny.js new file mode 100644 index 0000000..582b8fb --- /dev/null +++ b/scripts/council-deny.js @@ -0,0 +1,67 @@ +#!/usr/bin/env node +"use strict"; + +const fs = require("fs"); +const path = require("path"); + +const COUNCIL_DENY = ["Edit(~/.claude/agents-council/**)", "Edit(~/.local/state/agents-council/**)"]; + +function withCouncilDeny(data) { + data.permissions = data.permissions || {}; + data.permissions.deny = [...new Set([...(data.permissions.deny || []), ...COUNCIL_DENY])]; + return data; +} + +module.exports = { COUNCIL_DENY, withCouncilDeny }; + +function resolved(settingsPath) { + let link; + try { + link = fs.lstatSync(settingsPath).isSymbolicLink(); + } catch (err) { + if (err.code === "ENOENT") return settingsPath; + throw err; + } + if (!link) return settingsPath; + if (fs.existsSync(settingsPath)) return fs.realpathSync(settingsPath); + return path.resolve(path.dirname(settingsPath), fs.readlinkSync(settingsPath)); +} + +function main(settingsPath) { + if (!settingsPath) { + console.error("usage: council-deny.js "); + return 2; + } + const target = resolved(settingsPath); + let data = {}; + let mode = 0o600; + if (fs.existsSync(target)) { + mode = fs.statSync(target).mode & 0o777; + const raw = fs.readFileSync(target, "utf8").trim(); + if (raw) { + try { + data = JSON.parse(raw); + } catch (err) { + console.error(`skills: ${settingsPath} is not valid JSON; leaving it untouched (${err.message}).`); + return 1; + } + } + } + if (typeof data !== "object" || data === null || Array.isArray(data)) { + console.error(`skills: ${settingsPath} holds no JSON object; leaving it untouched.`); + return 1; + } + const temporary = `${target}.${process.pid}`; + try { + fs.writeFileSync(temporary, JSON.stringify(withCouncilDeny(data), null, 2) + "\n", { mode, flag: "wx" }); + fs.chmodSync(temporary, mode); + fs.renameSync(temporary, target); + } catch (err) { + fs.rmSync(temporary, { force: true }); + throw err; + } + console.log(`skills: Edit and Write on ${COUNCIL_DENY.length} council paths denied in ${settingsPath}`); + return 0; +} + +if (require.main === module) process.exit(main(process.argv[2])); diff --git a/scripts/enable-plugins.js b/scripts/enable-plugins.js index aa7b3d5..e2592ad 100644 --- a/scripts/enable-plugins.js +++ b/scripts/enable-plugins.js @@ -62,9 +62,7 @@ data.env = data.env || {}; if (!data.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW) data.env.CLAUDE_CODE_AUTO_COMPACT_WINDOW = "500000"; const PYTHON = "/usr/bin/python3 -I"; const ABSOLUTE = { python3: PYTHON, bash: "/usr/bin/bash" }; -const COUNCIL_CONFIG_DENY = "Edit(~/.claude/agents-council/**)"; -data.permissions = data.permissions || {}; -data.permissions.deny = [...new Set([...(data.permissions.deny || []), COUNCIL_CONFIG_DENY])]; +require("./council-deny").withCouncilDeny(data); const pluginRepos = new Set(Object.values(MARKETPLACES).map((entry) => entry.source.repo)); const lock = JSON.parse(fs.readFileSync(path.join(__dirname, "..", "skills-lock.json"), "utf8")); diff --git a/scripts/install.sh b/scripts/install.sh index 9e3db73..e2ac6bd 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -61,6 +61,9 @@ settings="${TARGET}/.claude/settings.local.json" if command -v node &>/dev/null; then log "skills: auto-enabling caveman + ponytail plugins in ${settings}" node "${REPO_ROOT}/scripts/enable-plugins.js" "${settings}" + if [[ "${TARGET}" -ef "${HOME}" ]]; then + node "${REPO_ROOT}/scripts/council-deny.js" "${HOME}/.claude/settings.json" + fi else warn "skills: node not found; skipped auto-enabling caveman/ponytail plugins." fi diff --git a/tests/test_dream.py b/tests/test_dream.py index 1ae4332..ae67ae5 100644 --- a/tests/test_dream.py +++ b/tests/test_dream.py @@ -17,6 +17,8 @@ NOTIFY = DREAM / "hooks" / "notify.sh" TIMER = DREAM / "systemd" / "kvb-dream-notify.timer" SERVICE = DREAM / "systemd" / "kvb-dream-notify.service" PATCHER = REPO_ROOT / "scripts" / "enable-plugins.js" +COUNCIL_DENY = REPO_ROOT / "scripts" / "council-deny.js" +DENIED = ["Edit(~/.claude/agents-council/**)", "Edit(~/.local/state/agents-council/**)"] class TestDreamSkill(unittest.TestCase): @@ -278,13 +280,48 @@ class TestSettingsRegistration(unittest.TestCase): with self.subTest(command=command): self.assertTrue(command.startswith("/usr/bin/bash ")) - def test_council_config_deny_is_added_once_next_to_existing_rules(self): + def test_council_config_and_state_denies_are_added_once_next_to_existing_rules(self): self.settings.write_text(json.dumps({"permissions": {"deny": ["Bash(rm -rf:*)"]}}), encoding="utf-8") self._patch() + self.assertEqual(self._patch()["permissions"]["deny"], ["Bash(rm -rf:*)", *DENIED]) + + def _deny(self, path: Path) -> subprocess.CompletedProcess: + return subprocess.run(["node", str(COUNCIL_DENY), str(path)], capture_output=True, text=True, check=False) + + def test_the_user_settings_get_the_council_denies_once_and_keep_everything_else(self): + real = Path(self.tmp.name) / "dotfiles" / "settings.json" + real.parent.mkdir() + real.write_text(json.dumps({"model": "opus", "permissions": {"deny": ["Bash(rm -rf:*)"], "ask": ["Bash(git push:*)"]}}), encoding="utf-8") + real.chmod(0o640) + self.settings.symlink_to(real) + for _ in range(2): + self.assertEqual(self._deny(self.settings).returncode, 0) + self.assertTrue(self.settings.is_symlink()) + self.assertEqual(real.stat().st_mode & 0o777, 0o640) self.assertEqual( - self._patch()["permissions"]["deny"], ["Bash(rm -rf:*)", "Edit(~/.claude/agents-council/**)"] + json.loads(real.read_text(encoding="utf-8")), + {"model": "opus", "permissions": {"deny": ["Bash(rm -rf:*)", *DENIED], "ask": ["Bash(git push:*)"]}}, ) + def test_a_dangling_settings_link_keeps_its_link_and_gets_its_file(self): + real = Path(self.tmp.name) / "dotfiles" / "settings.json" + real.parent.mkdir() + self.settings.symlink_to(real) + self.assertEqual(self._deny(self.settings).returncode, 0) + self.assertTrue(self.settings.is_symlink()) + self.assertEqual(real.stat().st_mode & 0o777, 0o600) + self.assertEqual(json.loads(real.read_text(encoding="utf-8")), {"permissions": {"deny": DENIED}}) + self.assertEqual(sorted(p.name for p in real.parent.iterdir()), ["settings.json"]) + + def test_user_settings_that_are_no_json_object_stay_untouched_and_fail_the_install(self): + for content in ("{not json", "[]"): + with self.subTest(content=content): + self.settings.write_text(content, encoding="utf-8") + done = self._deny(self.settings) + self.assertEqual(done.returncode, 1) + self.assertIn("leaving it untouched", done.stderr) + self.assertEqual(self.settings.read_text(encoding="utf-8"), content) + def test_plugin_skills_are_not_copied_twice(self): skills = Path(self.tmp.name) / "skills" for name in ("caveman", "ponytail-review", "cavecrew", "archify", "kvb-dream"):