@r1z4x/tezgah 1.11.0 → 1.13.0

package/hooks/tezgah_gate.py

@@ -114,7 +114,7 @@ from tezgah_integrity import (BASH_TOOLS, BEGAN_KIND, ENV_WORD, GIT_VALUE_OPTS,
                               write_texts)
 from tezgah_integrity import (SUBAGENT_TOOLS, TODO_TOOLS, file_url_path, newest_todo,
                               ready_heads)
-from tezgah_paths import (CACHE, CONFIG_DIR, HOST_DIRS, OFF_DIRS, PLUGIN_ROOT,
+from tezgah_paths import (AMP_PLUGIN, CACHE, CONFIG_DIR, GOOSE_PLUGIN, HOST_DIRS, OFF_DIRS, PLUGIN_ROOT,
                           REPO_MARKS, SWITCHES, _toplevel, cache_dir, fallback_cache,
                           linked_main, off, root_for, roots)
 
@@ -193,11 +193,11 @@ PATTERN_SEARCH_TOOLS = ("grep", "search", "ast_grep")
 BASH_SEARCH = re.compile(r"(?:^|[|;&(]\s*|\s)(?:grep|rg)\s+((?:-\S+\s+)*)(\S+)")
 # the credit forms, not a bare tool name: "OpenAI" or "Claude Code" in a
 # sentence (naming a tool to use it) is fine, "Co-Authored-By: ..." or a
-# generator named as the author (signing it) is the thing to stop. The "... by
-# ..." verbs credit only when their object names the machine or a model: a
-# report generated by the build script, or an index built by the gate, is prose,
-# while AI / an LLM / GPT / Claude / ... as that object is a signature, so each
-# verb is tied to the name it credits. `_CREDIT` is shared with the anchored
+# generator named as the author (signing it) is the thing to stop. A verb with
+# "by"/"with"/"using" credits only when its object names the machine or a model:
+# a report generated by the build script, or a note drafted with the owner, is
+# prose, while AI / an LLM / GPT / Claude / ... as that object is a signature, so
+# each verb is tied to the name it credits. `_CREDIT` is shared with the anchored
 # twin below so the two forms cannot drift apart.
 #
 # The cost of the model-object branch is deliberate and it falls on a message
@@ -206,12 +206,26 @@ BASH_SEARCH = re.compile(r"(?:^|[|;&(]\s*|\s)(?:grep|rg)\s+((?:-\S+\s+)*)(\S+)")
 # path pays nothing for it - `ATTRIB_LINE` anchors, so documentation that merely
 # names a form mid-sentence lands - and splitting the two sets apart was tried
 # and reverted, because the anchored half then missed `-m "Built by GPT"`.
+# A `with`/`using` credit is a signature only when the name ends its clause
+# ("Drafted with Claude", "Written using Claude Code.", "Generated using GPT-4,
+# reviewed by me", "Written with Claude (Opus)"): "built with cursor support" or
+# "client built using the OpenAI SDK" is prose, so that form takes a name that
+# a quote, a comma, a dash or the line's end closes, and never the word `cursor`
+# (review of plan 137). `by` keeps every name: "built by Cursor" is a credit.
+# ponytail: "Drafted with Cursor" passes, and "built using OpenAI, Anthropic and
+# others" is denied once; the deny names the reason, so one rephrase clears it.
 _CREDIT = (
     r"co-authored-by\s*:|generated with|made with|"
-    r"(?:generated|written|authored|built|assisted)\s+by\s+"
-    r"(?:(?:an?|the)\s+)?"
+    r"(?:generated|written|authored|built|assisted|drafted|produced|composed)"
+    r"\s+by\s+(?:(?:an?|the)\s+)?"
     r"(?:ai|llm|claude|chatgpt|gpt|copilot|codex|cursor|gemini|deepseek|"
-    r"openai|anthropic)\b|noreply@anthropic|\U0001F916")
+    r"openai|anthropic)\b|"
+    r"(?:generated|written|authored|built|assisted|drafted|produced|composed)"
+    r"\s+(?:with|using)\s+(?:(?:an?|the)\s+)?"
+    r"(?:ai|llm|claude|chatgpt|gpt|copilot|codex|gemini|deepseek|openai|anthropic)"
+    r"(?:-[\w.]+)?(?:\s+(?:code|cli))?(?:\s*\([^)\n]*\))?"
+    r"(?=[.!)\]*_`]*(?:[\x22\x27,;]|\s+-\s|\s*(?:\n|$)))|"
+    r"noreply@anthropic|\U0001F916")
 ATTRIB = re.compile(_CREDIT, re.I)
 # The same forms anchored to the start of a line, for the text a write/edit tool
 # is about to land. A credit is a signature: it owns its line, bare or behind a
@@ -2014,6 +2028,37 @@ def workspace_reason(inp, cwd, base):
     return None
 
 
