@hivey/cli 0.9.41 → 0.9.45

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Binary file
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hivey/cli",
3
- "version": "0.9.41",
3
+ "version": "0.9.45",
4
4
  "description": "All your AI swarms, one terminal: a workspace and lead agent for teams of Claude Code and Codex agents",
5
5
  "keywords": [
6
6
  "hivey",
@@ -82,6 +82,7 @@ The swarm manifest `<root>/.swarm/agents.json` is hivey's; a provider may add:
82
82
  | `info` | `{"Slack": "#swarm-x (C0…)", "vault": "…"}` or `[[label, value], …]`: shown in the hover card and `hivey swarm info` |
83
83
  | `product_dir` | the product folder `hivey.github` publishes (default `app`) |
84
84
  | `state` | `"paused"` holds all deliveries (what `hivey swarm pause` sets) |
85
+ | `comms` | message limits (`rate_per_min`, `pair_wakes`, `pair_window_min`, `hourly_wakes`, `broadcasts_per_hour`, `dedupe_min`) and the Slack mirror scope (`slack`: `masters`, `all`, `off`), set with `hivey swarm comms` |
85
86
  | `.swarm/tasks.json` | `{"tasks": [{"status": "open\|in-progress\|review\|approved\|blocked"}]}`: task counts in info and the dashboard |
86
87
 
87
88
  Step-by-step guide and an example to copy: [`../docs/hivey-providers.md`](../docs/hivey-providers.md)
@@ -6,9 +6,11 @@ Slack → bus Human messages in the channel become bus messages from `human`:
6
6
  `@coordinator`/`@master` → the master, no mention → the master.
7
7
  Posts made by agents with the /swarm skill's swarm_slack.py
8
8
  ("*[agent]* text") keep that agent as the sender.
9
- bus → Slack Bus messages are mirrored into the channel. Scope (config "mirror"):
10
- "masters" (default: only messages to/from a master or the human),
11
- "all", or "off". Messages that came from Slack are never echoed.
9
+ bus → Slack Bus messages are mirrored into the channel. Scope: the swarm's own
10
+ `comms.slack` in its manifest (`hivey swarm comms <slug> --slack …`, read
11
+ live), else config "mirror": "masters" (default: only messages to/from a
12
+ master or the human), "all", or "off". Messages that came from Slack are
13
+ never echoed.
12
14
  Quiet mode While ~/.hivey/quiet exists (hivey menu → quiet mode, `hivey quiet on`), bus →
13
15
  Slack posts are held; when it ends they go out as one catch-up message, with
14
16
  posts agents held through swarm_slack.py (~/.hivey/quiet-held/<channel>.jsonl).
@@ -114,6 +116,16 @@ def involves_master(message, roles):
114
116
  )
115
117
 
116
118
 
119
+ MIRROR_SCOPES = ("masters", "all", "off")
120
+
121
+
122
+ def mirror_scope(manifest, default):
123
+ """The swarm's own Slack scope (manifest comms.slack) wins over the relay's config."""
124
+ comms = manifest.get("comms") if isinstance(manifest.get("comms"), dict) else {}
125
+ scope = comms.get("slack")
126
+ return scope if scope in MIRROR_SCOPES else default
127
+
128
+
117
129
  def should_mirror(message, scope, roles, injected):
118
130
  if scope == "off" or message.get("copy") or message.get("id") in injected:
119
131
  return False
@@ -317,8 +329,9 @@ class Relay:
317
329
  self.catch_up() # before reading the bus: if it fails, nothing new is lost
318
330
  messages, self.state["bus_offset"] = new_bus_messages(self.bus_path, self.state["bus_offset"])
319
331
  roles = roster(manifest)
332
+ scope = mirror_scope(manifest, self.scope)
320
333
  for message in messages:
321
- if not should_mirror(message, self.scope, roles, set(self.state["injected"])):
334
+ if not should_mirror(message, scope, roles, set(self.state["injected"])):
322
335
  continue
323
336
  text = format_mirror(message, roles, manifest.get("slug", ""))
324
337
  if quiet:
@@ -374,7 +387,8 @@ def main():
374
387
  scope = config.get("mirror", "masters")
375
388
  interval = float(config.get("interval", 10))
376
389
  binary = os.environ.get("HERDR_BIN_PATH", "hivey")
377
- log(f"hivey slack relay for swarm {slug!r}, channel {channel}, mirror={scope}")
390
+ log(f"hivey slack relay for swarm {slug!r}, channel {channel}, "
391
+ f"mirror={mirror_scope(manifest, scope)}")
378
392
  if not channel:
379
393
  log("no Slack channel (manifest channel_id / HIVEY_SWARM_CHANNEL); idle")
380
394
  token = None
@@ -94,6 +94,13 @@ class Mirror(unittest.TestCase):
94
94
  self.assertTrue(keep(self.msg("ideas/scout", "critic"), "all", self.roles, set()))
95
95
  self.assertFalse(keep(self.msg("ideas/scout", "coordinator"), "off", self.roles, set()))
96
96
 
