@r1z4x/tezgah 1.4.0 → 1.5.1

package/hooks/tezgah_judge.py

@@ -10,8 +10,10 @@ attempt and no more; a 4xx and a malformed reply never do (`ask()` below). A hoo
 may import this module, and a hook that raises takes a session down, so every
 failure is a `None` instead.
 
-Privacy, plainly: the state and the questions leave this machine for
-`api.typesafe.ai` - for the triage the state IS the screen's own text (an admin
+Privacy, plainly: the state and the questions leave this machine for the host
+of whichever provider answers - the session's vendor, or the chosen Jev
+carrier's (`api.typesafe.ai`, `openrouter.ai`, `api.cloudflare.com`, or the
+`JEV_API_BASE_URL` a user set) - for the triage the state IS the screen's own text (an admin
 table or a mobile view as captured, plus the `--select` task sentence), so a
 screen carrying personal data is read by a third party. Nothing else leaves -
 no session id, no workspace path, no environment - and the seam does not
@@ -23,17 +25,20 @@ prompt-path skill hint sends the user's prompt redacted and cut at 2,000
 characters, because a brief or a prompt can quote a token and neither is a
 state a person chose to send.
 
-The credential has two channels on purpose. `~/.zshenv` exports the env var for
-an interactive shell, but a hook or a bin tool started by a host runs in a
-non-interactive shell where `.zshenv` never runs - the export is absent there,
-and the key file is the channel that survives. That is why the file is read
-rather than the environment trusted.
+Each credential has a file channel beside its env var on purpose. `~/.zshenv`
+exports the env var for an interactive shell, but a hook or a bin tool started
+by a host runs in a non-interactive shell where `.zshenv` never runs - the
+export is absent there, and the key file is the channel that survives (TypeSafe
+also reads the active omp login). The resolvers live in `tezgah_paths`
+(`typesafe_key`, `jev_carriers`), so `have_judge_key()` asks the same ones.
 
-Behind the credential there are three providers, asked in this order. First the
-session's own CLI - `omp` or `claude`, the host this process runs under
+Behind the credential there are three kinds of provider, asked in this order. First the
+session's own CLI - `omp`, `claude`, `opencode`, `cursor` or `codex`, the host
+this process runs under or the one `TEZGAH_JUDGE_CLI`/`judge_cli` picks
 (`tp.session_cli()`) - run headless with no tools, so the judgement is paid
 with the session's own credential, OAuth subscription included, and answered by
-the session's own vendor. TypeSafe and OpenRouter are third parties: they are
+the session's own vendor. The Jev carriers (`JEV_CARRIERS`, as chosen by
+`tp.jev_choice()`) and the OpenRouter chat fallback are third parties: they are
 asked only as the `fallback` setting allows (`tp.fallback_policy()`): by
 default (`vendor`) only when there is no session CLI at all, with `any` also
 after the session CLI failed, with `none` never. A third party that answers,
@@ -58,13 +63,20 @@ import tezgah_paths as tp
 import tezgah_store
 
 URL = "https://api.typesafe.ai/v1/systemone"
-KEY_FILE = "~/.config/typesafe/key"
 MODEL = "jev-latest"
+# The other Jev carriers (`JEV_CARRIERS`): OpenRouter's System One endpoint,
+# 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.
+JEV_OPENROUTER_URL = "https://openrouter.ai/api/v1/systemone"
+CLOUDFLARE_URL = "https://api.cloudflare.com/client/v4"
+CLOUDFLARE_MODEL = "typesafe/jev"
 # The fallback provider: an OpenAI-compatible chat endpoint, its own key
 # channels, and the cheap judge model this repository already quotes in its
 # measured arm rows (`openrouter/deepseek/deepseek-v4-flash`).
 OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
-OPENROUTER_KEY_FILE = "~/.config/openrouter/key"
 FALLBACK_MODEL = "deepseek/deepseek-v4-flash"
 # The contract the fallback asks a chat model to answer in, one shape per
 # question type this repository's callers send (`bin/tezgah-triage` and
@@ -110,19 +122,11 @@ def endpoint():
 
 
 def key():