+# What this closes (plan 136): `tezgah-research init` refused a line while
+# another session's line was in flight, and the session ran its whole line under
+# `.tezgah/research/.staging/<slug>/` - a dot dir `slugs()` skips, so `status`
+# and `check` never saw it. A dot dir directly under research/ is refused; the
+# line layouts (`open/`, `done/`) and dot files beside them (`.gitkeep`) are not.
+# Read against the main checkout (a linked worktree's session writes the main
+# checkout's `.tezgah`) and against the session's own root.
+RESEARCH_HIDDEN_DENY = (
+    "Workspace gate: %s is under a hidden dir. A research line lives under "
+    ".tezgah/research/open or done; a hidden dir there is invisible to status and "
+    "check. When `~/.config/tezgah/bin/tezgah-research` refuses a line, that "
+    "refusal goes to the owner - never a way around it.")
+
+
+def research_hidden_reason(inp, cwd, base):
+    """A deny reason when this write lands under `.tezgah/research/.<name>/` or
+    `.tezgah/research/open|done/.<name>/` (what `stray_dirs` reports), else None."""
+    if tezgah_task is None:
+        return None
+    for path in write_paths(inp):
+        for rel in (tezgah_task.main_relative(path, cwd, base),
+                    tezgah_task.relative(path, cwd, base)):
+            parts = (rel or "").casefold().split("/")
+            if len(parts) > 3 and parts[:2] == [".tezgah", "research"] \
+                    and (parts[2].startswith(".") or (
+                        len(parts) > 4 and parts[2] in ("open", "done")
+                        and parts[3].startswith("."))):
+                return RESEARCH_HIDDEN_DENY % path
+    return None
+
+
 # --- lesson lineage: a ledger write in a turn that read untrusted text -------
 # What this records (security-08): any session can append a standing constraint
 # to `.tezgah/lessons.md`, and a line written in a turn that read a web page, an
@@ -2755,8 +2800,9 @@ CONTROL_CLIS = {"tezgah-gate": ("decide",), "tezgah-capture": "",
 # under `hosts/<host>/` (HOOK_HOSTS); its launchers carry their own names.
 HOOK_ENTRIES = frozenset(("projects-auto-init", "projects-pretooluse",
                           "projects-posttooluse", "projects-stop",
-                          "tezgah-codex-hook", "tezgah-cursor-hook"))
-HOOK_HOSTS = frozenset(("codex", "cursor", "omp"))
+                          "tezgah-codex-hook", "tezgah-cursor-hook", "tezgah-qwen-hook",
+                          "tezgah-droid-hook", "tezgah-commandcode-hook", "tezgah-copilot-hook", "tezgah-gemini-hook", "tezgah-antigravity-hook", "tezgah-goose-hook"))
+HOOK_HOSTS = frozenset(("codex", "cursor", "omp", "qwen", "droid", "commandcode", "copilot", "gemini", "antigravity", "goose", "amp"))
 # Programs that change a path named in their arguments. Every positional is a
 # target, except for the copiers, whose last one is (`cp switch /tmp` reads it).
 # `sed`/`perl` count only with an in-place flag. `sqlite3` rewrites the cache
@@ -2797,9 +2843,9 @@ CONTROL_CACHE = ("evidence", "tezgah.db", "tezgah.db-wal", "tezgah.db-shm", "ses
                  "switches", "gate-inactive", "harness-drift", "import-crash",
                  "workspace-index.json")
 # Top-level keys tezgah writes into Claude's settings (bin/tezgah-setup
-# wire_claude_statusline, wire_claude_attribution), and the one that turns every
-# hook off at once; any other key or entry is tezgah's only when it names tezgah.
-CLAUDE_OWNED = ("statusLine", "attribution", "disableAllHooks")
+# wire_claude_statusline, wire_claude_attribution) and the ones that turn hooks off: Claude's
+# `disableAllHooks`, Gemini's `hooksConfig` (Goose's `disabledPlugins` is owned per tezgah entry).
+OWNED_KEYS = ("statusLine", "attribution", "disableAllHooks", "hooksConfig")
 PATCH_DELETE = re.compile(r"(?m)^\*\*\* Delete File: (\S.*?)\s*$")
 
 
