@r1z4x/tezgah 1.5.1 → 1.7.0

package/hooks/tezgah_gate.py

@@ -38,28 +38,26 @@ Rules, all only inside a tezgah root:
   8. a write while an active task is set - a plan file under .tezgah/plans/open whose
      frontmatter carries a valid `phase` - is refused when that phase is one
      that only reads, or when the file is outside the task's `allowed_paths`
-     refused (`task`). The record is the user's own, written by bin/tezgah-task and
-     never by the agent, so the refusal leans on a decision the user made rather
-     than one this gate inferred: no active task means no requirement, and the
-     rule invents nothing. The record also carries where the phase returns to - a
+     refused (`task`). The record is written by bin/tezgah-task, which the
+     orchestrating session runs itself as the work moves, so the refusal leans
+     on a state the CLI vetted (an Acceptance item per command, an answered
+     spike, a checkpoint) rather than one this gate inferred: no active task
+     means no requirement, and the rule invents nothing. The record also
+     carries where the phase returns to - a
      `checkpoint:` sha, or `pending` while the tree still holds work no commit
      names - and a write in `implementation` is refused while it reads `pending`
      and the tree is dirty, so the phase's work starts from a named state rather
      than on top of uncommitted changes; the per-file snapshots are not one
-     state to return to. Two further refusals close the ways a session could
-     move the boundary instead of respecting it: a write whose target IS that
-     record, and a shell command that would change it through the CLI. Both were
-     measured open before they were closed - with the refusal naming the command
-     that lifts it, an armed arm removed or disabled the gate in 25 of 25 runs
-     and obeyed it in none (an internal benchmark, block E7) - and neither
-     refusal names a command now. The phase covers the shell too, because the
+     state to return to. A write whose target IS that record is refused too:
+     retyping the frontmatter would skip the preconditions the CLI checks. The
+     phase covers the shell too, because the
      write tools are not the only way to change a file: with them refused, the
      armed arm wrote the target with a heredoc redirect in 3 of 25 runs, so a
      reading phase refuses a shell command that writes. A code-execution tool is
      a third route the phase does not cover: the same block measured one row in
      25 writing the target through `eval` after the write tools and the shell
      were both refused, and that one is named rather than closed. The `task-off`
-     kill switch removes all four.
+     kill switch removes all three.
   9. a `git commit` (or `--amend`) is refused while the newest check recorded in
      this session failed (`order`): a commit is a claim that the tree passed, and
      the state it would freeze is the one a check just rejected. The state is the
@@ -110,6 +108,7 @@ from tezgah_integrity import (BASH_TOOLS, BEGAN_KIND, ENV_WORD, GIT_VALUE_OPTS,
                               prior_calls, scratch_target, shortcut_command,
                               shortcut_edit, turn_rows, verify_command,
                               write_texts)
+from tezgah_integrity import SUBAGENT_TOOLS, TODO_TOOLS, newest_todo, ready_heads
 from tezgah_paths import (CACHE, CONFIG_DIR, HOST_DIRS, OFF_DIRS, PLUGIN_ROOT,
                           REPO_MARKS, SWITCHES, cache_dir, fallback_cache,
                           linked_main, off, root_for, roots)
@@ -126,9 +125,9 @@ except ImportError:  # pragma: no cover - only on an integrity module without th
 try:  # The race rule reads the write history through tezgah_integrity; that
     # reader is newer than some checkouts of the module, and a missing name must
     # cost the rule, never the session (this import runs on every gated call).
-    from tezgah_integrity import writers_elsewhere
+    from tezgah_integrity import spawn_of, writers_elsewhere
 except ImportError:  # pragma: no cover - only on an integrity module without it
-    writers_elsewhere = None
+    spawn_of = writers_elsewhere = None
 
 try:  # The bytes a write is about to change. The snapshot module is newer than
     # some checkouts too, and a missing module must cost the snapshot, never the
@@ -681,9 +680,10 @@ CLASS_NOTE = {
     "transient": "it names a failure the host's own client may retry - a "
                  "timeout, a connection error, a rate limit, a 5xx - and an "
                  "identical repeat by the agent adds nothing to that",
-    "user": "it names something only the user can fix - a credential, a "
-            "login, an access grant - so stop and ask the user for it rather "
-            "than change the approach",
+    "user": "it names something only the user can supply - a credential, a "
+            "login, an access grant - so take a route that needs none first "
+            "(another provider or member, a local run, a public source) and "
+            "ask the user once, naming what it unlocks, only when none is left",
     "permanent": "an assertion or a bad argument does not change by re-running "
                  "it",
 }
@@ -897,11 +897,23 @@ RACE_WINDOW_MIN = 10
 # overwrite, so this rule cannot be a soft one.
 RACE_REFUSE = True
 RACE_DENY = (
-    "Concurrent write refused: session %s wrote this file within the last %d "
+    "Concurrent write refused: %s wrote this file within the last %d "
     "minutes, so the copy of %s in your context may already be stale. Re-read "
     "the file and re-apply your change to what is on disk now; if both sessions "
     "are editing it, say so and let one of them own the file rather than "
     "overwriting the other's work.")
+# How RACE_DENY names a writer, by its relation to this session
+# (tezgah_integrity._relation): the bare ledger id sent a model to the wrong
+# cause - it called an omp fork "a second window of the same session"
+# (research orchestrator-flow-audit S7, finding 4).
+RACE_WHO = {
+    "child": "your own subagent %s (ledger %s), not ended in the slice journal",
+    "parent": "your parent session (ledger %s)",
+    "sibling": "sibling subagent %s of your parent (ledger %s)",
+    "fork": "an omp fork of this session (ledger %s)",
+    "forked-from": "the session this one was forked from (ledger %s)",
+    "unrelated": "another, unrelated session %s",
+}
 # The file a write call names, per host dialect, plus the apply_patch headers
 # (tezgah_integrity.PATCH_FILE) for the dialect whose paths live in the body.
 # The race guard resolves each against the call's cwd to an absolute real path
