feat(kvb-org-radio): split radio and post, add kvb-org-update

The radio (call, broadcast, security, pan-pan, mayday) reaches its addressee at the next tool step and wakes it. The post (post with --to, newsletter without, call receipts) arrives through a new Stop hook when the turn ends and never wakes. Legacy rows map onto the two channels and send direct stays as an alias. A PreToolUse hook holds the mayday's radio silence for writing tools and Bash. Only the sender, helpers who join with radio.py assist, bare radio.py calls and the config's allowed commands pass, and any shell operator or parse error blocks. kvb-org-update announces changed skills as one newsletter. Callers moved to send call --to.

🎯 Fix: 90 %
💥 Break: 5 %
💸 Cost: 104 %
⏱️ Time: 100 %
🛡️ Security: 100 %
💰 Value: ?
🏆 Score: 82
🚦 Gate: ⚠️ cost 104 % > 100: ask the operator before the commit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-06 18:08:10 +00:00
1 parent 5cb5da81ec
commit 367fe56dd4
21 files changed
+882 -257

No files matched your search

+34
View File
@@ -0,0 +1,34 @@
---
name: kvb-org-update
description: >
Tell every agent which skills changed, as one newsletter. Run after
installing skills.
---
Agents keep the skill text they read earlier in their context and go on using
it. `${CLAUDE_SKILL_DIR}/scripts/update.py` sends one newsletter through the
`kvb-org-radio` skill that names each changed skill with its latest commit
subjects and tells every agent to re-read that `SKILL.md` before its next use.
```bash
update.py --repo <skills repo> [--since <rev>] [--dry-run] [--session <id>]
```
## Steps
1. After `make install` of the skills repository, run `update.py --repo
<skills repo> --dry-run` and check the text.
2. Run it without `--dry-run`. It sends the newsletter and records `HEAD` as
announced in the council directory, so the next run starts there; a run
without new skill commits sends nothing.
3. The first run on a host only records `HEAD`; pass `--since <rev>` to
announce from an older revision, for example the last released tag.
## Rules
- One newsletter per update, never a radio class: agents read it when their
turn ends, and the old commands stay valid as aliases until then.
- A change that breaks a running agent's command needs an alias in the
changed script first; this skill only tells, it never migrates.
- Other runtimes read the newsletter with `radio.py show`.
- Add `update.py` as a tool of your task in the `kvb-org-rasci` register.
+128
View File
@@ -0,0 +1,128 @@
#!/usr/bin/env python3
"""Tell every agent which skills changed and how to use them: one newsletter per update.
Environment:
AGENTS_COUNCIL_ROOT: council directory shared by every agent on the host;
/tmp/agents-council unless set. The last announced revision per
repository lives in <root>/skills-announced.json.
CLAUDE_CODE_SESSION_ID: the sending session, passed on to radio.py.
Args:
--repo <dir>: the skills repository whose skills/ changes are announced.
--since <rev>: announce from this revision instead of the last announced
one. Without either, the run only records HEAD as announced.
--dry-run: print the newsletter without sending or recording it.
--session <id>: the sending session for radio.py.
Exit codes:
0 sent, recorded or nothing new; 1 radio.py failed; 2 usage error or a
council directory others can write.
"""
from __future__ import annotations
import argparse
import functools
import importlib.util
import json
import os
import subprocess
import sys
from pathlib import Path
from types import ModuleType
ROOT = Path(os.environ.get("AGENTS_COUNCIL_ROOT", "/tmp/agents-council"))
ANNOUNCED = ROOT / "skills-announced.json"
SKILLS = Path(__file__).resolve().parents[2]
RADIO = SKILLS / "kvb-org-radio" / "scripts" / "radio.py"
ORGANIZE = SKILLS / "kvb-org-organize" / "scripts"
GIT = ("git", "-c", "maintenance.auto=false")
SUBJECTS = 3
@functools.cache
def organize(name: str) -> ModuleType:
spec = importlib.util.spec_from_file_location(f"kvb_update_{name}", ORGANIZE / f"{name}.py")
module = importlib.util.module_from_spec(spec)
spec.loader.exec_module(module)
return module
def git(repo: Path, *args: str) -> str:
return subprocess.run([*GIT, *args], cwd=repo, capture_output=True, text=True, check=True).stdout
def revision(repo: Path, rev: str) -> str:
try:
return git(repo, "rev-parse", "--verify", "--quiet", f"{rev}^{{commit}}").strip()
except subprocess.CalledProcessError:
print(f"update: {rev} is no commit of {repo}; pass --since <rev>", file=sys.stderr)
sys.exit(2)
def marks() -> dict:
try:
data = json.loads(organize("nofollow").read_text(ROOT, ANNOUNCED))
except (OSError, ValueError):
return {}
return data if isinstance(data, dict) else {}
def record(repo: Path, head: str) -> None:
organize("nofollow").replace(ROOT, ANNOUNCED, json.dumps({**marks(), str(repo): head}), 0o600)
def changes(repo: Path, base: str) -> dict[str, list[str]]:
paths = git(repo, "diff", "--name-only", f"{base}..HEAD", "--", "skills/").splitlines()
names = sorted({Path(path).parts[1] for path in paths if len(Path(path).parts) > 2})
return {name: git(repo, "log", "--format=%s", f"{base}..HEAD", "--", f"skills/{name}").splitlines() for name in names}
def summary(repo: Path, name: str, subjects: list[str]) -> str:
if not (repo / "skills" / name).is_dir():
return f"{name} (removed)"
more = [f"+{len(subjects) - SUBJECTS} more"] if len(subjects) > SUBJECTS else []
return f"{name} ({'; '.join(subjects[:SUBJECTS] + more)})"
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("--repo", type=Path, required=True)
parser.add_argument("--since")
parser.add_argument("--dry-run", action="store_true")
parser.add_argument("--session")
args = parser.parse_args()
refused = organize("watch").guard_root(hook=False)
if refused is not None:
return refused
repo = args.repo.resolve()
head = revision(repo, "HEAD")
base = revision(repo, args.since) if args.since else marks().get(str(repo))
if base is None:
if not args.dry_run:
record(repo, head)
print(f"recorded {head[:7]} as announced; nothing sent")
return 0
found = changes(repo, base)
if not found:
if not args.dry_run:
record(repo, head)
print("nothing new")
return 0
text = (
f"Skills updated {base[:7]}..{head[:7]}: "
f"{', '.join(summary(repo, name, subjects) for name, subjects in found.items())}. "
"Re-read each changed SKILL.md before its next use."
)
print(text)
if args.dry_run:
return 0
session = ["--session", args.session] if args.session else []
if subprocess.run([sys.executable, str(RADIO), "post", text, *session], check=False).returncode != 0:
return 1
record(repo, head)
return 0
if __name__ == "__main__":
sys.exit(main())