@@ -2884,6 +2930,11 @@ def _registration(real):
     shared = (os.path.join(HOST_DIRS["codex"], "hooks.json"),
               os.path.join(HOST_DIRS["codex"], "config.toml"),
               os.path.join(HOST_DIRS["cursor"], "hooks.json"),
+              os.path.join(HOST_DIRS["qwen"], "settings.json"),
+              # Droid reads hooks.json, else the `hooks` key of its settings.json
+              os.path.join(HOST_DIRS["droid"], "hooks.json"),
+              os.path.join(HOST_DIRS["droid"], "settings.json"),
+              os.path.join(HOST_DIRS["commandcode"], "settings.json"), os.path.join(HOST_DIRS["copilot"], "settings.json"), os.path.join(HOST_DIRS["gemini"], "settings.json"), os.path.join(HOST_DIRS["antigravity"], "settings.json"), os.path.join(os.path.dirname(HOST_DIRS["antigravity"]), "config", "hooks.json"), os.path.join(HOST_DIRS["goose"], "settings.json"),
               os.path.join(claude, "plugins", "installed_plugins.json"),
               os.path.join(claude, "plugins", "known_marketplaces.json"))
     if (name in ("settings.json", "settings.local.json")
@@ -2894,8 +2945,8 @@ def _registration(real):
         return "shared"
     owned = [os.path.join(HOST_DIRS["opencode"], d, "tezgah.js")
              for d in ("plugins", "plugin")]
-    owned.append(os.path.join(HOST_DIRS["omp"], "agent", "hooks", "pre",
-                              "tezgah-hook.ts"))
+    owned += [os.path.join(HOST_DIRS["omp"], "agent", "hooks", "pre", "tezgah-hook.ts"),
+              os.path.join(HOST_DIRS["copilot"], "hooks", "tezgah.json")] + [os.path.join(HOST_DIRS["gemini"], "extensions", "tezgah", *p) for p in (("gemini-extension.json",), ("hooks", "hooks.json"))] + [os.path.join(GOOSE_PLUGIN, *p) for p in (("plugin.json",), ("hooks", "hooks.json"))] + [AMP_PLUGIN]
     cache = os.path.realpath(os.path.join(claude, "plugins", "cache"))
     if real in {_real(p, None) for p in owned} or (
             _under(real, cache) and "tezgah" in real[len(cache):].lower()):
@@ -2988,14 +3039,14 @@ def _project(node):
 
 def _owned(node, path=()):
     """The tezgah-owned entries of a parsed JSON document, position-free: the
-    CLAUDE_OWNED top-level keys, any key naming tezgah, and each list item that
+    OWNED_KEYS top-level keys, any key naming tezgah, and each list item that
     names tezgah, projected (`_project`)."""
     def dump(value):
         return json.dumps(value, sort_keys=True)
     if isinstance(node, dict):
         out = []
         for key, value in node.items():
-            if (not path and key in CLAUDE_OWNED) or "tezgah" in key.lower():
+            if (not path and key in OWNED_KEYS) or "tezgah" in key.lower():
                 out.append((path + (key,), dump(value)))
             else:
                 out += _owned(value, path + (key,))
@@ -3584,8 +3635,11 @@ def decision(tool, inp, cwd, session_id=None, record=True, agent=None):
                  check=1 if t in BASH_TOOLS and verify_command(command, cwd) else None)
     # Claude's Task names the agent `subagent_type`; omp's task names it `agent`,
     # on the call (flat shape) or on each `tasks[]` item (batch shape).
-    subs = [inp.get("subagent_type"),
-            (inp.get("args") or {}).get("subagent_type"), inp.get("agent")]
+    # A shell tool's `args` can be a list (Command Code splits argv there): only
+    # a dict carries a subagent type, and a list must not crash the decision,
+    # which the hook's guard would turn into a silent pass (plan 139)
+    args = inp.get("args") if isinstance(inp.get("args"), dict) else {}
+    subs = [inp.get("subagent_type"), args.get("subagent_type"), inp.get("agent")]
     subs += [item.get("agent") for item in inp.get("tasks") or ()
              if isinstance(item, dict)]
     # The body a shell call writes, read once: the three write-tool-only rules
@@ -3705,9 +3759,10 @@ def decision(tool, inp, cwd, session_id=None, record=True, agent=None):
             if reason:
                 return _deny(session_id, "task", reason, tool, inp, base)
     # Workspace: tezgah state belongs under .tezgah/, never a root plans/,
-    # research/ or analysis/ the project does not own (see workspace_reason).
+    # research/ or analysis/ the project does not own (see workspace_reason),
+    # nor a hidden dir under .tezgah/research/ (see research_hidden_reason).
     if not off("workspace-off") and t in WRITE_TOOLS + BASH_TOOLS:
-        reason = workspace_reason(inp, cwd, base)
+        reason = workspace_reason(inp, cwd, base) or research_hidden_reason(inp, cwd, base)
         if reason:
             return _deny(session_id, "workspace", reason, tool, inp, base)
     # MCP: a server's effect tool lands text the way a write tool or a `gh`
@@ -3896,7 +3951,8 @@ ASK_NO_DEFAULT = (
     "default (omp `ask`: `recommended`; AskUserQuestion: a \"({RECOMMENDED})\" "
     "option), and the work proceeds on it unless the step waits on the user's "
     "answer by nature (a force push, a delete of what the session did not "
-    "make, production, a credential, a spend over the cap). ")
+    "make, production, a credential, a spend over the cap, a recommended "
+    "variant, a way around a tezgah refusal, another session's work). ")
 ASK_GRANTED = (
     "tezgah: the user already granted %s this session; that step is taken, "
     "not asked again.")