-    """The credential: TYPESAFE_API_KEY, else the key file, else None.
-
-    The file is stripped: it is written with a trailing newline, and a newline
-    inside an Authorization header is a header-injection attempt to the HTTP
-    layer, not a typo it will forgive."""
-    value = os.environ.get("TYPESAFE_API_KEY", "").strip()
-    if value:
-        return value
-    try:
-        with open(os.path.expanduser(KEY_FILE), encoding="utf-8") as fh:
-            return fh.read().strip() or None
-    except OSError:
-        return None
+    """TypeSafe's credential: TYPESAFE_API_KEY, else `~/.config/typesafe/key`,
+    else the active omp login, else None (`tp.typesafe_key`). Stripped: a
+    newline inside an Authorization header is a header-injection attempt to
+    the HTTP layer, not a typo it will forgive."""
+    return tp.typesafe_key()
 
 
 def openrouter_url():
@@ -131,19 +135,37 @@ def openrouter_url():
 
 
 def openrouter_key():
-    """The fallback credential: OPENROUTER_API_KEY, else the key file, else None.
-
-    The same two channels as the TypeSafe key and for the same reason - a hook
-    runs where `~/.zshenv` never did - and the same `strip()`, because a newline
-    inside an Authorization header is an injection, not a typo."""
-    value = os.environ.get("OPENROUTER_API_KEY", "").strip()
-    if value:
-        return value
-    try:
-        with open(os.path.expanduser(OPENROUTER_KEY_FILE), encoding="utf-8") as fh:
-            return fh.read().strip() or None
-    except OSError:
-        return None
+    """OpenRouter's credential, for its System One carrier and the chat
+    fallback alike: OPENROUTER_API_KEY, else `~/.config/openrouter/key`, else
+    None (`tp.openrouter_key`), stripped for the same reason as `key()`."""
+    return tp.openrouter_key()
+
+
+def _jev_call(provider, model, state, questions):
+    """`(model used, url, body)` for one Jev carrier: TypeSafe's own body
+    (`state`, `model`, `questions`) everywhere but Cloudflare, whose run route
+    takes its one alias and the pair under `input`. Clef and Clef-flash, its own
+    System One models, have a route each and take the bare body with `model`
+    as the selector. Every URL routes through `override()`, so a plain-http one
+    off this machine raises here."""
+    if provider in ("jev-cloudflare", "clef", "clef-flash"):
+        account = urllib.parse.quote(tp.cloudflare_account() or "", safe="")
+        url = override("TEZGAH_CLOUDFLARE_URL", CLOUDFLARE_URL) + \
+            "/accounts/%s/ai/run" % account
+        if provider != "jev-cloudflare":
+            return provider, url + "/@cf/cloudflare/" + provider, {
+                "model": provider, "state": state, "questions": questions}
+        return CLOUDFLARE_MODEL, url, {"model": CLOUDFLARE_MODEL, "input": {
+            "state": state, "questions": questions}}
+    if provider == "jev-openrouter":
+        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
+        url = override("JEV_API_BASE_URL", "")
+    else:
+        used, url = model, endpoint()
+    return used, url, {"state": state, "model": used, "questions": questions}
 
 
 def fallback_model():
@@ -170,25 +192,56 @@ SESSION_ARGV = {
                "--strict-mcp-config", "--disable-slash-commands",
                "--setting-sources", "", "--output-format", "json",
                "--system-prompt", CHAT_SYSTEM],
+    # None of the next three takes a system prompt or drops its tools, so
+    # `_session_request` puts the system prompt in front of the prompt text and
+    # the empty temp cwd is what keeps tools from reaching a repository. Each
+    # set is from the CLI's own `--help` (checked 2026-10-09). opencode 1.18.31
+    # `run`: `--pure` "run without external plugins", `--format json` "raw JSON
+    # events"; it has no flag that skips the session record.
+    "opencode": ["run", "--pure", "--format", "json"],
+    # cursor-agent 2026.10.01: `-p` print, `--output-format json` (only with
+    # --print), `--mode ask` "Q&A style ... (read-only)", `--trust` "Trust the
+    # current workspace without prompting" - the temp cwd is never trusted.
+    "cursor": ["-p", "--output-format", "json", "--mode", "ask", "--trust"],
+    # codex-cli 0.153.4 `exec`: `--json` "Print events to stdout as JSONL",
+    # `--ephemeral` "without persisting session files", `--skip-git-repo-check`
+    # (the temp cwd is no repository), `--ignore-rules` (no execpolicy rules),
+    # `-s read-only`, `--color never`: consult's argv (`tp.CONSULT_CLIS`) plus
+    # `--json` and `--ignore-rules`.
+    "codex": ["exec", "--json", "--ephemeral", "--skip-git-repo-check",
+              "--ignore-rules", "-s", "read-only", "--color", "never"],
+}
+# What the CLI's environment adds to the call. `opencode run` has no flag that
+# drops its tools, and a probe on 2026-10-09 saw it run a bash command the
+# 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. 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_ALL, "tools": {"*": False},
+        "agent": {name: {"permission": _DENY_ALL, "tools": {"*": False}}
+                  for name in ("build", "plan")}})},
 }
