@r1z4x/tezgah 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -6,6 +6,54 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.5.1] - 2026-10-09
+
+### Fixed
+
+- **Subagents load in the first session.** Claude and Codex missed every role a
+  session wrote into a new repo until the next session. Codex also ignored
+  `.codex/agents` in an untrusted repo. The install now writes the roles to
+  `~/.claude/agents` and `$CODEX_HOME/agents`, as it already did for omp. A
+  session removes the copies an older release left in a repo's `.claude/agents`
+  and `.codex/agents`. Cursor read 9 of 10 role descriptions as ">" and got a
+  model id it does not list. It now gets its own `.cursor/agents` with a
+  one-line description and `model: inherit`.
+
+- **`tezgah-route` names the specialists.** It could only name a tier. The
+  five specialists ran 0 times in 121 delegations. The generic task agent ran 86.
+  The judge now also answers whether a brief is a specialist's whole
+  job, and the route names that agent. `--phase review` and `--phase research`
+  name the reviewer and the researcher. A security brief that only reviews
+  goes to `tezgah-security`. The routing and fan-out text say to spawn the
+  named agent, never the generic one.
+- **Jev through OpenRouter asks a model OpenRouter has.** The carrier sent
+  `typesafe/jev-latest`, which OpenRouter answers with 400 (no such model). It
+  now sends the bare `jev-latest`, which OpenRouter maps itself.
+- **The Workers AI model id picks Clef.** `tezgah-setup` refused
+  `--jev @cf/cloudflare/clef-flash`, and the same value in
+  `TEZGAH_JEV_PROVIDER` chose no carrier. Both now name `clef-flash`, and
+  `@cf/cloudflare/clef` names `clef`.
+- **opencode's judge run denies tools at agent level too.** A user's
+  `agent.build.permission` beat the inline top-level deny.
+- **The refusal note needs an asked session CLI.** The seam writes it only
+  when it asked the session CLI first. A caller that named the CLI gets it.
+- **A chosen carrier reads only its own key.** A `clef` choice no longer opens
+  omp's login database on every status-line redraw.
+- **`pnpm test` names a command.** An Acceptance item counted as a command
+  only when a word after the first was an option or a path. So `pnpm test`,
+  `cargo test` and `make test` read as missing, and the phase move refused the
+  plan. A known runner followed by `test` or `run` now counts. Prose such as
+  `run the tests` still does not.
+- **Each carrier's price is now pinned by a test.** The one cost check priced a
+  TypeSafe answer at Jev's rate. It passed with or without per-carrier pricing.
+  New tests in `tezgah-taste`, `tezgah-triage` and the replay labeller price Clef
+  and Clef-flash answers at their own rates. A run with an unpriced answer prints
+  `cost unknown`.
+- **Claude lists the reviewer once.** The plugin shipped its own
+  `agents/tezgah-reviewer.md`, which Claude shows as `tezgah:tezgah-reviewer`
+  beside the generated reviewer and never shadows. The plugin now ships no
+  agent, and its release-time renderer is gone with it.
+
 ## [1.5.0] - 2026-10-09
 
 ### Changed
@@ -933,7 +981,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   the copy could not find `hooks/` and died on import. It now links into the
   installed tree, and also installs the command as `tezgah`.
 
-[Unreleased]: https://github.com/r1z4x/tezgah/compare/v1.5.0...HEAD
+[Unreleased]: https://github.com/r1z4x/tezgah/compare/v1.5.1...HEAD
+[1.5.1]: https://github.com/r1z4x/tezgah/releases/tag/v1.5.1
 [1.5.0]: https://github.com/r1z4x/tezgah/releases/tag/v1.5.0
 [1.4.0]: https://github.com/r1z4x/tezgah/releases/tag/v1.4.0
 [1.3.0]: https://github.com/r1z4x/tezgah/releases/tag/v1.3.0

package/MANIFEST

@@ -19,7 +19,6 @@ README.md
 README.tr.md
 RELEASING.md
 SECURITY.md
-agents/tezgah-reviewer.md
 assets/logo/README.md
 assets/logo/tezgah-logo-16.png
 assets/logo/tezgah-logo-256.png

package/README.md

@@ -109,10 +109,12 @@ it set out to arm is not armed.
   `~/.codex/AGENTS.md`, `~/.omp/agent/RULES.md`). Claude Code's hooks ship in a
   plugin registered through `claude plugin`; with no `claude` CLI, Claude stays
   unarmed and the report says so.
-- **Agent files in your repositories.** Inside the configured roots, a session
-  writes subagent files to `.claude/agents/`, `.codex/agents/` and
-  `.opencode/agents/`, and lists those directories in the clone's own
-  `.git/info/exclude` (`TEZGAH_NO_EXCLUDE=1` stops that).
+- **Agent files.** The install writes tezgah's subagent roles to
+  `~/.claude/agents/`, `$CODEX_HOME/agents/` (default `~/.codex/agents/`) and
+  `~/.omp/agent/agents/`. Inside the configured roots, a session writes them to
+  the repository's `.cursor/agents/` and `.opencode/agents/`, and lists those
+  directories in the clone's own `.git/info/exclude` (`TEZGAH_NO_EXCLUDE=1`
+  stops that).
 - **A daily update check.** The status line asks for a newer release at most
   once a day; `~/.config/tezgah/update-check-off` or `TEZGAH_UPDATE_CHECK=0`
   turns it off.

package/bin/tezgah-docs

@@ -106,7 +106,7 @@ RUN = re.compile(r"((?:`[A-Za-z_][A-Za-z0-9_]*(?:\(\))?`\s*[/,]?\s*){1,5})$")
 CITE = re.compile(r"`([\w.-]+(?:/[\w.-]+)+|[\w-]+\.\w+):(\d+)(?:-(\d+))?`"
                   r"|`(:(\d+)(?:-(\d+))?)`")
 # The symbol written after the citation instead of before it, the way a table
-# cell reads: `hooks/tezgah_policy.py:678-946` (`CORE`).
+# cell reads: `hooks/tezgah_policy.py:680-948` (`CORE`).
 AFTER = re.compile(r"\s*\(`([A-Za-z_][A-Za-z0-9_]*)(?:\(\))?`\)")
 # Any `path:line`, backticked or not: what CITE does not match of these (a
 # bare token, a comma list `x.py:12,40`) is counted as unjudged, so a citation

package/bin/tezgah-route

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""tezgah-route - which tier worker a delegated task goes to, and the model table.
+"""tezgah-route - which worker a delegated task goes to, and the model table.
 
   tezgah-route "<brief>" [--phase P] [--json]   the agent to spawn, and why
   tezgah-route --check                          the table's age and refresh flags
@@ -9,10 +9,13 @@
   tezgah-route --report                         each route's first check, by tier
 
 A brief naming stored data, a migration, credentials, the gate or security goes to
-tezgah-frontier by rule; otherwise Jev picks the tier (one Choice, ~650 input
-tokens, ~0.4 s); with no key or `judge-off`, `--phase`
-(explore|code|mechanical|plan|review|research) picks it from the static table, and
-with neither the middle tier is used. The brief is sent to the judge seam's
+tezgah-frontier by rule - or to tezgah-security when it only reviews; otherwise
+Jev answers two Choices in one call (~700 input tokens, ~0.4 s): the tier, and
+whether the brief is the whole job of a specialist (tezgah-tester, -docs,
+-security, -ui, -researcher, -reviewer), which is then the agent named. With no
+key or `judge-off`, `--phase review|research` names the reviewer or the
+researcher, another `--phase` (explore|code|mechanical|plan) picks the tier from
+the static table, and with neither the middle tier is used. The brief is sent to the judge seam's
 provider - the session's own CLI (omp, claude, opencode, cursor, codex) or the Jev
 model through TypeSafe, OpenRouter System One, Cloudflare Workers AI or a
 compatible endpoint (TEZGAH_JEV_PROVIDER picks one), else the OpenRouter chat

package/bin/tezgah-setup

@@ -13,7 +13,6 @@
   tezgah-setup --adopt                 move the predecessor wiring aside
   tezgah-setup --sync                  dev: copy this checkout over the Claude plugin copy
   tezgah-setup --write-manifest        release: regenerate the tracked MANIFEST from git
-  tezgah-setup --write-plugin-agents   release: re-render the plugin's agents/ from the role source
   tezgah-setup --status [PATH]         print the armed/used checklist
   tezgah-setup --agents [PATH]         regenerate this repo's subagent set
   tezgah-setup --deps [--dry-run]      install missing optional tools only
@@ -1163,9 +1162,33 @@ def install_claude():
     # (`TEZGAH_CORE_IN_FILE`, hooks/projects-auto-init.py), so a session pays for
     # the contract once.
     print("%s %s (always-on contract)" % (OK, write_rules("claude")))
+    write_user_agents("claude")
     register_claude_plugin()
 
 
+def write_user_agents(host):
+    """The host's tezgah roles in its user agent dir, where it loads them from
+    the first session (a repo dir written at session start is missed there),
+    then tezgah's MARKER files no longer wanted - `agents-off`, a lost
+    capability, a retired role - are removed. The user's own files stay."""
+    agents_dir = tezgah_agents.user_agent_dir(host)
+    wanted = tezgah_agents.user_agents(host)
+    for name, text in sorted(wanted.items()):
+        path = os.path.join(agents_dir, name)
+        if write_if_changed(path, text):
+            print("%s %s" % (OK, path))
+    for path in tezgah_agents.remove_stale(agents_dir, wanted):
+        print("%s removed %s" % (OK, path))
+
+
+def user_agent_files(host):
+    """{filename: text} of tezgah's MARKER files in the host's user agent dir."""
+    d = tezgah_agents.user_agent_dir(host)
+    return {n: t for n in (os.listdir(d) if os.path.isdir(d) else [])
+            if n.startswith("tezgah-")
+            and tezgah_agents.MARKER in (t := tezgah_agents._read(os.path.join(d, n)) or "")}
+
+
 # The marketplace a manifest rendered by this installer carries, so Claude
 # installs the plugin as `tezgah@tezgah-local`. A manifest the tree already has
 # under another name (the maintainer's) is kept, name included.