@@ -912,8 +924,27 @@ RACE_DENY = (
 # tool device, never a file on disk. Deliberately a list, not `scheme://`: a
 # file reached through a URI scheme is still a file two sessions can race on.
 URI_CHANNEL = re.compile(
-    r"^(?:agent|xd|local|artifact|proc|skill|mcp|omp|issue|pr|history|ssh|cfg)://",
-    re.I)
+    r"^(?:agent|xd|local|artifact|proc|skill|mcp|omp|issue|pr|history|ssh|cfg|"
+    r"conflict)://", re.I)
+# The task rule's wider reading: ANY scheme. Its question is "is this a path in
+# the checkout", and a URI is not one - `tezgah_task.relative` would read
+# `xd://mcp__codegraph_explore` as a relative file and refuse a name that exists
+# nowhere (a user session, 2026-10-11: `xd://` and `conflict://` writes refused
+# as outside the allowlist).
+# `file://` is the one scheme that names a checkout file, so it stays guarded,
+# as the race rule already reads it.
+URI_TARGET = re.compile(r"^(?!file://)[A-Za-z][A-Za-z0-9+.-]*://", re.I)
+# A shell target still holding a variable or a substitution once write_paths
+# expanded what it could: the shell names the file at run time, the gate cannot.
+UNEXPANDED = re.compile(r"\$[A-Za-z_{(]|`")
+# One unexpanded piece of a shell target, for `known_tail`.
+UNEXPANDED_PIECE = re.compile(
+    r"\$\{[^}]*\}|\$\([^)]*\)|\$[A-Za-z_][A-Za-z0-9_]*|`[^`]*`")
+# `NAME=value` at a word start, and the `$NAME`/`${NAME}` a later word reads.
+SHELL_ASSIGN = re.compile(
+    r"(?:^|(?<=[\s;&|(]))([A-Za-z_][A-Za-z0-9_]*)="
+    r"((?:'[^']*'|\"[^\"]*\"|[^\s;&|)'\"])*)")
+SHELL_VAR = re.compile(r"\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))")
 WRITE_PATH = ("file_path", "filePath", "path", "notebook_path")
 # The write-tool name a shell write's target is handed to `capture` under. capture
 # takes a write tool's own path field and no shell tool name, and the row it
@@ -949,8 +980,107 @@ def write_paths(inp):
     paths = [m.group(1) for m in PATCH_FILE.finditer(str(inp.get("patch") or ""))]
     if paths:
         return paths
-    target = shell_target(inp.get("command") or inp.get("cmd") or "")
-    return [os.path.expanduser(os.path.expandvars(target))] if target else []
+    command = str(inp.get("command") or inp.get("cmd") or "")
+    target = shell_target(command)
+    return [os.path.expanduser(_expand(target, command))] if target else []
+
+
+def _expand(target, command):
+    """`target` with each `$VAR`/`${VAR}` the shell would substitute: an
+    assignment earlier on the same line (`B=/tmp/x; git diff > $B/f`), else the
+    environment. A name with no known value stays as spelled, so
+    `unnamed_target` can tell the gate it does not know the file. ponytail: the
+    assignments are read off the raw text, so `echo "a B=x"` counts as one; that
+    only matters when the target then reads `$B`."""
+    env = dict(os.environ)
+
+    def sub(text):
+        return SHELL_VAR.sub(
+            lambda m: env.get(m.group(1) or m.group(2), m.group(0)), text)
+
+    cut = command.find(target)
+    for m in SHELL_ASSIGN.finditer(command[:cut if cut >= 0 else len(command)]):
+        name, value = m.group(1), m.group(2)
+        if "$(" in value or "`" in value:
+            env.pop(name, None)         # a command's output: unknown here
+        elif value[:1] == "'":
+            env[name] = value.strip("'")
+        else:
+            env[name] = sub(value.strip('"'))
+    return sub(target)
+
+
+def unnamed_target(path, inp, top=None):
+    """True when a write target is no file the task rule can place in the
+    checkout: a URI (a host tool device such as `xd://<tool>`, an agent message,
+    a `conflict://N` resolution) or a shell target whose variable has no known
+    value and that `known_tail` cannot place. Refusing either names a path
+    that does not exist. A write tool's own path is never read for `$`:
+    `Outer$Inner.java` is a real file name."""
+    if URI_TARGET.match(path):
+        return True
+    if not isinstance(inp, dict):
+        return False
+    command = str(inp.get("command") or inp.get("cmd") or "")
+    return bool(command) and bool(UNEXPANDED.search(path)) and not known_tail(
+        path, top, command)
+
+
+# A value that is the checkout itself: `R=$(git rev-parse --show-toplevel)`,
+# `R=$(pwd)`, `R=$PWD`.
+ROOT_VALUE = re.compile(
+    r"^[\"']?(?:\$\(\s*(?:git\s+rev-parse\s+--show-toplevel|pwd)\s*\)"
+    r"|`\s*(?:git\s+rev-parse\s+--show-toplevel|pwd)\s*`|\$\{?PWD\}?)[\"']?$")
+
+
+def known_tail(path, top, command=""):
+    """The checkout path a target names when it opens on a variable the same
+    command line set to the checkout (`ROOT_VALUE`), or None. `R=$(git
+    rev-parse --show-toplevel); printf x > $R/src/a.py` writes `src/a.py`, so the
+    rule holds that file. Any other unknown variable - a `mktemp -d` directory,
+    a loop variable, one an earlier call exported - leaves the target unnamed:
+    re-rooting `$D/README.md` or `packages/$p/x` at the checkout refused writes
+    that never touched it (review of plan 083, N1).
+    ponytail: a root exported by an earlier call (`export R=$PWD`, then `> $R/x`)
+    is not seen, so that write passes unnamed."""
+    if not top:
+        return None
+    pieces = list(UNEXPANDED_PIECE.finditer(path))
+    if len(pieces) != 1 or pieces[0].start() != 0:
+        return None
+    name = pieces[0].group(0).strip("${}")
+    rest = path[pieces[0].end():].lstrip("/")
+    if not rest or UNEXPANDED.search(rest):
+        return None
+    cut = command.find(path)
+    head = command[:cut if cut >= 0 else len(command)]
+    values = re.findall(r"(?:^|(?<=[\s;&|(]))%s=(\$\([^)]*\)|`[^`]*`|\"[^\"]*\"|\S+)"
+                        % re.escape(name), head)
+    return (os.path.join(top, rest)
+            if values and ROOT_VALUE.match(values[-1]) else None)
+
+
+# The front matter key that makes a plan the active task (tezgah_task.active).
+PLAN_PHASE_LINE = re.compile(r"(?m)^\s*\+?\s*phase\s*:\s*\S")
+
+
+def workspace_free(rel, inp):
+    """True when `rel` is tezgah's own workspace the plan does not scope: every
+    `.tezgah/` path but the slice journal (`tezgah-task slice` writes it) and a
+    plan file that could make itself the active task - a shell write into
+    `.tezgah/plans/open/` (its text is unknown) or a write tool's text that
+    carries a `phase:` line. plan-add's own plan file and README stay free.
+    Compared casefolded: on a case-insensitive disk `.tezgah/PLANS/` is the
+    plans directory (review of plan 083, N2 and N5)."""
+    low = (rel or "").casefold()
+    if not low.startswith(".tezgah/") or low.startswith(".tezgah/slices/"):
+        return False
+    if low.startswith(".tezgah/plans/open/"):
+        if not isinstance(inp, dict) or inp.get("command") or inp.get("cmd"):
+            return False
+        return not any(isinstance(inp.get(k), str) and PLAN_PHASE_LINE.search(inp[k])
+                       for k in EDIT_TEXT)
+    return True
 
 
 def race_reason(inp, session_id, cwd=None):