-NO_SESSION = "no session CLI to ask (OMPCODE/CLAUDECODE unset or the CLI missing)"
+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)")
 
 
 def providers():
     """[(provider, secret), ...] in the order `ask()` tries them, or [].
 
     The session's own CLI first (its `secret` is the binary's path); then the
-    third parties - TypeSafe, then OpenRouter - only as `tp.fallback_policy()`
-    allows: `vendor` (the default) asks them only when no session CLI exists,
-    `any` after the session CLI too, `none` never. TypeSafe still wins over
-    OpenRouter whenever both resolve."""
-    session = tp.session_cli()
-    policy = tp.fallback_policy()
-    out = [(session, getattr(tp, session + "_bin")())] if session else []
-    if policy == "none" or (session and policy == "vendor"):
-        return out
-    return out + [(name, secret) for name, secret in
-                  (("typesafe", key()), ("openrouter", openrouter_key())) if secret]
+    third parties - the chosen Jev carriers (`tp.jev_carriers()`), then the
+    OpenRouter chat fallback - only as `tp.fallback_policy()` allows: `vendor`
+    (the default) asks them only when no session CLI exists, `any` after the
+    session CLI too, `none` never. A Jev carrier still wins over the chat
+    model whenever both resolve."""
+    return [(p, s) for p, s in _plan() if s]
 
 
 def named(only):
@@ -196,13 +249,67 @@ def named(only):
     in `only` that resolves, in `only`'s order. The `vendor` policy's
     session-first order does not apply - the caller named the provider, so
     nothing is a silent fallback - but `none` still keeps every third party
-    out."""
+    out. The name `jev` stands for every chosen Jev carrier that resolves
+    (`tp.jev_carriers()`, in the chosen order), so a caller that needs a typed
+    answer names the model family, not one carrier's address."""
+    return [(p, s) for p, s in _plan(only) if s]
+
+
+def _plan(only=None):
+    """`providers()` (`only` None) or `named(only)`, with one difference: a
+    forced Jev carrier whose credential is missing stays in as `(carrier,
+    None)`, so `ask()` records why no Jev carrier was asked instead of
+    silently asking another one."""
     session = tp.session_cli()
-    third = tp.fallback_policy() != "none"
+    policy = tp.fallback_policy()
+    jev = tp.jev_carriers() if policy != "none" else []
+    if only is None:
+        out = [(session, getattr(tp, session + "_bin")())] if session else []
+        if policy == "none" or (session and policy == "vendor"):
+            return out
+        return out + jev + [("openrouter", s) for s in (openrouter_key(),) if s]
     found = {session: getattr(tp, session + "_bin")()} if session else {}