package/hooks/tezgah_integrity.py

@@ -387,13 +387,22 @@ SHAPE_BLOCKS = frozenset(("placating opener", "forbidden closer", "list cap",
 # agent could decide is no false completion. Counted in `blocked_claims` under
 # their own class, kept out of `false_completion`.
 LIST_BLOCKS = frozenset(("residual work", "ready steps", "stopped slice",
-                         "needless ask"))
+                         "needless ask", "handed step"))
+# The host permission modes in which the session can neither write nor run: a
+# plan-mode turn reads and proposes, so the step it names is the user's to
+# approve, not one it could have taken (`read_only_turn`). Claude, Command
+# Code and Qwen spell it `plan`, Droid `spec`; omp's extension sends `plan`
+# from `sessionModes.getState()`. A host that sends no mode reads as `default`,
+# which is what every rule did before the field.
+READ_ONLY_MODES = frozenset(("plan", "spec"))
 
 WRITE_TOOLS = ("edit", "write", "multiedit", "notebookedit", "apply_patch",
                "str_replace_editor", "create_file", "str_replace", "edit_file",
                "write_file", "search_replace")
+# `monitor` is Claude's and Qwen's background watch: its `command` is a shell
+# command (review of plan 138), so every shell rule reads it.
 BASH_TOOLS = ("bash", "shell", "command", "exec_command", "run_command",
-              "powershell", "pwsh")
+              "powershell", "pwsh", "monitor")
 # The read/search tools: known calls that do no step of work and that no rule
 # reads a row for, spelled as the hosts send them (Claude/Cursor's capitalized
 # set, omp's lowercase one, codex's `grep`). They are not `unknown` - the ledger
@@ -517,7 +526,7 @@ LEDGER_FIELDS = frozenset(("id", "exit", "out_bytes", "fail_class", "workspace",
                            "check", "key", "block", "repo", "empty_run", "cause",
                            "host", "switches", "harness", "authorized", "inflight",
                            "reask", "open", "ready", "blocked", "heads", "residual",
-                           "questions", "defaults", "taken", "partial"))
+                           "questions", "defaults", "taken", "partial", "mode"))
 
 # The row contract's own version, stamped by the writer beside `kind` and `ts` so
 # it is not a caller field. It exists because a row is read back to decide a
@@ -3220,7 +3229,7 @@ def classify(tool, inp, cwd=None):
 # host can put in front of the model; the taint notice that flags a later effect
 # in such a turn is the untrusted module's own, not the gate's.
 WEB_TOOLS = ("web_search", "websearch", "web_fetch", "webfetch", "fetch",
-             "browser", "browse")
+             "browser", "browse", "read_web_page")
 MCP_TOOL = re.compile(r"^mcp__", re.I)
 # The verb classes of an MCP tool, read off its name: what the server is asked to
 # do picks which of the gate's existing content rules read the payload