@@ -971,61 +1101,286 @@ def race_reason(inp, session_id, cwd=None):
         # this guard read the scheme as a relative path. Only the harness's own
         # channels are skipped - a `file://`, `s3://` or editor URI can name a
         # real target two sessions both write, and stays guarded.
-        if URI_CHANNEL.match(path) or scratch_target(path, cwd):
+        # a shell target whose `$VAR` has no known value names no file the
+        # ledger could hold either (unnamed_target)
+        if (URI_CHANNEL.match(path) or scratch_target(path, cwd)
+                or (not URI_TARGET.match(path) and unnamed_target(path, inp))):
             continue    # a temp file or a device is no one's shared work
-        others = writers_elsewhere(path, session_id, RACE_WINDOW_MIN, cwd=cwd)
+        others = [w for w in writers_elsewhere(path, session_id, RACE_WINDOW_MIN,
+                                               cwd=cwd, lineage=True)
+                  if not ended_child(w, session_id, path, cwd)]
         if others:
-            return RACE_DENY % (", ".join(str(s) for s in others[:3]),
+            return RACE_DENY % (", ".join(race_who(*w[:3]) for w in others[:3]),
                                 RACE_WINDOW_MIN, path)
     return None
 
 
-# --- task scope: the user's own phase and path allowlist --------------------
-# What this closes: a session that has been told what it is working on - the
-# user activated a plan file under .tezgah/plans/open, so the work has a phase and the
-# files it may touch - and then writes anyway. Two shapes cost the user real
-# work: a write in `discovery`, where the whole point of the phase is to read
-# before deciding, and a write outside the plan's own allowlist, which is how a
-# bounded task quietly becomes an unbounded one. Both are the user's own
-# decisions, which is why this rule may refuse at all: the record is written by
-# bin/tezgah-task, by hand, and never by the agent - a rule the agent could
-# satisfy by editing its own record would be a nudge wearing a gate's clothes.
+def race_who(stem, relation, agent):
+    """One writer as RACE_DENY names it (RACE_WHO)."""
+    text = RACE_WHO.get(relation, RACE_WHO["unrelated"])
+    return text % ((agent or "?", stem) if text.count("%s") == 2 else (stem,))
+
+
+def ended_child(writer, session_id, path, cwd):
+    """True when `writer` (a writers_elsewhere (stem, relation, agent, ts)) is
+    this session's own subagent whose slice record closed after its newest
+    write of this file: a parent taking over a child that stopped on a quota
+    error is no race (research orchestrator-flow-audit S7, finding 3). The
+    record is read after `pending` closes an ended omp child, from cwd's journal
+    and the written file's. No record, one still open, or a write newer than the
+    record's close is a live writer and stays refused. ponytail: the close time
+    is stored to the second, so a write in the second the record closed counts
+    as before the close."""
+    import calendar
+    stem, relation, agent, wrote = writer
+    if relation != "child" or not agent or tezgah_task is None:
+        return False
+    repos = {r for r in (tezgah_task.main_repo(os.path.join(cwd or os.getcwd(), path)),
+                         tezgah_task.main_repo(cwd or os.getcwd())) if r}
+    base = re.sub(r"-\d+$", "", agent)
+    recs = []
+    try:
+        for repo in repos:
+            tezgah_task.pending(repo)   # closes an omp child whose transcript ended
+            recs += [r for r in tezgah_task.slices(repo) if r.get("parent") == session_id
+                     and (r.get("name") or r.get("id")) in (agent, base)]
+        closed = max(calendar.timegm(time.strptime(str(r.get("updated")), "%Y-%m-%dT%H:%M:%SZ"))
+                     for r in recs) if recs else None
+    except Exception:
+        return False
+    return (closed is not None and closed >= int(wrote)
+            and all(r.get("status") != "open" for r in recs))
+
+
+# --- lease: a sibling slice owns this file (plan 086, S6) --------------------
+# What this closes: the race rule refuses only after the other slice wrote, and
+# 24 genuine sibling refusals in real transcripts were all in a shared place -
+# one worktree for 4 or 10 concurrent slices, a predecessor's tree, a shared
+# plan record (research orchestrator-flow-audit S6, findings 3 and 5). A brief's
+# `Owns:` line is a lease on the slice record (`tezgah_task.owned_globs`), and a
+# write by one slice into a path an open sibling of the same parent owns is
+# refused before any work is lost. The second refusal is the checkout itself:
+# a slice whose record names a worktree writing into the main checkout (plan
+# 086 wave 1: two slices did, by relative paths that resolved against the
+# parent's cwd). Refused, not noted: a notice arrives after the file landed in
+# the parent's tree, and the fix - the same write under the worktree - costs
+# one re-issue. `.tezgah/` (the plan record, research data) and scratch stay
+# free: they live in the main checkout by design.
+#
+# The writing session is mapped to its record two ways. omp: its ledger's
+# `spawned` row (`tezgah_integrity.spawn_of`: parent session and spawned name);
+# omp writes it for every task child, and the record stays open while the child
+# runs. Claude: a background child's calls carry the parent's session id and
+# their own `agent_id`, which the spawn's result named and the record keeps as
+# `child` (`hooks/projects-posttooluse.py`). Every other case fails open:
+# Claude's foreground agents, dsh, Cursor and opencode open the record only when
+# the synchronous spawn returns, so no sibling record is open while the child
+# writes, and Codex writes no `spawned` row. A slice may write a path its own
+# `Owns:` names even when a sibling's names it too: the overlap is the parent's
+# brief, and the race rule still stands between the two.
+LEASE_DENY = (
+    "Lease: %s is owned by sibling slice %s (owns %s), still open under your "
+    "parent. Leave the file to it: %s, or ask your parent to move the lease; "
+    "once the owner has finished, `tezgah-task slice done %s` frees it. Every "
+    "lease is on `tezgah-task slice board`.")
+MAIN_CHECKOUT_DENY = (
+    "Lease: %s is in the main checkout %s, but your slice %s works in worktree "
+    "%s. Write the same path under that worktree: an absolute path, or a shell "
+    "whose `cwd` or `cd` is there - a relative path resolves against this "
+    "session's cwd.")
+
+
+def _channel(rec):
+    """How a sibling reaches the slice `rec` on its host."""
+    if rec.get("host") == "claude" and rec.get("child"):
+        return "message the owner (`SendMessage` to %s)" % rec["child"]
+    if rec.get("host") == "omp":
+        return "message the owner (`write agent://%s`)" % (rec.get("name") or rec["id"])
+    return "ask the owner through your parent"
+
+
+def _shell_dir(inp, cwd):
+    """The directory a shell call's redirect or `tee` target resolves against:
+    the call's own `cwd`/`workdir`, then each `cd`/`pushd` before the first
+    redirect or `tee` that writes a file, read the way `shell_control` walks
+    the line. A redirect to `/dev/*`, a descriptor (`2>&1`) or `-` writes no
+    file, so `pushd /wt >/dev/null && x > out` resolves `out` under `/wt`."""
+    base = inp.get("cwd") or inp.get("workdir")
+    where, words, pending = _full(base, cwd) if base else cwd, [], False
+    for word, is_op in _shell_words(inp.get("command") or inp.get("cmd") or ""):
+        if pending:
+            pending = False
+            if not is_op:
+                target = _unquote(word)
+                if not (target.startswith(("&", "/dev/")) or target.isdigit()
+                        or target == "-"):
+                    return where
+                continue
+        if is_op and ">" in word:
+            if words and words[-1].isdigit():
+                words.pop()  # the descriptor before `2>`
+            pending = True
+            continue
+        if not is_op:
+            if _unquote(word) == "tee" and not words:
+                return where
+            words.append(_unquote(word))
+            continue
+        while words and words[0] in SHELL_KEYWORDS:
+            words = words[1:]
+        if words and words[0] in ("cd", "pushd"):
+            dest = [a for a in words[1:] if not a.startswith("-")]
+            where = _full(dest[0] if dest else "~", where)
+        words = []
+    return where
+
+
+def lease_reason(inp, session_id, cwd=None, agent=None):
+    """LEASE_DENY or MAIN_CHECKOUT_DENY for the first of this call's files
+    that meets one, else None. `agent` is Claude's `agent_id`. Fails open: no
+    `spawned` row and no `agent_id`, no open record of that slice, an
+    unreadable journal."""
+    if spawn_of is None or tezgah_task is None or not session_id:
+        return None
+    spawn = spawn_of(session_id) or ((session_id, agent) if agent else None)
+    if not spawn:
+        return None
+    here = cwd or os.getcwd()
+    try:
+        if inp.get("command") or inp.get("cmd"):
+            here = _shell_dir(inp, here)
+        for path in write_paths(inp):
+            if (URI_CHANNEL.match(path) or scratch_target(path, here)
+                    or unnamed_target(path, inp)):
+                continue
+            real = os.path.realpath(os.path.join(here, os.path.expanduser(path)))
+            repo = tezgah_task.main_repo(real)
+            me = tezgah_task.slice_of(repo, *spawn) if repo else None
+            if not me or me.get("status") != "open":
+                continue
+            tree = me.get("declared") or ""
+            top = linked_main(real) and tezgah_task._sibling_worktree(real, repo)
+            rel = os.path.relpath(real, top or repo).replace(os.sep, "/")
+            if rel.startswith((".tezgah/", "../")) or rel == ".tezgah":
+                continue
+            if not top and tree and tree != repo and os.path.isdir(tree):
+                return MAIN_CHECKOUT_DENY % (rel, repo, me["id"], tree)
+            if any(tezgah_task.match(rel, g) for g in me.get("owns") or ()):
+                continue
+            owner = tezgah_task.owner_of(repo, rel, spawn[0], me["id"])
+            if owner:
+                return LEASE_DENY % (rel, owner.get("name") or owner["id"],
+                                     ", ".join(owner["owns"][:3]), _channel(owner),
+                                     owner["id"])
+    except Exception:
+        return None
+    return None
+
+
+def spawn_advice(tool, inp, session_id, cwd=None):
+    """The shared-worktree warning for a spawn call (`tezgah_task.worktree_clash`),
+    else None. A warning, never a deny: a fan-out of read-only reviewers on one
+    checkout is fine, and the agent name is how this reads which ones are. Off
+    under `orchestrate-off`, whose rule text it backs."""
+    if (str(tool or "").lower() not in SUBAGENT_TOOLS or tezgah_task is None
+            or not cwd or off("orchestrate-off")):
+        return None
+    try:
+        root = tezgah_task.main_repo(cwd)
+        return tezgah_task.worktree_clash(root, tool, inp, session_id or "") if root else None
+    except Exception:
+        return None
+
+
+# The cross-project write notice: a session works under the rules of the
+# repository its cwd is in, so a write into another one is under none of that
+# repository's plans, lessons or slice journal (research orchestrator-flow-audit
+# S7, finding 7). A notice, never a refusal: the write may be the user's ask.
+CROSS_PROJECT = (
+    "tezgah: this write is in %s, not in this session's repository (%s). That "
+    "repository's plans, lessons and slice journal do not apply to this session. "
+    "Work on that project from a session opened there.")
+
+
+def _main_repo(path):
+    """The main checkout of the repository holding `path`, else None
+    (`tezgah_task.main_repo`: a repository's own `.tezgah` is that repository)."""
+    return tezgah_task.main_repo(path) if tezgah_task is not None else None
+
+
+def cross_project_note(session_id, tool, inp, cwd):
+    """CROSS_PROJECT when this write call's file lies in another repository than
+    cwd's (a worktree counts as its main checkout), once per session per target
+    repository (a `nudged` mark), else None. Every host's post-tool channel
+    carries it beside its other notices. Total: any failure is no notice."""
+    try:
+        name = str(tool or "").lower()
+        if (name not in WRITE_TOOLS and name not in BASH_TOOLS) or not cwd \
+                or not isinstance(inp, dict) or inp.get("command") == "view":
+            return None
+        here = _main_repo(cwd)
+        for path in write_paths(inp):
+            if URI_CHANNEL.match(path) or scratch_target(path, cwd):
+                continue
+            there = _main_repo(os.path.join(cwd, path))
+            if not there or there == here:
+                continue
+            key = "cross:" + hashlib.sha1(("%s\0%s" % (session_id, there)).encode(
+                "utf-8", "replace")).hexdigest()[:16]
+            return CROSS_PROJECT % (there, here or cwd) \
+                if tezgah_store.mark("nudged", key) else None
+    except Exception:
+        return None
+    return None
+
+
+# --- task scope: the plan's own phase and path allowlist --------------------
+# What this closes: a session that has declared what it is working on - a plan
+# file under .tezgah/plans/open is active, so the work has a phase and the
+# files it may touch - and then writes anyway. Two shapes cost real work: a
+# write in `discovery`, where the whole point of the phase is to read before
+# deciding, and a write outside the plan's own allowlist, which is how a
+# bounded task quietly becomes an unbounded one. The record is written by
+# bin/tezgah-task, which the orchestrating session runs itself: the plan's
+# lifecycle is the orchestrator's job, never a hand-off to the user. What keeps
+# the boundary is the CLI, not who runs it - a writing phase needs every
+# Acceptance item to name its proving command, `implementation` an answered
+# spike and a checkpoint, `close done` an approving review - so the record's own
+# file is refused to a write (TASK_RECORD_DENY): retyping the frontmatter is the
+# direct route that skips those checks. A shell line's positional target (`sed
+# -i`, `cp`) is not read here (see write_paths), the residual this rule names.
 #
 # The direction is fail-open wherever the record is missing, unreadable or out
-# of phase vocabulary (tezgah_task.active returns None for those), because a
-# refusal has to rest on an ask the user actually made: a rule that refused
-# every write until a record appeared would be the fail-closed trap the design
-# report names, with the whole session as its blast radius. Nothing is named
-# that the user did not name either: an empty allowlist is no scope asked for
-# rather than "nothing is allowed", so the phase is the whole requirement there.
+# of phase vocabulary (tezgah_task.active returns None for those): a rule that
+# refused every write until a record appeared would be the fail-closed trap the
+# design report names, with the whole session as its blast radius. An empty
+# allowlist is no scope declared rather than "nothing is allowed", so the phase
+# is the whole requirement there.
+#
+# The refusals name the CLI move, because running it is the work the rule asks
+# for and the CLI vets it. E7 measured a refusal that named a way to take the
+# rule off (the armed arm disabled the gate in 25 of 25 runs); the switches that
+# do that stay behind the control-plane rule below.
 TASK_PHASE_DENY = (
     "Task gate: the active task %s is in phase `%s`, and this call writes. "
-    "Writes belong to %s. The phase is the user's to move: ask them, or do the "
-    "reading this phase asks for and say what the write was for.")
+    "Writes belong to %s. Finish the reading this phase is for, then move the "
+    "phase yourself with `tezgah-task phase implementation` - it refuses until "
+    "the plan's Acceptance, spike and checkpoint are in order.")
 TASK_SCOPE_DENY = (
-    "Task gate: %s is outside the paths the active task %s allows (%s). The "
-    "allowlist is the user's to widen: ask them, or leave the file alone and say "
-    "why it looked in scope.")
-# The two refusals above deliberately name no command. They used to end with the
-# one that lifts them, and the E7 block measured what that costs: with the unlock
-# printed in the refusal, the armed arm removed or disabled the gate in 25 of 25
-# runs and obeyed it in none (an internal benchmark, block E7). A refusal
-# is a boundary or it is an instruction; it cannot be both.
+    "Task gate: %s is outside the paths the active task %s allows (%s). If the "
+    "plan's work genuinely reaches it, widen the scope yourself (allow replaces "
+    "the list, so this keeps the current globs): `%s --why \"<what in the plan "
+    "reaches it>\"`; otherwise leave the file alone.")
+# a target outside the repository: an allow glob is repo-relative, so none reaches it
+TASK_SCOPE_OUTSIDE = (
+    "Task gate: %s is outside the paths the active task %s allows (%s). It lies "
+    "outside this repository, and an allow glob is relative to it, so no "
+    "`tezgah-task allow` line reaches it; leave the file alone, or do the work "
+    "under that repository's own task.")
 TASK_RECORD_DENY = (
-    "Task gate: %s is the active task's own record. The phase and the allowlist "
-    "live in that file, so a session that edits it is editing the boundary it is "
-    "being held to. Ask the user to change the task; the record is theirs.")
-TASK_UNLOCK_DENY = (
-    "Task gate: this command changes the active task's own record. The phase and "
-    "the allowlist are the user's, and a session that can move them is held to "
-    "nothing. Ask the user to change the task instead.")
-# A shell command that changes the record. Matched on the masked text, so a
-# command that merely names the CLI - a grep over the docs, a commit message -
-# is not refused. The token is the CLI's own basename, with or without `.py`
-# and run through any interpreter, so any path to it counts.
-TASK_CHANGE = re.compile(
-    r"(?:^|[|;&(]\s*|\s)(?:python3?\s+)?\S*tezgah-task(?:\.py)?\s+"
-    r"(?:start|phase|allow|stop)\b")
+    "Task gate: %s is the active task's own record; only `tezgah-task` writes it, checking the plan's "
+    "Acceptance, spike and review on the way. The phase and allowlist: `tezgah-task phase|allow`; an "
+    "Acceptance box: `tezgah-task tick NNN <n>`; State/Next: `tezgah-task note NNN state|next \"...\"`.")
 # The shapes that make a shell command a write, for the phase rule below. The
 # tools are not the only way to change a file, and E7b measured the other one:
 # with `edit` and `write` refused twelve and six times, the armed arm wrote the
