@hivey/cli 0.9.40 → 0.9.43

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.40",
3
+ "version": "0.9.43",
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",
@@ -110,6 +110,16 @@ 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
+
113
123
  Messages (delivered when the target is idle; `--fyi` never wakes; `--urgent` now):
114
124
  ```bash
115
125
  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>
@@ -118,10 +118,17 @@ run; it has the full method.">
118
118
  and blocks you until it passes, up to 3 times. Answering a question isn't a run: don't set
119
119
  the flag for that.
120
120
  2. Do the work following **Method**.
121
- 3. **Review**: <with a reviewer:> hand the artifacts to the `reviewer` subagent (Agent tool,
122
- `subagent_type: reviewer`, with the paths). Fix every defect it reports, then ask again
123
- until it says PASS (at most 3 rounds; then record what's left in Status).
124
- <without one:> self-review (below), spot-checking 3 claims against their sources.
121
+ 3. **Fresh review**: <with fresh review, the default:> run
122
+ `python3 ~/.claude/skills/hivey/scripts/fresh_review.py run --folder . --label <run> --artifact <path> …`
123
+ (`~/.agents/skills/…` if that's missing; for code add `--repo . --range <first commit of
124
+ this run>~1..HEAD`; from round 2 add `--round <n> --previous <last review>`). It takes a few
125
+ minutes (allow up to 15: run it in the background or with a long timeout). <N> one-shot
126
+ critics read only your spec, the artifact and the check (not your notes or this
127
+ conversation), and it writes one merged review to `.agent/reviews/`. Exit 0 = APPROVED.
128
+ Otherwise fix **every** defect in its Defects list in one revision and run it again (at
129
+ most <R> rounds; then record what's left in Status and tell the user). Don't summarize or
130
+ defend your work to the critics: they judge the result.
131
+ <without (critics 0):> self-review (below), spot-checking 3 claims against their sources.
125
132
  4. **Check**: run `<check command>` yourself. It must exit 0.
126
133
  5. **Commit** this folder only, never push: `git add -A . && git commit -m "<name>: <what
127
134
  changed>"`. The git log is part of your memory.
@@ -167,7 +174,7 @@ does, its skills and tools, and whether it is busy or idle.
167
174
 
168
175
  ## Definition of done
169
176
  - [ ] Every deliverable's Check passes
170
- - [ ] Self-review done against The ask
177
+ - [ ] Fresh review APPROVED <or, with critics 0: self-review done against The ask>
171
178
  - [ ] <memory: wiki ingested>
172
179
  - [ ] <if Slack: run summary sent>
173
180
  - [ ] Committed, not pushed
@@ -210,11 +217,12 @@ The same CLAUDE.md works; adjust these parts:
210
217
  - **Skills**: these CLIs don't load `.claude/skills/` by themselves. In the Skills table, give
211
218
  each skill's path (`.claude/skills/<skill>/SKILL.md`) and write "read the skill's SKILL.md
212
219
  before the first time you use it".
213
- - **No hooks**: there is no done gate, resume context or reviewer subagent. Replace step 0 of
220
+ - **No hooks**: there is no done gate or resume context (the fresh review still works: it's a
221
+ script). Replace step 0 of
214
222
  "Start of every session" with: read `.agent/state/gate.log` (if any), `git log -5 --oneline
215
223
  -- .` and `tasks.json` (if any). In the Run protocol, run the check yourself and don't finish
216
- until it passes (at most 3 attempts; then write why into Status). Self-review instead of the
217
- reviewer.
224
+ until it passes (at most 3 attempts; then write why into Status). Use
225
+ `~/.agents/skills/hivey/scripts/fresh_review.py` for the review.
218
226
  - **Grok** can't work in extra folders: keep everything inside the agent folder.
219
227
  - **Codex** MCP servers live in `.codex/config.toml` (setup_agent.py copies them there).
220
228
  - Keep the `DONE:` rule: it's how hivey and the user see each run's summary.