@@ -4058,26 +4067,67 @@ NEGATION_BEFORE = re.compile(r"(?:%s)(?:\s+\S+){0,2}\s+\Z" % alts("negation_befo
 QUESTION_PARTICLE = re.compile(r"\s*(?:%s)\b" % alts("question_particle"), re.I)
 CLAUSE_END = re.compile(r"[.!?\n,;:\u2014\u2013()]|\b(?:%s)\b" % alts("clause_join"),
                         re.I)
+# The first-person claim that a command or a check was run ("test ettim", "i
+# ran the suite"): the one claim a read-only turn cannot have earned, read by
+# the `plan claim` class. Narrower than DONE/VERIFIED on purpose - a plan
+# states its acceptance in those words (plan 142, review round 2).
+RAN_IT = re.compile(alts("ask", "ran_it"), re.I)
 
 
-def asserted_claims(text):
-    """DONE/VERIFIED, with a claim word inside a question or under a negation of its
-    own clause not counted. Read by `_stop_block` on the no-work path and by
-    `stop_reason` for the claim row; a turn that did work is still judged on its
-    rows. ponytail: a window of words, not a parser."""
+def _asserted(pattern, text):
+    """The first match of `pattern` in `text` that is neither inside a question
+    nor under a negation of its own clause, else None. ponytail: a window of
+    words, not a parser."""
     t = str(text or "")
+    for m in pattern.finditer(t):
+        before = CLAUSE_END.split(t[max(0, m.start() - 80):m.start()])[-1]
+        end = CLAUSE_END.search(t, m.end())
+        asked = (QUESTION_PARTICLE.match(t, m.end())
+                 or (end and end.group(0) == "?"))
+        if not (NEGATION_BEFORE.search(before) or asked):
+            return m
+    return None
 
-    def said(pattern):
-        for m in pattern.finditer(t):
-            before = CLAUSE_END.split(t[max(0, m.start() - 80):m.start()])[-1]
-            end = CLAUSE_END.search(t, m.end())
-            asked = (QUESTION_PARTICLE.match(t, m.end())
-                     or (end and end.group(0) == "?"))
-            if not (NEGATION_BEFORE.search(before) or asked):
-                return True
-        return False
 
-    return said(DONE), said(VERIFIED)
+def asserted_claims(text):
+    """DONE/VERIFIED, with a claim word inside a question or under a negation of
+    its own clause not counted (`_asserted`). Read by `_stop_block` on the
+    no-work path and by `stop_reason` for the claim row; a turn that did work is
+    still judged on its rows."""
+    return bool(_asserted(DONE, text)), bool(_asserted(VERIFIED, text))
+
+
+def reply_prose(value):
+    """The reply's prose, whatever the host handed the Stop rule (plan 143).
+
+    omp's `session_stop` carries `last_assistant_message` as the message
+    OBJECT its `getLastAssistantMessage()` returns, not as text, and the bridge
+    passed it through: the rule then judged `str(dict)` - one line, no list
+    items, the prose diluted by the object's own fields. Measured on the
+    owner's ledger, 1643 of 1656 omp `shape` rows of 45 days carried
+    `lines: 1`, against 209 of 231 multi-line on every other host, so every
+    line-shaped class (the list cap, the residual sections, the question the
+    reply ends on, the handed step) read a text that had no lines.
+
+    A string passes through. A message object yields its `text` blocks, joined
+    the way the model wrote them; a thinking or tool block is not the reply.
+    Anything else is no reply at all, which is what the rule already does with
+    a missing one: it never becomes a judgement on a repr.
+    """
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        blocks = value.get("content")
+        if isinstance(blocks, str):
+            return blocks
+        if isinstance(blocks, list):
+            return "\n".join(
+                block["text"] for block in blocks
+                if isinstance(block, dict) and block.get("type") == "text"
+                and isinstance(block.get("text"), str)).strip()
+        if isinstance(value.get("text"), str):
+            return value["text"]
+    return ""
 
 
 def passing_check(entry):
@@ -4840,10 +4890,14 @@ def _record_only(refused, turns, after_block, cls):
 
 
 def stop_reason(text, session_id, cwd=None, after_block=0,
-                subagent=False, agent=None, parent=None):
+                subagent=False, agent=None, parent=None, mode=None):
     """Why this turn must not end yet, or None. Used by the Stop hooks (Claude,
     Codex, omp and Cursor, which share the payload fields and the block envelope).
     `cwd` is the session's directory, read for the repo's `.no-adhd` mark.
+    `mode` is the host's permission mode for this turn (Claude, Command Code
+    and Qwen send `permission_mode`; omp's extension sends its plan state as
+    one): a read-only one (`read_only_turn`) exempts the approval question the
+    mode asks for and refuses the done/tested claim it cannot have earned.
 
     The verdict is read off the current turn's rows (`turn_rows`) and not the
     whole ledger: the file grows with the session, the handler runs once per
@@ -4889,15 +4943,19 @@ def stop_reason(text, session_id, cwd=None, after_block=0,
     the child keeps a ledger of its own (omp's task sessions); the child's own
     rows still judge it. Both return None. A reply counts as
     claiming only with `asserted_claims`: "Testler geçti mi?" leaves no
-    `claim ok` row."""
+    `claim ok` row. `text` is read through `reply_prose`, so a host that hands
+    over a message object rather than its text is judged on the prose (plan
+    143)."""
+    text = reply_prose(text)
     rows, turns = turn_rows(session_id, turns=True)
     chain, rows = (_turn_refusals(session_id, rows) if turns
                    else (list(filter(_blocked, rows)), rows))
     refused = [str(entry.get("detail"))[len("blocked: "):] for entry in chain]
     if after_block and not subagent and not refused:
         return None
+    read_only = read_only_turn(mode)
     cls, reason = _stop_block(text, session_id, rows=rows, cwd=cwd,
-                              shape=not subagent)
+                              shape=not subagent, read_only=read_only)
     record_only = subagent or bool(
         (refused if turns else after_block)
         and (not reason or _record_only(refused, turns, after_block, cls)))
@@ -4905,7 +4963,11 @@ def stop_reason(text, session_id, cwd=None, after_block=0,
     # Keyed like the claim row, so Cursor's re-run of the handler on a follow-up
     # does not count the same reply twice; above the early return, so a reply
     # with no claim vocabulary still leaves its row.
+    # `mode` rides every row of a read-only turn: the verdict depended on it,
+    # and a replay of the ledger reads it back (`tezgah_replay._replay_one`).
     shape = reply_shape(text)
+    if read_only:
+        shape = dict(shape, mode=str(mode).strip().lower())
     if not record_only and not any(entry.get("kind") == "shape"
                                    and entry.get("id") == key for entry in rows):
         note(session_id, "shape", ",".join(shape_flags(text)) or "ok", id=key,
@@ -5356,7 +5418,8 @@ def _settled(rows):
     return not after or _bookkeeping_turn(after)
 
 
-def _stop_block(text, session_id, rows=None, cwd=None, shape=True, fold=None):
+def _stop_block(text, session_id, rows=None, cwd=None, shape=True, fold=None,
+                read_only=False):
     """stop_reason's decision as (reason class, block text), without the ledger
     side effect. The class names the branch that refused the turn; the text is
     what the host shows the model.
@@ -5413,11 +5476,18 @@ def _stop_block(text, session_id, rows=None, cwd=None, shape=True, fold=None):
     `fold` is the evidence fold the selector below calls. None, the default,
     is the temporal spec's (`tezgah_stopspec.fold`: the class from its formulas,
     the text from `_evidence_text`), and that outer call fills the text's