@@ -1053,8 +1408,8 @@ SHELL_WRITE = re.compile(
 TASK_SHELL_DENY = (
     "Task gate: the active task %s is in phase `%s`, and this command writes a "
     "file. The shell is a write route like any other, so the phase covers it. "
-    "The phase is the user's to move: ask them, or do the reading this phase "
-    "asks for and say what the write was for.")
+    "Finish the reading this phase is for, then move the phase yourself with "
+    "`tezgah-task phase implementation`.")
 
 
 # The marker a caller passes when it has NOT read the record, so a rule reads it
@@ -1100,11 +1455,10 @@ def task_shell_reason(inp, cwd, base, task=_UNRESOLVED):
 def task_record_reason(inp, cwd, base, task=_UNRESOLVED):
     """A deny reason when this write's target IS the active task's record.
 
-    The other route to the same hole as TASK_UNLOCK_DENY, and the one a write
-    tool takes: the record is a file in the repo, so an agent that may write
-    files can retype the phase instead of running the CLI. Refused whatever the
-    phase and whatever the allowlist says - the record is not inside its own
-    scope, because a scope that can widen itself is not one."""
+    The record is a file in the repo, so an agent that may write files could
+    retype the phase instead of running the CLI, and skip the Acceptance, spike
+    and review checks the CLI makes on the way. Refused whatever the phase and
+    whatever the allowlist says - the record is not inside its own scope."""
     task = _task(cwd, base, task)
     if not task:
         return None
@@ -1134,18 +1488,42 @@ def task_reason(inp, cwd, base, task=_UNRESOLVED):
     task = _task(cwd, base, task)
     if not task:
         return None
+    # The targets the plan scopes: not a URI or a shell target with no known
+    # value (unnamed_target), and not tezgah's own gitignored workspace under
+    # `.tezgah/` (research lines, lessons, briefs) - the active record there is
+    # task_record_reason's, refused before this rule runs. A call whose every
+    # target is one of those writes no project file, so the phase does not
+    # refuse it either; a call with no target at all still meets the phase.
+    paths = write_paths(inp)
+    project = []
+    top = tezgah_task.repo_root(cwd, base) if cwd else None
+    command = str(inp.get("command") or inp.get("cmd") or "") if isinstance(inp, dict) else ""
+    for spelled in paths:
+        if unnamed_target(spelled, inp, top):
+            continue
+        path = (known_tail(spelled, top, command) or spelled) if command else spelled
+        rel = tezgah_task.relative(path, cwd, base, worktrees=True)
+        if rel is not None and workspace_free(rel, inp):
+            continue
+        project.append((spelled, path, rel))
+    if paths and not project:
+        return None
     if task["phase"] not in tezgah_task.WRITE_PHASES:
         return TASK_PHASE_DENY % (task["id"], task["phase"],
                                   " or ".join(tezgah_task.WRITE_PHASES))
     patterns = task["allowed_paths"]
     if not patterns:
         return None
-    for path in write_paths(inp):
-        if scratch_target(path, cwd):
+    for spelled, path, rel in project:
+        if scratch_target(spelled, cwd):
             continue
-        rel = tezgah_task.relative(path, cwd, base)
         if rel is None or not any(tezgah_task.match(rel, p) for p in patterns):
-            return TASK_SCOPE_DENY % (path, task["id"], ", ".join(patterns))
+            # the call's own spelling: the agent has to recognize its argument
+            if rel is None:
+                return TASK_SCOPE_OUTSIDE % (spelled, task["id"], ", ".join(patterns))
+            ready = " ".join(["tezgah-task allow"] + [shlex.quote(p) for p in
+                                                      list(patterns) + [rel]])
+            return TASK_SCOPE_DENY % (spelled, task["id"], ", ".join(patterns), ready)
     return None
 
 
@@ -1182,11 +1560,9 @@ def task_reason(inp, cwd, base, task=_UNRESOLVED):
 # be read, and `task-off` above. A refusal has to rest on something a reader can
 # check, and a rule that cannot answer must not refuse.
 #
-# The refusal names the one command that makes the boundary real. That is not the
-# mistake TASK_PHASE_DENY records: the E7 lesson is a refusal that names how to
-# take the constraint off (the phase is the user's to move), while the checkpoint
-# command *satisfies* the requirement - running it is the work the rule asks for,
-# so naming it is naming what the rule wants rather than a way around it.
+# The refusal names the one command that makes the boundary real: running it is
+# the work the rule asks for, so naming it is naming what the rule wants rather
+# than a way around it.
 CHECKPOINT_DENY = (
     "Checkpoint gate: the active task %s is in phase `implementation` and its "
     "plan records a pending checkpoint (`checkpoint: pending <sha>`), so this "
@@ -1212,6 +1588,9 @@ def checkpoint_reason(inp, cwd, base, task=_UNRESOLVED):
         # a shell line that changes no file is not this rule's, the same read of
         # the same shape table task_shell_reason makes
         return None
+    paths = write_paths(inp)
+    if command is None and paths and all(URI_TARGET.match(p) for p in paths):
+        return None     # a tool device or a message changes no tree state
     task = _task(cwd, base, task)
     if not task or task["phase"] != "implementation":
         return None
@@ -1285,6 +1664,18 @@ def workspace_reason(inp, cwd, base):
 # or whose target is a positional argument (`cp`, `sed -i`), leaves a row with
 # no `key` or no row at all - the gate cannot read the line it adds - so the
 # context cannot label that line.
+#
+# History, whatever the turn read (plan 077, rsi-borrow-screen idea 2): a write
+# that rewrites or removes a ledger line leaves one `lesson_changed` row per such
+# line, keyed by the old line and carrying its text, so a standing constraint
+# that was edited away can be read back from the ledger. Still never a refusal.
+# ponytail: a shell write the gate cannot read the new text of (`sed -i`, an
+# `echo >` body) leaves no `lesson_changed` row, and a rewritten line carries no
+# `new_key`: the row contract (`tezgah_integrity.LEDGER_FIELDS`) has no field
+# for it, so the line's new key rides only its `lesson_tainted` row, if any.
+LESSON_CHANGED_MAX = 10
+
+
 def lesson_taint(tool, inp, cwd, session_id, agent=None, shell_body=None):
     """Write one `lesson_tainted` row per lesson line this call leaves in a
     ledger that the ledger did not hold, when the user turn already holds a row