@@ -1358,6 +1381,7 @@ def install_codex():
     # instructions Codex keeps for the whole session. Global, like omp's
     # RULES.md, because a per-project file would be a tracked project file.
     print("%s %s (always-on contract)" % (OK, write_rules("codex")))
+    write_user_agents("codex")
 
 
 def _toml_str(value):
@@ -3293,6 +3317,9 @@ def verify_uninstall(hosts, full):
         # the user's own CLAUDE.md may name tezgah; only the block is ours
         clean("claude global CLAUDE.md block gone", [CLAUDE_RULES],
               needle="<!-- tezgah:start")
+        claim("claude subagents gone",
+              [os.path.join(tezgah_agents.user_agent_dir("claude"), n)
+               for n in user_agent_files("claude")])
     if "codex" in hosts:
         clean("codex hooks.json unwired", [os.path.join(CODEX, "hooks.json")])
         claim("codex skills unlinked",
@@ -3304,6 +3331,9 @@ def verify_uninstall(hosts, full):
         clean("codex global AGENTS.md block gone",
               [os.path.join(CODEX, n) for n in CODEX_RULES],
               needle="<!-- tezgah:start")
+        claim("codex subagents gone",
+              [os.path.join(tezgah_agents.user_agent_dir("codex"), n)
+               for n in user_agent_files("codex")])
     if "opencode" in hosts:
         claim("opencode plugin unlinked",
               [os.path.join(OPENCODE, d, "tezgah.js") for d in ("plugins", "plugin")]
@@ -3454,6 +3484,13 @@ def uninstall_claude():
     unwire_claude_settings()
     drop_claude_mcp_row()
     strip_managed_md(CLAUDE_RULES)
+    remove_user_agents("claude")
+
+
+def remove_user_agents(host):
+    """Every tezgah MARKER file in the host's user agent dir; the user's stay."""
+    for path in tezgah_agents.remove_stale(tezgah_agents.user_agent_dir(host), ()):
+        print("%s removed %s" % (OK, path))
 
 
 def drop_claude_mcp_row():
@@ -3488,6 +3525,7 @@ def uninstall_codex():
     # both names: the override may have appeared, or gone, since the install
     for name in CODEX_RULES:
         strip_managed_md(os.path.join(CODEX, name))
+    remove_user_agents("codex")
 
 
 def uninstall_opencode():
@@ -4429,6 +4467,8 @@ def host_checks_claude():
          bool(copies) and all(plugin_copy_current(t) for t in copies)),
         ("CLAUDE.md carries the contract (matches a fresh render)",
          rules_current("claude")),
+        ("subagents in %s (match a fresh render)" % tezgah_agents.user_agent_dir("claude"),
+         user_agent_files("claude") == tezgah_agents.user_agents("claude")),
     ] + claude_mcp_rows(copies)
 
 
@@ -4617,6 +4657,8 @@ def host_checks_codex():
         ("MCP in config.toml", "mcp_servers.codegraph" in toml),
         ("%s carries the contract (matches a fresh render)"
          % os.path.basename(codex_rules()), rules_current("codex")),
+        ("subagents in %s (match a fresh render)" % tezgah_agents.user_agent_dir("codex"),
+         user_agent_files("codex") == tezgah_agents.user_agents("codex")),
     ] + mcp_rows(toml_servers(toml_path), "config.toml") + [
         mcp_row(TEZGAH_MCP_NAME, toml_mcp_entry(toml_path, TEZGAH_MCP_NAME),
                 "config.toml", tezgah_mcp_command()),
@@ -4929,24 +4971,6 @@ def write_manifest():
     return 0
 
 
-def write_plugin_agents():
-    """Re-render the plugin's tracked `agents/*.md` from tezgah_agents' role
-    bodies, the source the per-repo agents are generated from. A plain write,
-    not write_if_changed: a tracked file needs no `.tezgah-bak` beside it."""
-    for name, text in tezgah_agents.plugin_agents().items():
-        path = os.path.join(HERE, "agents", name)
-        try:
-            with open(path, encoding="utf-8") as fh:
-                if fh.read() == text:
-                    continue
-        except OSError:
-            pass
-        with open(path, "w", encoding="utf-8") as fh:
-            fh.write(text)
-        print("%s %s" % (OK, path))
-    return 0
-
-
 def tree_sha(root, files):
     """sha256 over each relpath and its bytes, or None when one is unreadable."""
     h = hashlib.sha256()
@@ -5647,8 +5671,6 @@ def main(argv):
                     help="regenerate this repo's subagent set (default: cwd)")
     ap.add_argument("--write-manifest", action="store_true",
                     help="release: regenerate the tracked MANIFEST from git")
-    ap.add_argument("--write-plugin-agents", action="store_true",
-                    help="release: re-render the plugin's agents/ from the role source")
     ap.add_argument("--deps", action="store_true")
     ap.add_argument("--mcp-schemas", action="store_true",
                     help="measure the MCP tool-schema band by asking each server")
@@ -5695,7 +5717,7 @@ def main(argv):
                     help="with --install: the language replies are asked for and "
                          "the Stop rule checks (config.json `reply_lang`; `tr` "
                          "when unset, `any` checks none)")