-    placeholders once (`_said`)."""
+    placeholders once (`_said`).
+
+    `read_only` is the host's word that this turn ran in a plan mode
+    (`read_only_turn`), where no command and no write was possible. Two classes
+    read it: `plan claim` below, which refuses a done/tested claim such a turn
+    cannot have behind it, and the `needless ask` exemption in
+    `_residual_block`, since the approval question is what the mode asks for."""
     if fold is None:
         # imported here: tezgah_stopspec imports this module at its top
         import tezgah_stopspec
-        verdict = _stop_block(text, session_id, rows, cwd, shape, tezgah_stopspec.fold)
+        verdict = _stop_block(text, session_id, rows, cwd, shape,
+                              tezgah_stopspec.fold, read_only)
         return (verdict[0], verdict[1] and _said(verdict[1]))
     t = str(text or "")
     shaped = _shape_block(t, cwd) if shape else (None, None)
@@ -5431,6 +5501,19 @@ def _stop_block(text, session_id, rows=None, cwd=None, shape=True, fold=None):
         return ("evidence tampered", TAMPERED)
     if (done or verified) and any(r.get(ORPHAN) for r in rows):
         return ("evidence tampered", ORPHANED)
+    # A read-only turn (the host's plan mode) ran no check, so a reply that says
+    # it ran one says what cannot have happened - unless a check of its own
+    # passed, which is evidence like any other. The trigger is the first-person
+    # run claim (RAN_IT: "test ettim", "i ran the suite"), never the done or
+    # verified vocabulary: a plan states its acceptance in those words ("Done
+    # when all tests pass", "her adım `pytest -k apps` ile doğrulanır") and
+    # review round 2 of plan 142 caught both refused. Above `_admitted`:
+    # "doğrulanmadı" repairs an unverified claim, and here nothing was checked.
+    if read_only and not any(passing_check(r) for r in rows):
+        ran = _asserted(RAN_IT, t)
+        if ran:
+            return ("plan claim",
+                    PLAN_CLAIM % cut(" ".join(ran.group(0).split()), 64))
     fold = _admitted(fold, t)
     # The trigger is the turn's own evidence, not its words. The claim vocabulary
     # below catches a claim-shaped reply; it missed the same unfounded state
@@ -5487,11 +5570,12 @@ def _stop_block(text, session_id, rows=None, cwd=None, shape=True, fold=None):
     # shape that used to leave such a claim unjudged.
     external = _external_claim(t)
     if (not worked or read) and not (done or verified) and not external:
-        return _residual_block(t, rows, shape, session_id=session_id, cwd=cwd)
+        return _residual_block(t, rows, shape, session_id=session_id, cwd=cwd,
+                               read_only=read_only)
     if lost:
         return _residual_block(t, rows, shape,
                                fold(rows, worked | {BEGAN_KIND}, external),
-                               session_id, cwd)
+                               session_id, cwd, read_only)
     # A check that answered with an outcome nobody saw (exit 0 and nothing
     # returned, a status a pipe owns: not `passing_check`) is no pass, and as a
     # check it is no work row either. A done or tested claim resting on it owes
@@ -5524,7 +5608,7 @@ def _stop_block(text, session_id, rows=None, cwd=None, shape=True, fold=None):
             if not external and not unseen and _settled(srows):
                 return _residual_block(t, rows, shape, fold(
                     _before_turn(srows), True, None, "this session"),
-                    session_id, cwd)
+                    session_id, cwd, read_only)
         if (not worked or quiet) and (done or verified):
             # A claim in a turn that did nothing: "Tamamlandı, tüm testler
             # geçti" after a turn that edited and ended "doğrulanmadı" was
@@ -5545,7 +5629,7 @@ def _stop_block(text, session_id, rows=None, cwd=None, shape=True, fold=None):
     if unseen:
         worked = worked | {"verify_ok"}
     return _residual_block(t, rows, shape, fold(judged, worked, external),
-                           session_id, cwd)
+                           session_id, cwd, read_only)
 
 
 def _before_turn(rows):