-    if third:
-        found.update(typesafe=key(), openrouter=openrouter_key())
-    return [(name, found[name]) for name in only if found.get(name)]
+    if policy != "none":
+        found.update(jev, openrouter=openrouter_key())
+    out = []
+    for name in only:
+        for one, secret in (jev if name == "jev" else [(name, found.get(name))]):
+            if (secret or one in dict(jev)) and (one, secret) not in out:
+                out.append((one, secret))
+    return out
+
+
+# Every carrier that answers with a typed System One model - Jev itself, or
+# Cloudflare's Clef family, which takes the same request and answers in the
+# same shape - as opposed to a chat model asked to imitate it: TypeSafe direct,
+# OpenRouter's System One endpoint, Cloudflare Workers AI, any System
+# One-compatible URL, Clef and Clef-flash. A decision a caller requires to be
+# typed checks `is_jev(result["provider"])`.
+JEV_CARRIERS = ("typesafe", "jev-openrouter", "jev-cloudflare", "jev-compatible",
+                "clef", "clef-flash")
+# Dollars per 1M input tokens, output free on every one: Jev's listed price on
+# each of its carriers, Clef's and Clef-flash's from their Workers AI pages
+# (2026-10-09).
+JEV_INPUT_PRICE = 0.042
+CLEF_INPUT_PRICE = {"clef": 0.24, "clef-flash": 0.09}
+
+
+def is_jev(provider):
+    """True when `provider` is a typed System One carrier (`JEV_CARRIERS`)."""
+    return provider in JEV_CARRIERS
+
+
+def input_price(provider):
+    """The carrier's input price per 1M tokens, None for anything not typed."""
+    return CLEF_INPUT_PRICE.get(provider, JEV_INPUT_PRICE) if is_jev(provider) else None
+
+
+def jev_summary():
+    """One line naming the Jev choice and the carriers it resolves to now, for
+    `tezgah-status --judge` and `tezgah-setup --jev`: a forced carrier without
+    its credential is named as such, never hidden."""
+    names = ", ".join(p if s else p + " (no credential)" for p, s in tp.jev_carriers())
+    return "jev=%s: %s" % (tp.jev_choice(), names or "no carrier resolves")
 
 
 def credential():