@@ -1294,24 +1685,28 @@ def lesson_taint(tool, inp, cwd, session_id, agent=None, shell_body=None):
     the call lands (`_after_text`), so a partial-line edit names the line it
     leaves, not its fragment. The keyed rows also go to the ledger's repository
     index (`tezgah_lessons.write_taint`), which the context labels lines from.
+    In any turn, one `lesson_changed` row per ledger line the call drops - its
+    old `key`, its old text in `detail` (redacted by `note`), the ledger in
+    `target`: read off the post-write text, a patch's `-` lines, or a shell
+    heredoc that overwrites the file; an append drops nothing.
     Returns nothing: it is never a refusal."""
-    if tezgah_lessons is None or turn_rows is None or not session_id:
+    if tezgah_lessons is None or not session_id:
         return
     t = str(tool or "").lower()
 
     def norm(path):
         return os.path.normpath(os.path.join(cwd, os.path.expanduser(path)))
 
-    texts = {norm(path): new for path, _old, new in
-             write_texts(inp if t in WRITE_TOOLS else shell_body)}
+    written = write_texts(inp if t in WRITE_TOOLS else shell_body)
+    texts = {norm(path): new for path, _old, new in written}
     targets = sorted(p for p in set(texts) | set(map(norm, write_paths(inp)))
                      if tezgah_lessons.is_ledger(p))
     if not targets:
         return
     source = next((row["source"] for row in reversed(
-        turn_rows(session_id, agent=agent)) if row.get("source")), None)
-    if not source:
-        return
+        turn_rows(session_id, agent=agent)) if row.get("source")),
+        None) if turn_rows else None
+    minus = {norm(path): old for path, old, _new in written}
     key_of = tezgah_lessons.lesson_key
     for path in targets:
         try:
@@ -1319,23 +1714,68 @@ def lesson_taint(tool, inp, cwd, session_id, agent=None, shell_body=None):
                 current = fh.read()
         except OSError:
             current = ""
-        have = set(map(key_of, tezgah_lessons.entries(current)))
+        lines = tezgah_lessons.entries(current)
+        have = set(map(key_of, lines))
         new = texts.get(path)
+        gone = ()
         if t in WRITE_TOOLS and new is not None:
             after = _after_text(inp, current)
-            new = new if after is None else after    # None: a patch's `+` lines
+            if after is None and path in _patch_deletes(inp, norm):
+                gone = list(dict.fromkeys(lines))    # a patch's Delete File
+            elif after is None:  # a patch: its `-` lines leave, its `+` lines land
+                gone = _dropped(tezgah_lessons.entries(minus.get(path) or ""), new)
+            else:
+                new, gone = after, _dropped(lines, after)
+        elif new is not None and not _shell_appends(inp.get("command")):
+            gone = _dropped(lines, new)
+        fields = dict(target=path, agent=agent, workspace=root_for(cwd),
+                      id=call_id(tool, inp))
+        # a rewrite of the whole ledger would otherwise push the refusal rules'
+        # fixed tails (the last verify, prior calls) out of their window
+        for line in gone[:LESSON_CHANGED_MAX]:
+            note(session_id, "lesson_changed", line, key=key_of(line), **fields)
+        if len(gone) > LESSON_CHANGED_MAX:
+            rest = len(gone) - LESSON_CHANGED_MAX
+            note(session_id, "lesson_changed", "%d more lines changed" % rest,
+                 items=rest, **fields)
+        if not source:
+            continue
         keys = [k for k in dict.fromkeys(map(key_of, tezgah_lessons.entries(
             new or ""))) if k not in have] or [None]
-        fields = dict(source=source, target=path, agent=agent,
-                      workspace=root_for(cwd), id=call_id(tool, inp))
         for key in keys:
-            note(session_id, "lesson_tainted", source, key=key, **fields)
+            note(session_id, "lesson_tainted", source, key=key, source=source,
+                 **fields)
         if keys != [None]:
             write_taint(os.path.dirname(os.path.dirname(path)), have | set(keys),
                         [{"key": k, "source": source, "ts": int(time.time())}
                          for k in keys])
 
 
+PATCH_DELETE = re.compile(r"^\*\*\* Delete File: (.+?)\s*$", re.M)
+
+
+def _patch_deletes(inp, norm):
+    """The paths an apply_patch input deletes (`*** Delete File: <path>`), normed;
+    read from the patch text itself, so a hunk of blank lines is not a delete."""
+    text = "\n".join(v for v in (inp or {}).values() if isinstance(v, str))
+    return {norm(p) for p in PATCH_DELETE.findall(text)}
+
+
+def _dropped(lines, after):
+    """The ledger `lines` the text `after` no longer holds, once each, in order."""
+    keep = set(map(tezgah_lessons.lesson_key, tezgah_lessons.entries(after)))
+    return [ln for ln in dict.fromkeys(lines)
+            if tezgah_lessons.lesson_key(ln) not in keep]
+
+
+def _shell_appends(command):
+    """Whether a shell write's body is added to its target (`>>`, `tee -a`) rather
+    than replacing it; True when the target is not read (no row beats a false one)."""
+    m = SHELL_TARGET.search(mask(str(command or "")))
+    return not m or m.group(0).startswith(">>") or bool(
+        re.search(r"\s-(?:[A-Za-z]*a[A-Za-z]*|-append)\s", m.group(0)))
+
+
 # --- the shell's write body: three write-tool rules reached through a heredoc -
 # What this closes (the route E7c measured): SKIP_TEST, ATTRIB_LINE and the
 # prefixed-token credential scan (secret_edit) read the text a write tool lands,
@@ -1579,6 +2019,48 @@ def effectful(tool, inp):
     return mcp_class(tool) is not None
 
 
+# --- ready: an idle `wait` while ready steps are open (plan 086, S1) ----------
+# omp's `wait` blocks the parent until a job settles. Measured over 15 omp
+# sessions, 68.3% of spawns were followed by `wait` with no other call between,
+# and at 86 of the 163 such waits that had a todo list two or more items were
+# open. The owner's default is a warning, never a deny: the line rides back with
+# the wait's result, as the graph line does (`graph_advice`).
+READY_WAIT = (
+    "tezgah: idle wait - nothing ran since the spawn while %d ready todo "
+    "step(s) are open: %s. Dispatch every ready step now, independent ones as "
+    "subagents in one message, or mark it blocked on the slice it waits for. "
+    "Ending the turn is the non-blocking alternative to `wait`: the host wakes "
+    "you on the result.")
+
+
+def ready_advice(tool, session_id, cwd=None):
+    """The idle-wait warning for a `wait` call, else None: the newest spawn in
+    the ledger tail is followed by no call but waits and todo updates, and the
+    session's newest `todo` row (`tezgah_integrity.newest_todo`) holds a ready
+    item no open slice of this session is working on
+    (`tezgah_integrity.ready_heads`). A row with no `tool` (a turn marker, a
+    `spawn` row) is no call. Off under `orchestrate-off`, whose rule text it
+    backs."""
+    if str(tool or "").lower() != "wait" or not session_id:
+        return None
+    if off("orchestrate-off"):
+        return None
+    rows = events(session_id, tail=DRIFT_TAIL)
+    for row in reversed(rows):
+        name = str(row.get("tool") or "").lower()
+        if name in SUBAGENT_TOOLS:
+            break
+        if name and name != "wait" and name not in TODO_TOOLS:
+            return None
+    else:
+        return None
+    todo = newest_todo(reversed(rows))
+    heads = ready_heads(todo, session_id, cwd) if todo else []
+    if not heads:
+        return None
+    return READY_WAIT % (len(heads), "; ".join(cut(h, 48) for h in heads[:3]))
+
+
 # --- plan required: work that spans files on main has no plan ----------------
 # What this closes: a turn that wrote four product files - a hook, its tests, its
 # docs and the changelog - straight onto `main`, with the plan opened afterwards.
@@ -1823,8 +2305,8 @@ def _refusing(label):
 # `tezgah-gate decide` writes a genuine `began` row with `check=1`; the capture
 # CLI writes snapshot rows; pony and adhd write CONFIG_DIR; `tezgah-context
 # attest` re-attests a session, and a clean result clears its drift mark. The
-# task CLI is not here: it is the task rule's (TASK_CHANGE), which `task-off`
-# removes, and that switch is one of the files this rule protects.
+# task CLI is not here: the orchestrating session runs it, and the checks that
+# matter live in the CLI itself (see the task rule above).
 # `tezgah-context user_prompt` is a prompt event, and a prompt naming a switch
 # writes the `authorized` row the switch latch honors (tezgah_paths.off).
 CONTROL_CLIS = {"tezgah-gate": ("decide",), "tezgah-capture": "",
@@ -2651,11 +3133,19 @@ def decision(tool, inp, cwd, session_id=None, record=True, agent=None):
         reason = race_reason(inp, session_id, cwd)
         if reason:
             return _deny(session_id, "race", reason, tool, inp, base)
-    # Task scope: the user's own record for this work - its phase and the files
-    # its allowlist names (see task_reason). The
-    # record itself is refused first of all, and a shell that would change it
-    # through the CLI is refused with it: a boundary the agent can move is not a
-    # boundary, and both routes to moving this one were measured open (E7).
+    # Lease: a write into a file an open sibling slice owns, or into the main
+    # checkout by a slice whose record names a worktree (see LEASE_DENY). After
+    # the race rule, which names a write already lost; before the task scope,
+    # since the allowlist is the plan's and the lease is one slice's share of it.
+    # It backs the fan-out rule's text, so its switch is that rule's; with the
+    # journal off there is no record to read.
+    if writes and not off("orchestrate-off") and not off("slices-off"):
+        reason = lease_reason(inp, session_id, cwd, agent)
+        if reason:
+            return _deny(session_id, "lease", reason, tool, inp, base)
+    # Task scope: the active plan's phase and the files its allowlist names (see
+    # task_reason). The record itself is refused first of all: only
+    # bin/tezgah-task writes it, through the checks it makes on the way.
     if not off("task-off"):
         # The record is read once and handed to every rule below: each read lists
         # `.tezgah/plans/open/` and parses a plan, and this path is every write of
@@ -2667,9 +3157,6 @@ def decision(tool, inp, cwd, session_id=None, record=True, agent=None):
             reason = task_record_reason(inp, cwd, base, task)
             if reason:
                 return _deny(session_id, "task", reason, tool, inp, base)
-        if t in BASH_TOOLS and TASK_CHANGE.search(
-                mask(str(inp.get("command") or ""))):
-            return _deny(session_id, "task", TASK_UNLOCK_DENY, tool, inp, base)
         if t in BASH_TOOLS:
             reason = task_shell_reason(inp, cwd, base, task)
             if reason:
@@ -2819,8 +3306,9 @@ def _dry_decision(tool, inp, cwd, session_id, agent=None):
     """`decision` with every write it makes swapped out for the call.
 
     The writers are module names `decision` reaches through (`note` for the
-    deny, drift, nudge and lesson_tainted rows, `write_taint` for the lesson
-    taint index, `first_nudge` for the once-per-session mark, `capture` for the
+    deny, drift, nudge, lesson_tainted and lesson_changed rows, `write_taint`
+    for the lesson taint index, `first_nudge` for the once-per-session mark,
+    `capture` for the
     snapshot), so one swap covers every rule and a new rule
     that records through them is dry here without being told. Safe because
     the dry run is its own process (bin/tezgah-gate check): nothing else in it