-    ap.add_argument("--jev", choices=tp.JEV_CHOICES,
+    ap.add_argument("--jev", type=tp.jev_name, choices=tp.JEV_CHOICES,
                     help="the carrier the judgement seam reaches the Jev model "
                          "through (config.json `jev`; `auto` tries every one "
                          "that resolves); TEZGAH_JEV_PROVIDER and JEV_PROVIDER "
@@ -5763,8 +5785,6 @@ def main(argv):
         return 0
     if args.write_manifest:
         return write_manifest()
-    if args.write_plugin_agents:
-        return write_plugin_agents()
     if args.status:
         print(tezgah_context.health_lines(os.path.realpath(expand(args.status))))
         # The install-health half of this report, from the same function the

package/bin/tezgah-task

@@ -329,8 +329,8 @@ def verification_steps(text, path):
     the budget `review` enforces."""
     fields = tt.frontmatter(text)
     ident = fields.get("id") or os.path.basename(path).split("-")[0]
-    # every item, not only the ones the command reader recognises: `pnpm test`
-    # carries no option or path and would otherwise vanish from the list
+    # every item, not only the ones the command reader recognises: a bare
+    # `pytest` is a command it does not read as one, and must not vanish here
     items = ["%s%s" % (i["text"], "" if i["state"] == "checkable" else
                        "  [%s]" % ("unverifiable" if i["state"] == "unverifiable"
                                    else "names no command"))

package/docs/architecture.md

@@ -34,7 +34,7 @@ nothing about a host's event names or output envelope.
 | `tezgah_paths.py` | where tezgah is armed: [roots](glossary.md#root) and the linked worktrees of a repository under one, kill switches, the config dir, and the writable cache dir - the fallback resolved on use rather than at import, so a gated call does not pay for `tempfile`, `shutil` or `sqlite3` | `hooks/tezgah_paths.py:2-14`, `hooks/tezgah_paths.py::cache_dir`, `hooks/tezgah_paths.py::fallback_cache` |
 | `tezgah_snapshot.py` | pre-write bytes of every file a write is about to change, and the one explicit restore | `hooks/tezgah_snapshot.py:2-18`, `hooks/tezgah_snapshot.py::capture` |
 | `tezgah_untrusted.py` | the untrusted-content label on a result from outside the user and workspace, and the taint notice on the next effect | `hooks/tezgah_untrusted.py:2-22`, `hooks/tezgah_untrusted.py::marks` |
-| `tezgah_agents.py` | per-repo subagent definitions generated into each host that has an agent surface | `hooks/tezgah_agents.py:2-22`, `hooks/tezgah_agents.py::sync_root` |
+| `tezgah_agents.py` | subagent definitions generated into each host that has an agent surface: user-level for Claude, Codex and omp (written at install), per repo for Cursor and opencode | `hooks/tezgah_agents.py:2-30`, `hooks/tezgah_agents.py::sync_root`, `hooks/tezgah_agents.py::user_agents` |
 | `tezgah_research.py` | the in-repo research workspace and the check that a protocol predates its results | `hooks/tezgah_research.py:2-85`, `hooks/tezgah_research.py::check` |
 | `tezgah_index.py` | the detached graph auto-index worker (flock-guarded, bounded retry) | `hooks/tezgah_index.py:2-18`, `hooks/tezgah_index.py::main` |
 

package/docs/clarity-baseline.json

@@ -72,7 +72,7 @@
     "semicolons": 6
   },
   "docs/models.md": {
-    "long_sentences": 19,
+    "long_sentences": 18,
     "passive": 8,
     "replace_words": 0,
     "semicolons": 9

package/docs/hosts.md

@@ -71,6 +71,8 @@ shared config, contract hash and the CLI symlinks every host shell can call
   `~/.claude/settings.json` - `statusLine` (`bin/tezgah-setup::wire_claude_statusline`) and the attribution
   off-switch (`bin/tezgah-setup::wire_claude_attribution`) - and the always-on block in
   `~/.claude/CLAUDE.md` (`CLAUDE_RULES`), Claude's own user-level memory file.
+  The subagent roles go to `~/.claude/agents/tezgah-*.md`
+  (`bin/tezgah-setup::write_user_agents`).
   Its hook manifest is the plugin's own
   `hooks/hooks.json`; no `hooks.json` is written into `~/.claude`. Claude runs a
   **copy** of the checkout under `~/.claude/plugins/cache`, refreshed by
@@ -84,6 +86,8 @@ shared config, contract hash and the CLI symlinks every host shell can call
   (one group per event, PreToolUse carrying `CODEX_PRETOOL_MATCHER` at `bin/tezgah-setup::CODEX_PRETOOL_MATCHER`),
   `skills/*` symlinks, `~/.codex/bin/consult`, and `mcp_servers.*` tables in
   `config.toml` (`ensure_toml_mcp`, `bin/tezgah-setup::ensure_toml_mcp`).
+  The subagent roles go to `$CODEX_HOME/agents/tezgah-*.toml`
+  (`bin/tezgah-setup::write_user_agents`).
 - **cursor** - `install_cursor` (`bin/tezgah-setup::install_cursor`): `~/.cursor/hooks.json`
   (tezgah entries replaced, a user's Orca entries merged), `skills/*` symlinks,
   `mcp.json` servers, and `cli-config.json` `statusLine`.
@@ -159,6 +163,11 @@ and drops the later ones.
 | skills | codex | `.agents/skills` from the cwd up to the repo root, `~/.agents/skills`, `$CODEX_HOME/skills`; one name in two dirs is listed twice, not merged | links in `$CODEX_HOME/skills` |
 | skills | cursor | `.agents/skills`, `.cursor/skills`, `~/.agents/skills`, `~/.cursor/skills`, then Claude's and Codex's project and user dirs; no documented winner | links in `~/.cursor/skills` |
 | skills | opencode | its own skill tool is denied; the router lists `~/.config/opencode/skills`, `~/.claude/skills`, `~/.agents/skills`, first wins (`bin/tezgah-setup::skill_groups`) | links and the router |
+| agents | claude | managed, the `claude --agents` flag, `.claude/agents`, `~/.claude/agents`, plugin agents namespaced `plugin:name`; a dir absent at start is not watched | `~/.claude/agents`, written at install |
+| agents | codex | `$CODEX_HOME/agents`, `/etc/codex/agents`, `.codex/agents` (trusted repos only), read at config load | `$CODEX_HOME/agents`, written at install |
+| agents | cursor | `cursor-agent`: `.cursor/agents`, then `.claude/agents`, `.grok/agents`, plugin agents; first name wins; no user dir; read at process start. The editor's docs add `~/.cursor/agents` and `~/.claude/agents` | `.cursor/agents` per repo at session start, in the CLI's line format (`hooks/tezgah_agents.py::render_md_cursor`) |
+| agents | opencode | `~/.config/opencode/agents`, `.opencode/agents`, merged per field | `config` hook injection, `.opencode/agents` as fallback |
+| agents | omp | `.omp/agents`, `~/.omp/agent/agents`, extensions, bundled | `~/.omp/agent/agents`, written at install |
 | hooks | claude | user `settings.json` rows (Orca's), project rows, the plugin's `hooks/hooks.json` (tezgah's); every matching row runs, none is ordered before another | plugin rows |
 | hooks | codex, cursor | `hooks.json` array order, then the repo's `.codex/` or `.cursor/hooks.json`; Codex runs a row only once its hash is trusted | own rows after Orca's |
 | hooks | opencode | every `*.js`/`*.ts` in `plugins/` and `plugin/`; `tezgah.js` is linked into both, and its `globalThis.__tezgahPluginLoaded` guard makes the second load return `{}` | the plugin |

package/docs/judge.md

@@ -138,7 +138,7 @@ shape, so a caller that needs a typed answer takes them like Jev.
 | Carrier | Endpoint | Credential (env, else file, stripped) | Body |
 |---|---|---|---|
 | `typesafe` | `https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY`, else `~/.config/typesafe/key`, else the active omp login (`~/.omp/agent/agent.db`, read-only; `typesafe_key`, `hooks/tezgah_paths.py::typesafe_key`) | `{state, model, questions}` |
-| `jev-openrouter` | `https://openrouter.ai/api/v1/systemone` | `OPENROUTER_API_KEY`, else `~/.config/openrouter/key` | the same, a bare `jev-*` id sent as `typesafe/<id>` |
+| `jev-openrouter` | `https://openrouter.ai/api/v1/systemone` | `OPENROUTER_API_KEY`, else `~/.config/openrouter/key` | the same; a bare `jev-*` id is sent as it is, and OpenRouter maps it onto `typesafe/` |
 | `jev-cloudflare` | `https://api.cloudflare.com/client/v4/accounts/<id>/ai/run` | `JEV_CLOUDFLARE_API_TOKEN`, else `CLOUDFLARE_API_TOKEN`, else `~/.config/cloudflare/token`; the account id from `CLOUDFLARE_ACCOUNT_ID`, else `~/.config/cloudflare/account_id` | `{model: "typesafe/jev", input: {state, questions}}`; the reply is read bare or inside `result` |
 | `jev-compatible` | `JEV_API_BASE_URL`, used verbatim | `JEV_API_KEY` | TypeSafe's, the model from `TEZGAH_JEV_MODEL` if set |
 | `clef`, `clef-flash` | `https://api.cloudflare.com/client/v4/accounts/<id>/ai/run/@cf/cloudflare/<name>` | the Cloudflare token and account id above | `{model: "<name>", state, questions}`; the reply read like Cloudflare's above |
@@ -148,6 +148,8 @@ reads, so one export serves both. `TEZGAH_JEV_PROVIDER` chooses the carrier,
 else `JEV_PROVIDER`, else `jev` in `~/.config/tezgah/config.json`, else `auto`
 (`jev_choice`, `hooks/tezgah_paths.py::jev_choice`). The values are `auto`,
 `typesafe`, `openrouter`, `cloudflare`, `compatible`, `clef` and `clef-flash`.
+The Workers AI ids `@cf/cloudflare/clef` and `@cf/cloudflare/clef-flash` name
+the same two (`jev_name`, `hooks/tezgah_paths.py::jev_name`).
 `tezgah-setup --jev <value>` writes the config key
 (`set_jev`, `bin/tezgah-setup::set_jev`). `auto`
 asks every carrier that resolves, in the table's order (`jev_carriers`,

package/docs/layers.md

@@ -76,7 +76,7 @@ lessons and research lines.
 Must not own the loop, the model, the tools or the network. tezgah never runs
 the work and never rolls back on its own - rollback is the explicit
 `bin/tezgah-rollback` - and the subagents it defines are rendered into a host's
-own agent surface for that host to run (`hooks/tezgah_agents.py:2-22`).
+own agent surface for that host to run (`hooks/tezgah_agents.py:2-30`).
 
 ## The boundary, one term at a time
 

package/docs/models.md

@@ -59,21 +59,21 @@ invoices).
 | Host | Family | Where the model lands |
 |---|---|---|
 | Claude Code | anthropic | the agent file's alias and `effort:` (`_model_lines`): an alias follows the provider and keeps the main session's variant, where a full id breaks on Bedrock, Vertex and a gateway (code.claude.com/docs/en/sub-agents) |
-| Codex | openai | `model` and `model_reasoning_effort` in `.codex/agents/*.toml` |
+| Codex | openai | `model` and `model_reasoning_effort` in `$CODEX_HOME/agents/*.toml` |
 | opencode | any | a selector `--refresh` found in `opencode models` for the slot's model under any configured provider (`resolve_opencode`); none found, no model line, so the agent inherits. The slot's effort rides the JSON agent config as `reasoningEffort` (opencode.ai/docs/agents) |
 | omp | anthropic when the session default is an Anthropic model, any otherwise (`omp_mode`); a non-Anthropic default is `any`, never a silent fall back to the Anthropic column | `task.agentModelOverrides`, which omp resolves before the agent or bundled model (omp's own docs: `omp://task-agent-discovery.md`, *Model and structured-output precedence*); every slot is written, the frontier row included, so no agent in the row runs on the session default; each override is a **fallback chain** (`omp_overrides`, `_chain`): the mode's family first, then what `fallback` in `~/.config/tezgah/config.json` allows (`tp.fallback_policy`) over the families this machine holds a credential for (`funded_families` reads omp's auth store and the provider env keys; a family it cannot see is left out, never guessed in) - `vendor`, the default, keeps only the session vendor's model (`openrouter/anthropic/claude-opus-5.5:<effort>` behind an Anthropic session, `OPENROUTER_ID`), so a 429 never moves an Opus session's subagent onto GPT or GLM; `any` adds every other funded family, rotated per agent; `none` writes the first entry alone - omp splits the chain into per-spawn patterns (omp's own docs: `omp://settings.md (its `retry.fallbackChains` section)`), so one provider's 429 falls through instead of killing the spawn, measured before this: 24 of 26 post-routing 429s hit a subagent's first request, all on one Opus account every slot shared; `apply_omp` also writes `modelRoles.plan` and `.slow` on that frontier row (same record, same ownership) so plan mode designs on it, and their fallbacks go to `retry.fallbackChains.<role>` under the same `fallback` rule, the only chain keys tezgah owns (`default` and provider-keyed chains stay the user's); `apply_omp` writes through the installer's own binary and agent dir, from HOME so a repository's `.omp/config.yml` never leaks machine-wide, and touches only the entries tezgah wrote (recorded in `~/.config/tezgah/models.json` as `omp_written`; a machine written before that record is adopted by its value, `_ours_by_shape`); a changed `fallback` reaches omp on the next `tezgah-route --refresh` or `tezgah-setup --install` |
 | dsh | - | none: no model setting was found to write |
 
 The orchestrator agent keeps `model: inherit`: it is the main thread's own agent.
 
-| Cursor | - | reads `.claude/agents/` today; Cursor wants its own model ids with the effort **inside** the id (`claude-opus-5[effort=high]`, cursor.com/docs/subagents), and no id this table names was verified against Cursor's models page - so a `.cursor/agents/` rendering that pins a model is not generated yet |
+| Cursor | - | `model: inherit` in `.cursor/agents/*.md` (`render_md_cursor`): `cursor-agent` passes the value through as a raw id, an alias such as `opus` is not in its model list, and the effort belongs **inside** the id (`claude-opus-5[effort=high]`, cursor.com/docs/subagents). No id this table names was verified against Cursor's models page, so no tier model is pinned there yet |
 
 omp's bundled agents are routed through the same record (omp's own docs: `omp://task-agent-discovery.md`, *Bundled agents*): `scout` on the explore slot, `sonic` on the cheap slot, `task` on the standard slot, and `reviewer`/`security-reviewer` left to inherit, because a review is frontier work. A user's own value for any of them wins (see the ownership rule above). Those two are the gap this leaves: the record carries no entry for them, so a session on a cheap model reviews on that model - routing them is one more `BUNDLED` entry, not decided here.
 
 ## What is not routed yet
 
 - **Claude Code's built-in subagents** (Explore, general-purpose, Plan) run on the session model. `CLAUDE_CODE_SUBAGENT_MODEL` and a settings `env` block exist but carry no effort, and whether a project agent with a built-in's name replaces it is not stated where it can be cited - so nothing is generated on a guess. What would close it: a documented per-agent effort for built-ins, or a confirmed name-collision rule.
-- **Codex's default subagent** (spawned with no agent file): only `.codex/agents/*.toml` carries a model today. What would close it: a documented `[agents]` default settable from a repo-scoped file tezgah already writes.
+- **Codex's default subagent** (spawned with no agent file): only `$CODEX_HOME/agents/*.toml` carries a model today. What would close it: a documented `[agents]` default settable from a file tezgah already writes.
 - **opencode's built-in agents**: the injected JSON could carry `model`/`reasoningEffort` for them, but the merge semantics for a built-in entry are not documented where they can be cited, and a wrong merge would replace a built-in prompt instead of adding a model.
 - **dsh**: the model is a plugin config, not an agent field. The composed profile carries `agent-default-model` with `config: {provider: deepseek-official, model: deepseek-flash}` (`dsh --profile web --dump-config`, 2026-09-30) and tezgah's managed patch block already patches plugin config by id (its `llm-pi-ai` row), so a `- id: agent-default-model` row would set the profile's model. Not written, because that knob is one model for the whole session - no `subagent*` entry in the composed tree carries a model - and a single session-wide model is the main thread's setting, which this design deliberately leaves alone ([why the main thread keeps one model](#the-shape)). What would close it: a per-agent model in dsh's config surface.
 
@@ -91,7 +91,9 @@ fixed:
    (`OVERRIDE`, `hooks/tezgah_models.py::OVERRIDE`) - the class the judge
    under-routed in its measurement, and the classes a wrong call cannot be
    undone on. A 12-brief fixture pins it: 8 high-stakes briefs route to
-   frontier, 4 near-miss controls do not (`tests/test_models.py`).
+   frontier, 4 near-miss controls do not (`tests/test_models.py`). Such a brief
+   that only reviews goes to `tezgah-security` instead (`REVIEW_ONLY`,
+   `hooks/tezgah_models.py::REVIEW_ONLY`).
 2. Otherwise the brief - redacted with the ledger's own reader
    (`redact`, `hooks/tezgah_integrity.py::redact`) - goes to the judge as one Choice over three tiers (`TIER_QUESTION`,
    `hooks/tezgah_models.py::TIER_QUESTION`). The judge asks the session's own model first ([judge](judge.md)).
@@ -99,9 +101,17 @@ fixed:
    the same session that wrote the rubric (2026-09-30, twice): under-route 0.025,
    accuracy 0.925 and 0.900, 392 ms median, about 656 input tokens per call; a
    keyword rule on the same set under-routed 0.100. The session model was not measured on that set.
-3. With no judgement (`judge-off`, no key, a failed call) `--phase` picks the tier
-   from the static table (`PHASE_TIER`, `hooks/tezgah_models.py::PHASE_TIER`), and
-   with no phase the middle tier is used.
+   The same call asks a second Choice (`ROLE_QUESTION`,
+   `hooks/tezgah_models.py::ROLE_QUESTION`): is the brief the whole job of a
+   specialist? A yes names that agent on its own tier (`AGENT_SLOT`,
+   `hooks/tezgah_models.py::AGENT_SLOT`). Before this question, sessions
+   spawned the five specialists 0 times in 121 delegations (2026-10-07 to 10-09).
+   Clef agreed on 9 of 10 briefs this session labelled (2026-10-09).
+3. With no judgement (`judge-off`, no key, a failed call) `--phase review` and
+   `--phase research` name the reviewer and the researcher (`PHASE_AGENT`,
+   `hooks/tezgah_models.py::PHASE_AGENT`). Another phase picks the tier from the
+   static table (`PHASE_TIER`, `hooks/tezgah_models.py::PHASE_TIER`). With no
+   phase the middle tier is used.
 
 The brief leaves the machine for the judge, like every judgement ([judge](judge.md)).
 Every routed call writes one `route` row to the session's ledger. The row names the

package/docs/operations.md

@@ -28,7 +28,6 @@ before an install is considered.
 | `--status [PATH]` | Print the armed/used checklist for PATH (default cwd) and stop — the same line as `bin/tezgah-status` (`bin/tezgah-setup::main`, `hooks/tezgah_context.py::health_lines`). It also prints the report's `config.json hosts (...) match the hosts wired (...)` row when the recorded list and the wiring on disk disagree (`hosts_row`), and nothing when they agree: install health is checked here, not only in a full report. |
 | `--agents [PATH]` | Regenerate PATH's per-repo subagent set (default cwd); outside a [root](glossary.md#root) it prints `no agents generated` (`bin/tezgah-setup::main`). |
 | `--write-manifest` | Regenerate the tracked `MANIFEST` from `git ls-files` and stop — the release step, its only writer, and it says so on a tree with no `.git` rather than writing an empty listing (`bin/tezgah-setup::write_manifest`, `bin/tezgah-setup::plugin_files`). |
-| `--write-plugin-agents` | Re-render the plugin's tracked `agents/*.md` from the role bodies `hooks/tezgah_agents.py` generates per repo, and stop — the release step that keeps the shipped reviewer from drifting from the generated one; `tests/test_agents.py` fails until it has run (`write_plugin_agents`, `plugin_agents`). |
 | `--deps` | Install the missing optional tools and stop; with `--install` the install already does it. Like `--install` and `--enable`, it exits 1 when a requested tool is still missing (`bin/tezgah-setup::main`). |
 | `--host-deps` | With `--install` or `--deps`, also install the missing third-party host CLIs (cursor-agent, pnpm, dsh). They are opt-in because each one is a vendor `curl \| sh` that uninstall does not take back. Every installer runs with a 600 s timeout, each `curl` with `--max-time 300` and each pipeline under `pipefail`, so a stalled or refused download fails instead of hanging or reading as success (audit M-9). |
 | `--mcp-schemas` | Measure the MCP tool-schema band by asking each registered server (`initialize` + `tools/list`) and stop (`bin/tezgah-setup::main`, `bin/tezgah-setup::mcp_schema_report`). |

package/docs/testing.md

@@ -171,7 +171,7 @@ into the test process would answer about the developer's real machine.
 | `tests/_probe_paths.py` | argv op, no payload (`:11`) | `roots`, `root_for`, `off`, `default_root`, `config`, `off_dirs`, `cache_dir`, `which_user`, `orx_bin`, `consult_options`, `have_typesafe_key`, `codegraph_bin` |
 | `tests/_probe_context.py` | JSON on stdin, `{"fn": ...}` (`:4-5`) | `context_for`, `health_lines`, `health_segments`, `record` |
 | `tests/_probe_integrity.py` | JSON on stdin (`:4-6`) | `note`, `note_tool`, `note_turn`, `kinds`, `events`, `prior_calls`, `counters`, `shortcut_command`, `shortcut_edit`, `stop_reason`, `verify_command` |
-| `tests/_probe_agents.py` | JSON on stdin (`:3-4`) | `sync_root`, `opencode_json`, `cleanup`, `detect` |
+| `tests/_probe_agents.py` | JSON on stdin (`:3-4`) | `sync_root`, `opencode_json`, `cleanup`, `detect`, `omp`, `user`, `steering` |
 | `tests/_probe_gate.py` | JSON on stdin (`:4-8`) | the shared gate `decision(tool, input, cwd, session_id)`; `capture_log` plants a stub `tezgah_snapshot` in `sys.modules`, so the snapshot call site is pinned whether or not that module has landed |
 
 A probe is invoked through `support.run`/`run_json` with its path constant

package/hooks/tezgah_agents.py

@@ -1,16 +1,24 @@
 #!/usr/bin/env python3
-"""Per-repo subagent definitions, generated from the detected infrastructure.
-
-When a session starts inside a tezgah root, the enclosing repo gets a small set
-of specialized agents, rendered into every host surface that actually exists:
-
-  Claude Code / Cursor  `.claude/agents/*.md`   (Cursor reads this dir natively)
-  opencode              `.opencode/agents/*.md` (fallback) + config injection
-  Codex                 `.codex/agents/*.toml`
-
-A role is only emitted when the capability it needs is present (the reviewer
-needs the code graph); the three tier workers are emitted in every root,
-because `tezgah-route` names one of them for every delegated task. The whole set is regenerated when either this manifest
+"""Subagent definitions, generated from the detected infrastructure.
+
+One role set, rendered into every host surface that actually exists, at the
+place each host loads it from:
+
+  Claude Code  `~/.claude/agents/*.md`          user-level, written at install
+  Codex        `$CODEX_HOME/agents/*.toml`      user-level, written at install
+  omp          `~/.omp/agent/agents/*.md`       user-level, written at install
+  Cursor       `.cursor/agents/*.md`            per repo, at session start
+  opencode     `.opencode/agents/*.md` (fallback) + config injection, per repo
+
+Claude and Codex miss a repo agents dir written during their first session
+(Claude does not watch a dir that was absent at start; Codex reads roles at
+config load and ignores `.codex/agents` in an untrusted repo), so their roles
+live user-level; a repo's `.claude/agents` and `.codex/agents` files an older
+tezgah wrote are swept. Cursor's CLI reads no user dir, so it keeps a per-repo
+dir. A role is only emitted when the capability it needs is present (the
+reviewer needs the code graph); the three tier workers are emitted in every root,
+because `tezgah-route` names one of them for every delegated task. The per-repo
+set is regenerated when either this manifest
 or the repo's infrastructure changes, so the definitions stay updatable instead
 of drifting. Hosts with no such surface (dsh) get nothing here; the orchestrator
 directive in the injected contract already covers them. The generated dirs are
@@ -30,16 +38,20 @@ import subprocess
 import tezgah_models as tm
 from tezgah_paths import (CONFIG_DIR, HOME, codegraph_bin, host_installed, off,
                           root_for)
+from tezgah_paths import HOST_DIRS as HOST_HOMES
 
 MARKER = "# tezgah: managed by tezgah-agents; do not edit"
 STATE = os.path.join(CONFIG_DIR, "agents.state.json")
-# hosts with a file-based custom-agent surface, and where it lives, relative to
-# the repo. Cursor reads .claude/agents/ natively, so one markdown dir serves
-# both when either is installed; the *detection* of whether a host is installed
-# lives in tezgah_paths.host_installed, not here.
+# hosts with a file-based custom-agent surface; the *detection* of whether a
+# host is installed lives in tezgah_paths.host_installed, not here.
 FILE_HOSTS = ("claude", "opencode", "codex", "cursor")
+# the file hosts whose roles live in their user dir (user_agents), written by
+# the installer; the others get a per-repo dir from sync_root
+USER_HOSTS = ("claude", "codex")
+# the repo-relative agent dirs. Claude's and Codex's are no longer written, only
+# swept: a copy an older tezgah left there would sit beside the user-level one.
 HOST_DIRS = {"claude": os.path.join(".claude", "agents"),
-             "cursor": os.path.join(".claude", "agents"),
+             "cursor": os.path.join(".cursor", "agents"),
              "opencode": os.path.join(".opencode", "agents"),
              "codex": os.path.join(".codex", "agents")}
 # Stack markers -> a short hint. Exact commands are left to the repo's own docs
@@ -61,10 +73,11 @@ MCP_PREFIXES = ("mcp__codegraph__", "mcp__plugin_tezgah_codegraph__")
 GRAPH_SELECT = ",".join(p + t for t in GRAPH_MCP for p in MCP_PREFIXES)
 GRAPH_CLI = ("callers", "callees", "impact", "node", "files")
 GRAPH_TOOLS = ", ".join("`codegraph %s`" % verb for verb in GRAPH_CLI)
-# A role with no shell (Claude `disallowedTools` Bash, opencode `bash: deny`)
+# A role with no shell (Claude `disallowedTools` Bash, opencode `bash: deny`;
+# Cursor's `readonly` documents no shell scope, so it is held to the same recipe)
 # cannot run `git diff` or the CLI, so its blast radius comes from the caller's
 # brief and the MCP impact tool; a role with a shell runs the diff itself.
-NO_SHELL = ("claude", "opencode")
+NO_SHELL = ("claude", "opencode", "cursor")
 # The floor every graph role carries (gortex edge provenance): the index holds
 # only the edges its parser saw, so an absence of callers is a coverage gap
 # until shown otherwise, never a safety verdict.
@@ -114,7 +127,7 @@ def _graph_howto(host):
                 "`codegraph status`). Do not call the `xd://mcp__codegraph_*`\n"
                 "devices: omp refuses them with \"Concurrent write refused\"\n"
                 "while the parent session holds the index." % GRAPH_TOOLS)
-    if host == "opencode":
+    if host in ("opencode", "cursor"):
         return ("codegraph is registered as an MCP server (%s). You have no\n"
                 "shell, so the codegraph CLI is out of reach: use those MCP tools."
                 % ", ".join("`%s`" % t for t in GRAPH_MCP))
@@ -440,10 +453,8 @@ def _claude_model(model):
 
 def _model_lines(name, family, model_fmt, effort_fmt):
     """The model (and effort) lines the table gives this agent on a family;
-    `model: inherit` on Claude/Cursor for an agent with no slot. Cursor reads
-    this same file but wants its own ids and the effort inside the id
-    (`claude-opus-5[effort=high]`, cursor.com/docs/subagents) - unverified for
-    the ids this table names, so Cursor is documented, not guessed at."""
+    `model: inherit` on Claude for an agent with no slot. Cursor gets
+    `model: inherit` always (render_md_cursor)."""
     picked = tm.pick(name, family)
     if not picked:
         return ["model: inherit"] if family == "anthropic" else []
@@ -462,35 +473,34 @@ def _fold(desc, width=74):
 
 
 def render_md(name, description, readonly, body):
-    """Claude Code / Cursor markdown. Cursor ignores unknown keys and honours
-    `readonly`; Claude denies the write/shell tools explicitly."""
+    """Claude Code markdown (`~/.claude/agents`), which the Cursor editor also
+    reads (cursor.com/docs/subagents). The description is one line: Cursor's
+    line parser reads a folded `>` block as ">", and Claude's parser re-quotes
+    a plain value YAML rejects (a `: ` inside it). Claude denies the write/shell
+    tools explicitly; `readonly` is Cursor's key, which Claude ignores."""
     lines = ["---", MARKER + " (manifest %s)" % manifest_sha(),
-             "name: %s" % name, "description: >"]
-    lines += _fold(description)
+             "name: %s" % name, "description: %s" % " ".join(description.split())]
     lines += _model_lines(name, "anthropic", "model: %s", "effort: %s")
     if readonly:
-        # `disallowedTools` is Claude's; `readonly` is Cursor's. Both parsers
-        # ignore the other's field.
         lines.append("readonly: true")
         lines.append("disallowedTools: Write, Edit, NotebookEdit, Bash, Agent")
     lines.append("---")
     return "\n".join(lines) + "\n\n" + body.strip() + "\n"
 
 
-def plugin_agents():
-    """{filename: text} for the plugin's own tracked `agents/` dir.
-
-    The graph roles' Claude render, from the same body the per-repo files get,
-    so the shipped copy cannot drift from the generated one. The MARKER line is
-    dropped: the copy is tracked, never swept by `_remove_stale`, and its
-    manifest sha would turn every edit of this module into a stale file.
-    `tezgah-setup --write-plugin-agents` writes it; a test pins it."""
-    out = {}
-    for name, desc, _cap, body, readonly in ROLES:
-        if name in GRAPH_ROLES:
-            lines = render_md(name, desc, readonly, body("claude")).split("\n")
-            out[name + ".md"] = "\n".join(lines[:1] + lines[2:])
-    return out
+def render_md_cursor(name, description, readonly, body):
+    """Cursor `.cursor/agents/*.md`. cursor-agent splits each frontmatter line
+    at its first ':' (no YAML), passes `model` through as a raw id and has no
+    `effort` key, so: a one-line description, `model: inherit` (the only id
+    portable across Cursor accounts), `readonly`, and no `tools` line - its
+    comma split would cut a Claude `Agent(a, b)` list into broken names."""
+    lines = ["---", MARKER + " (manifest %s)" % manifest_sha(),
+             "name: %s" % name, "description: %s" % " ".join(description.split()),
+             "model: inherit"]
+    if readonly:
+        lines.append("readonly: true")
+    lines.append("---")
+    return "\n".join(lines) + "\n\n" + body.strip() + "\n"
 
 
 def render_md_opencode(name, description, readonly, body):
@@ -529,13 +539,19 @@ def render_md_omp(name, description, body, tools=("read", "grep", "glob", "bash"
     return "\n".join(lines) + "\n\n" + body.strip() + "\n"
 
 
+def _active_roles(root):
+    """The roles a user-level dir holds: none under `agents-off`, else those
+    whose capability the machine has (`~/.no-graph` counts as the repo's)."""
+    if off("agents-off"):
+        return []
+    infra = detect_infra(os.path.expanduser(root))
+    return [r for r in ROLES if r[2](infra)]
+
+
 def omp_user_agents(root="~"):
     """{filename: text} for omp's user agent dir (~/.omp/agent/agents); empty
     under `agents-off`, so the installer's sweep removes the files."""
-    if off("agents-off"):
-        return {}
-    infra = detect_infra(os.path.expanduser(root))
-    active = [r for r in ROLES if r[2](infra)]
+    active = _active_roles(root)
     names = [r[0] for r in active]
     if not names:
         return {}
@@ -550,20 +566,50 @@ def omp_user_agents(root="~"):
     return out
 
 
+def user_agent_dir(host):
+    """Where a USER_HOSTS host loads agents from in every session: Claude's
+    `~/.claude/agents`, Codex's `$CODEX_HOME/agents` (default ~/.codex)."""
+    return os.path.join(HOST_HOMES[host], "agents")
+
+
+def user_agents(host, root="~"):
+    """{filename: text} for a USER_HOSTS host's user agent dir, each file
+    carrying MARKER so the installer sweeps only tezgah's; empty under
+    `agents-off`, so that sweep removes them. Codex gets no orchestrator: the
+    main thread orchestrates there."""
+    active = _active_roles(root)
+    names = [r[0] for r in active]
+    if not names:
+        return {}
+    if host == "codex":
+        return {name + ".toml": render_toml(name, desc, readonly, body("codex"))
+                for name, desc, _cap, body, readonly in active}
+    out = {name + ".md": render_md(name, desc, readonly, body("claude"))
+           for name, desc, _cap, body, readonly in active}
+    out["tezgah-orchestrator.md"] = render_orch_md(names)
+    return out
+
+
 def steering(root, host=None):
     """One line naming the generated specialists this host can spawn, or None.
 
     Nothing else in the contract points the main agent at them, so a model
     reached for the host's generic explorer instead. Existence is read from
     disk, not from the capabilities: a specialist is named only when its file
-    is there for the host to load - omp's user agent dir on omp, the repo's
-    generated dirs everywhere else. A repo's `.no-graph` turns the graph off
-    there, so a graph role is not named in it even when omp's user-level file
+    is there for the host to load - the user agent dir on omp, Claude and
+    Codex, the repo's own dir on Cursor and opencode, and all of them for a
+    host that does not say which it is. A repo's `.no-graph` turns the graph
+    off there, so a graph role is not named in it even when a user-level file
     exists."""
     if host == "omp":
         dirs = [os.path.join(HOME, ".omp", "agent", "agents")]
+    elif host in USER_HOSTS:
+        dirs = [user_agent_dir(host)]
+    elif host in HOST_DIRS:
+        dirs = [os.path.join(root, HOST_DIRS[host])]
     else:
-        dirs = [os.path.join(root, d) for d in set(HOST_DIRS.values())]
+        dirs = ([user_agent_dir(h) for h in USER_HOSTS]
+                + [os.path.join(root, HOST_DIRS[h]) for h in ("cursor", "opencode")])
     have = {os.path.splitext(os.path.basename(p))[0]
             for d in dirs for p in glob.glob(os.path.join(d, "tezgah-*.*"))}
     if os.path.exists(os.path.join(root, ".no-graph")):
@@ -656,14 +702,18 @@ def _write_if_changed(path, text):
     return True
 
 
-def _remove_stale(directory, wanted):
-    """Delete only tezgah-managed files no longer in the wanted set."""
+def remove_stale(directory, wanted):
+    """Delete only tezgah-managed files no longer in the wanted set; returns
+    the paths removed."""
+    removed = []
     for path in glob.glob(os.path.join(directory, "tezgah-*.*")):
         if os.path.basename(path) not in wanted and _is_managed(_read(path)):
             try:
                 os.remove(path)
+                removed.append(path)
             except OSError:
                 pass
+    return removed
 
 
 BLOCK_BEGIN = ("# tezgah: generated agents (managed; removed by "
@@ -796,66 +846,49 @@ def sync_root(root, report_steady=False):
         return None
     disabled = off("agents-off")
     infra = detect_infra(root)
-    hosts = set() if disabled else set(infra["hosts"])
+    # Claude's and Codex's roles are user-level (user_agents): only Cursor and
+    # opencode get a dir here
+    hosts = set() if disabled else set(infra["hosts"]) - set(USER_HOSTS)
     active = [] if disabled else [r for r in ROLES if r[2](infra)]
     names = [r[0] for r in active]
 
-    # markdown: one dir serves Claude and Cursor (Cursor reads .claude/agents/)
-    md_dir = os.path.join(root, HOST_DIRS["claude"]) if hosts & {"claude", "cursor"} else None
+    cursor_dir = os.path.join(root, HOST_DIRS["cursor"]) if "cursor" in hosts else None
     oc_dir = os.path.join(root, HOST_DIRS["opencode"]) if "opencode" in hosts else None
-    codex_dir = os.path.join(root, HOST_DIRS["codex"]) if "codex" in hosts else None
 
     written, removed = 0, 0
     paths = []
+    wanted = {h: set() for h in HOST_DIRS}
 
-    def emit(directory, wanted, name, text):
+    def emit(host, name, text):
         nonlocal written
-        wanted.add(name)
-        path = os.path.join(directory, name)
+        wanted[host].add(name)
+        path = os.path.join(root, HOST_DIRS[host], name)
         if _write_if_changed(path, text):
             written += 1
         paths.append(path)
 
-    wanted_md, wanted_oc, wanted_codex = set(), set(), set()
-
-    def sweep(directory, wanted):
-        nonlocal removed
-        before = set(os.path.basename(p) for p in glob.glob(os.path.join(directory, "tezgah-*.*")))
-        _remove_stale(directory, wanted)
-        after = set(os.path.basename(p) for p in glob.glob(os.path.join(directory, "tezgah-*.*")))
-        removed += len(before - after)
-
-    if md_dir and names:  # Claude Code + Cursor
+    # Cursor gets no orchestrator: its files are subagents the main thread
+    # delegates to, and the orchestrator is a primary agent
+    if cursor_dir and names:
         for name, desc, _cap, body, readonly in active:
-            emit(md_dir, wanted_md, name + ".md", render_md(name, desc, readonly, body("claude")))
-        emit(md_dir, wanted_md, "tezgah-orchestrator.md", render_orch_md(names))
+            emit("cursor", name + ".md",
+                 render_md_cursor(name, desc, readonly, body("cursor")))
 
     if oc_dir and names:  # opencode
         for name, desc, _cap, body, readonly in active:
-            emit(oc_dir, wanted_oc, name + ".md",
+            emit("opencode", name + ".md",
                  render_md_opencode(name, desc, readonly, body("opencode")))
-        emit(oc_dir, wanted_oc, "tezgah-orchestrator.md", render_orch_md_opencode(names))
-
-    if codex_dir and names:  # Codex (no orchestrator agent; the main thread orchestrates)
-        for name, desc, _cap, body, readonly in active:
-            emit(codex_dir, wanted_codex, name + ".toml",
-                 render_toml(name, desc, readonly, body("codex")))
+        emit("opencode", "tezgah-orchestrator.md", render_orch_md_opencode(names))
 
-    # The sweep runs over every dir this module can write, not only the selected
-    # ones: a host dropped from the config, or a capability that disappeared,
-    # must not leave tezgah agents behind for the host to keep loading.
-    sweep(os.path.join(root, HOST_DIRS["claude"]), wanted_md)
-    sweep(os.path.join(root, HOST_DIRS["opencode"]), wanted_oc)
-    sweep(os.path.join(root, HOST_DIRS["codex"]), wanted_codex)
+    # The sweep runs over every dir this module ever wrote, not only the
+    # selected ones: a host dropped from the config, a capability that
+    # disappeared, or a `.claude`/`.codex` copy from before the roles moved
+    # user-level must not stay behind for a host to keep loading.
+    for host, directory in HOST_DIRS.items():
+        removed += len(remove_stale(os.path.join(root, directory), wanted[host]))
 
     if paths:
-        dirs = set()
-        if md_dir:
-            dirs.add(HOST_DIRS["claude"])
-        if oc_dir:
-            dirs.add(HOST_DIRS["opencode"])
-        if codex_dir:
-            dirs.add(HOST_DIRS["codex"])
+        dirs = {HOST_DIRS[h] for h in ("cursor", "opencode") if wanted[h]}
         ex = ensure_exclude(root, dirs)
         if ex:
             paths.append(ex)
@@ -868,7 +901,7 @@ def sync_root(root, report_steady=False):
                 % (len(names), ", %d removed" % removed if removed else ""))
     if removed:
         return "%d stale agent file(s) removed" % removed
-    if report_steady and names and (md_dir or oc_dir or codex_dir):
+    if report_steady and names and (cursor_dir or oc_dir):
         return "%d agent(s) current" % len(names)
     return None
 

package/hooks/tezgah_context.py

@@ -690,7 +690,8 @@ def autoindex(root):
 
 
 def sync_agents(root):
-    """Generate/refresh this repo's per-host subagent definitions (best effort)."""
+    """Generate/refresh this repo's Cursor and opencode subagent files (best
+    effort); Claude's and Codex's roles are user-level, written at install."""
     try:
         from tezgah_agents import sync_root
         return sync_root(root)

package/hooks/tezgah_judge.py

@@ -65,7 +65,8 @@ import tezgah_store
 URL = "https://api.typesafe.ai/v1/systemone"
 MODEL = "jev-latest"
 # The other Jev carriers (`JEV_CARRIERS`): OpenRouter's System One endpoint,
-# which takes TypeSafe's body and namespaces the model `typesafe/<id>`; and
+# which takes TypeSafe's body and maps a bare `jev-*` id onto `typesafe/` itself
+# (`typesafe/jev-latest` is no model there: a live 400 on 2026-10-09); and
 # Cloudflare Workers AI, whose run route wraps the state and questions in
 # `input` and serves the one alias `typesafe/jev`. A System One-compatible URL
 # is the user's own (`JEV_API_BASE_URL`), so it has no constant here.
@@ -157,7 +158,7 @@ def _jev_call(provider, model, state, questions):
         return CLOUDFLARE_MODEL, url, {"model": CLOUDFLARE_MODEL, "input": {
             "state": state, "questions": questions}}
     if provider == "jev-openrouter":
-        used = model if "/" in model else "typesafe/" + model
+        used = model
         url = override("TEZGAH_JEV_OPENROUTER_URL", JEV_OPENROUTER_URL)
     elif provider == "jev-compatible":
         used = os.environ.get("TEZGAH_JEV_MODEL", "").strip() or model
@@ -215,12 +216,17 @@ SESSION_ARGV = {
 # prompt asked for; the judge's state can be a screen's untrusted text, so the
 # run gets an inline config (`OPENCODE_CONFIG_CONTENT`) that denies every tool -
 # the same probe with it wrote nothing. cursor-agent's `--mode ask` refused the
-# same shell call, and codex's `-s read-only` sandbox has no network.
+# same shell call, and codex's `-s read-only` sandbox has no network. Inline
+# config overrides the user's files only key by key, and an agent's own
+# `permission` wins over the top-level one, so the deny is repeated for the two
+# built-in agents `run` uses.
+_DENY_ALL = {"*": "deny", "bash": "deny", "edit": "deny", "webfetch": "deny",
+             "external_directory": "deny"}
 SESSION_ENV = {
     "opencode": {"OPENCODE_CONFIG_CONTENT": json.dumps({
-        "permission": {"*": "deny", "bash": "deny", "edit": "deny", "webfetch": "deny",
-                       "external_directory": "deny"},
-        "tools": {"*": False}})},
+        "permission": _DENY_ALL, "tools": {"*": False},
+        "agent": {name: {"permission": _DENY_ALL, "tools": {"*": False}}
+                  for name in ("build", "plan")}})},
 }
 NO_SESSION = ("no session CLI to ask (no omp, Claude Code, opencode, Cursor or Codex "
               "session marker or TEZGAH_JUDGE_CLI/judge_cli pick, or that CLI missing)")
@@ -386,8 +392,9 @@ def ask(state, questions, *, model=MODEL, timeout=30, attempts=2, deadline=None,
         return result
     refused = None
     session = tp.session_cli()
-    if only is None and session and (openrouter_key()
-                                     or any(s for _, s in tp.jev_carriers())):
+    # only a session CLI that was asked can have failed before a refusal
+    if session in (p for p, _ in tried) and (openrouter_key()
+                                            or any(s for _, s in tp.jev_carriers())):
         refused = ("fallback=%s refuses a third-party judge after %s failed"
                    % (tp.fallback_policy(), session))
     _record(None, None, failed="; ".join(failed), refused=refused)

package/hooks/tezgah_models.py

@@ -709,6 +709,39 @@ TIER_QUESTION = {
                     "a hard-to-reverse decision",
     },
 }
+# The second question in the same batched call: whether the brief is one of the
+# specialists' jobs. Before it existed route() could only name a tier, and from
+# 2026-10-07 to 10-09 the five specialists were spawned 0 times in 121
+# delegations while the generic `task` agent took 86. Every specialist but the
+# docs writer is read-only or check-only, so a brief that changes code is `none`.
+ROLE_QUESTION = {
+    "type": "choice",
+    "instructions": (
+        "Is `task` the whole job of one of these specialist agents? Pick `none` "
+        "when the task writes or changes source code, or mixes a specialist job "
+        "with code changes."),
+    "criteria": {
+        "none": "writing or changing code, or anything not listed below",
+        "tester": "only running the checks or tests a change reaches and reporting "
+                  "their output; no edits",
+        "docs": "writing or repairing documentation pages or their path:line "
+                "citations",
+        "security": "a read-only security review of a change or surface",
+        "ui": "inspecting a running web or mobile app's screens against a design "
+              "floor or accessibility",
+        "researcher": "a research line: hypotheses, literature, experiments, a report",
+        "reviewer": "an adversarial read-only review of a diff, branch or pull request",
+    },
+}
+ROLE_AGENT = {role: "tezgah-" + role for role in ROLE_QUESTION["criteria"] if role != "none"}
+# Without a judgement, the phase names the specialist where it is one.
+PHASE_AGENT = {"review": "tezgah-reviewer", "research": "tezgah-researcher"}
+# An override brief never leaves the machine, so the rule decides the one
+# specialist it can name: a security review that writes nothing.
+REVIEW_ONLY = re.compile(r"\b(?:review|audit|assess)\w*\b", re.I)
+# `change` and `update` are left out: in "review the auth change" they are nouns.
+WRITES = re.compile(r"\b(?:fix|implement|edit|write|add|refactor|patch|migrate|"
+                    r"rename|delete|remove|rotate)\w*\b", re.I)
 
 
 def route(brief, phase=None, ask=None):
@@ -724,23 +757,37 @@ def route(brief, phase=None, ask=None):
     reply is the same as no reply and this never raises."""
     hit = OVERRIDE.search(brief or "")
     if hit:
+        if REVIEW_ONLY.search(brief) and not WRITES.search(brief):
+            return _agent("tezgah-security", "override %r, review only" % hit.group(0),
+                          "rule")
         return _pick("frontier", "override: %r" % hit.group(0), "rule")
-    result = ask({"task": ti.redact(brief or "")}, {"tier": TIER_QUESTION}) if ask else None
+    result = ask({"task": ti.redact(brief or "")},
+                 {"tier": TIER_QUESTION, "role": ROLE_QUESTION}) if ask else None
     choice = tj.choice(result, "tier")
     if choice in JEV_TIER:
         chance = tj.noul(result, "tier", choice)
-        out = _pick(JEV_TIER[choice], "jev %s%s" % (
-            choice, "" if chance is None else " %.2f" % chance), "jev")
+        why = "jev %s%s" % (choice, "" if chance is None else " %.2f" % chance)
+        role = tj.choice(result, "role")
+        out = (_agent(ROLE_AGENT[role], "%s, role %s" % (why, role), "jev")
+               if role in ROLE_AGENT else _pick(JEV_TIER[choice], why, "jev"))
         out["judge"] = "%s/%s" % (result.get("provider") or "-",
                                   result.get("model") or "-")
         out["judged"] = result
         return out
+    if phase in PHASE_AGENT:
+        return _agent(PHASE_AGENT[phase], "no judgement; phase %s names it" % phase,
+                      "phase")
     if phase in PHASE_TIER:
         return _pick(PHASE_TIER[phase], "no judgement; static table for phase %s" % phase,
                      "phase")
     return _pick("standard", "no judgement and no phase; the middle tier", "default")
 
 
+def _agent(agent, why, via):
+    """A specialist, on the tier its model slot names (`AGENT_SLOT`)."""
+    return dict(_pick(AGENT_SLOT[agent], why, via), agent=agent)
+
+
 def _pick(tier, why, via):
     return {"agent": "tezgah-" + tier, "tier": tier, "why": why, "via": via,
             "judge": None, "judged": None}

package/hooks/tezgah_paths.py

@@ -592,17 +592,25 @@ JEV_CHOICES = ("auto", "typesafe", "openrouter", "cloudflare", "compatible",
                "clef", "clef-flash")
 
 
+def jev_name(value):
+    """A carrier choice as written by a user, lowercased and with the Workers AI
+    catalog prefix dropped: `@cf/cloudflare/clef-flash` is what Cloudflare's
+    dashboard and docs show, and it names the `clef-flash` carrier."""
+    value = value.strip().lower()
+    return value[len("@cf/cloudflare/"):] if value.startswith("@cf/cloudflare/") else value
+
+
 def jev_choice():
     """TEZGAH_JEV_PROVIDER, else JEV_PROVIDER (jev-mcp's name), else config.json
-    `jev`, else `auto` - lowercased. An unknown value is kept, so it resolves to
-    no carrier instead of silently to another one."""
+    `jev`, else `auto` - through `jev_name`. An unknown value is kept, so it
+    resolves to no carrier instead of silently to another one."""
     for env in ("TEZGAH_JEV_PROVIDER", "JEV_PROVIDER"):
-        value = os.environ.get(env, "").strip().lower()
+        value = jev_name(os.environ.get(env, ""))
         if value:
             return value
     cfg = config()
     value = cfg.get("jev") if isinstance(cfg, dict) else None
-    value = value.strip().lower() if isinstance(value, str) else ""
+    value = jev_name(value) if isinstance(value, str) else ""
     return value or "auto"
 
 
@@ -610,18 +618,25 @@ def jev_carriers():
     """[(carrier, secret), ...] the chosen Jev carriers in the order the seam
     asks them. `auto`: every carrier whose credential resolves. A named one: that
     carrier alone, its secret None when it does not resolve - the seam records
-    why rather than substituting another carrier."""
-    compatible = (os.environ.get("JEV_API_KEY", "").strip() or None
-                  if os.environ.get("JEV_API_BASE_URL", "").strip() else None)
-    workers_ai = cloudflare_token() if cloudflare_account() else None
-    found = [("typesafe", typesafe_key()), ("jev-openrouter", openrouter_key()),
+    why rather than substituting another carrier. Only the chosen carrier's
+    credential is read: the status line asks this on every redraw, and the
+    TypeSafe channel ends in omp's login database."""
+    def compatible():
+        return (os.environ.get("JEV_API_KEY", "").strip() or None
+                if os.environ.get("JEV_API_BASE_URL", "").strip() else None)
+
+    def workers_ai():
+        return cloudflare_token() if cloudflare_account() else None
+    found = [("typesafe", typesafe_key), ("jev-openrouter", openrouter_key),
              ("jev-cloudflare", workers_ai), ("jev-compatible", compatible),
              ("clef", workers_ai), ("clef-flash", workers_ai)]
     choice = jev_choice()
     if choice == "auto":
-        return [(name, secret) for name, secret in found if secret]
+        return [(name, secret) for name, secret in ((n, read()) for n, read in found)
+                if secret]
     name = choice if choice in ("typesafe", "clef", "clef-flash") else "jev-" + choice
-    return [(name, dict(found).get(name))]
+    read = dict(found).get(name)
+    return [(name, read() if read else None)]
 
 
 # How far a model call may leave the session's own vendor (config.json

package/hooks/tezgah_policy.py

@@ -303,8 +303,10 @@ active --json` and track it with `orca worktree ps --json` or `tezgah-status
 status in Orca; outside Orca, `git worktree add`. Either way the brief names
 absolute paths under that checkout.
 Routing: `{ROUTE_BIN} "<brief>"` names the worker - tezgah-cheap, -standard or
--frontier (overrides for stored data, credentials, security first; then a Jev
-judgement; the static phase table with no key). A worker that answers
+-frontier, or the specialist whose whole job the brief is (tezgah-tester,
+-docs, -security, -ui, -researcher, -reviewer) - and the spawn uses that name,
+never the host's generic task agent (overrides for stored data, credentials,
+security first; then a Jev judgement; the static phase table with no key). A worker that answers
 `ESCALATE:` is restarted on tezgah-frontier with the original brief, never
 continued; the main thread never switches model (the cache is per model). A
 code-discovery brief names codegraph's tools (`codegraph callers`, `callees`,
@@ -951,9 +953,11 @@ CONDITIONAL_KEYS = ("spec", "consult", "research", "product", "graph", "fanout")
 # the session had to recall, and the second list of a session was worked one
 # item at a time. It is the paragraph's own clause, cut to one sentence.
 FANOUT_ACTION = ("count the independent items, spawn one subagent per item in "
-                 "ONE message (each writing slice in its own worktree, absolute "
-                 "paths), and keep the main thread for integrating and verifying;"
-                 " a subagent does its own slice and never fans out again.")
+                 "ONE message, each the agent `tezgah-route` names - a specialist "
+                 "by name, never the generic task agent - (each writing slice in "
+                 "its own worktree, absolute paths), and keep the main thread for "
+                 "integrating and verifying; a subagent does its own slice and "
+                 "never fans out again.")
 
 # The always-on replacement for the conditional paragraphs: one line each so a
 # host without a per-turn hook still knows the rule exists and where the full

package/hooks/tezgah_task.py

@@ -158,6 +158,12 @@ _MARKER = re.compile(r"unverifiable(?![-\w])", re.I)
 # why") has no separator there and is not a declaration.
 _SEPARATORS = ":,;(-"
 _SPAN = re.compile(r"`([^`\n]+)`")
+# A runner whose test entry point is a bare subcommand: `pnpm test`, `cargo
+# test`, `uv run pytest` carry no option and no path, yet each is the command.
+# The runner has to be the first word, so `run the tests` stays prose.
+_RUNNERS = ("npm", "pnpm", "yarn", "bun", "deno", "cargo", "go", "make", "mix",
+            "dotnet", "gradle", "mvn", "poetry", "uv")
+_SUBCOMMANDS = ("test", "run")
 
 
 def _argument(token):
@@ -179,14 +185,16 @@ def _argument(token):
 
 def names_command(text):
     """Does this acceptance item name the command that proves it? A command is a
-    backticked run of two or more words carrying an option, a path or a script:
-    `bin/tezgah-docs --citations`, `python3 -m unittest tests/test_task.py`. A
-    citation (`hooks/tezgah_task.py`, `plan:line`) is not one, and an invocation
-    with no argument at all is not recognised either - both are reported, which
-    is the safe direction for a report a person reads."""
+    backticked run of two or more words carrying an option, a path or a script
+    (`bin/tezgah-docs --citations`, `python3 -m unittest tests/test_task.py`), or
+    a known runner followed by `test` or `run` (`pnpm test`, `npm run test`). A
+    citation (`hooks/tezgah_task.py`, `plan:line`) is not one, and any other
+    invocation with no argument is not recognised either - both are reported,
+    which is the safe direction for a report a person reads."""
     for span in _SPAN.findall(text):
         tokens = span.split()
-        if len(tokens) > 1 and any(_argument(token) for token in tokens[1:]):
+        if len(tokens) > 1 and (any(_argument(token) for token in tokens[1:]) or
+                                (tokens[0] in _RUNNERS and tokens[1] in _SUBCOMMANDS)):
             return True
     return False
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r1z4x/tezgah",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "One shared working contract for every AI coding assistant you run: Claude Code, Codex, Cursor, opencode, dsh and oh-my-pi (omp).",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,6 @@
     "output-styles/",
     "commands/",
     "docs/",
-    "agents/",
     "statusline.py",
     "MANIFEST",
     "CHANGELOG.md",

package/skills/tezgah-contract/SKILL.md

@@ -233,8 +233,10 @@ active --json` and track it with `orca worktree ps --json` or `tezgah-status
 status in Orca; outside Orca, `git worktree add`. Either way the brief names
 absolute paths under that checkout.
 Routing: `~/.config/tezgah/bin/tezgah-route "<brief>"` names the worker - tezgah-cheap, -standard or
--frontier (overrides for stored data, credentials, security first; then a Jev
-judgement; the static phase table with no key). A worker that answers
+-frontier, or the specialist whose whole job the brief is (tezgah-tester,
+-docs, -security, -ui, -researcher, -reviewer) - and the spawn uses that name,
+never the host's generic task agent (overrides for stored data, credentials,
+security first; then a Jev judgement; the static phase table with no key). A worker that answers
 `ESCALATE:` is restarted on tezgah-frontier with the original brief, never
 continued; the main thread never switches model (the cache is per model). A
 code-discovery brief names codegraph's tools (`codegraph callers`, `callees`,

package/agents/tezgah-reviewer.md

@@ -1,79 +0,0 @@
----
-name: tezgah-reviewer
-description: >
-  Adversarial, read-only review of a diff, branch or PR: derives the blast
-  radius, checks correctness, contract, security, tests and performance, and
-  classifies every finding confirmed/refuted/unverified. One review per
-  plan, at most two rounds; spawn one per dimension in one message for a
-  large diff.
-model: opus
-effort: high
-readonly: true
-disallowedTools: Write, Edit, NotebookEdit, Bash, Agent
----
-
-You are tezgah-reviewer, an adversarial code reviewer. Review a change,
-not the whole repo, with the code graph as below.
-
-Load the graph tools first: ToolSearch("select:mcp__codegraph__codegraph_explore,mcp__plugin_tezgah_codegraph__codegraph_explore,mcp__codegraph__codegraph_impact,mcp__plugin_tezgah_codegraph__codegraph_impact,mcp__codegraph__codegraph_callers,mcp__plugin_tezgah_codegraph__codegraph_callers,mcp__codegraph__codegraph_node,mcp__plugin_tezgah_codegraph__codegraph_node"). You have no
-shell, so the codegraph CLI is out of reach: use those MCP tools.
-
-Review the raw artifact, never a summary of it and never the author's
-self-assessment. Format, schema, frontmatter and spec-compliance problems
-live in the exact text, and a framing you were handed is a finding you will
-not make: a reviewer given the implementer's view finds measurably fewer
-defects. If you were handed a paraphrase, read the files instead.
-
-You have no shell, so you cannot run `git diff`: the caller passes
-the changed files and symbols of the target (a base branch, a ref or
-the PR under review). Run the MCP `codegraph_impact` tool per changed
-symbol - that is the blast radius. If the brief names no changed files,
-say so and ask for them instead of guessing. Read the changed code and any caller you intend to accuse.
-An empty or short caller list is not proof that a change is safe: the
-index records only the edges its parser saw, so say what it cannot see
-(dynamic dispatch, string or config lookups, unindexed files) instead of
-implying the list is complete.
-Look only for defects the change causes: correctness, contract/callers,
-security, tests, concurrency and performance. Classify every candidate as
-confirmed (concrete failure scenario + file:line), refuted (a guard,
-caller contract, type or test already prevents it) or unverified (not
-settled). Default to refuted when the evidence is unclear. Only the code
-or a run you observed settles a candidate: a doc, a comment, a lessons
-file, a memory note or an earlier report may raise a question but never
-makes it confirmed or refuted on its own. Report only confirmed findings
-as bugs; no style notes, no praise; empty is the correct answer for a
-clean change.
-
-Score the constraints separately from the defects. For every constraint
-the task stated - keep this behaviour, touch no other file, preserve this
-format - report kept or violated with the file:line that shows which. A
-patch that passes the tests and breaks a stated constraint is not clean,
-and a functional test will not notice it.
-
-Every finding carries a severity - critical (the change cannot stand as
-written), major (a real weakness that must be fixed), minor (noticeable),
-suggestion (an improvement, not a flaw) - and a verbatim quote of the
-code it accuses; a finding about an absence carries no quote. A severity
-is lowered only by evidence: a check you could not complete never
-downgrades a confirmed finding - keep its severity and mark it
-provisional. Disclose the order you read the files in.
-
-Scope and budget. One review per plan, over its whole diff in the
-verification phase; at most two rounds - only a confirmed critical or
-major finding opens round two, a minor or suggestion one is recorded
-fix-later, and after round two what is left goes to the user or is
-recorded fix-later, never a third round. A round may be a fan-out of
-reviewers spawned at once, one per dimension (correctness and contract,
-security, tests and performance) or per file group: when your brief
-names a dimension or files, review only those - a sibling owns the rest.
-Round two reads only the delta since the sha round one recorded
-(`tezgah-task review` prints it), plus the round-one hunks and direct
-callers of the symbols that delta touches, and marks every round-one
-finding closed or open: re-reading the whole diff re-reports what was
-already triaged. Test results are input, not a task - read the author's
-output file; do not run the suite, and run at most one `-k` test when a
-specific accusation needs it. The same defect family confirmed in both
-rounds is a sign the design needs a pivot, not another patch.
-
-You may use: the codegraph MCP tools, read, grep and glob. Read-only:
-no writes, no edits, no shell.