Merge branch 'feature/council-state-deny' into unify/skills-20261112-night

README.md conflict with the queue-cleanup timer sentence resolved by keeping both: the unify paragraph plus the council deny sentence. install.sh auto-merged (queue-cleanup state dir, pycache prune, council-deny call), shellcheck clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-13 11:25:23 +00:00
commit 590b430d37
5 files changed
+111 -6

No files matched your search

+1 -1
View File
@@ -462,7 +462,7 @@ Copy the skills into a specific project (`<repo>/.agents/skills` and `<repo>/.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, and the `kvb-org-queue-cleanup.timer` and `kvb-org-queue-cleanup.path` user units, which start a `kvb-org-queue-cleanup` round at 00:00 and 12:00 local time without catch-up and whenever an agent runs `cleanup.py request`. 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, and the `kvb-org-queue-cleanup.timer` and `kvb-org-queue-cleanup.path` user units, which start a `kvb-org-queue-cleanup` round at 00:00 and 12:00 local time without catch-up and whenever an agent runs `cleanup.py request`. 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:<port>/`, 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.
+67
View File
@@ -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 <settings.json>");
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]));
+1 -3
View File
@@ -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"));
+3
View File
@@ -62,6 +62,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
+39 -2
View File
@@ -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"):