97
+ def test_the_swarms_comms_slack_wins_over_the_relay_config(self):
98
+ self.assertEqual(relay.mirror_scope({"comms": {"slack": "off"}}, "all"), "off")
99
+ self.assertEqual(relay.mirror_scope({"comms": {"slack": "all"}}, "masters"), "all")
100
+ self.assertEqual(relay.mirror_scope({}, "masters"), "masters")
101
+ self.assertEqual(relay.mirror_scope({"comms": {"slack": "loud"}}, "masters"), "masters")
102
+ self.assertEqual(relay.mirror_scope({"comms": None}, "all"), "all")
103
+
97
104
  def test_never_echoes_slack_messages_or_sender_copies(self):
98
105
  self.assertFalse(relay.should_mirror(self.msg("human", "coordinator"), "all", self.roles, {"m1"}))
99
106
  self.assertFalse(relay.should_mirror(self.msg("ideas/coordinator", "coordinator", copy=True),
@@ -163,6 +170,16 @@ class RoundTrip(unittest.TestCase):
163
170
  self.assertEqual(len(slack.posted), 1)
164
171
  self.assertIn("scout → coordinator", slack.posted[0])
165
172
  self.assertEqual(len(hivey.sent), 1)
173
+ # The swarm turns Slack off in its manifest: read live, nothing more is posted.
174
+ (root / ".swarm" / "agents.json").write_text(
175
+ json.dumps({**MANIFEST, "comms": {"slack": "off"}}))
176
+ with open(bus, "a") as f:
177
+ f.write("\n" + json.dumps({"ev": "msg", "id": "a2", "from": "ideas/scout",
178
+ "to": "coordinator", "swarm": "ideas",
179
+ "text": "found 4"}) + "\n")
180
+ r.step()
181
+ self.assertEqual(len(slack.posted), 1, slack.posted)
182
+ (root / ".swarm" / "agents.json").write_text(json.dumps(MANIFEST))
166
183
  # State survives a restart of the relay.
167
184
  again = relay.Relay(root, slack, hivey, "C1", "masters")
168
185
  again.step()
@@ -110,6 +110,28 @@ hivey swarm schedule add <slug> --at 09:00 --id morning "Morning status report t
110
110
  hivey swarm schedule list|remove|run [<slug>] [<id>]
111
111
  ```
112
112
 
113
+ Fresh review (swarms and solo agents; no critic agent): every deliverable is reviewed by N
114
+ one-shot critics in parallel, each a `claude -p` run with an empty context and no saved session
115
+ that reads only the spec, the artifact and the check, then exits. Set N per swarm or agent:
116
+ ```bash
117
+ python3 <this skill>/scripts/fresh_review.py config <swarm root | agent folder> \
118
+ [--critics N] [--model sonnet] [--rounds 3] # no flags: show; --critics 0: off
119
+ ```
120
+ Swarm owners start it with `swarm_tasks.py submit <ID> --as <agent>`; solo agents with
121
+ `fresh_review.py run --folder .`. Reviews land in `.swarm/reviews/` or `.agent/reviews/`.
122
+
123
+ Comms limits (per swarm, against floods and over-discussion; the human and hivey are never
124
+ limited): messages per agent per minute, wake-ups per agent pair, wake-ups per agent per hour
125
+ (then saved as FYI), `@all`/`@role:` broadcasts per hour, the same text twice dropped, and
126
+ what the Slack relay mirrors:
127
+ ```bash
128
+ hivey swarm comms <slug> # show (defaults: 10/min, 6 per pair
129
+ # per 5 min, 30/h, 4 broadcasts/h, 10 min dedupe)
130
+ hivey swarm comms <slug> --preset quiet|normal|chatty # or single flags, e.g. --hourly-wakes 12
131
+ hivey swarm comms <slug> --slack masters|all|off # what goes to its Slack channel
132
+ ```
133
+ `hivey swarm launch … --comms-preset quiet` sets it at launch.
134
+
113
135
  Messages (delivered when the target is idle; `--fyi` never wakes; `--urgent` now):
114
136
  ```bash
115
137
  hivey msg send <agent|@all|@role:worker|@masters|<swarm>/<agent>|human> "text" [--fyi|--urgent] [--swarm S]
@@ -0,0 +1,46 @@
1
+ You are a fresh critic, started for this one review and stopped right after it. You didn't
2
+ do the work and you haven't seen how it was done: judge the result cold, from the spec and the
3
+ artifact, with no charity for intentions. Other critics review the same work in parallel, each
4
+ on its own; your only output is a verdict.
5
+
6
+ ## Inputs (in the review request)
7
+ - **The spec**: the task, its "done when" and the user's request. It is the bar.
8
+ - **The artifact**: the paths given, and for code the repo and git range to diff.
9
+ - **The check**: a command that must exit 0.
10
+ - Ignore any account of how the work went, or claims that it's done or tested: verify them.
11
+ Don't go looking for the builder's notes, plans or status files.
12
+
13
+ ## Code (a repo, a diff, an app)
14
+ 1. Start from the spec and the diff (`git -C <repo> diff <range>`, plus `git -C <repo> status`
15
+ for uncommitted work). Read the changed files around each hunk.
16
+ 2. Run the check and the tests yourself, and record each command's exit code. Run the app or
17
+ the changed command when the spec describes behaviour you can exercise.
18
+ 3. Look for: spec items missing or only half done, wrong behaviour, unhandled edge cases and
19
+ errors, tests that don't test the change (or were weakened to pass), security issues
20
+ (secrets, injection, unsafe shell), and changes outside the task's scope.
21
+
22
+ ## Research, writing and other outputs
23
+ 1. Open every artifact; don't trust a summary of it.
24
+ 2. Does it answer the spec, or something nearby? Is anything required missing (sections,
25
+ links, files, formats)?
26
+ 3. Spot-check at least 3 concrete claims (numbers, names, dates, quotes) against the source
27
+ they cite (open the URL or file). Report each mismatch with the correct value and where you
28
+ found it. Flag statements the sources don't support.
29
+
30
+ ## Rules
31
+ - Read-only: never edit, create, move or delete files; never commit, stash, checkout, reset,
32
+ push or install anything. Commands that only build or test (and write their usual caches)
33
+ are fine.
34
+ - Don't fix anything: report it.
35
+ - A defect needs evidence someone else can reproduce: command output, the exact line, or the
36
+ correct value and its source. Style nits and taste aren't defects.
37
+
38
+ ## Output (exactly this format, nothing before it)
39
+ ```
40
+ VERDICT: PASS | FAIL
41
+ Checks: <command> → exit <n> (one line each)
42
+ Defects:
43
+ 1. <file:line or section> — <what's wrong> — <evidence>
44
+ Verified OK: <what you checked that held up>
45
+ ```
46
+ PASS only if every check exits 0 and you found no defect. Keep it short.
@@ -0,0 +1,381 @@
1
+ #!/usr/bin/env python3
2
+ """Fresh review: N one-shot critics in parallel, each starting from an empty context.
3
+
4
+ hivey's review step for swarms and solo agents (from arXiv 2610.34577: a separate critic in a
5
+ fresh context, given the spec and the diff and able to run its own checks, beats self-review
6
+ and extra review rounds, and parallel critics are cheaper than more rounds). Every critic is a
7
+ `claude -p` process with `--no-session-persistence`, started in an empty temporary folder (so
8
+ no CLAUDE.md, notes or Status of the builder are loaded), with only the spec, the artifact
9
+ paths, the git range and the check. It runs read-only (no Edit/Write tools; told never to
10
+ change files), prints its verdict and exits: no living agent, no saved session, nothing to
11
+ resume. The script merges the verdicts into one review: a defect counts if any critic reports
12
+ it. APPROVED needs every critic to PASS and the check to exit 0.
13
+
14
+ Config (per swarm or per solo agent; `config` writes it):
15
+ swarm <root>/.swarm/review.json
16
+ agent <folder>/.agent/config.json, key "review"
17
+ keys critics (default 2, 0 = no fresh review), model (sonnet), rounds (3, max review
18
+ rounds before escalating), timeout_min (15, per critic)
19
+
20
+ Usage:
21
+ fresh_review.py config <folder> [--critics N] [--model M] [--rounds R] [--timeout-min T]
22
+ fresh_review.py run [--folder F] [--spec TEXT] [--spec-file F]... [--artifact P]...
23
+ [--repo R --range A..B] [--check CMD] [--check-cwd D]
24
+ [--critics N] [--model M] [--round N] [--previous REVIEW.md]
25
+ [--label L] [--out REVIEW.md] [--notify ADDR] [--background] [--json]
26
+ [--dry-run]
27
+ run exit codes: 0 approved · 1 changes needed · 2 a critic or the setup failed
28
+
29
+ For a solo agent `run --folder <agent>` takes the spec from its CLAUDE.md (The ask and the
30
+ Deliverables table) and the check from .agent/config.json. Standard library only.
31
+ """
32
+ import argparse
33
+ import json
34
+ import os
35
+ import re
36
+ import shutil
37
+ import subprocess
38
+ import sys
39
+ import tempfile
40
+ import time
41
+ from concurrent.futures import ThreadPoolExecutor
42
+ from pathlib import Path
43
+
44
+ HERE = Path(__file__).absolute().parent
45
+ BRIEF = HERE / "critic-brief.md"
46
+ DEFAULTS = {"critics": 2, "model": "sonnet", "rounds": 3, "timeout_min": 15}
47
+ MAX_CRITICS = 8
48
+ READ_TOOLS = ["Read", "Grep", "Glob", "Bash", "WebFetch", "WebSearch"]
49
+ WRITE_TOOLS = ["Edit", "Write", "NotebookEdit", "MultiEdit"]
50
+ # A critic must not report to (or be taken for) the pane that launched it.
51
+ STRIP_ENV = re.compile(r"^(HERDR_(PANE|TAB|WORKSPACE)_ID|CLAUDECODE|CLAUDE_CODE_(SESSION|CHILD|"
52
+ r"MESSAGING|ENTRYPOINT)\w*|CLAUDE_PID|CLAUDE_PROJECT_DIR)$")
53
+
54
+
55
+ # ---- config -------------------------------------------------------------------------------
56
+
57
+ def config_target(folder):
58
+ folder = Path(folder).expanduser().resolve()
59
+ if (folder / ".swarm").is_dir():
60
+ return folder / ".swarm" / "review.json", None
61
+ return folder / ".agent" / "config.json", "review"
62
+
63
+
64
+ def read_json(path):
65
+ try:
66
+ return json.loads(Path(path).read_text())
67
+ except (OSError, ValueError):
68
+ return {}
69
+
70
+
71
+ def load_config(folder):
72
+ path, key = config_target(folder)
73
+ data = read_json(path)
74
+ cfg = dict(DEFAULTS)
75
+ cfg.update({k: v for k, v in (data.get(key, {}) if key else data).items() if k in DEFAULTS})
76
+ return cfg
77
+
78
+
79
+ def save_config(folder, updates):
80
+ path, key = config_target(folder)
81
+ data = read_json(path)
82
+ section = data.setdefault(key, {}) if key else data
83
+ section.update(updates)
84
+ path.parent.mkdir(parents=True, exist_ok=True)
85
+ path.write_text(json.dumps(data, indent=2) + "\n")
86
+ return path, load_config(folder)
87
+
88
+
89
+ def cmd_config(args):
90
+ updates = {k: v for k, v in [("critics", args.critics), ("model", args.model),
91
+ ("rounds", args.rounds), ("timeout_min", args.timeout_min)]
92
+ if v is not None}
93
+ if "critics" in updates and not 0 <= updates["critics"] <= MAX_CRITICS:
94
+ sys.exit(f"--critics must be 0..{MAX_CRITICS}")
95
+ if updates:
96
+ path, cfg = save_config(args.folder, updates)
97
+ else:
98
+ path, cfg = config_target(args.folder)[0], load_config(args.folder)
99
+ print(json.dumps({"config": str(path), **cfg}, indent=2))
100
+ return 0
101
+
102
+
103
+ # ---- spec ---------------------------------------------------------------------------------
104
+
105
+ def brief_sections(claude_md, names=("The ask", "Deliverables")):
106
+ """The spec parts of a solo agent's CLAUDE.md, never its Status or notes."""
107
+ try:
108
+ text = Path(claude_md).read_text()
109
+ except OSError:
110
+ return ""
111
+ out = []
112
+ for name in names:
113
+ m = re.search(rf"^## {re.escape(name)}[^\n]*\n(.*?)(?=^## |\Z)", text, re.M | re.S)
114
+ if m:
115
+ out.append(f"### {name}\n{m.group(1).strip()}")
116
+ return "\n\n".join(out)
117
+
118
+
119
+ def previous_defects(review_md):
120
+ try:
121
+ text = Path(review_md).read_text()
122
+ except OSError:
123
+ return ""
124
+ m = re.search(r"^## Defects\n(.*?)(?=^## |\Z)", text, re.M | re.S)
125
+ return m.group(1).strip() if m else ""
126
+
127
+
128
+ # ---- critics ------------------------------------------------------------------------------
129
+
130
+ def build_request(a, spec, k, n):
131
+ parts = [f"# Review request: {a.label}, round {a.round} (critic {k} of {n}, independent)",
132
+ "## Spec", spec or "(no spec given: judge against the artifact's own stated purpose)"]
133
+ if a.artifact:
134
+ parts += ["## Artifacts", "\n".join(f"- {p}" for p in a.artifact)]
135
+ if a.repo:
136
+ rng = a.range or "HEAD~1..HEAD"
137
+ parts += ["## Code", f"Repo: {a.repo}\nDiff: `git -C {a.repo} diff {rng}` "
138
+ f"(and `git -C {a.repo} status` for uncommitted work)"]
139
+ if a.check:
140
+ parts += ["## Check (must exit 0)", f"`{a.check}`, run in `{a.check_cwd}`"]
141
+ prev = previous_defects(a.previous) if a.previous else ""
142
+ if prev:
143
+ parts += ["## Defects reported last round",
144
+ "Verify each one is fixed, then review everything else fresh as well:\n" + prev]
145
+ parts.append("Reply with the verdict in the format of your instructions.")
146
+ return "\n\n".join(parts)
147
+
148
+
149
+ def forget_project(workdir):
150
+ """Claude Code makes ~/.claude/projects/<cwd>/ (an empty memory/ folder) even with
151
+ --no-session-persistence. Remove it if nothing was saved, so no trace of a critic stays."""
152
+ key = re.sub(r"[^A-Za-z0-9]", "-", str(Path(workdir).resolve()))
153
+ for d in {key, re.sub(r"[^A-Za-z0-9]", "-", workdir)}:
154
+ proj = Path.home() / ".claude" / "projects" / d
155
+ if proj.is_dir() and not any(f.is_file() for f in proj.rglob("*")):
156
+ shutil.rmtree(proj, ignore_errors=True)
157
+
158
+
159
+ def critic_env():
160
+ env = {k: v for k, v in os.environ.items() if not STRIP_ENV.match(k)}
161
+ env["HIVEY_CRITIC"] = "1"
162
+ return env
163
+
164
+
165
+ def run_critic(a, spec, k, n, cfg, dirs):
166
+ claude = shutil.which("claude")
167
+ if not claude:
168
+ return {"critic": k, "ok": False, "error": "claude CLI not found"}
169
+ workdir = tempfile.mkdtemp(prefix="hivey-critic-") # empty: no CLAUDE.md, no history
170
+ cmd = [claude, "-p", "--model", cfg["model"], "--no-session-persistence",
171
+ "--output-format", "json", "--append-system-prompt", BRIEF.read_text(),
172
+ "--allowedTools", *READ_TOOLS, "--disallowedTools", *WRITE_TOOLS]
173
+ for d in dirs:
174
+ cmd += ["--add-dir", d]
175
+ started = time.time()
176
+ try:
177
+ r = subprocess.run(cmd, input=build_request(a, spec, k, n), capture_output=True,
178
+ text=True, cwd=workdir, env=critic_env(),
179
+ timeout=cfg["timeout_min"] * 60)
180
+ except subprocess.TimeoutExpired:
181
+ return {"critic": k, "ok": False, "error": f"timed out after {cfg['timeout_min']} min"}
182
+ finally:
183
+ shutil.rmtree(workdir, ignore_errors=True)
184
+ forget_project(workdir)
185
+ try:
186
+ out = json.loads(r.stdout)
187
+ text, cost = out.get("result", ""), out.get("total_cost_usd")
188
+ except ValueError:
189
+ text, cost = r.stdout, None
190
+ m = re.search(r"VERDICT:\s*(PASS|FAIL)", text or "")
191
+ if r.returncode != 0 or not m:
192
+ return {"critic": k, "ok": False, "text": text,
193
+ "error": f"exit {r.returncode}, no verdict: {(r.stderr or '').strip()[-300:]}"}
194
+ return {"critic": k, "ok": True, "verdict": m.group(1), "text": text.strip(),
195
+ "defects": parse_defects(text), "cost_usd": cost,
196
+ "seconds": round(time.time() - started)}
197
+
198
+
199
+ def parse_defects(text):
200
+ m = re.search(r"^Defects:\s*\n(.*?)(?=^Verified OK:|^```|\Z)", text, re.M | re.S)
201
+ if not m:
202
+ return []
203
+ items, cur = [], None
204
+ for line in m.group(1).splitlines():
205
+ if re.match(r"^\s*\d+\.\s+", line):
206
+ cur = re.sub(r"^\s*\d+\.\s+", "", line).strip()
207
+ items.append(cur)
208
+ elif cur is not None and line.strip():
209
+ items[-1] += " " + line.strip()
210
+ return [i for i in items if i and i.lower() not in ("none", "none.", "-")]
211
+
212
+
213
+ def merge(results):
214
+ """Union of defects; the same location from several critics is listed once."""
215
+ merged = {}
216
+ for r in results:
217
+ for d in r.get("defects", []):
218
+ loc = d.split(" — ")[0].split(" - ")[0].strip().lower()
219
+ entry = merged.setdefault(loc, {"text": d, "critics": []})
220
+ entry["critics"].append(r["critic"])
221
+ if len(d) > len(entry["text"]):
222
+ entry["text"] = d
223
+ return list(merged.values())
224
+
225
+
226
+ # ---- run ----------------------------------------------------------------------------------
227
+
228
+ def run_check(cmd, cwd):
229
+ if not cmd:
230
+ return None
231
+ try:
232
+ r = subprocess.run(cmd, shell=True, cwd=cwd, capture_output=True, text=True, timeout=1800)
233
+ return {"cmd": cmd, "exit": r.returncode, "tail": (r.stdout + r.stderr)[-1500:]}
234
+ except subprocess.TimeoutExpired:
235
+ return {"cmd": cmd, "exit": 124, "tail": "timed out after 30 min"}
236
+
237
+
238
+ def write_review(path, a, cfg, check, results, defects, verdict):
239
+ lines = [f"# Fresh review: {a.label}, round {a.round}", "",
240
+ f"**Verdict:** {verdict} · **Critics:** {len(results)} × {cfg['model']} "
241
+ f"(one-shot, fresh context, no saved session) · **Date:** "
242
+ f"{time.strftime('%Y-%m-%d %H:%M')}", ""]
243
+ if check:
244
+ lines += [f"**Check:** `{check['cmd']}` → exit {check['exit']}", ""]
245
+ lines.append("| Critic | Verdict | Defects | Time | Cost |")
246
+ lines.append("|---|---|---|---|---|")
247
+ for r in results:
248
+ cost = f"${r['cost_usd']:.2f}" if r.get("cost_usd") is not None else "-"
249
+ lines.append(f"| {r['critic']} | {r.get('verdict', 'ERROR')} | {len(r.get('defects', []))} "
250
+ f"| {r.get('seconds', '-')}s | {cost} |")
251
+ lines += ["", "## Defects"]
252
+ lines += [f"{i}. {d['text']} (critic {', '.join(map(str, d['critics']))})"
253
+ for i, d in enumerate(defects, 1)] or ["None."]
254
+ if check and check["exit"] != 0:
255
+ lines += ["", "## Check output (tail)", "```", check["tail"], "```"]
256
+ lines += ["", "## Each critic's verdict"]
257
+ for r in results:
258
+ lines += ["", f"### Critic {r['critic']}", ""]
259
+ lines += [r.get("text") or f"ERROR: {r.get('error')}"]
260
+ if r.get("error") and r.get("text"):
261
+ lines += ["", f"ERROR: {r['error']}"]
262
+ Path(path).parent.mkdir(parents=True, exist_ok=True)
263
+ Path(path).write_text("\n".join(lines) + "\n")
264
+
265
+
266
+ def default_out(folder, label, rnd):
267
+ folder = Path(folder)
268
+ base = folder / ".swarm" / "reviews" if (folder / ".swarm").is_dir() else folder / ".agent" / "reviews"
269
+ safe = re.sub(r"[^A-Za-z0-9_.-]+", "-", label).strip("-") or "review"
270
+ return base / f"{safe}-r{rnd}-{time.strftime('%Y%m%d-%H%M%S')}.md"
271
+
272
+
273
+ def notify(addr, text):
274
+ if addr and shutil.which("hivey"):
275
+ subprocess.run(["hivey", "msg", "send", addr, text], capture_output=True)
276
+
277
+
278
+ def cmd_run(a):
279
+ folder = Path(a.folder).expanduser().resolve()
280
+ cfg = load_config(folder)
281
+ for k in ("critics", "model", "timeout_min"):
282
+ if getattr(a, k) is not None:
283
+ cfg[k] = getattr(a, k)
284
+ if not 1 <= cfg["critics"] <= MAX_CRITICS:
285
+ sys.exit(f"critics is {cfg['critics']}: fresh review is off for {folder} "
286
+ f"(fresh_review.py config {folder} --critics 2 turns it on)")
287
+ agent_cfg = read_json(folder / ".agent" / "config.json")
288
+ a.check = a.check or agent_cfg.get("check")
289
+ a.check_cwd = str(Path(a.check_cwd).expanduser().resolve()) if a.check_cwd else str(folder)
290
+ a.label = a.label or folder.name
291
+ a.artifact = [str(Path(p).expanduser().resolve()) for p in a.artifact]
292
+ a.repo = str(Path(a.repo).expanduser().resolve()) if a.repo else None
293
+ spec_parts = list(a.spec)
294
+ for f in a.spec_file:
295
+ spec_parts.append(Path(f).expanduser().read_text())
296
+ if not spec_parts and (folder / "CLAUDE.md").exists():
297
+ spec_parts.append(brief_sections(folder / "CLAUDE.md"))
298
+ spec = "\n\n".join(p for p in spec_parts if p.strip())
299
+ out = Path(a.out).expanduser() if a.out else default_out(folder, a.label, a.round)
300
+
301
+ if a.background:
302
+ argv = [arg for arg in sys.argv[1:] if arg != "--background"]
303
+ if not a.out:
304
+ argv += ["--out", str(out)]
305
+ log = out.with_suffix(".log")
306
+ log.parent.mkdir(parents=True, exist_ok=True)
307
+ p = subprocess.Popen([sys.executable, __file__, *argv], stdout=open(log, "w"),
308
+ stderr=subprocess.STDOUT, start_new_session=True, cwd=str(folder))
309
+ print(json.dumps({"started": True, "pid": p.pid, "critics": cfg["critics"],
310
+ "review": str(out), "log": str(log), "notify": a.notify}))
311
+ return 0
312
+
313
+ dirs = sorted({str(Path(p) if Path(p).is_dir() else Path(p).parent) for p in a.artifact}
314
+ | ({a.repo} if a.repo else set()) | {a.check_cwd})
315
+ if a.dry_run:
316
+ print(build_request(a, spec, 1, cfg["critics"]))
317
+ print(json.dumps({"critics": cfg["critics"], "model": cfg["model"], "dirs": dirs,
318
+ "review": str(out)}, indent=2))
319
+ return 0
320
+
321
+ check = run_check(a.check, a.check_cwd)
322
+ with ThreadPoolExecutor(max_workers=cfg["critics"]) as pool:
323
+ results = list(pool.map(lambda k: run_critic(a, spec, k, cfg["critics"], cfg, dirs),
324
+ range(1, cfg["critics"] + 1)))
325
+ defects = merge(results)
326
+ failed = [r for r in results if not r["ok"]]
327
+ if failed:
328
+ verdict, code = "ERROR", 2
329
+ elif all(r["verdict"] == "PASS" for r in results) and not defects and (not check or check["exit"] == 0):
330
+ verdict, code = "APPROVED", 0
331
+ else:
332
+ verdict, code = "CHANGES", 1
333
+ write_review(out, a, cfg, check, results, defects, verdict)
334
+ summary = {"verdict": verdict, "label": a.label, "round": a.round, "review": str(out),
335
+ "critics": [{k: r.get(k) for k in ("critic", "verdict", "error", "seconds", "cost_usd")}
336
+ for r in results],
337
+ "defects": len(defects), "check_exit": check["exit"] if check else None}
338
+ check_note = f", check exit {check['exit']}" if check else ""
339
+ print(json.dumps(summary, indent=2) if a.json else
340
+ f"{verdict}: {a.label} r{a.round}, {len(defects)} defect(s) from {len(results)} fresh "
341
+ f"critic(s){check_note} → {out}")
342
+ notify(a.notify, f"FRESH REVIEW {verdict} {a.label} r{a.round}: {len(defects)} defect(s) "
343
+ f"from {len(results)} critic(s) → {out}")
344
+ return code
345
+
346
+
347
+ def main():
348
+ p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
349
+ sub = p.add_subparsers(dest="cmd", required=True)
350
+ c = sub.add_parser("config", help="show or set the review config of a swarm root or agent folder")
351
+ c.add_argument("folder")
352
+ c.add_argument("--critics", type=int)
353
+ c.add_argument("--model")
354
+ c.add_argument("--rounds", type=int)
355
+ c.add_argument("--timeout-min", type=int)
356
+ r = sub.add_parser("run", help="run one fresh review")
357
+ r.add_argument("--folder", default=".", help="swarm root or agent folder (config, default out)")
358
+ r.add_argument("--spec", action="append", default=[], help="spec text (repeatable)")
359
+ r.add_argument("--spec-file", action="append", default=[], help="file with spec text (repeatable)")
360
+ r.add_argument("--artifact", action="append", default=[], help="path to review (repeatable)")
361
+ r.add_argument("--repo", help="git repo or worktree of the change")
362
+ r.add_argument("--range", help="git range to diff, e.g. main...swarm/builder (default HEAD~1..HEAD)")
363
+ r.add_argument("--check", help="command that must exit 0 (default: .agent/config.json check)")
364
+ r.add_argument("--check-cwd", help="where to run the check (default: --folder)")
365
+ r.add_argument("--critics", type=int)
366
+ r.add_argument("--model")
367
+ r.add_argument("--timeout-min", type=int)
368
+ r.add_argument("--round", type=int, default=1)
369
+ r.add_argument("--previous", help="last round's review: its defects are re-checked")
370
+ r.add_argument("--label", help="what is reviewed, e.g. T2 or the run name")
371
+ r.add_argument("--out", help="review file (default .swarm/reviews/ or .agent/reviews/)")
372
+ r.add_argument("--notify", help="hivey address to message with the verdict")
373
+ r.add_argument("--background", action="store_true", help="return at once; --notify gets the verdict")
374
+ r.add_argument("--json", action="store_true")
375
+ r.add_argument("--dry-run", action="store_true", help="print the request and settings, run nothing")
376
+ a = p.parse_args()
377
+ sys.exit(cmd_config(a) if a.cmd == "config" else cmd_run(a))
378
+
379
+
380
+ if __name__ == "__main__":
381
+ main()
@@ -66,8 +66,8 @@ From the request, work out:
66
66
  | `agy`, Antigravity (Gemini) | fast, cheap tasks; image generation | see the `hivey-agy` skill's model table |
67
67
 
68
68
  All four read the brief: you write `CLAUDE.md`, and launch links `AGENTS.md` (and `GEMINI.md`
69
- for agy) to it. Only Claude Code gets hivey's safety hooks, the done gate and the reviewer
70
- subagent; say so when you suggest another kind.
69
+ for agy) to it. Only Claude Code gets hivey's safety hooks and the done gate; say so when
70
+ you suggest another kind. The fresh review works for all four.
71
71
  - **schedule** (ongoing agents): on demand only, an interval (`--heartbeat 6h`), or fixed times
72
72
  (`hivey swarm schedule add <name> --at 08:57 …`). Draft the exact prompt each run gets.
73
73
 
@@ -121,7 +121,8 @@ Skills: <a> (why), <b> (why) gaps: <gap> → suggestion
121
121
  MCPs: none | <x> (why, needs key: <name>) CLIs: <ok…> missing: <tool> → <install cmd>
122
122
  Permissions: pre-approved + hivey safety on | (non-Claude: no safety hooks) deny: git push, <…>
123
123
  Extra dirs: <paths>
124
- Run check: <command> · done gate: yes | no · reviewer: yes | no (Claude Code only)
124
+ Run check: <command> · done gate: yes | no (Claude Code only)
125
+ Review: <N> fresh critics × <model> per run, <R> rounds max | none (default 2 × sonnet, 3)
125
126
  Memory: <name>-wiki | none
126
127
  Slack: #<name> | none (Slack not connected)
127
128
  Schedule: on demand | --heartbeat <6h> | at <HH:MM>, … → "<run prompt>"
@@ -140,9 +141,13 @@ tool (AskUserQuestion in Claude Code; otherwise plain questions):
140
141
  3. **Schedule** (ongoing agents only): your recommendation first. Runs happen only while hivey
141
142
  runs; each wake-up arrives as a `[hivey]` message when the agent is idle, never piles up and
142
143
  never expires.
143
- 4. **Done gate and reviewer** (Claude Code only): propose the reviewer when the output can be
144
- checked against sources or specs and a second read is worth the tokens; leave it out for
145
- routine ops.
144
+ 4. **Done gate** (Claude Code only) and **fresh review** (every kind, on by default): how many
145
+ fresh critics review each run before it counts as done (suggest 2; 3 for code or claims
146
+ where a miss is costly; 0 only for trivial routine ops), their model (suggest `sonnet`) and
147
+ the maximum rounds (suggest 3). Each critic is a one-shot `claude -p` run with an empty
148
+ context and no saved session: it gets only the spec (The ask, Deliverables), the artifact
149
+ and the check, runs the check itself, gives PASS or defects with evidence, and exits. N
150
+ critics cost about N extra reads of the output.
146
151
 
147
152
  **Slack is not a question.** Run `hivey slack status`. Connected: launch creates (or joins)
148
153
  `#<name>`, invites the user and starts the relay. Not connected: ask the user to run `hivey
@@ -157,7 +162,7 @@ Adjust the plan if the user tweaks it; continue once they approve.
157
162
  python3 $A/setup_agent.py "$DIR" --name <name> --kind <claude|codex|grok|agy> \
158
163
  [--dirs /extra/path,…] [--allow 'Bash(gh:*)'] [--deny 'Bash(rm:*)'] \
159
164
  [--mcp '<server>={"command":"npx","args":["-y","<pkg>"]}'] \
160
- [--check-cmd 'bash scripts/check.sh'] [--gate] [--reviewer] [--git]
165
+ [--check-cmd 'bash scripts/check.sh'] [--gate] [--critics 2 --critic-model sonnet --review-rounds 3] [--git]
161
166
  ```
162
167
 
163
168
  It is idempotent (re-running only adds) and prints JSON. It writes:
@@ -168,9 +173,10 @@ It is idempotent (re-running only adds) and prints JSON. It writes:
168
173
  - `.mcp.json` with each `--mcp` server (`--enable-mcps x,y` pre-approves servers already in
169
174
  it). For a Codex agent the same servers are copied into `.codex/config.toml`. Grok and agy:
170
175
  set up MCP servers with their own CLI if really needed, or prefer a CLI tool;
171
- - `.agent/config.json` with the run check; with `--gate` (Claude Code) the **done gate** and
172
- **resume context** hooks are registered in the agent's own `.claude/settings.json`, never the
173
- global one; `--reviewer` installs the read-only `reviewer` subagent in `.claude/agents/`;
176
+ - `.agent/config.json` with the run check and the fresh review (`"review"`: critics, model,
177
+ rounds; change it later with `fresh_review.py config <folder> --critics N`); with `--gate`
178
+ (Claude Code) the **done gate** and **resume context** hooks are registered in the agent's
179
+ own `.claude/settings.json`, never the global one;
174
180
  - `.gitignore` (keeps `.mcp.json`, `.codex/`, `.agent/state/`, `logs/` out of git) and, with
175
181
  `--git`, a git repo in the folder if it isn't in one.
176
182
 
@@ -185,7 +191,7 @@ The harness, when chosen:
185
191
  |---|---|
186
192
  | Done gate | Stop hook `agent_gate.py`: while `.agent/state/run_active` exists, runs the check when the agent tries to finish and blocks it (at most 3 times), logging to `.agent/state/gate.log` |
187
193
  | Resume context | SessionStart hook `agent_context.py`: on startup, resume and compaction injects run-in-progress, gate log, `tasks.json` progress, recent commits and the newest progress-log entries |
188
- | Reviewer | `.claude/agents/reviewer.md`: read-only subagent (Sonnet) that checks artifacts against The ask and their sources |
194
+ | Fresh review | the hivey skill's `fresh_review.py run --folder .`: N one-shot critics in parallel (`claude -p`, empty context, no saved session, read-only), merged into one review in `.agent/reviews/`; exit 0 only if every critic PASSes and the check exits 0 |
189
195
 
190
196
  The hooks point at this skill's scripts, so improving them upgrades every agent. Codex, Grok
191
197
  and agy agents run the check themselves (the template says how).
@@ -265,7 +271,7 @@ MCPs: <list> | none (keys in .mcp.json for: …)
265
271
  Memory: <DIR>/<name>-wiki | none
266
272
  Slack: #<name> | none
267
273
  Schedule: on demand | heartbeat <6h> | at <times>
268
- Harness: check `<cmd>` · done gate · resume context · reviewer | none
274
+ Harness: check `<cmd>` · done gate · resume context · fresh review <N> × <model> | none
269
275
  Space: <emoji> <name> (★ in the sidebar)
270
276
  Talk to it: hivey msg send <name>/master "…" (or in #<name>)
271
277
  Relaunch: hivey swarm relaunch <name>