@@ -6061,6 +6145,27 @@ OPEN_TODO = (
     "{ACCESS}, {IRREVERSIBLE} or {ENV}, or marked blocked in the todo list "
     "with its reason.")
 
+# The `handed step` class (plan 142): the reply tells the reader to run a
+# command this session ran commands beside (`handed_steps`). Filled with up to
+# three of those lines.
+HANDED_STEP = (
+    "{HANDED_LEAD}The reply hands the user %d step(s) this session can run "
+    "itself: %s. Run each one now and report what it printed. A step stays the "
+    "user's only when it is outward with no grant from this session, when it "
+    "cannot be undone, or when it needs {ACCESS} or {ENV} - and then its own "
+    "line says which, with the command that failed. In a host plan mode, where "
+    "nothing can run, the plan is the deliverable and the step runs in the turn "
+    "after the approval.")
+
+# The `plan claim` class (plan 142): a done/tested claim made in a turn the
+# host ran in a read-only mode (`read_only_turn`), where no command and no
+# write was possible, so nothing can be behind it.
+PLAN_CLAIM = (
+    "{PLAN_LEAD}This turn ran in the host's read-only plan mode: no command "
+    "and no write was possible, so \"%s\" has nothing behind it. Say what the "
+    "plan is and which command will prove it, and claim the result in the turn "
+    "that runs it, after the plan is approved.")
+
 
 def _tr_lower(text):
     """`text` lowercased the Turkish way (I -> ı, İ -> i): `str.lower` reads
@@ -6378,6 +6483,10 @@ NEVER_DEFAULT = re.compile(alts("ask", "never_default"), re.I)
 # A reply that names a plan it wrote, or asks to build one: building a plan the
 # turn wrote is class F (plan 105), so asking it is the policy, not a needless ask
 PLAN_BUILD = re.compile(alts("ask", "plan_build"), re.I)
+# A last line asking the owner to pick a variant or option a research, analysis
+# or review recommends, to take a way around a tezgah refusal, or to decide
+# about another session's work (its line, plan or branch): class F (plan 136)
+OWNER_CHOICE = re.compile(alts("ask", "owner_choice"), re.I)
 SPEND = re.compile(alts("ask", "spend"), re.I)
 AMOUNT = re.compile(r"\$\s?(\d+(?:\.\d+)?)|(\d+(?:\.\d+)?)\s?(?:\$|usd\b|dolar)", re.I)
 DEFAULT_MARK = re.compile(alts("ask", "default_mark"), re.I)
@@ -6398,10 +6507,12 @@ NEEDLESS_ASK = (
     "merge, a run parameter within the standing spend cap - are taken and "
     "stated in one line, and an outward step the user granted this session is "
     "taken, not asked again. An outward step the user has not granted waits "
-    "for the answer and never proceeds on a default, and so does building a "
-    "plan this turn wrote. Do it now, or, when only "
-    "the user can decide it, put it under a \"{APPROVAL_HEADING}\" heading with "
-    "a \"{RECOMMENDED}:\" default and proceed on that default.")
+    "for the answer and never proceeds on a default, and so do building a "
+    "plan this turn wrote, choosing a variant or option a research, analysis "
+    "or review recommends, a way around a tezgah refusal and deciding about "
+    "another session's work. Do it now, or, when it is a taste or intent fork "
+    "only the user can decide, put it under a \"{APPROVAL_HEADING}\" heading "
+    "with a \"{RECOMMENDED}:\" default and proceed on that default.")
 
 
 def outward_classes(text):
@@ -6449,7 +6560,9 @@ def needless_ask(text, granted=frozenset):
     """The question the reply ends on when the agent can decide it, else None.
 
     The last line asks (QUESTION_END), its paragraph carries no recommended
