@r1z4x/tezgah 1.11.0 → 1.14.0

package/docs/environment.md

@@ -4,7 +4,9 @@ Every environment variable tezgah reads, in one table per concern: what reads it
 what it defaults to, and what setting it changes. For someone pinning an install
 in CI, repointing an endpoint in a test, or wondering why a hook ignores the
 Python on PATH. A variable not on this page is not read by tezgah; one read by a
-host and only passed through (such as `HOME` or `PATH`) is left out.
+host and only passed through (such as `HOME` or `PATH`) is left out. Vendored
+upstream skill scripts (under `skills/`, such as hallmark's) are out of scope:
+the variables they read are theirs, not tezgah's.
 
 Nothing loads a `.env` file: a variable reaches tezgah only through the
 environment of the process that started it - the shell, the host, or the host's
@@ -19,32 +21,40 @@ the kill switches are files, not variables, and live in
 
 | Variable | Read by | Default | Effect |
 |---|---|---|---|
-| `TEZGAH_PREFIX` | `packaging/install.sh:30`, `packaging/upgrade.sh`, `packaging/install.ps1`, `bin/tezgah-setup::default_prefix` | `$XDG_DATA_HOME/tezgah`, else `%LOCALAPPDATA%\tezgah` on Windows, else `~/.local/share/tezgah` | Where the artifact install unpacks its versions and the `current` link; `tezgah-setup` treats it as the install prefix. |
-| `TEZGAH_VERSION` | `packaging/install.sh`, `packaging/upgrade.sh`, `packaging/install.ps1`, `packaging/build.sh:70` | the newest GitHub release; `build.sh` falls back to `VERSION`/the CHANGELOG | The version to install, or the version `build.sh` stamps when `--version` is not given. |
-| `TEZGAH_REPO` | `packaging/install.sh:13`, `packaging/upgrade.sh`, `packaging/install.ps1` | `r1z4x/tezgah` | The GitHub repository releases are fetched from. |
+| `TEZGAH_PREFIX` | `packaging/install.sh`, `packaging/upgrade.sh`, `packaging/install.ps1`, `bin/tezgah-setup::default_prefix`, `hooks/tezgah_gate.py::_install_trees` | `$XDG_DATA_HOME/tezgah`, else `%LOCALAPPDATA%\tezgah` on Windows, else `~/.local/share/tezgah` | Where the artifact install unpacks its versions and the `current` link; `tezgah-setup` treats it as the install prefix. |
+| `TEZGAH_VERSION` | `packaging/upgrade.sh`, `packaging/install.ps1`, `packaging/build.sh:70` | the newest GitHub release; `build.sh` falls back to `VERSION`/the CHANGELOG | The version to install, or the version `build.sh` stamps when `--version` is not given. `install.sh` does not read it: the `upgrade.sh` it runs does. |
+| `TEZGAH_REPO` | `packaging/install.sh:13`, `packaging/upgrade.sh`, `packaging/install.ps1`, `hooks/tezgah_update.py::REPO` | `r1z4x/tezgah` | The GitHub repository releases are fetched from, and the one the daily release check asks. |
+| `TEZGAH_GITHUB_TOKEN`, `GITHUB_TOKEN`, `GH_TOKEN` | `packaging/install.sh`, `packaging/upgrade.sh`, `packaging/install.ps1` | unset | The first one set is sent as the bearer token for a private repository's release download; unset, the download is anonymous. |
 | `TEZGAH_UPDATE_URL` | `hooks/tezgah_update.py` | `https://github.com/<TEZGAH_REPO>/releases/latest` | Where the daily release check reads the newest tag: from the redirect, or from a JSON body's `tag_name`. Tests point it at a `file://` fixture. |
 | `TEZGAH_UPDATE_CHECK` | `hooks/tezgah_update.py` | unset | `0` turns off the update chip and the daily check. The test suite sets it, so no test reaches the network. |
-| `TEZGAH_DIST` | `packaging/upgrade.sh:105`, `packaging/install.ps1` | unset: the release URL | A directory holding `tezgah-<V>.tar.gz` and its `.sha256` (what `build.sh --out` writes) used instead of the release download; CI exercises the real fetch-verify-unpack path with it. |
+| `TEZGAH_DIST` | `packaging/upgrade.sh:109`, `packaging/install.ps1` | unset: the release URL | A directory holding `tezgah-<V>.tar.gz` and its `.sha256` (what `build.sh --out` writes) used instead of the release download; CI exercises the real fetch-verify-unpack path with it. |
 | `TEZGAH_GH` | `packaging/upgrade.sh` | `gh` on PATH | The `gh` that checks the tarball's build provenance (`gh attestation verify`). A path that does not exist reads as no `gh`: the upgrade prints `provenance not checked` and goes on. Tests point it at a stand-in. |
 | `TEZGAH_NO_DEPS` | `bin/tezgah-setup::main` | unset | Any value but empty or `0` is `--no-deps`: the optional tools (codegraph, orx, host CLIs) are not installed. |
 | `TEZGAH_NO_SYMLINK` | `bin/tezgah-setup::symlinks_refused` | unset | Any value but empty or `0` writes the copy layout a machine without symlinks gets, on a machine that has them. |
-| `TEZGAH_PYTHON` | `hooks/tezgah_paths.py::python_cmd`, `bin/tezgah.js`, `bin/tezgah-dsh.cmd`, `hooks/hooks.json`, `hosts/*/hooks.json`, `hosts/omp/tezgah-hook.ts.in`, `hosts/opencode/plugins/tezgah.js`, `packaging/build.sh` | this process's interpreter, then `python3`/`python`/`py` on PATH | The interpreter every host hook and the npm shim start; pin it when the right Python is not first on PATH. |
+| `TEZGAH_PYTHON` | `hooks/tezgah_paths.py::python_cmd`, `bin/tezgah.js`, `bin/tezgah-dsh.cmd`, `hooks/hooks.json`, `hosts/cursor/hooks.json`, `hosts/dsh/hooks.json`, `hosts/omp/tezgah-hook.ts.in`, `hosts/amp/tezgah-plugin.ts.in`, `hosts/opencode/plugins/tezgah.js`, `packaging/build.sh` | this process's interpreter, then `python3`/`python`/`py` on PATH | The interpreter every host hook and the npm shim start; pin it when the right Python is not first on PATH. Codex's hook command is rendered at install (`bin/tezgah-setup::codex_hook_groups`) rather than read from a shipped file. |
 
 ## Where tezgah and the hosts keep state
 
 | Variable | Read by | Default | Effect |
 |---|---|---|---|
 | `TEZGAH_ROOTS` | `hooks/tezgah_paths.py::roots`, `bin/tezgah-setup`, `hosts/opencode/plugins/tezgah.js` | `roots` in `~/.config/tezgah/config.json`, else `~/Projects` | The directories tezgah is armed over, `os.pathsep`-separated (`;` on Windows, the opencode plugin included); it outranks the config file. |
-| `XDG_CONFIG_HOME` | `hooks/tezgah_paths.py::CONFIG_DIR`, `bin/tezgah-doctor`, `bin/tezgah-dsh.cmd`, `hosts/opencode/plugins/tezgah.js` | `~/.config` | Parent of tezgah's config dir (kill switches, `bin/` links, config) and of opencode's. |
-| `XDG_DATA_HOME` | `bin/tezgah-setup::default_prefix`, `packaging/install.sh`, `packaging/upgrade.sh` | `~/.local/share` | Parent of the default install prefix. |
+| `XDG_CONFIG_HOME` | `hooks/tezgah_paths.py::CONFIG_DIR`, `hooks/tezgah_paths.py::AMP_PLUGIN`, `hooks/tezgah_skill_pick.py::_host_roots`, `bin/tezgah-doctor`, `bin/tezgah-dsh.cmd`, `hosts/opencode/plugins/tezgah.js` | `~/.config` | Parent of tezgah's config dir (kill switches, `bin/` links, config), of opencode's, and of Amp's system plugin dir (`amp/plugins/tezgah.ts`). |
+| `XDG_DATA_HOME` | `bin/tezgah-setup::default_prefix`, `packaging/install.sh`, `packaging/upgrade.sh`, `hooks/tezgah_gate.py::_install_trees` | `~/.local/share` | Parent of the default install prefix. |
 | `XDG_CACHE_HOME` | `hooks/tezgah_apps.py::ARTIFACTS` | `~/.cache` | Parent of the app-analysis artifact dir. |
-| `TEZGAH_DEBUG` | `hooks/tezgah_guard.py` | unset | `1` makes every hook process append one line to `<cache>/debug.log` (host, script, each guarded call's outcome or exception class, elapsed ms; no prompt or tool text), created 0600 and swept by `tezgah-doctor --clean`. Off, it costs one environment read. |
 | `TEZGAH_FALLBACK_CACHE` | `hooks/tezgah_paths.py::fallback_cache` | `<tempdir>/tezgah` | The cache a sandboxed hook writes when its normal cache dir is denied; a test knob. |
 | `TEZGAH_ARTIFACTS` | `hooks/tezgah_apps.py::ARTIFACTS` | `$XDG_CACHE_HOME/tezgah/apps` | Where `analyze-app` screenshots, traces and tree dumps land. |
 | `TEZGAH_NO_EXCLUDE` | `hooks/tezgah_agents.py::ensure_exclude` | unset | `1` stops tezgah adding its generated-agent dirs to the repository's `.git/info/exclude`. |
-| `CODEX_HOME` | `hooks/tezgah_paths.py::HOST_DIRS` | `~/.codex` | The Codex home tezgah installs into and checks; the same variable Codex itself reads. |
+| `CODEX_HOME` | `hooks/tezgah_paths.py::HOST_DIRS`, `hooks/tezgah_skill_pick.py::_host_roots` | `~/.codex` | The Codex home tezgah installs into and checks; the same variable Codex itself reads. |
 | `DSH_HOME` | `hooks/tezgah_paths.py::HOST_DIRS`, `bin/tezgah-dsh`, `bin/tezgah-dsh.cmd` | `~/.dsh` | The dsh home tezgah installs into, and where `tezgah-dsh` looks for the CLI. |
+| `QWEN_HOME`, `COPILOT_HOME` | `hooks/tezgah_paths.py::HOST_DIRS` | `~/.qwen`, `~/.copilot` | The Qwen Code and Copilot CLI homes tezgah installs into and checks; the same variables those CLIs read to relocate their home. |
+| `GEMINI_CLI_HOME` | `hooks/tezgah_paths.py::HOST_DIRS` | the home dir | The directory holding Gemini CLI's `.gemini`, where tezgah installs its extension; the variable Gemini CLI itself reads. |
+| `CLAUDE_CONFIG_DIR` | `hooks/tezgah_stack.py::host_stack` | unset | Set (Claude Code's own relocation variable), omp's skill stack counts `~/.claude/skills` as loaded even when omp's `enabledProviders` does not list `claude`. The test suite unsets it. |
 | `ORCA_WORKTREE_ID`, `ORCA_TERMINAL_HANDLE`, `ORCA_PANE_KEY`, `TERM_PROGRAM=Orca` | `hooks/tezgah_orca.py::session` | unset | Exported by an Orca terminal. Any one marks the session as inside Orca: the session-start block gains the `Orca:` line and `tezgah-setup --status` an `orca:` line ([orca](orca.md)). tezgah never writes them. |
+| `ORCA_APP_VERSION` | `hooks/tezgah_orca.py::session` | unset | Exported by an Orca terminal: the Orca version the `Orca:` line reports. |
+| `ORCA_CLI_COMMAND`, `ORCA_CLI_BIN_DIR` | `hooks/tezgah_orca.py::cli` | unset | Exported by Orca: the command (WSL) or the bin dir of its CLI, tried after `TEZGAH_ORCA_BIN` and before PATH. The test suite unsets both. |
+| `TEZGAH_ENGAGEMENTS_ROOT` | `hooks/tezgah_extension.py::ENGAGEMENTS_ENV` | unset | A domain repository's engagement root: a session anywhere under `<root>/<slug>` reads that engagement's `.tezgah/extension.json` even when the walk up ran out first. |
+| `GIT_DIR`, `GIT_WORK_TREE` | `hooks/tezgah_agents.py::_exclude_path` | unset | Either one set moves the repository away from `.git`, so the generated-agent excludes are written where git says, not to `.git/info/exclude`. |
+| `LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG` | `hooks/tezgah_paths.py::env_language` | unset | A first install takes the reply language from the first one set and not empty (`LANGUAGE`'s first `:` entry); `en` when it names no shipped pack. |
 | `TEZGAH_OPENCODE_DATA` | `bin/tezgah-setup::OPENCODE_DATA`, `bin/tezgah-doctor` | `~/.local/share/opencode` | opencode's data dir: its session database for `tezgah-doctor` and the installer. |
 
 ## Which binary runs
@@ -54,9 +64,11 @@ the kill switches are files, not variables, and live in
 | `TEZGAH_CODEGRAPH_BIN` | `hooks/tezgah_paths.py::codegraph_bin` | the config file, then `codegraph` on PATH | The codegraph executable the index and the graph marks use. |
 | `TEZGAH_ORX_BIN` | `hooks/tezgah_paths.py::orx_bin` | `orx` on PATH | The OpenResearch CLI the research rule routes to. |
 | `TEZGAH_OCR_BIN` | `hooks/tezgah_paths.py::ocr_bin` | `ocr` on PATH | The open-code-review CLI the opt-in OCR review spec runs ([operations](operations.md#opt-in-ocr-review-spec-ocr)). |
+| `TEZGAH_OCR_REVIEW_READY_TIMEOUT` | `bin/tezgah-ocr-review::run` | `30` (seconds) | How long `tezgah-ocr-review` waits for its model gateway to answer before it reports a setup failure. Must be a number. |
+| `GIT_CONFIG_GLOBAL`, `GIT_CONFIG_COUNT` | `bin/tezgah-ocr-review::run` | unset | OCR runs with a private HOME, so `tezgah-ocr-review` pins git to the user's `~/.gitconfig` and global excludes: an explicit `GIT_CONFIG_GLOBAL` wins over that pin, and the excludes entry is appended after the `GIT_CONFIG_COUNT` entries already set. |
 | `TEZGAH_ORCA_BIN` | `hooks/tezgah_orca.py::cli` | `ORCA_CLI_COMMAND`, then `$ORCA_CLI_BIN_DIR/orca`, then `orca` on PATH (`orca-ide` on Linux outside Orca), then the macOS app's CLI | The Orca CLI `tezgah-status --orca` and `tezgah-setup --status` ask. A missing path is no CLI, never a fallback: the test suite points it at one. |
 | `TEZGAH_OMP_BIN` | `hooks/tezgah_paths.py::omp_bin` | `omp` on PATH | The omp binary the installer, the model table, consult's session-model lookup and the judgement seam's session call run; tests point it at a stand-in. |
-| `TEZGAH_CLAUDE_BIN` | `claude_bin`, `hooks/tezgah_paths.py::claude_bin` | `claude` on PATH | The Claude Code CLI `--install` registers the plugin with (`claude plugin`) and the judgement seam asks in a Claude Code session; the test suite points it at a path that does not exist, or at a stand-in. |
+| `TEZGAH_CLAUDE_BIN` | `hooks/tezgah_paths.py::claude_bin` | `claude` on PATH | The Claude Code CLI `--install` registers the plugin with (`claude plugin`) and the judgement seam asks in a Claude Code session; the test suite points it at a path that does not exist, or at a stand-in. |
 | `TEZGAH_OPENCODE_BIN`, `TEZGAH_CURSOR_BIN`, `TEZGAH_CODEX_BIN` | `hooks/tezgah_paths.py::opencode_bin`, `hooks/tezgah_paths.py::cursor_bin`, `hooks/tezgah_paths.py::codex_bin` | `opencode`, `cursor-agent`, `codex` on PATH or a per-user bin dir | The CLI the judgement seam asks in that host's session; tests point them at stand-ins. |
 | `TEZGAH_DSH_BIN` | `bin/tezgah-setup::reconcile_json_servers` | the profile-local entry, then `bin/tezgah-dsh`, then npx | How the installer invokes the dsh CLI. |
 | `TEZGAH_INDEX_BIN` | `bin/tezgah-dsh:19`, `bin/tezgah-dsh.cmd` | `~/.config/tezgah/bin/tezgah-index` | The index worker `tezgah-dsh` warms before it starts dsh. |
@@ -75,11 +87,18 @@ the kill switches are files, not variables, and live in
 
 | Variable | Read by | Default | Effect |
 |---|---|---|---|
-| `OMPCODE`, `CLAUDECODE`, `OPENCODE`, `CURSOR_AGENT`, `CURSOR_VERSION`, `CODEX_THREAD_ID` | `hooks/tezgah_paths.py::session_cli` (all), `bin/consult`, `hooks/tezgah_models.py::worker_model` (the first two) | set by the host | Name the host session: the judgement seam asks that host's CLI first, in the order listed (omp sets both of the first two, so `OMPCODE` wins; Cursor sets `CURSOR_AGENT` in its shell tool and `CURSOR_VERSION` in its hooks; Codex sets `CODEX_THREAD_ID` in its shell tool only). The test suite unsets all of them. |
+| `OMPCODE`, `CLAUDECODE`, `OPENCODE`, `CURSOR_AGENT`, `CURSOR_VERSION`, `CODEX_THREAD_ID` | `hooks/tezgah_paths.py::session_cli` (all), `bin/consult`, `hooks/tezgah_models.py::worker_model` (the first two), `bin/tezgah-task::print_ocr_spec` (the first) | set by the host | Name the host session: the judgement seam asks that host's CLI first, in the order listed (omp sets both of the first two, so `OMPCODE` wins; Cursor sets `CURSOR_AGENT` in its shell tool and `CURSOR_VERSION` in its hooks; Codex sets `CODEX_THREAD_ID` in its shell tool only). The test suite unsets all of them. |
 | `TYPESAFE_API_KEY` | `hooks/tezgah_judge.py::key`, `hooks/tezgah_paths.py` | `~/.config/typesafe/key` | The judgement seam's first third-party credential, used as `fallback` in `config.json` allows ([judge](judge.md)); omp also reads it for its own judge. |
-| `OPENROUTER_API_KEY` | `hooks/tezgah_judge.py::openrouter_key`, `bin/consult`, `bin/codegen`, `hooks/tezgah_models.py` | `~/.config/openrouter/key` | The seam's chat fallback, consult's and codegen's `openrouter` provider, and omp's `any` family. |
+| `OPENROUTER_API_KEY` | `hooks/tezgah_judge.py::openrouter_key`, `bin/consult`, `bin/codegen`, `hooks/tezgah_models.py`, `hooks/tezgah_research_evidence.py::cmd_label` | `~/.config/openrouter/key` | The seam's chat fallback, consult's and codegen's `openrouter` provider, omp's `any` family, and the `--provider openrouter` rater of `tezgah-research label`. |
 | `DEEPSEEK_API_KEY`, `INCEPTION_API_KEY` | `bin/consult`, `bin/codegen`, `hooks/tezgah_replay.py::label_model` | `~/.config/deepseek/key`, `~/.config/inception/key` | The `deepseek` and `inception` providers of consult and codegen; `DEEPSEEK_API_KEY` alone is also the replay sheet's `--provider deepseek` rater. |
-| `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ZAI_API_KEY`, `OPENAI_CODEX_OAUTH_TOKEN` | `hooks/tezgah_models.py::OMP_AUTH` | omp's own auth store | Read as presence only: whether omp can run the `anthropic`, `zai` or `openai` model family, so the model table can pick a row omp will run. |
+| `ANTHROPIC_OAUTH_TOKEN`, `ANTHROPIC_API_KEY`, `ZAI_API_KEY`, `OPENAI_CODEX_OAUTH_TOKEN`, `EXPERIMENTALLABS_API_KEY` | `hooks/tezgah_models.py::OMP_AUTH` | omp's own auth store | Read as presence only: whether omp can run the `anthropic`, `zai`, `openai` or `experientiallabs` model family, so the model table can pick a row omp will run. |
+| `TEZGAH_HEALTH_CHECK` | `hooks/tezgah_models.py::health_due`, `hooks/tezgah_models.py::note_limit`, `hooks/tezgah_models.py::other_family_up` | unset | `0` turns off the provider health probe and the limit notes that read credentials; the test suite sets it, so no test asks a model or reads this machine's keys. |
+| `TEZGAH_JEV_PROVIDER`, `JEV_PROVIDER` | `hooks/tezgah_paths.py::jev_choice` | `jev` in `config.json`, else `auto` | The Jev carrier the judgement seam asks (`JEV_PROVIDER` is jev-mcp's own name); `auto` asks every carrier whose credential resolves, an unknown name resolves to none ([judge](judge.md)). |
+| `JEV_API_BASE_URL`, `JEV_API_KEY` | `hooks/tezgah_paths.py::jev_carriers`, `hooks/tezgah_judge.py::_jev_call` | unset | The `jev-compatible` carrier: any System One-compatible endpoint and its key. Plain `http` is refused unless the host is this machine. |
+| `TEZGAH_JEV_MODEL` | `hooks/tezgah_judge.py::_jev_call` | the seam's model | The model the `jev-compatible` carrier asks. |
+| `CLOUDFLARE_ACCOUNT_ID` | `hooks/tezgah_paths.py::cloudflare_account` | `~/.config/cloudflare/account_id` | The Workers AI account the `jev-cloudflare` and `clef` carriers call. |
+| `JEV_CLOUDFLARE_API_TOKEN`, `CLOUDFLARE_API_TOKEN` | `hooks/tezgah_paths.py::cloudflare_token` | `~/.config/cloudflare/token` | The Workers AI token, the first one set. |
+| `TEZGAH_CLOUDFLARE_URL`, `TEZGAH_JEV_OPENROUTER_URL` | `hooks/tezgah_judge.py::_jev_call` | Cloudflare's API base, OpenRouter's System One URL | Repoint the Workers AI and `jev-openrouter` carriers (tests). Plain `http` is refused unless the host is this machine. |
 | `TEZGAH_TYPESAFE_URL` | `hooks/tezgah_judge.py::endpoint` | `https://api.typesafe.ai/v1/systemone` | Repoints the seam's TypeSafe endpoint (tests). Plain `http` is refused unless the host is this machine; a cross-host redirect is refused. |
 | `TEZGAH_OPENROUTER_URL` | `hooks/tezgah_judge.py::openrouter_url` | OpenRouter's chat-completions URL | Repoints the seam's chat fallback (tests). Plain `http` is refused unless the host is this machine. |
 | `TEZGAH_DEEPSEEK_URL` | `hooks/tezgah_replay.py::_deepseek` | `https://api.deepseek.com/chat/completions` | Repoints the replay sheet's `--provider deepseek` rater (tests). Plain `http` is refused unless the host is this machine. |
@@ -99,6 +118,13 @@ the kill switches are files, not variables, and live in
 | `CODEGEN_URL` | `bin/codegen::ask` | the provider's URL | Repoints codegen's endpoint. Plain `http` is refused unless the host is this machine (`127.0.0.1`, `localhost`); a redirect to another host is refused. |
 | `CODEGEN_MODEL` | `bin/codegen::MODEL` | the cheap `any` row of the models table | The model codegen drafts with. |
 
+## Research capture
+
+| Variable | Read by | Default | Effect |
+|---|---|---|---|
+| `TEZGAH_SCOPUS_KEY` | `hooks/tezgah_research_capture.py::cmd_search` | unset | The Elsevier API key the `scopus` search connector sends; without it that connector refuses. |
+| `TEZGAH_CAPTURE_MAP` | `hooks/tezgah_research_capture.py::fetch_url` | unset | A JSON map that answers the capture commands' fetches instead of the network; tests set it, and `hooks/tezgah_research_evidence.py::cmd_release_check` sets it to its fixtures' `capture-map.json`. |
+
 ## Status line
 
 | Variable | Read by | Default | Effect |
@@ -106,8 +132,9 @@ the kill switches are files, not variables, and live in
 | `NO_COLOR` | `hooks/tezgah_context.py::color_default`, `hosts/omp/tezgah-hook.ts.in` | unset | Any value renders the status line without ANSI colour. |
 | `TEZGAH_STATUS_COLOR` | `hooks/tezgah_context.py::color_default`, `hosts/omp/tezgah-hook.ts.in` | unset | `0` is the same opt-out as `NO_COLOR`, for tezgah alone. |
 | `TEZGAH_STATUS_ANIMATE` | `hosts/omp/tezgah-hook.ts.in:65` | unset (animated) | `0` keeps omp's status colours and drops the motion. |
-| `TEZGAH_STATUS_HOST` | `statusline.py::HOST` | `claude` | `cursor` renders for Cursor (the same as `--cursor`). |
-| `TEZGAH_STATUS_LEGEND` | `statusline.py:127` | unset | `1` prints the mark legend under the line. |
+| `TEZGAH_STATUS_HOST` | `statusline.py::HOST` | `claude` | `cursor`, `qwen`, `droid`, `copilot` or `antigravity` renders for that host (the same as `--cursor` and the like). |
+| `TEZGAH_STATUS_LEGEND` | `statusline.py:138` | unset | `1` prints the mark legend under the line. |
+| `COLORFGBG` | `hooks/tezgah_context.py::light_background` | unset (dark) | The terminal's reported colours: a light background picks the light palette. |
 
 ## Set by tezgah or the host, not by a user
 
@@ -119,15 +146,16 @@ the kill switches are files, not variables, and live in
 | `TEZGAH_CORE_IN_FILE` | `hooks/projects-auto-init.py::core_is_in_a_file`, `hooks/hooks.json` | unset | `1` (set by the Claude plugin's hook rows) drops the core rules from the injection when the host's static file really carries the tezgah block; a file without it falls back to the hook. |
 | `TEZGAH_HOST` | `hooks/tezgah_context.py::context_for`, `hooks/hooks.json` | unset | `claude` (set by the Claude plugin's UserPromptSubmit row; the payload names no host) makes the skill hint name the Skill tool's `tezgah:<name>` beside the path instead of a `skill://` address (`hooks/tezgah_skill_pick.py::_emit`). A host that sends `host` in the payload (omp, opencode) is not read from here. |
 | `TEZGAH_NESTED` | `hooks/tezgah_integrity.py::_shape_block`, `bin/consult` | unset | Set by consult on the agent CLIs it runs: that session's Stop rule does not fire. |
-| `TEZGAH_CALL_OUTCOME` | `hooks/projects-posttooluse.py::main`, `hosts/dsh/hooks.json` | unset | `none` (dsh's Task rows) records the call's outcome as unknown instead of as a pass. |
+| `TEZGAH_CALL_OUTCOME` | `hooks/projects-posttooluse.py::main`, `hooks/tezgah_integrity.py::_hook_host`, `hosts/dsh/hooks.json` | unset | `none` (dsh's Task rows) records the call's outcome as unknown instead of as a pass. |
 | `CLAUDE_PROJECT_DIR` | `hooks/projects-auto-init.py::main` | the process cwd | The project dir when the hook payload carries no `cwd`. |
-| `PLAYWRIGHT_BROWSERS_PATH`, `LOCALAPPDATA` | `hooks/tezgah_apps.py::_browser_caches`, `bin/tezgah-setup::default_prefix` (`LOCALAPPDATA` only) | Playwright's own cache dirs | Where `analyze-app` looks for an installed browser before it reports one missing; on Windows `LOCALAPPDATA` is also the parent of the default install prefix. |
+| `PLAYWRIGHT_BROWSERS_PATH`, `LOCALAPPDATA` | `hooks/tezgah_apps.py::_browser_caches`, `bin/tezgah-setup::default_prefix` and `packaging/install.ps1` (LOCALAPPDATA only) | Playwright's own cache dirs | Where `analyze-app` looks for an installed browser before it reports one missing; on Windows `LOCALAPPDATA` is also the parent of the default install prefix. |
+| `AMP_IGNORE_GUIDANCE_FILES` | `hosts/amp/tezgah-plugin.ts.in` | set by the user for Amp | Amp's own list of guidance files to skip; when it is set the plugin asks for the session brief with the core in it, since `~/.config/amp/AGENTS.md` may be skipped. |
 
 ## Test knob
 
 | Variable | Read by | Default | Effect |
 |---|---|---|---|
-| `TEZGAH_E2E_STRICT` | `tests/e2e_*.py`, `.github/workflows/ci.yml` | unset (a missing prerequisite is a SKIP) | `1` turns an end-to-end script's SKIP into a FAIL; CI sets it. |
+| `TEZGAH_E2E_STRICT` | `tests/e2e_analyze_wiring.py`, `tests/e2e_docker_cycle.py`, `tests/e2e_packaged_install.py`, `tests/e2e_plan_flow.py`, `tests/e2e_tezgah_mcp.py`, `tests/neuter_matrix.py`, `.github/workflows/ci.yml`, `.github/workflows/neuter.yml` | unset (a missing prerequisite is a SKIP) | `1` turns a SKIP into a FAIL in the six scripts listed. CI sets it on `e2e_plan_flow`, `e2e_analyze_wiring` and `e2e_packaged_install` (ci.yml) and on `neuter_matrix` (neuter.yml). `e2e_docker_cycle` and `e2e_tezgah_mcp` read it but are opt-in: set it by hand to make their missing prerequisite a failure. The other end-to-end scripts (`e2e_qwen`, `e2e_droid`, `e2e_omp_statusline`, `e2e_dsh_statusline`, `e2e_analyze_web`, `e2e_analyze_mobile`) ignore it: they need a host CLI or paid model calls a CI run does not have, and still SKIP. |
 | `TEZGAH_OPENCODE_NO_SQLITE` | `hosts/opencode/plugins/tezgah.js` | unset (node:sqlite when the runtime has it) | `1` makes the opencode plugin read and write the evidence ledger through `python3 hooks/tezgah_store.py evidence ...`, the path a runtime without node:sqlite takes; a test sets it. |
 
 ## Debugging
@@ -135,17 +163,24 @@ the kill switches are files, not variables, and live in
 | Variable | Read by | Default | Effect |
 |---|---|---|---|
 | `TEZGAH_DEBUG` | `hooks/tezgah_guard.py` | unset (off) | Any value but empty or `0` makes every hook process append one line to `<cache>/debug.log` (created 0600): `<epoch> host=<codex\|cursor\|omp\|claude/dsh> script=<entry script> calls=<core fn>:<answer\|none\|ExceptionClass>,... ms=<elapsed>`. `answer` means the core returned something (a deny reason, a context block, a block decision). No prompt or tool text is written. Off, it costs one environment read. `tezgah-doctor --clean` removes the file once it has gone untouched for `--retention-days` (default 30). |
+| `TEZGAH_REPO_RULE` | `hooks/tezgah_gate.py::REPO_RULE_VALVE`, `hosts/opencode/plugins/tezgah.js` | unset | `0` skips a repository's own `.tezgah/gate.py` rule ([gate](gate.md#a-repositorys-own-rule)): the off valve for a refusal the repository, not tezgah, wrote. |
 
 ## Source of truth
 
 `hooks/tezgah_paths.py`, `hooks/tezgah_judge.py`, `hooks/tezgah_models.py`,
 `hooks/tezgah_index.py`, `hooks/tezgah_apps.py`, `hooks/tezgah_agents.py`,
 `hooks/tezgah_context.py`, `hooks/tezgah_integrity.py`,
+`hooks/tezgah_orca.py`, `hooks/tezgah_extension.py`, `hooks/tezgah_stack.py`,
+`hooks/tezgah_update.py`, `hooks/tezgah_guard.py`, `hooks/tezgah_gate.py`,
+`hooks/tezgah_skill_pick.py`, `hooks/tezgah_research_capture.py`,
+`hooks/tezgah_research_evidence.py`,
 `hooks/projects-auto-init.py`, `hooks/projects-posttooluse.py`, `statusline.py`,
 `bin/tezgah-setup`, `bin/consult`, `bin/codegen`, `bin/tezgah-status`,
-`bin/tezgah-doctor`, `bin/tezgah-dsh`, `bin/tezgah.js`, `packaging/install.sh`,
+`bin/tezgah-doctor`, `bin/tezgah-dsh`, `bin/tezgah-ocr-review`, `bin/tezgah-task`,
+`bin/tezgah.js`, `packaging/install.sh`,
 `packaging/upgrade.sh`, `packaging/install.ps1`, `packaging/build.sh`,
-`hosts/omp/tezgah-hook.ts.in`, `hosts/opencode/plugins/tezgah.js`,
-`hosts/dsh/statusline/lib/index.js`. The list was taken by searching the shipped
-code for `os.environ`, `getenv`, `process.env`, `$env:` and `${...}` reads; re-run
-that search after adding a variable and add its row here.
+`hosts/omp/tezgah-hook.ts.in`, `hosts/amp/tezgah-plugin.ts.in`,
+`hosts/opencode/plugins/tezgah.js`, `hosts/dsh/statusline/lib/index.js`. The
+list covers the shipped code's `os.environ`, `getenv`, `process.env`, `$env:` and
+`${...}` reads. `tests/test_docs.py::ContractAndEnvironment` re-runs that search
+and fails on a name with no row here.

package/docs/evidence.md

@@ -11,8 +11,12 @@ One append-only ledger per session, stored as the `evidence` rows of `<cache>/te
 (`hooks/tezgah_store.py::EVIDENCE_SCHEMA`). A row keeps the JSON text its writer produced, with the
 session, `kind` and `ts` in columns beside it. A caller names a ledger by its old file path,
 `<cache>/evidence/<slug>.jsonl`. The stem is the session key: a readable prefix plus a hash of the
-session id, which nothing can turn back into the id (`hooks/tezgah_integrity.py::_slug`). Every writer goes through `note_path` (`hooks/tezgah_integrity.py::note_path`): `note()`
-derives the path from the session id (`hooks/tezgah_integrity.py::note`). The row is built in exactly one place (`hooks/tezgah_integrity.py::note_path`), and its shape is
+session id, which nothing can turn back into the id (`hooks/tezgah_integrity.py::_slug`). Every Python writer but one goes through `note_path` (`hooks/tezgah_integrity.py::note_path`): `note()`
+derives the path from the session id (`hooks/tezgah_integrity.py::note`). The exception is the pre-write snapshot writer
+(`hooks/tezgah_snapshot.py::_append`). Its `snapshot` and `rollback` rows keep a path longer than `DETAIL_MAX` and a `forced`
+key, which `note_path` would cut and drop. So they go straight to the same `_append` and the same ledger. They carry the same
+`v`, but their `detail` is neither redacted nor cut. The opencode plugin builds its rows in JavaScript and inserts them itself
+(`appendRow` in `hosts/opencode/plugins/tezgah.js`), with no `v`. Every other row is built in one place (`hooks/tezgah_integrity.py::note_path`). Its shape is
 `{"kind": …, "ts": …, "v": …, "detail": …}` plus whatever `LEDGER_FIELDS` keys the writer knew — for a check
 the host reported passing, `{"kind": "verify_ok", "ts": 1758000000, "v": 3, "detail": "pytest -q",
 "id": "a1b2c3d4e5f6", "exit": 0, "out_bytes": 4312, "tool": "Bash", "repo": "/home/u/proj"}`. `v` names the shape the row was written under
@@ -33,11 +37,21 @@ JSON key (`"password": "x"`) and as a flag with its value after a space (`--pass
 `--api-key X`, `mysql -pPASS`) - an `Authorization` scheme (`Bearer`, `Basic`, `Token`, `Digest`),
 the password of URL userinfo (`scheme://user:pass@`) and of `-u user:pass`, and a prefixed token
 family lose theirs (`hooks/tezgah_integrity.py::REDACTIONS`; audit L-6, which found each of those stored verbatim). The optional fields are exactly `LEDGER_FIELDS`
-(`hooks/tezgah_integrity.py::LEDGER_FIELDS`) — `id`, `exit`, `out_bytes`, `fail_class`, `workspace`, `source`, `hash`, `changed`, `tool`,
-`target`, plus the reply-shape names `lines`, `chars`, `items`, `longest_list`, `tr_share`, `answer_first` and the compaction
-row's `summary_chars`, `summary_hash`, `constraint_found`, `constraint_expected`, the `attest`
-row's `host` and `switches`, a `claim` row's `harness` and a Stop refusal row's `reask` (the key of its own text, which the `turn` row of omp's continuation carries, `hooks/tezgah_integrity.py::_turn_refusals`) — and
-a key outside that set is dropped, a `None` value left out, because every reader treats a missing key
+(`hooks/tezgah_integrity.py::LEDGER_FIELDS`):
+
+- a call's `id`, `exit`, `out_bytes`, `fail_class`, `workspace`, `source`, `hash`, `changed`, `tool`, `target`, `repo`,
+  `empty_run`, and the began row's `check`
+- the reply-shape names `lines`, `chars`, `items`, `longest_list`, `tr_share`, `answer_first`, and a read-only turn's `mode`
+- the compaction row's `summary_chars`, `summary_hash`, `constraint_found` and `constraint_expected`
+- the attest row's `host` and `switches`, a claim row's `harness`, and a refusal's `cause`
+- a Stop refusal row's `reask`: the key of its own text, which the turn row of omp's continuation carries
+  (`hooks/tezgah_integrity.py::_turn_refusals`)
+- the lineage names `parent`, `child` and `agent`, on the spawned, forked, spawn, subagent_start and subagent_end rows
+- a lesson row's `key` and `block`, the authorized row's `authorized`, and a turn row's `inflight`
+- a todo row's `open`, `ready`, `blocked`, `heads`, `taken` and `partial`
+- a subagent_end row's `residual`, and an ask row's `questions` and `defaults`
+
+Any key outside that set is dropped, a `None` value left out, because every reader treats a missing key
 as `None` (`hooks/tezgah_integrity.py::note_path`). `tool` is the call's own name (`Bash`, `Write`, `mcp__codegen__status`),
 written by `note_tool` (`hooks/tezgah_integrity.py::note_tool`) because `classify` folds the name into
 a kind and drops it; it is what `_counts`' tool histogram counts and what the retirement report on
@@ -121,14 +135,15 @@ a write tool is `edit`, a shell call is `verify` when its command matches the ch
 | `wait` | `hooks/tezgah_integrity.py::note_tool`, for omp's `wait` | `hooks/tezgah_gate.py::ready_advice`, which counts it as idle; nothing counts it as work |
 | `ask` | `hooks/tezgah_gate.py::ask_advice`, for an omp `ask` or Claude AskUserQuestion call: `detail` holds the questions, cut; `questions` counts them and `defaults` the ones with a recommended option | nothing refuses on it; the row is the record of what the session asked |
 | `grant` | `hooks/tezgah_context.py::context_for`, from each prompt's `user_grants` (`hooks/tezgah_context.py::user_grants`): `detail` holds the user's clause, `target` the outward class it covers (`push`, `release`, `publish`, `pr` or `all`), or `lift:<class>` when the prompt took it back | `hooks/tezgah_integrity.py::grants_in_force`, read by the `needless ask` Stop class and the ask-tool warning |
-| `began` | the gate's allow path for a write or shell call `hooks/tezgah_gate.py::decision`; on opencode the plugin's before-hook when the core was not asked (`hosts/opencode/plugins/tezgah.js:2602-2618`) | `hooks/tezgah_integrity.py::unanswered`, behind a claim in the Stop rule and in `counters.unanswered` |
+| `began` | the gate's allow path for a write or shell call `hooks/tezgah_gate.py::decision`; on opencode the plugin's before-hook too, ahead of its own refusals and on its allow path, once per call: a call the core already wrote a row for keeps that one (`hosts/opencode/plugins/tezgah.js::noteBegan`) | `hooks/tezgah_integrity.py::unanswered`, behind a claim in the Stop rule and in `counters.unanswered` |
 | `claim` | `hooks/tezgah_integrity.py::stop_reason`, only for a reply in the claim vocabulary - a completion or verification word (`DONE`/`VERIFIED`), blocked or allowed, or a refused claim about an external system's state (`_external_claim`) | `hooks/tezgah_integrity.py::counters` |
 | `refusal` | `stop_reason`, for a blocked reply that claimed nothing - a work-only or a shape refusal - with the same `blocked: <class>` detail (row version 3) | `counters.refusals`, and `shape_blocked` for a shape class; never a claim; `NOT_TOOL_HOOK` lists it |
 | `after_block` | `hooks/tezgah_integrity.py::stop_reason`, on a reply after this rule's own block (a turn holding a `blocked:` claim or refusal row) that is not refused again (`_record_only`) on Claude, Codex, Cursor and omp; `detail` is `would block: <class>`, `ok` or `no claim` | nothing yet: a record for the after-block observation window, not a claim and not a second `shape` row, so `counters` counts it neither as a claim nor as a reply; `NOT_TOOL_HOOK` lists it |
-| `subagent_end` | `stop_reason(..., subagent=True)`, from Claude's SubagentStop (`hooks/hooks.json`) and Cursor's subagentStop `summary`; the evidence half only, never a block (ADR 011); `detail` as `after_block`'s | nothing yet: the rows plan 055 replays before a subagent end may block; `NOT_TOOL_HOOK` lists it. On Claude a subagent's tool rows sit in the parent's ledger, so until the agent key (plan 050) lands the row judges the parent's turn |
+| `subagent_end` | `stop_reason(..., subagent=True)`, from Claude's SubagentStop (`hooks/projects-stop.py::main`), Cursor's subagentStop `summary` (`hosts/cursor/hook.py::dispatch`), Droid's SubagentStop `task_result` (`hosts/droid/hook.py::main`), Qwen's and Copilot's SubagentStop (`hosts/qwen/hook.py::main`, `hosts/copilot/hook.py::main`), and Amp's and omp's `subagent_stop`, which their bridges send from the child's end with its `parent` (`hosts/amp/hook.py::handle`, `hosts/omp/hook.py::handle`); the evidence half only, never a block (ADR 011); `detail` as `after_block`'s | nothing yet: the rows plan 055 replays before a subagent end may block; `NOT_TOOL_HOOK` lists it. On Claude a subagent's tool rows sit in the parent's ledger, so until the agent key (plan 050) lands the row judges the parent's turn |
+| `reply_unread` | Droid's, Command Code's, Copilot's, Antigravity's and Goose's Stop (`hosts/droid/hook.py::main`, `hosts/commandcode/hook.py::main`, `hosts/copilot/hook.py::main`, `hosts/antigravity/hook.py::main`, `hosts/goose/hook.py::main`) when the transcript or payload yields no closing assistant text (`hosts/droid/hook.py::last_reply`, `hosts/copilot/hook.py::last_reply`); `detail` names the transcript, or says there was none. Such a Stop event carries no reply, or carries it empty, and an empty reply judged would pass any claim as "no claim", so the turn end is recorded and not judged | nothing yet; `NOT_TOOL_HOOK` lists it |
 | `stop_spec` | nothing since plan 101. Plan 063's shadow wrote one per reply that left a claim or a refusal row: `agree`, `disagree` or `error`, and `fold` or `selector`. The fold it compared against is gone | nothing. `NOT_TOOL_HOOK` still lists it and the replay keeps it beside its claim (`hooks/tezgah_replay.py::SIDE_KINDS`), so an old ledger reads as it did |
 | `deny`, `nudge` | the [gate](gate.md)'s `hooks/tezgah_gate.py::_deny`, first-nudge `hooks/tezgah_gate.py::decision` | `hooks/tezgah_integrity.py::counters` |
-| `snapshot`, `rollback` | `hooks/tezgah_snapshot.py::_capture_one`, `hooks/tezgah_snapshot.py::restore` | `hooks/tezgah_integrity.py::_snapshot_hash`; no counter |
+| `snapshot`, `rollback` | `hooks/tezgah_snapshot.py::_capture_one`, `hooks/tezgah_snapshot.py::restore`, through the module's own `hooks/tezgah_snapshot.py::_append` rather than `note_path` (the Python exception, above): the row carries `v` but keeps its full path, and a forced rollback's `forced` | `hooks/tezgah_integrity.py::_snapshot_hash`; no counter |
 | `compact` | `hooks/tezgah_integrity.py::note_compaction`, from the post-compaction path (`tezgah_context.remember_compaction` `hooks/tezgah_context.py::remember_compaction`) | `hooks/tezgah_integrity.py::_counts` (what `counters` folds with) |
 | `lesson` | `hooks/tezgah_context.py::note_lesson`, one row per lesson the budget left in a session block or a per-turn block, with its 8-hex `key` and `block` (`session` or `turn`), inside the host's `safe()` like the rest of the prompt path | no counter; `hooks/tezgah_context.py::NOT_TOOL_HOOK` keeps it out of `hooks/tezgah_context.py::_ledger_since`, so a session of lesson rows still reads as a gate that never ran |
 | `lesson_tainted` | the gate's allow path for a write to a `.tezgah/lessons.md` (`hooks/tezgah_gate.py::lesson_taint`, from `decision` after every refusal) in a user turn that already holds a row carrying `source`, folded over `turn_rows` (that subagent's rows when the host names one). One row per lesson line the ledger will hold after the write and does not hold now, read off the post-write text, so a partial-line edit names the whole line; its 8-hex `key`, the channel in `source` and `detail`, the ledger in `target`. One row with no `key` when the gate cannot name the line (an `echo` append, an edit whose old text is not there, a removal). The keyed rows also go to the repository's index, which keeps only the ledger's current lines (`hooks/tezgah_lessons.py::write_taint`). Never a refusal (ADR 010); the dry run writes neither | the per-line data label on that lesson in both lesson blocks (`hooks/tezgah_context.py::LESSON_TAINTED`, read once per prompt through `hooks/tezgah_lessons.py::tainted`); no counter |
@@ -138,6 +153,16 @@ a write tool is `edit`, a shell call is `verify` when its command matches the ch
 | `disarm` | `hooks/tezgah_context.py::disarmed`, on the prompt a switch first appears on after the session's first prompt; `detail` is the switch name. Also the gate (`hooks/tezgah_gate.py::decision`), for a call it lets through that changes a `CONTROL_EVIDENCE` target - an open plan's delete or move, a forced `git add` of a `.tezgah/` path - with the call's `id` and `detail` `control: <what>` | the status line's `gate` mark ([status-line.md](status-line.md)) for the switch rows, set by the same check that writes them; the gate's rows are read by a person or a replay; no counter |
 | `attest` | `hooks/tezgah_attest.py::run`, once per session start: Claude and dsh (`hooks/projects-auto-init.py::main`), Codex, Cursor and omp from their session-start events, opencode at the first message through `oncePerSession` (`bin/tezgah-context::main`). `detail` is `ok`, `drifted: <entries>` (an entry added, removed or changed since install, a hook file any user can write, a stale omp bridge, a changed entry script on a release install) or `unverified: <why>`; `host` names the host, `switches` the kill switches present. The module is imported only inside that call, so a broken one costs the row and never a gate | the `drift` status mark and the `harness` field of the session's later `claim` rows, read from one `harness_drift` row of `<cache>/tezgah.db` per session and host (`hooks/tezgah_attest.py::drift_key`, so one host's clean start cannot clear another's) - an annotation, never a Stop block; `NOT_TOOL_HOOK` lists it, so a session start after a compaction does not read as a gate that ran |
 | `crash` | `hooks/tezgah_guard.py::safe` for a core call that raised, and `hooks/tezgah_guard.py::import_failed` for an entry point whose core imports raised (`detail` `import: <class>: <message>`). An import failure also writes one stderr line and the status line's `crash` mark, always; when `tezgah_integrity` or `tezgah_paths` is the module that failed, the row is the part that cannot be written. Hooks fail open with exit 0; `tezgah-gate check` exits 3 | `NOT_TOOL_HOOK` lists it; no counter |
+| `shape` | `hooks/tezgah_integrity.py::stop_reason`, one row per judged reply, keyed like the claim row: `detail` is the report-only shape flags or `ok`, with the reply-shape fields and, in a read-only turn, `mode` | `hooks/tezgah_integrity.py::_counts` (`replies`, `shape`); `hooks/tezgah_integrity.py::_in_flight` |
+| `authorized` | `hooks/tezgah_integrity.py::note_turn`, before the `turn` row of a prompt that names a kill switch while no call is in flight; `authorized` lists the names | the switch latch (`hooks/tezgah_paths.py::_authorized`), which honors a switch made mid-session only when such a row names it |
+| `drift` | `hooks/tezgah_gate.py::drift_reason`, once per turn, before the refusal that re-states the rules once the turn passed `DRIFT_STEPS` steps; `detail` is the step count | `drift_reason` itself (one per turn); `hooks/tezgah_shapes.py::GATE_SIDE_KINDS` and the replay's `hooks/tezgah_replay.py::SIDE_KINDS` |
+| `spawned`, `forked` | the child's session start, in the child's ledger: `spawned` on omp and Amp for a subagent whose bridge names its `parent` (`hosts/omp/hook.py::handle`, `hosts/amp/hook.py::handle`), on Cursor's subagentStart (`hosts/cursor/hook.py::dispatch`) and on opencode's `session.created` of a child (the plugin's `event` hook in `hosts/opencode/plugins/tezgah.js`), with its `agent`; `forked` on omp for a fork, `parent` holding the session it was forked from | the race rule's relation (`hooks/tezgah_integrity.py::_relation`, `hooks/tezgah_integrity.py::spawn_of`); `tezgah-route --report` (`hooks/tezgah_models.py::route_report`); the replay corpus (`hooks/tezgah_replay.py::build_corpus`) |
+| `spawn` | omp's post-tool path for a `task` call (`hosts/omp/hook.py::handle`), one row per named task in the parent's ledger: `child` is the task name, `agent` the agent it runs (`task` when none is given) | `tezgah-route --report`, joining a route to its worker (`hooks/tezgah_models.py::route_report`) |
+| `subagent_start` | the SubagentStart event in the parent's ledger: Claude's (`hooks/projects-auto-init.py::note_child`), Codex's (`hosts/codex/hook.py::main`) and Qwen's (`hosts/qwen/hook.py::main`); `detail` is the agent type, `agent` the agent id | `tezgah-route --report` (`hooks/tezgah_models.py::route_report`) |
+| `orch` | `hooks/tezgah_context.py::record`, for a subagent event (Claude's and dsh's SubagentStart, Codex, Cursor, Droid, Qwen and Copilot subagent events) or a call a host classifies as a delegation | `counters.fanout` (`hooks/tezgah_integrity.py::_counts`) |
+| `judge` | each model judgement's caller: the skill pick (`hooks/tezgah_skill_pick.py::judge`), `tezgah-route` (`bin/tezgah-route.py::main`), `tezgah-docs` and `tezgah-triage` (`bin/tezgah-docs.py::record`, `bin/tezgah-triage.py::record`); `detail` names the caller, the model and the token counts | `counters.judge` (`hooks/tezgah_integrity.py::_counts`) |
+| `route` | `bin/tezgah-route.py::main`, when the call knows its session: the routing verdict (`hooks/tezgah_models.py::route_detail`) | `tezgah-route --report` (`hooks/tezgah_models.py::route_fields`, `hooks/tezgah_models.py::route_report`); the replay's `hooks/tezgah_replay.py::TEST_ROW_KINDS` |
+| `delegation` | opencode's plugin only (`noteDelegation` in `hosts/opencode/plugins/tezgah.js`), when the Python core could not be asked about a call: `detail` is `gate: <failure>`, `id` the session. The call still passes | no reader by name; `counters`' kind histogram counts it (`hooks/tezgah_integrity.py::_counts`) |
 
 **`compact` is what a compaction kept, from the record.** When the host hands the PostCompact
 payload the text the model is about to receive — Claude's `compact_summary` — the shared path
@@ -296,12 +321,31 @@ The checker is `_stop_block` (`hooks/tezgah_integrity.py::_stop_block`), reached
 (`hosts/omp/hook.py::handle`) — all with `{"decision": "block", "reason": …}`, all inert outside a
 [root](glossary.md#root) and under the `verify-off` [kill switch](glossary.md#kill-switch)
 (`hooks/projects-stop.py::main`). Each of these hosts judges the reply after a block again.
+The reply the rule judges is read through `reply_prose`
+(`hooks/tezgah_integrity.py::reply_prose`). A string passes through. A host that hands over
+a message object yields its `text` blocks, joined the way the model wrote them. A thinking
+or tool block is left out. omp's `session_stop` carries `last_assistant_message` as the object
+its `getLastAssistantMessage()` returns, and the bridge passed it through, so the rule judged
+`str(dict)`: one line, no list items, diluted prose. Measured on
+the owner's evidence database (2026-10-29): 1643 of 1656 omp `shape` rows of 45 days carried
+`lines: 1`. Every other host wrote 209 multi-line rows of 231. Of the three days' refusals, 24
+were `reply language` over such a row, and every line-shaped class read a text that had no
+lines. The bridge now sends the text too
+(`hosts/omp/tezgah-hook.ts.in`), but the core is where a host cannot repeat it (plan 143).
 The re-ask budget is the core's (`_record_only`, `hooks/tezgah_integrity.py::_record_only`): at
 most `STOP_REASKS` = 2 refusals in one user turn, and never two for one reason class. The count
 comes from the turn's `blocked:` claim and refusal rows, not from the host's payload. The omp host
-hands a block back as a queued message. Its prompt hook writes that text as a new `turn` row. A
-refusal row stores the key of its text as `reask`. A `turn` row with that key starts no new user
-turn for the count (`_turn_refusals`, `hooks/tezgah_integrity.py::_turn_refusals`). The omp host
+hands a block back as a queued message. Its prompt hook writes that text as a new `turn` row.
+Gemini does the same: an AfterAgent deny comes back through BeforeAgent as the next prompt
+(`hosts/gemini/hook.py::main`). A refusal row stores the key of its text as `reask`. A `turn` row with that key starts no new user
+turn for the count (`_turn_refusals`, `hooks/tezgah_integrity.py::_turn_refusals`). Antigravity's
+`continue` re-enters the loop with no prompt, so its first-invocation hook writes no `turn` row
+while the ledger's last row is that refusal (`hosts/antigravity/hook.py::reentered`). A Goose Stop
+block keeps the turn going with no new prompt and no host count, so its turn rows alone decide
+(`hosts/goose/hook.py::main`). Amp's plugin continues a blocked turn with a user message that
+starts with `[tezgah:stop]`. The plugin never sends that prompt as a `user_prompt`. So it writes
+no `turn` row and grants nothing. The Stop rule then judges that turn with `stop_hook_active`
+(`hosts/amp/tezgah-plugin.ts.in`). The omp host
 caps the continuations it starts itself, but never a chain of blocks, so tezgah's count bounds that
 chain. So a reply that fixes the first class but adds a new one gets one more refusal. A blocker
 list with no evidence is such a new class. A reply after a block that is not refused writes one
@@ -310,7 +354,7 @@ while the turn holds no refusal of this rule. That reply gets no refusal and no
 Stop hook may have blocked. The host's count rules only where the ledger cannot. A session with no
 `turn` row allows one refusal per chain. A Cursor `loop_count` of 2 ends the chain. The opencode
 host has no Stop rule and so no budget. Its plugin API has no end-of-turn hook with an output. The
-`event` hook of `hosts/opencode/plugins/tezgah.js` only observes. Twelve triggers, in order, each naming its reason class (`_stop_block`
+`event` hook of `hosts/opencode/plugins/tezgah.js` only observes. Fifteen triggers, in order, each naming its reason class (`_stop_block`
 `hooks/tezgah_integrity.py::_stop_block`).
 The first four judge how the reply is written (`_shape_block`, `hooks/tezgah_integrity.py::_shape_block`); the rest judge its evidence:
 
@@ -339,8 +383,9 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    are read at a command position on the masked text, `re.M` so that a command on its own later
    line of the same call counts. A component turn owes one thing more: when a changed UI source is
    a component rather than a screen (`hooks/tezgah_integrity.py::DESIGN_COMPONENT` - a file
-   under a component/views/widgets
-   directory, or a name that carries the convention on its own), a fresh read of the screen is not
+   under a component/views/widgets/templates directory, a name that carries the convention on its
+   own, a single-file `.vue`/`.svelte`/`.astro` component, or the route file a framework with no
+   `components/` convention renders from: `page.tsx`, `layout.tsx`, `+page.svelte`), a fresh read of the screen is not
    enough by itself and a `tezgah-design check` row has to be newer than the component write it
    judges (`hooks/tezgah_integrity.py::_design_evidence`, branch `hooks/tezgah_stopspec.py::verdict`) - and it has
    to be a check whose pass was seen (`passing_check`, `hooks/tezgah_integrity.py::passing_check`), because
@@ -376,8 +421,12 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    A prose edit is no step and no change (`hooks/tezgah_integrity.py::_prose_edit`,
    `hooks/tezgah_integrity.py::_work_row`). Such an `edit` row has a real `target` ending in
    `.md`, `.markdown`, `.rst` or `.adoc`. It owes no check and does not stale a pass. An agent
-   instruction file is not prose: `SKILL.md`, `AGENTS.md`, `CLAUDE.md` and anything under
-   `skills/`, `prompts/`, `agents/`, `commands/` or a host directory stay a change. A reply that
+   instruction file is not prose (`hooks/tezgah_integrity.py::INSTRUCTION_NAMES`,
+   `hooks/tezgah_integrity.py::INSTRUCTION_DIRS`, matched without case): a file named `SKILL.md`, `AGENTS.md`,
+   `CLAUDE.md`, `GEMINI.md`, `copilot-instructions.md` or `rules.md`, and anything with `skills/`,
+   `prompts/`, `templates/`, `agents/`, `commands/`, `output-styles/`, `hooks/`, `.claude/`,
+   `.cursor/`, `.codex/`, `.omp/` or `.github/` among its directories, stay a change. A repo's own
+   `hosts/<host>` directory is not in the set. A reply that
    claims a test ran ("tested", "tüm testler geçti") still needs a pass after a prose-only turn.
    A comment-only edit to code is still a change: the row carries no text to tell it apart.
 10. **no external read** — the reply states the state of a system tezgah does not own — a registry,
@@ -457,7 +506,8 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    refused. A turn with no step, a ledger with no turn marker and a nested session skip it. A
    subagent's end is never refused (ADR 011). Its `subagent_end` row carries the count of its
    untyped items as `residual`. The parent's Stop then refuses a reply that types no item of its
-   own. Claude and Cursor write that row from their subagent-stop events. omp fires none for a
+   own. Claude, Cursor, Droid, Qwen and Copilot write that row from their subagent-stop events,
+   and Amp's bridge from the child's end. omp fires none for a
    task session. Its bridge sends the child's last reply from `agent_end`. The row lands in the
    ledger of the session that spawned the child, read from the child's own session header, and
    counts once per child. Codex, opencode and dsh write no such row. On omp the reply after a
@@ -516,18 +566,71 @@ The four shape classes share their switches with the text they enforce: `adhd-of
    (`hooks/tezgah_integrity.py::QUESTION_END`). Its paragraph names no recommended default, and
    it names no step the ask policy keeps from a default (`hooks/tezgah_integrity.py::never_default`).
    Such steps are a force push, a delete, production, a credential, a third party, or a spend
-   over `spend_cap`. The class then refuses a process question: the packs' `ask.process`
+   over `spend_cap`. Building a plan the reply wrote is one too
+   (`hooks/tezgah_integrity.py::PLAN_BUILD`). So is a last line that asks the owner to pick a
+   variant ("V4 mü V1 mi?"), to take a way around a tezgah refusal, or to decide about another
+   session's work (`hooks/tezgah_integrity.py::OWNER_CHOICE`, plan 136). The
+   class then refuses a process question: the packs' `ask.process`
    shapes, such as "Başlayayım mı?", "shall I proceed?" and "which first?"
    (`hooks/tezgah_integrity.py::PROCESS_ASK`). It also refuses a question about an outward
    step the user granted this session (`hooks/tezgah_integrity.py::grants_in_force`). A question
    about an outward step the user has not granted is the one the policy asks, so it passes. The
-   refusal says to take the step, or to move it into the approval batch with a default. Under
+   refusal says to take the step, or to move a taste or intent fork into the approval batch
+   with a default. A class-F step waits for the answer. Under
    `tr` it opens with "Bu soruyu sorma". `_residual_block` asks it after `residual work` and
    before `ready steps` (`hooks/tezgah_integrity.py::needless_ask`). Unlike those two, it needs
-   no work in the turn, because a plan proposal that ends "Başlayayım mı?" is its measured case.
+   no work in the turn, because a reply that ends on a bare "Başlayayım mı?" is its measured case.
    The research line counted 33 process questions among 48 question endings in the owner's omp
    transcripts. It refuses once per turn and counts like `residual work`
    (`hooks/tezgah_integrity.py::LIST_BLOCKS`).
+14. **handed step** — a turn that ran a command of its own ends by telling the reader to run
+   one (plan 142). The line names a command in backticks and addresses the reader as the one
+   who runs it: the packs' `ask.hand_over` shapes, "komutunu sen çalıştır", "çalıştırman
+   gerekiyor", "senin adımın", "please run", "your step:"
+   (`hooks/tezgah_integrity.py::handed_steps`). An answer about how something is done is not
+   one of them. "you can run `git config --global ...`" answers the question the reader
+   asked, and the review of this plan caught the wider wording refusing it. The turn must
+   hold a
+   `run`/`verify*` row (`hooks/tezgah_integrity.py::COMMAND_KINDS`). A turn that ran nothing
+   could not have run this either, which keeps the class inert on a host that sends no mode. A
+   read-only mode closes it outright: there every step waits for the approval. A table row and
+   a quoted line are not the
+   reply speaking, so the class skips them. The line stays the user's when it names an
+   outward step (`hooks/tezgah_integrity.py::outward_classes`), a class-F step
+   (`hooks/tezgah_integrity.py::never_default`), the owner's consent, tezgah's own install or a
+   `brew` step (`hooks/tezgah_integrity.py::OWNER_STEP`), or when it types its own blocker. The
+   refusal says to run each one and report what it printed. `_residual_block` asks it after
+   `needless ask` and before `ready steps`. A handover under a residual label ("Sonraki adım:")
+   belongs to `residual work`, which comes first. This class is the plain sentence that one
+   never saw. It refuses once per turn and counts like `residual work`
+   (`hooks/tezgah_integrity.py::LIST_BLOCKS`). Measured on the owner's top-level omp and Claude
+   transcripts (2026-10-29): of 3307 user turns, 27 replies handed the reader a command and no
+   class refused any of them. The shipped shapes refuse 9 of those turns, 8 of them a step the
+   session could have taken. Those eight are four `tezgah-task phase` moves, a local merge,
+   two "the next step is yours" and a server command that owes an ACCESS line. The ninth
+   quotes the gate's own refusal. The wider wording of the first two review rounds refused 40
+   turns and then 14, an answer about how a command is run among them.
+15. **plan claim** — a first-person claim that a command or check ran, in a turn the host ran
+   in a read-only mode (plan 142).
+   The host sends the mode with the Stop payload: `permission_mode` on Claude, Command Code,
+   Qwen and Droid, and omp's extension sends `plan` from `ctx.sessionModes`. `plan` and Droid's
+   `spec` are the read-only ones (`hooks/tezgah_integrity.py::READ_ONLY_MODES`). Nothing could
+   run in such a turn, so the claim says what cannot have happened. `_stop_block` asks it right
+   after the tamper classes and before the
+   admission, since "doğrulanmadı" repairs an unverified claim and here there was nothing to
+   check. A check that passed in the turn anyway clears it, like any other
+   evidence: a host may allow a read-only command in the mode. The trigger is the packs'
+   `ask.ran_it` vocabulary (`hooks/tezgah_integrity.py::RAN_IT`) - "test ettim", "i ran the
+   suite". It is read through the question and negation filter a claim is read through
+   (`hooks/tezgah_integrity.py::_asserted`). The done and verified vocabularies are not the
+   trigger: a plan states its acceptance in those words ("Done when all tests pass", "testler
+   yeşil olunca"), and the review of this plan caught both refused. It counts
+   as a false completion. The same mode exempts `needless ask` and closes `handed step`
+   (`hooks/tezgah_integrity.py::_residual_block`): the approval question is what plan mode asks
+   for, and every step it names waits for that approval. Every row of such a turn carries
+   `mode`, so a replay judges it as the mode it ran in
+   (`hooks/tezgah_replay.py::build_corpus`). A host that sends no
+   mode reads as `default`, which is what every rule did before the field.
 
 A past-time temporal spec decides classes 5–10 (`hooks/tezgah_stopspec.py::FORMULAS`,
 plan 063). Seven formulas read ten row atoms (`ROW_ATOMS`) and the turn marker. The module compiles
@@ -810,9 +913,9 @@ Cursor (`hosts/cursor/hook.py::dispatch`), omp (`hosts/omp/hook.py::handle`, whi
 empty stand-in for the result body its bridge never sends, so a subagent's report keeps its label), and opencode, whose plugin
 cannot import the core in process and mirrors the control in JavaScript instead — the channel on the
 call's own row, the label and the taint notice in front of the result the hook is handed, including
-the `external` row an MCP answer or a fetched page earns (`untrustedSource`
-`hosts/opencode/plugins/tezgah.js:1971`, `labelResult` `:2022`, with the tier's argv reader
-`tierRead` at `:1902`). The two halves are pinned against each other over a shared corpus, so neither
+the `external` row an MCP answer or a fetched page earns (`hosts/opencode/plugins/tezgah.js::untrustedSource`,
+`hosts/opencode/plugins/tezgah.js::labelResult`, with the tier's argv reader
+`hosts/opencode/plugins/tezgah.js::tierRead`). The two halves are pinned against each other over a shared corpus, so neither
 can move without failing the other's test (`tests/test_opencode_plugin.py::OpenCodePlugin.test_the_classifier_agrees_with_the_python_half_on_a_shared_corpus`). One difference is deliberate:
 opencode's plugin writes that `external` row itself and carries the channel alone, since the UI rule
 `_screen_read` belongs to the Python half and does not run there.