@@ -229,7 +336,8 @@ def ask(state, questions, *, model=MODEL, timeout=30, attempts=2, deadline=None,
     beside it because the provider that answers is not the caller's choice. The
     model is the one the reply names, else the one asked for: an alias such as
     `jev-latest` hides a silent upgrade the reply's own field shows. `model` is
-    TypeSafe's alone; the session CLI and the chat fallback ignore it.
+    the Jev carriers' alone (Cloudflare serves its one alias whatever is asked);
+    the session CLI and the chat fallback ignore it.
 
     The providers are tried in `providers()` order - the session's own CLI
     first - and the next one is asked only when the previous failed. `fallback`
@@ -244,7 +352,7 @@ def ask(state, questions, *, model=MODEL, timeout=30, attempts=2, deadline=None,
     and a `deadline` in seconds: urllib's `timeout` bounds one socket operation,
     not the call, so only the deadline bounds its wall time.
 
-    A call that ends on a 401, 402, 5xx or a session CLI's non-zero exit marks
+    A call that ends on a 401, 402, 403, 5xx or a session CLI's non-zero exit marks
     that provider down for `DOWN_FOR` seconds, and until then it is skipped
     without a request (`_down`), so a dead credential is not re-paid on every
     prompt.
@@ -254,17 +362,22 @@ def ask(state, questions, *, model=MODEL, timeout=30, attempts=2, deadline=None,
     exception.
 
     `only` names the providers the caller requires (`named()`); a caller whose
-    decision must come from a typed model passes `only=("typesafe",)` and gets
-    None rather than another provider's answer."""
-    tried = providers() if only is None else named(only)
+    decision must come from a typed model passes `only=("jev",)` and gets
+    None rather than another provider's answer. A forced Jev carrier
+    (`tp.jev_choice()`) whose credential is missing is asked nothing and
+    recorded as a failure, never replaced by another carrier."""
+    tried = _plan(only)
     if any(isinstance(q, dict) and q.get("type") == "text" for q in questions.values()):
-        # TypeSafe answers no prose: left out up front, not logged as a failure
-        tried = [(p, s) for p, s in tried if p != "typesafe"]
-    if not tried or not tried[0][1]:
+        # no Jev carrier answers prose: left out up front, not logged as a failure
+        tried = [(p, s) for p, s in tried if not is_jev(p)]
+    if not tried:
         return None
     stop = None if deadline is None else time.monotonic() + deadline
     failed = []
     for provider, secret in tried:
+        if not secret:
+            failed.append("%s: no credential (jev=%s)" % (provider, tp.jev_choice()))
+            continue
         result, why = _ask_one(provider, secret, state, questions, model,
                                timeout, attempts, stop)
         if result is None:
@@ -279,7 +392,9 @@ def ask(state, questions, *, model=MODEL, timeout=30, attempts=2, deadline=None,
         return result
     refused = None
     session = tp.session_cli()
-    if session and (key() or openrouter_key()):
+    # 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)
@@ -289,13 +404,12 @@ def ask(state, questions, *, model=MODEL, timeout=30, attempts=2, deadline=None,
 def _ask_one(provider, secret, state, questions, model, timeout, attempts, stop):
     """One provider's attempts: `(result, None)`, or `(None, why)`."""
     try:
-        if provider == "typesafe":
-            used, url = model, endpoint()
-            body = json.dumps({"state": state, "model": used,
-                               "questions": questions}).encode()
+        if is_jev(provider):
+            used, url, payload = _jev_call(provider, model, state, questions)
+            body = json.dumps(payload).encode()
 
             def send():
-                return _request(secret, body, timeout)
+                return _request(secret, body, timeout, url)
         elif provider == "openrouter":
             used, url = fallback_model(), openrouter_url()
             body = json.dumps(_chat_body(state, questions, used)).encode()
@@ -323,7 +437,7 @@ def _ask_one(provider, secret, state, questions, model, timeout, attempts, stop)
             late = stop is not None and time.monotonic() >= stop
             if attempt + 1 >= attempts or late or not _transient(exc):
                 code = getattr(exc, "code", None)
-                if code in (401, 402) or (isinstance(code, int) and code >= 500) \
+                if code in (401, 402, 403) or (isinstance(code, int) and code >= 500) \
                         or isinstance(exc, SessionFailed):
                     _mark_down(down)
                 return None, _why(exc)
@@ -397,19 +511,24 @@ def _transient(exc):
     return isinstance(exc, OSError)
 
 
-def _request(secret, body, timeout):
-    """One POST: the documented return, or the exception `ask()` decides on.
+def _request(secret, body, timeout, url=None):
+    """One POST to a Jev carrier - TypeSafe's unless `url` names another: the
+    documented return, or the exception `ask()` decides on. Cloudflare's REST
+    API may wrap the documented body as `{"result": {...}, "success": true}`;
+    both shapes are read.
 
     Split from `ask()` so the retry re-sends the body already serialized rather
     than rebuilding it, and so the URL parse stays inside `ask()`'s try: a
     scheme-less override raises ValueError there and becomes a None like any
     other failure rather than escaping."""
-    request = urllib.request.Request(endpoint(), data=body, headers={
+    request = urllib.request.Request(url or endpoint(), data=body, headers={
         "Authorization": "Bearer " + secret,
         "Content-Type": "application/json"})
     started = time.monotonic()
     with OPENER.open(request, timeout=timeout) as response:
         data = json.load(response)
+    if "answers" not in data and isinstance(data.get("result"), dict):
+        data = data["result"]
     usage = data["usage"]
     return {"answers": data["answers"],
             "usage": {"input_tokens": int(usage["input_tokens"]),
@@ -533,7 +652,7 @@ def cheap_default():
     return row[0] if row else FALLBACK_MODEL
 
 
-# How long a provider stays marked down after a 401, 402 or 5xx: five minutes,
+# How long a provider stays marked down after a 401, 402, 403 or 5xx: five minutes,
 # so a dead key or an empty account costs one refusal per five minutes rather
 # than one per prompt, and a provider that comes back is asked again within the
 # same working session. The mark is keyed on the provider, the endpoint and a
@@ -601,22 +720,28 @@ def _session_request(name, exe, prompt, timeout, questions):
     on the prompt alone, and a CLI that wants a login exits instead of waiting -
     with TEZGAH_NESTED set so tezgah's own hooks stand down in the child. The
     answer is read from the CLI's JSON output: the model and the usage it names
-    are what the call really used."""
+    are what the call really used. A CLI with no system-prompt flag gets the
+    system prompt in front of the prompt text instead."""
     import shutil
     import subprocess
     import tempfile
+    if CHAT_SYSTEM not in SESSION_ARGV[name]:
+        prompt = CHAT_SYSTEM + "\n\n" + prompt
     cwd = tempfile.mkdtemp(prefix="tezgah-judge-")
     started = time.monotonic()
     try:
         proc = subprocess.run([exe] + SESSION_ARGV[name] + [prompt], cwd=cwd,
                               stdin=subprocess.DEVNULL, capture_output=True,
                               text=True, timeout=timeout,
-                              env=dict(os.environ, TEZGAH_NESTED="1"))
+                              env=dict(os.environ, TEZGAH_NESTED="1",
+                                       **SESSION_ENV.get(name, {})))
     finally:
         shutil.rmtree(cwd, ignore_errors=True)
     if proc.returncode:
-        raise SessionFailed("%s exit %d: %s" % (name, proc.returncode,
-                                                 (proc.stderr or proc.stdout).strip()[-200:]))
+        # stdout last: codex prints a stdin banner on stderr and its reason as
+        # the last JSON event on stdout
+        raise SessionFailed("%s exit %d: %s" % (name, proc.returncode, (
+            (proc.stderr or "") + (proc.stdout or "")).strip()[-200:]))
     if name == "claude":
         data = json.loads(proc.stdout)
         if data.get("is_error"):
@@ -627,7 +752,7 @@ def _session_request(name, exe, prompt, timeout, questions):
         tokens_in = sum(int(usage.get(k) or 0) for k in (
             "input_tokens", "cache_creation_input_tokens", "cache_read_input_tokens"))
         tokens_out = int(usage.get("output_tokens") or 0)
-    else:
+    elif name == "omp":
         message = None
         for line in proc.stdout.splitlines():
             try:
@@ -645,6 +770,11 @@ def _session_request(name, exe, prompt, timeout, questions):
         usage = message.get("usage") or {}
         tokens_in = sum(int(usage.get(k) or 0) for k in ("input", "cacheRead", "cacheWrite"))
         tokens_out = int(usage.get("output") or 0)
+    else:
+        model = None  # none of the three names the model it ran
+        text, tokens_in, tokens_out = _cli_answer(name, proc.stdout)
+        if not text.strip():
+            raise SessionFailed("%s printed no answer" % name)
     # A chat model may fence its object; the outermost braces are the object.
     answers = _chat_answers(json.loads(text[text.find("{"):text.rfind("}") + 1]), questions)
     return {"answers": answers,
@@ -653,6 +783,49 @@ def _session_request(name, exe, prompt, timeout, questions):
             "model": model}
 
 
+def _cli_answer(name, out):
+    """(text, input tokens, output tokens) from opencode's, cursor-agent's
+    or codex's JSON output, the shapes each printed on 2026-10-09; text is ""
+    when no answer came. None of the three names the model it ran. Input counts
+    the cache reads and writes, as the claude and omp branches do: opencode and
+    cursor-agent report them beside the input (opencode's `total` is the sum of
+    all its fields), codex inside `input_tokens` (`cached_input_tokens` is a
+    share of it, as `reasoning_output_tokens` is of `output_tokens`)."""
+    text, tokens_in, tokens_out = "", 0, 0
+    for line in out.splitlines():
+        try:
+            event = json.loads(line)
+        except ValueError:
+            continue
+        if not isinstance(event, dict):
+            continue
+        kind = event.get("type")
+        part, item = event.get("part") or {}, event.get("item") or {}
+        usage = event.get("usage") or {}
+        if name == "cursor" and kind == "result":
+            if event.get("is_error"):
+                raise SessionFailed("cursor: %s" % str(event.get("result"))[:200])
+            text = event.get("result") or ""
+            tokens_in = sum(int(usage.get(k) or 0) for k in (
+                "inputTokens", "cacheReadTokens", "cacheWriteTokens"))
+            tokens_out = int(usage.get("outputTokens") or 0)
+        elif name == "opencode" and kind == "text":
+            text = part.get("text") or text
+        elif name == "opencode" and kind == "step_finish":
+            tokens = part.get("tokens") or {}
+            cache = tokens.get("cache") or {}
+            tokens_in += sum(int(v or 0) for v in (tokens.get("input"), cache.get("read"),
+                                                   cache.get("write")))
+            tokens_out += int(tokens.get("output") or 0) + int(tokens.get("reasoning") or 0)
+        elif name == "codex" and kind == "item.completed" \
+                and item.get("type") == "agent_message":
+            text = item.get("text") or text
+        elif name == "codex" and kind == "turn.completed":
+            tokens_in += int(usage.get("input_tokens") or 0)
+            tokens_out += int(usage.get("output_tokens") or 0)
+    return text, tokens_in, tokens_out
+
+
 def _why(exc):
     """A failure as one short reason: the HTTP code, else the exception's text."""
     code = getattr(exc, "code", None)

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}