@@ -2850,6 +3338,54 @@ def _dry_decision(tool, inp, cwd, session_id, agent=None):
 DENY_RULES = {"control": None, "explorer": None, "shortcut": "verify-off",
               "piped": "verify-off",
               "attribution": None, "lang": "lang-off", "race": None,
+              "lease": "orchestrate-off",
               "task": "task-off", "workspace": "workspace-off", "secret": None,
               "plan": None, "order": "verify-off", "loop": "verify-off",
               "retry": "verify-off", "drift": "reminder-off"}
+
+
+# --- ask: an ask-tool question with no recommended option (plan 086, S3) -----
+# The ask policy's structured half: omp's `ask` and Claude's AskUserQuestion
+# carry their questions as data, so the check needs no word list for the
+# question itself. 7 of 51 distinct `ask` questions in the owner's omp
+# transcripts carried no `recommended` option (research orchestrator-flow-audit
+# S3, finding 4). A warning, never a deny (the owner's 2026-09-26 decision
+# removed the per-command consent gate): the line rides back with the call's
+# result, as the graph line does (`graph_advice`). Every such call leaves an
+# `ask` row, the counts `tezgah-gate replay` and the ledger read.
+ASK_NO_DEFAULT = (
+    "tezgah: %d of %d question(s) in this %s call carry no "
+    "recommended option. Each question put to the user names a recommended "
+    "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). ")
+ASK_GRANTED = (
+    "tezgah: the user already granted %s this session; that step is taken, "
+    "not asked again.")
+
+
+def ask_advice(tool, inp, session_id, cwd=None):
+    """The ask-policy warning for an ask-tool call, else None: a question with
+    no recommended option (`tezgah_integrity.undefaulted`), or one about an
+    outward step the user granted this session (`grants_in_force`). Records
+    one `ask` row per call with the counts. Off under `verify-off`, whose Stop
+    rule the policy's other half rides, and `pretooluse-off`."""
+    from tezgah_integrity import (ASK_TOOLS, _said as said, grants_in_force,
+                                  never_default, outward_classes, undefaulted)
+    name = str(tool or "").lower()
+    if name not in ASK_TOOLS or not session_id or not (cwd and root_for(cwd)) \
+            or off("pretooluse-off") or off("verify-off"):
+        return None
+    asked, defaulted = undefaulted(inp)
+    if not asked:
+        return None
+    qs = inp.get("questions") if isinstance(inp.get("questions"), list) else [inp]
+    text = " ".join(str(q.get("question") or "") for q in qs if isinstance(q, dict))
+    note(session_id, "ask", cut(" ".join(text.split()), 120), tool=str(tool),
+         questions=asked, defaults=defaulted)
+    out = ASK_NO_DEFAULT % (asked - defaulted, asked, tool) if defaulted < asked else ""
+    granted = outward_classes(text) & grants_in_force(session_id)
+    if granted and not never_default(text):
+        out += ASK_GRANTED % ", ".join(sorted(granted))
+    return said(out.strip()) if out else None