-    default (DEFAULT_MARK) and it names no class-F step (`never_default`); it
+    default (DEFAULT_MARK) and it names no class-F step (`never_default`, or
+    OWNER_CHOICE: a variant or option to pick, a way around a refusal, another
+    session's work); it
     is then needless when it names an outward step (OUTWARD) the user granted
     this session, every one it names (`granted()`, called only then, so a reply
     that ends on no question reads no ledger), or, naming none, when it asks a
@@ -6460,7 +6573,8 @@ def needless_ask(text, granted=frozenset):
     if not lines or not QUESTION_END.search(lines[-1]):
         return None
     last = lines[-1]
-    if (never_default(last) or PLAN_BUILD.search(_tr_lower(t))
+    if (never_default(last) or OWNER_CHOICE.search(_tr_lower(last))
+            or PLAN_BUILD.search(_tr_lower(t))
             or DEFAULT_MARK.search(_tr_lower(re.split(r"\n\s*\n", t)[-1]))):
         return None
     low = _tr_lower(last)
@@ -6472,6 +6586,56 @@ def needless_ask(text, granted=frozenset):
     return None
 
 
+# The "you run it" shape: a line that tells the reader to run something
+# (`ask.hand_over`), beside a command in backticks (CODE_SPAN, the module's
+# own: a fence line carries no backtick span and never qualifies).
+HAND_OVER = re.compile(alts("ask", "hand_over"), re.I)
+# The steps the owner runs by design, whatever the session can do: tezgah's own
+# consent command, its installation and a machine-level `brew` step (the
+# session-scope rule). An outward or class-F step is read off the line itself
+# (`outward_classes`, `never_default`).
+OWNER_STEP = re.compile(r"(?i)\btezgah-(?:consent|setup|update)\b|\bconsent\b|\bbrew\b")
+
+
+def read_only_turn(mode):
+    """True when the host says this turn ran in a mode that can neither write
+    nor run (READ_ONLY_MODES). A host that sends nothing reads as False."""
+    return str(mode or "").strip().lower().replace("_", "-") in READ_ONLY_MODES
+
+
+def handed_steps(text, rows, read_only=False):
+    """The lines that hand the reader a step this session could have taken.
+
+    A line qualifies when it names a command in backticks and tells the reader
+    to run it (HAND_OVER: the reader addressed as the one who runs it, never
+    the "you can run X" of an answer about how something is done). A table row
+    (TABLE_ROW) and a quoted line are not
+    the reply speaking: a refusal or a log the reply quotes carries the same
+    words. It is kept - the ask policy's, not the agent's - when it names an
+    outward step (`outward_classes`), a class-F step
+    (`never_default`), the owner's consent or tezgah's own install
+    (OWNER_STEP), or when the line types its blocker. The turn must have run a
+    command of its own (COMMAND_KINDS): a turn that ran none could not have run
+    this one either, which keeps the class inert on a host that sends no mode.
+    `read_only` closes it outright: in a plan mode every step waits for the
+    approval, which is what the contract tells the turn to do."""
+    if read_only or not any(str(r.get("kind")) in COMMAND_KINDS for r in rows):
+        return []
+    out = []
+    for line in str(text or "").splitlines():
+        said = line.strip()
+        if said.startswith(("|", ">")) or TABLE_ROW.match(line):
+            continue
+        if not (CODE_SPAN.search(said) and HAND_OVER.search(said)):
+            continue
+        prose = _prose(said)
+        if (outward_classes(said) or never_default(said) or OWNER_STEP.search(said)
+                or BLOCKER_SAID.search(prose) or BLOCKER_TRIED.search(prose)):
+            continue
+        out.append(said)
+    return out
+
+
 def undefaulted(inp):
     """(questions, with a default) of an ask-tool payload: omp's `ask` marks
     the default with a question's `recommended` index, Claude's
@@ -6527,14 +6691,18 @@ def unblocked_items(text, rows):
 
 
 def _residual_block(text, rows, shape, verdict=(None, None), session_id=None,
-                    cwd=None):
+                    cwd=None, read_only=False):
     """`verdict` when it refuses; else, in a turn that did work (a STEP_KINDS
     row), the `residual work` class when `unblocked_items` names one, or when a
     subagent ended in the turn handing up items no type accounts for (the
     `residual` count on its `subagent_end` row) and this reply types none; else
     the `needless ask` class when `needless_ask` names the question the reply
     ends on (any turn, worked or not: the plan proposal that ends "Başlayayım
-    mı?" is its measured case); else the `ready steps` class when `ready_left`
+    mı?" is its measured case) - except in a read-only turn, where the host's
+    plan mode asks for that approval and the agent cannot take the step it
+    would be asked about; else the `handed step` class when `handed_steps`
+    names a step the reply left to the reader; else the `ready steps` class
+    when `ready_left`
     names one; else the `open todo` class when `open_left` names one; else the
     `stopped slice` class when `_stopped_slice` finds one; else `verdict`. Not
     asked for a subagent's end (`shape` false) or a nested session: both
@@ -6566,9 +6734,15 @@ def _residual_block(text, rows, shape, verdict=(None, None), session_id=None,
         move = next(filter(None, (_limit_move(item, failed, spawn_failed)
                                   for _label, item in left)), None)
         return ("residual work", RESIDUAL_WORK % named + (LIMIT_MOVE % move if move else ""))
-    asked = needless_ask(text, lambda: grants_in_force(session_id))
+    asked = None if read_only else needless_ask(
+        text, lambda: grants_in_force(session_id))
     if asked:
         return ("needless ask", NEEDLESS_ASK % cut(asked, 80))
+    passed = handed_steps(text, rows, read_only)
+    if passed:
+        return ("handed step", HANDED_STEP % (
+            len(passed), "; ".join(cut(" ".join(line.split()), 64)
+                                   for line in passed[:3])))
     todo = _turn_todo(rows, session_id)
     ready = _ready_in(text, todo, session_id, cwd)
     if ready: