@r1z4x/tezgah 1.7.0 → 1.8.3

package/hooks/tezgah_gate.py

@@ -102,7 +102,8 @@ from tezgah_integrity import (BASH_TOOLS, BEGAN_KIND, ENV_WORD, GIT_VALUE_OPTS,
                               HEREDOC_RISK, HOOKS_KEY, PATCH_FILE,
                               PLAIN_TAIL, SECRET_PREFIXED, STEP_KINDS,
                               WRITE_TOOLS, _blank_heredocs, _heredocs, bind_session,
-                              _shell_lines, _shell_segments, _turn_start,
+                              _shell_commands, _shell_lines, _shell_segments,
+                              _turn_start,
                               _unquoted_backticks, call_id, cut, events,
                               heredoc_bodies, mask, mcp_class, mcp_text, note,
                               prior_calls, scratch_target, shortcut_command,
@@ -110,7 +111,7 @@ from tezgah_integrity import (BASH_TOOLS, BEGAN_KIND, ENV_WORD, GIT_VALUE_OPTS,
                               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,
+                          REPO_MARKS, SWITCHES, _toplevel, cache_dir, fallback_cache,
                           linked_main, off, root_for, roots)
 
 try:  # The ordering rule's two readers (the newest check's state, folded the way
@@ -267,6 +268,46 @@ SECRET_SINK = re.compile(
 # log` hands the piped text to tee. The split is read off the masked text, so a
 # quoted `;` does not split.
 SEGMENT = re.compile(r"\|\||&&|[;&\n]")
+# Plan 096: a token in a leading `NAME=value` word (after an optional `env`)
+# reaches only the program's own environment, so that program's redirected
+# output carries no key. The value reads quotes, one level of `$( )` and a
+# backtick body; a value it cannot read ends the prefix early, and the token
+# then sits outside it and holds. Names are ASCII, as bash reads them.
+SECRET_PREFIX = re.compile(
+    r"[\s;&|]*(?:env\s+)?(?:[A-Za-z_]\w*=(?:'[^']*'|\"(?:\\.|[^\"\\])*\"|"
+    r"\$\([^()]*\)|`[^`]*`|\\.|[^\s;&|()<>'\"`\\])*\s+)+", re.ASCII)
+# The sinks that carry a program's output, and nothing but it: the only ones a
+# key in that program's environment stays out of.
+SECRET_OUTPUT = re.compile(r">>?(?![&=])|\|\s*tee\b")
+# The ceiling of that relaxation is an allowlist (`_secret_runner`): a script
+# runner given a script file, with no option that makes it run its own text,
+# stdin or a preload, or trace the commands it runs. Every other program may
+# print its environment, so it holds. The rule cannot read the script itself:
+# an allowlisted script that prints its own environment still writes the key.
+SECRET_RUNNER = re.compile(r"python[\d.]*|node|bun|deno|bash|sh|zsh")
+SECRET_SCRIPT = re.compile(r"[^$`\s]+\.(?:py|js|mjs|ts|sh)")
+SECRET_INLINE = {"python": re.compile(r"-[A-Za-z]*[cmi]"),
+                 "sh": re.compile(r"-[A-Za-z]*[csxv]|-o$|--(?:verbose|debugger)"),
+                 "js": re.compile(r"-[A-Za-z]*[epri]|--(?:eval|print|require|"
+                                  r"import|loader|experimental-loader|preload|"
+                                  r"interactive)(?:=|$)")}
+# A line that reads the environment from /proc, sets a variable an interpreter
+# reads at startup or a shell trace, turns the shell's own trace on, or defines
+# a function that can shadow the program, gets no relaxation.
+SECRET_ENVIRON = re.compile(r"/proc/[^/\s]*/environ")
+SECRET_STARTUP = re.compile(
+    r"(?<![\w$])(?:SHELLOPTS|BASHOPTS|BASH_ENV|ENV|PS4|ZDOTDIR|NODE_OPTIONS|"
+    r"PYTHONSTARTUP|PYTHONINSPECT|PERL5OPT|PERL5DB|RUBYOPT|LD_PRELOAD|DYLD_\w*)=",
+    re.ASCII)
+SECRET_TRACE = re.compile(
+    r"(?:^|[\s;&|(])set\s+(?:-[A-Za-z]*[xv]|-o\s+(?:xtrace|verbose))")
+SECRET_FUNCTION = re.compile(
+    r"(?:^|[\s;&|(])(?:function\s+[^\s(){};&|]+|[^\s(){};&|$=]+\s*\(\s*\))")
+# The programs a carried name is printed by when they own a sink. An
+# interpreter running its own text is read off `_program`, which names the
+# interpreter only then; a program the shell names at run time prints too.
+SECRET_PRINTERS = frozenset(("echo", "printf", "cat", "eval", "awk", "perl",
+                             "ruby"))
 
 SECRET_DENY = (
     "Credential write denied: this command would land a credential in a file "
@@ -795,8 +836,14 @@ def secret_command(command):
 
     Reading an env var or running a tool with a key in its env is the normal work
     this must not touch, so a token only counts next to a write sink, and a sink
-    only carries the text of its own simple command. A `git add` that names a
-    credential file is refused whatever its text holds (`_secret_add`)."""
+    only carries the text of its own simple command. A token held only by the
+    leading `NAME=value` words of an allowlisted program is in that program's
+    env (`_env_prefix_only`), unless the line reads /proc's environ, sets a
+    startup or trace variable, turns `set -x` on or defines a function. A name
+    an earlier command assigned a token is carried, and a
+    printer owning a sink that reads it still writes it (`_printer_owns_sink`).
+    A `git add` that names a credential file is refused whatever its text holds
+    (`_secret_add`)."""
     c = str(command or "")
     added = _secret_add(c)
     if added:
@@ -804,15 +851,97 @@ def secret_command(command):
     if not c or not SECRET_TOKEN.search(c):
         return None
     masked = mask(c)
-    start = 0
+    relax = not (SECRET_ENVIRON.search(c) or SECRET_STARTUP.search(c)
+                 or SECRET_FUNCTION.search(masked) or SECRET_TRACE.search(masked))
+    start, carried = 0, set()
     for end in [m.start() for m in SEGMENT.finditer(masked)] + [len(c)]:
-        if (SECRET_TOKEN.search(c[start:end])
-                and SECRET_SINK.search(masked[start:end])):
-            return SECRET_DENY
+        text = c[start:end]
+        if SECRET_SINK.search(masked[start:end]):
+            if SECRET_TOKEN.search(text) and not (relax and _env_prefix_only(text)):
+                return SECRET_DENY
+            if (carried & {a or b for a, b in SHELL_VAR.findall(text)}
+                    and _printer_owns_sink(text, masked[start:end])):
+                return SECRET_DENY
+        carried |= {m.group(1) for m in SHELL_ASSIGN.finditer(text)
+                    if SECRET_TOKEN.search(m.group(0))}
         start = end
     return None
 
 
+def _env_prefix_only(text):
+    """True when every token in this simple command's text sits in its leading
+    `NAME=value` words (SECRET_PREFIX), no sink runs inside them, the sinks after
+    them carry only the program's output (SECRET_OUTPUT: a `git add` or a curl
+    trace holds), and the program is on the allowlist (`_secret_runner`, plan
+    096). Any doubt reads False: the rule holds."""
+    m = SECRET_PREFIX.match(text)
+    if not m:
+        return False
+    rest = text[m.end():]
+    return not (SECRET_TOKEN.search(rest) or SECRET_SINK.search(text[:m.end()])
+                or SECRET_SINK.search(SECRET_OUTPUT.sub(" ", rest))
+                or not _secret_runner(rest))
+
+
+def _first_command(text):
+    """The words of the first command `text` runs, a `$( )` body skipped."""
+    text = text.lstrip(" \t\n;&|")
+    return next((w for w, sep in _shell_commands(text) if sep != "$)"), [])
+
+
+def _secret_runner(text):
+    """True when the first program `text` runs, past the wrappers, is a script
+    runner named by itself (SECRET_RUNNER; a path could be any program) given a
+    script file (SECRET_SCRIPT), with no `-` or SECRET_INLINE option before it:
+    no inline text, stdin, preload, interactive mode or trace."""
+    words = _past_wrappers(_first_command(text))
+    if not words or not SECRET_RUNNER.fullmatch(words[0]):
+        return False
+    name = words[0]
+    args = words[1:]
+    if name == "deno":
+        if args[:1] != ["run"]:
+            return False
+        args = args[1:]
+    inline = SECRET_INLINE["python" if name.startswith("python")
+                           else "js" if name in ("node", "bun", "deno") else "sh"]
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "-" or inline.match(arg):
+            return False
+        if not arg.startswith(("-", "+")):
+            return bool(SECRET_SCRIPT.fullmatch(arg))
+        i += 2 if arg in INTERPRETER_VALUE_OPTS else 1
+    return False
+
+
+def _printer_owns_sink(text, masked):
+    """True when a pipeline stage of this simple command that owns a file sink
+    - a `>` to a file other than /dev/null, or a pipe into `tee` - is a printer:
+    SECRET_PRINTERS, an interpreter running its own text, or a program the shell
+    names at run time. `echo "$T" | docker login --password-stdin > log` hands
+    the key to docker's stdin, and docker's output is what lands."""
+    cuts = [m.start() for m in re.finditer(r"(?<!>)\|", masked)]
+    stages = list(zip([0] + [k + 1 for k in cuts], cuts + [len(text)]))
+    for k, (a, b) in enumerate(stages):
+        owns = any(text[a + m.end():b].split()[:1] != ["/dev/null"]
+                   for m in re.finditer(r">>?(?![&=])", masked[a:b]))
+        if k + 1 < len(stages) and re.match(r"\s*tee\b", masked[stages[k + 1][0]:]):
+            owns = True
+        if owns and _secret_printer(text[a:b]):
+            return True
+    return False
+
+
+def _secret_printer(text):
+    """True when the first program `text` runs prints a carried name."""
+    program = _program(_first_command(text))[0]
+    return (program in SECRET_PRINTERS or program in INTERPRETERS
+            or bool(re.fullmatch(r"python[\d.]+", program)
+                    or UNEXPANDED.search(program)))
+
+
 def _secret_add(command):
     """The credential file a `git add` in this command names, or None."""
     if SECRET_FILE is None or "add" not in command:
@@ -1064,12 +1193,13 @@ def known_tail(path, top, command=""):
 PLAN_PHASE_LINE = re.compile(r"(?m)^\s*\+?\s*phase\s*:\s*\S")
 
 
-def workspace_free(rel, inp):
+def workspace_free(rel, inp, path=""):
     """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.
+    `.tezgah/plans/open/` (its text is unknown) or a write tool whose plan text,
+    once written, carries a `phase:` line (`_text_after`, read from `path`).
+    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()
@@ -1078,11 +1208,50 @@ def workspace_free(rel, inp):
     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 not PLAN_PHASE_LINE.search(_text_after(inp, path))
     return True
 
 
+_OLD_TEXT = ("old_string", "oldString", "old_str")
+_NEW_TEXT = ("new_string", "newString", "new_str")
+
+
+def _text_after(inp, path):
+    """The file's text once this write lands, as far as the call says: a Write's
+    content, the current text with an Edit's (or a MultiEdit's) replacements
+    made, and for any other shape (a patch, a host's own edit format) the
+    current text beside every new string - the refusing direction. Judging the
+    new string alone let two edits each harmless on its own (`xphase:`, then
+    `xphase` -> `phase`) give an unphased plan a phase."""
+    for key in ("content", "file_text"):
+        if isinstance(inp.get(key), str):
+            return inp[key]
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            text = fh.read()
+    except (OSError, TypeError):
+        text = ""
+    edits = inp.get("edits") if isinstance(inp.get("edits"), list) else [inp]
+    pairs = [(next((e[k] for k in _OLD_TEXT if isinstance(e.get(k), str)), None),
+              next((e[k] for k in _NEW_TEXT if isinstance(e.get(k), str)), None), e)
+             for e in edits if isinstance(e, dict)]
+    if pairs and all(old is not None and new is not None for old, new, _ in pairs):
+        for old, new, e in pairs:
+            text = text.replace(old, new) if e.get("replace_all") else text.replace(old, new, 1)
+        return text
+    return "\n".join([text] + [inp[k] for k in EDIT_TEXT + ("input",)
+                               if isinstance(inp.get(k), str)])
+
+
+def _scratch(path, cwd):
+    """`scratch_target`, unless a git checkout holds `path`: a checkout under the
+    temp dir (CI's /tmp, a worktree beside one) is a checkout, and its files meet
+    the race, lease and task rules like any other's. A plain temp file stays
+    scratch (plan 099)."""
+    return scratch_target(path, cwd) and not _toplevel(
+        os.path.realpath(os.path.join(cwd or os.getcwd(), path)))
+
+
 def race_reason(inp, session_id, cwd=None):
     """A deny reason when another session wrote one of this call's files inside
     RACE_WINDOW_MIN, else None.
@@ -1103,7 +1272,7 @@ def race_reason(inp, session_id, cwd=None):
         # real target two sessions both write, and stays guarded.
         # 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)
+        if (URI_CHANNEL.match(path) or _scratch(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 = [w for w in writers_elsewhere(path, session_id, RACE_WINDOW_MIN,
@@ -1250,7 +1419,7 @@ def lease_reason(inp, session_id, cwd=None, agent=None):
         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)
+            if (URI_CHANNEL.match(path) or _scratch(path, here)
                     or unnamed_target(path, inp)):
                 continue
             real = os.path.realpath(os.path.join(here, os.path.expanduser(path)))
@@ -1428,12 +1597,138 @@ def _task(cwd, base, task):
         return task
     if tezgah_task is None:
         return None
-    return tezgah_task.active(cwd, base)
+    return tezgah_task.active(cwd, base, held=True)
+
+
+def _resolved(spelled, top, command):
+    """A write target as the task rules read it: a shell target behind a
+    variable the same line set to the checkout is that checkout path
+    (`known_tail`); any other target is the call's own spelling."""
+    return (known_tail(spelled, top, command) or spelled) if command else spelled
+
+
+# worktree_task per (target, cwd, base) for one decision: the phase, scope and
+# checkpoint rules each ask it of the same targets, and each answer costs a
+# realpath and a read of the worktree's pointer files. `decision` clears it.
+_WORKTREE_TASKS = {}
+
+
+def _worktree_task(path, cwd, base):
+    key = (path, cwd, base)
+    if key not in _WORKTREE_TASKS:
+        _WORKTREE_TASKS[key] = tezgah_task.worktree_task(path, cwd, base)
+    return _WORKTREE_TASKS[key]
+
+
+# Files under no repository that the task rule still holds: an agent definition,
+# an instruction file or a shell rc steers every later session, so it is never
+# the repository-free work `_no_repo` exempts. Globs relative to HOME, matched
+# without case (a case-insensitive filesystem opens `~/.ZSHRC` as `~/.zshrc`).
+HOME_HELD = (".claude/agents/**", ".claude/hooks/**", ".claude/commands/**",
+             ".claude/skills/**", ".claude/CLAUDE.md", ".omp/agent/**",
+             ".codex/AGENTS.md", ".codex/prompts/**", ".cursor/**",
+             ".config/opencode/**", ".zshrc", ".zshenv", ".zprofile", ".zlogin",
+             ".bashrc", ".bash_profile", ".bash_login", ".profile")
+# A line that makes a link: a path under no checkout may point into one by the
+# time the write runs (`ln -s <repo>/hooks ~/l && echo x > ~/l/a.py`).
+LINK_MAKER = re.compile(
+    r"(?<![\w-])(?:ln|link|install)\s|"
+    r"(?<![\w-])cp\s[^;&|\n]*?(?:\s-[A-Za-z]*[sl]|\s--(?:symbolic-)?link\b)")
+# A line that moves the directory, however spelled (`builtin cd`, `X=1 cd`,
+# `(cd x; ...)`), or reads it back (`$PWD`, quoted or not): where its targets
+# land is not read.
+DIR_MOVE = re.compile(r"(?<![\w-])(?:cd|pushd|popd)\b")
+PWD_READ = re.compile(r"\$\{?(?:OLD)?PWD\b")
+
+
+def _no_repo(path, inp, cwd, command):
+    """True when the write target `path` is no repository's work, so the task
+    rules leave it to the rules every write meets (plan 094: the user's
+    `~/.config/runpod/key` was refused as outside the repository).
+
+    Every doubt holds it: a line that moves the directory or makes a link, a
+    parent directory that does not exist yet, a file with a second hard link
+    and HOME_HELD. Then a target under a git checkout or a configured root is
+    some repository's; a relative one is read in the call's own directory."""
+    masked = mask(command) if command else ""
+    if (DIR_MOVE.search(masked) or PWD_READ.search(command or "")
+            or LINK_MAKER.search(masked)):
+        return False
+    path = os.path.expanduser(path)
+    if not os.path.isabs(path):
+        path = os.path.join(_shell_dir(inp, cwd) if command else cwd or "", path)
+    path = os.path.normpath(path)
+    real = os.path.realpath(path)
+    if root_for(real) or _toplevel(real) or not os.path.isdir(os.path.dirname(real)):
+        return False
+    try:
+        if os.path.isfile(real) and os.stat(real).st_nlink > 1:
+            return False
+    except OSError:
+        return False
+    home = os.path.expanduser("~")
+    for p, h in ((path, home), (real, os.path.realpath(home))):
+        rel = os.path.relpath(p, h).replace(os.sep, "/").casefold()
+        if not rel.startswith("../") and any(
+                tezgah_task.match(rel, g.casefold()) for g in HOME_HELD):
+            return False
+    return True
+
+
+def _write_targets(inp, command):
+    """The targets the task rules read: for a shell line that writes, every
+    redirect and `tee` target (`shell_targets`, expanded as `write_paths`
+    expands its one), else write_paths."""
+    if command and SHELL_WRITE.search(mask(command)):
+        return [os.path.expanduser(_expand(t, command)) for t in shell_targets(command)]
+    return write_paths(inp)
+
+
+def _owners(inp, cwd, base, task):
+    """The records this call's write targets are held to, each once: plan NNN's
+    for a target in a sibling worktree on a `plan/NNN-...` branch
+    (`tezgah_task.worktree_task`), none for a target that is no repository's
+    (`_no_repo`), the active task for every other target, and the active
+    task alone when the call names no target.
+
+    A shell line is read target by target (`shell_targets`: every redirect and
+    `tee` target). The cwd's task is an owner too when the line writes where no
+    target was read: a positional writer (`sed -i`, `cp`, `mv`, `truncate`,
+    `dd`, `patch`, `git apply`, a `tee` with other than one operand) or more
+    write shapes than targets read.
+
+    A held reading (`tezgah_task.active` with `held`: every phased plan is held
+    by its worktree, and this checkout is none of them) owns no target: a
+    held plan's scope is its worktree's, so a target outside the plan worktrees
+    is held to no plan."""
+    scope = None if task.get("held") else task
+    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 ""
+    paths = _write_targets(inp, command)
+    out = []
+    for spelled in paths:
+        path = _resolved(spelled, top, command)
+        if _no_repo(path, inp, cwd, command):
+            continue
+        own = _worktree_task(path, cwd, base) or scope
+        if own and own not in out:
+            out.append(own)
+    if command and scope and scope not in out:
+        masked = mask(command)
+        shapes = SHELL_WRITE.findall(masked)
+        positional = any(not s.startswith(">") and "tee" not in s for s in shapes) or any(
+            len([t for t in re.split(r"[;&|<>\n]", masked[m.end():], maxsplit=1)[0].split()
+                 if not t.startswith("-")]) != 1
+            for m in re.finditer(r"\|\s*tee\b", masked))
+        if positional or len(shapes) > len(paths):
+            out.append(scope)
+    return out if paths or not scope else [scope]
 
 
 def task_shell_reason(inp, cwd, base, task=_UNRESOLVED):
-    """A deny reason when the active task's phase only reads and this shell
-    command writes a file, else None.
+    """A deny reason when this shell command writes a file and the phase of the
+    record its target is held to (`_owners`: a plan worktree's own plan, else
+    the active task) only reads, else None.
 
     The route to the hole the phase rule closes, and the one E7b measured: with
     the write tools refused, the armed arm wrote the target with a heredoc
@@ -1445,15 +1740,18 @@ def task_shell_reason(inp, cwd, base, task=_UNRESOLVED):
     write tool's path, while a positional target is not read at all (see
     write_paths), and the same fail-open holds: no record, no requirement."""
     task = _task(cwd, base, task)
-    if not task or task["phase"] in tezgah_task.WRITE_PHASES:
-        return None
-    if not SHELL_WRITE.search(mask(str(inp.get("command") or ""))):
+    if not task or not SHELL_WRITE.search(mask(str(inp.get("command") or ""))):
         return None
-    return TASK_SHELL_DENY % (task["id"], task["phase"])
+    for own in _owners(inp, cwd, base, task):
+        if own["phase"] not in tezgah_task.WRITE_PHASES:
+            return TASK_SHELL_DENY % (own["id"], own["phase"])
+    return None
 
 
 def task_record_reason(inp, cwd, base, task=_UNRESOLVED):
-    """A deny reason when this write's target IS the active task's record.
+    """A deny reason when this write's target IS the active task's record, or
+    any other open plan carrying a phase (a plan running beside it in its own
+    worktree, `tezgah_task.branch_task`).
 
     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
@@ -1462,10 +1760,15 @@ def task_record_reason(inp, cwd, base, task=_UNRESOLVED):
     task = _task(cwd, base, task)
     if not task:
         return None
-    record = os.path.relpath(task["path"],
-                             tezgah_task.repo_root(cwd, base)).replace(os.sep, "/")
+    # read against the main checkout, which keeps the records, so a session in
+    # a plan worktree meets the same rule; without case, since a
+    # case-insensitive filesystem opens `.TEZGAH/...` as the record
+    record = (tezgah_task.main_relative(task["path"], cwd, base) or "").casefold()
+    root = tezgah_task.repo_root(cwd, base)
+    main = linked_main(root) or root
     for path in write_paths(inp):
-        if tezgah_task.relative(path, cwd, base) == record:
+        rel = tezgah_task.main_relative(path, cwd, base)
+        if rel and (rel.casefold() == record or tezgah_task.phased_record(main, rel)):
             return TASK_RECORD_DENY % path
     return None
 
@@ -1481,49 +1784,69 @@ def task_reason(inp, cwd, base, task=_UNRESOLVED):
     hunk like every other write rule's here. A path that resolves outside the
     repo root is refused by `relative` before any pattern is tried - a `**`
     allowlist must not reach out of the repo - unless it is the session's own
-    scratch (`scratch_target`: a temp file, a device), which is no task's work;
-    build output inside the repo is a repo path and stays held. The refusal
+    scratch (`scratch_target`: a temp file, a device), which is no task's work,
+    or is no repository's at all (`_no_repo`), which is no plan's;
+    build output inside the repo is a repo path and stays held, and so is a path
+    in the repo or its worktrees when the checkout lives under the temp dir
+    (plan 099: CI's /tmp). The refusal
     names the file as the call spelled it, because the agent has to recognize
-    its own argument."""
+    its own argument.
+
+    A target in a sibling worktree on a `plan/NNN-...` branch is held to plan
+    NNN's record when that plan carries a phase (`tezgah_task.worktree_task`):
+    two plans run at once, one per worktree, and neither's scope reaches into
+    the other's checkout. Every other target keeps the active task."""
     task = _task(cwd, base, task)
     if not task:
         return None
+    # a held reading scopes nothing outside the plan worktrees (`_owners`)
+    scope = None if task.get("held") else task
     # 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)
+    # A shell line is read target by target: each redirect and `tee` target
+    # meets the allowlist of the record it lands under.
+    command = str(inp.get("command") or inp.get("cmd") or "") if isinstance(inp, dict) else ""
+    paths = _write_targets(inp, command)
     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
+        path = _resolved(spelled, top, command)
         rel = tezgah_task.relative(path, cwd, base, worktrees=True)
-        if rel is not None and workspace_free(rel, inp):
+        if rel is None and _no_repo(path, inp, cwd, command):
+            continue
+        full = os.path.join(cwd or "", os.path.expanduser(path))
+        # the main checkout's `.tezgah` is every checkout's workspace (plan 097),
+        # so a worktree session meets the exemption the main checkout gets there
+        # (review of plan 097, F1); a phased record stays task_record_reason's
+        ws_rel = rel if rel is not None else tezgah_task.main_relative(path, cwd, base)
+        if ws_rel is not None and workspace_free(ws_rel, inp, full):
             continue
-        project.append((spelled, path, rel))
+        own = (_worktree_task(path, cwd, base) if rel is not None else None) or scope
+        if own:
+            project.append((spelled, path, rel, own))
     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 spelled, path, rel in project:
-        if scratch_target(spelled, cwd):
+    for own in [entry[3] for entry in project] or [o for o in (scope,) if o]:
+        if own["phase"] not in tezgah_task.WRITE_PHASES:
+            return TASK_PHASE_DENY % (own["id"], own["phase"],
+                                      " or ".join(tezgah_task.WRITE_PHASES))
+    for spelled, path, rel, own in project:
+        patterns = own["allowed_paths"]
+        if not patterns or (rel is None and scratch_target(spelled, cwd)):
             continue
         if rel is None or not any(tezgah_task.match(rel, p) for p in 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))
+                return TASK_SCOPE_OUTSIDE % (spelled, own["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 TASK_SCOPE_DENY % (spelled, own["id"], ", ".join(patterns), ready)
     return None
 
 
@@ -1573,9 +1896,11 @@ CHECKPOINT_DENY = (
 
 
 def checkpoint_reason(inp, cwd, base, task=_UNRESOLVED):
-    """A deny reason when the active task is in `implementation`, its plan's
-    `checkpoint:` waits for a commit (`pending <sha>`), that sha is still HEAD,
-    and the tree still holds uncommitted work - else None.
+    """A deny reason when the record a write target is held to (`_owners`: a
+    plan worktree's own plan, else the active task) is in `implementation`, its
+    plan's `checkpoint:` waits for a commit (`pending <sha>`), that sha is still
+    HEAD of the checkout the plan works in (the plan's worktree, else this
+    root), and that tree still holds uncommitted work - else None.
 
     The recorded sha, not the word `pending`, is the switch: the commit the
     refusal names moves HEAD off it, so the refusal clears by itself. The section
@@ -1592,14 +1917,25 @@ def checkpoint_reason(inp, cwd, base, task=_UNRESOLVED):
     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":
+    if not task:
+        return None
+    for own in _owners(inp, cwd, base, task):
+        reason = _pending_checkpoint(own, own.get("worktree")
+                                     or tezgah_task.repo_root(cwd, base))
+        if reason:
+            return reason
+    return None
+
+
+def _pending_checkpoint(task, root):
+    """checkpoint_reason for one record against the checkout `root`."""
+    if task["phase"] != "implementation":
         return None
     sha = tezgah_task.checkpoint_sha(task.get("checkpoint"))
     if not sha:
         return None
     # HEAD read from the ref file, not a fork: this question is asked on every
     # write of the phase, and an unreadable HEAD fails open.
-    root = tezgah_task.repo_root(cwd, base)
     if _head(root) != sha:
         return None
     import subprocess  # deferred: only a plan still pending its checkpoint pays
@@ -1610,7 +1946,8 @@ def checkpoint_reason(inp, cwd, base, task=_UNRESOLVED):
         return None
     if listed.returncode != 0 or not listed.stdout.strip():
         return None
-    return CHECKPOINT_DENY % (task["id"], tezgah_task.checkpoint_command(task["path"]))
+    return CHECKPOINT_DENY % (task["id"], tezgah_task.checkpoint_command(
+        task["path"], task.get("worktree")))
 
 
 # --- workspace: per-project tezgah state lives under <repo>/.tezgah only ------
@@ -1825,8 +2162,12 @@ def shell_target(command):
     if not SHELL_WRITE.search(masked):
         return ""
     m = SHELL_TARGET.search(masked)
-    if not m:
-        return ""
+    return _target_slice(c, m) if m else ""
+
+
+def _target_slice(c, m):
+    """The target one SHELL_TARGET match `m` (over the masked text) names in the
+    raw command `c`."""
     start, end = m.span(1) if m.group(1) else m.span(2)
     raw = c[start:end]
     # `\S+` runs to the next whitespace, so the separator of a chained command
@@ -1839,6 +2180,16 @@ def shell_target(command):
     return raw.strip("'\"").rstrip(";|&)")
 
 
+def shell_targets(command):
+    """Every redirect and `tee` target a shell command's text names, in order,
+    `> /dev/null` aside - the per-target reading the task rules need where
+    `shell_target` gives the first one only."""
+    c = str(command or "")
+    masked = mask(c)
+    return [t for t in (_target_slice(c, m) for m in SHELL_TARGET.finditer(masked))
+            if t and t != "/dev/null"]
+
+
 def shell_write_body(command, cwd=None):
     """The `{file_path, content}` a shell command writes into a file, or None when
     this command writes no file's content of its own.
@@ -2175,9 +2526,10 @@ def _head(root):
     Read from `.git/HEAD` - the ref file, or the packed-refs line beside it -
     rather than a `git` fork, the way `_branch` reads the branch: the checkpoint
     rule asks this on every write of an `implementation` phase, and an
-    unanswerable question must pass. ponytail: a worktree's packed refs live in
-    the common dir, not in the worktree gitdir this reads, so a repacked ref in a
-    linked worktree falls back to "" - the fail-open direction."""
+    unanswerable question must pass. A linked worktree keeps only its HEAD in
+    its own gitdir; its branch refs, loose or packed, live in the common dir its
+    `commondir` file names, so that is where the ref is read (plan 093 reads a
+    plan worktree's checkpoint against that worktree's HEAD)."""
     gitdir = _gitdir(root)
     if not gitdir:
         return ""
@@ -2190,6 +2542,11 @@ def _head(root):
     if not ref.startswith("ref: "):
         return ref if _SHA.fullmatch(ref) else ""
     name = ref[len("ref: "):].strip()
+    try:
+        with open(os.path.join(gitdir, "commondir"), encoding="utf-8") as fh:
+            gitdir = os.path.join(gitdir, fh.readline().strip())
+    except (OSError, UnicodeDecodeError):
+        pass    # a main checkout's gitdir is its own common dir
     try:
         with open(os.path.join(gitdir, name), encoding="utf-8",
                   errors="replace") as fh:
@@ -2740,11 +3097,9 @@ WRAPPER_VALUE_OPTS = {"sudo": ("-u", "-g", "-h", "-p", "-C", "-D", "-r", "-t", "
 INTERPRETER_VALUE_OPTS = ("-X", "-W", "-o", "+o", "-O")
 
 
-def _program(words):
-    """(program basename without `.py`, its arguments) for one simple command,
-    past compound keywords, env assignments, the wrappers (WRAPPER_VALUE_OPTS,
-    by basename, with their options) and an interpreter's options before the
-    script it runs."""
+def _past_wrappers(words):
+    """`words` past compound keywords, env assignments and the wrappers
+    (WRAPPER_VALUE_OPTS, by basename, with their options)."""
     i = 0
     while i < len(words):
         word = words[i]
@@ -2759,7 +3114,14 @@ def _program(words):
             i += 2 if words[i] in WRAPPER_VALUE_OPTS[wrapper] else 1
         if wrapper == "timeout" and i < len(words):
             i += 1  # the duration
-    words = words[i:]
+    return words[i:]
+
+
+def _program(words):
+    """(program basename without `.py`, its arguments) for one simple command,
+    past compound keywords, env assignments, the wrappers (`_past_wrappers`)
+    and an interpreter's options before the script it runs."""
+    words = _past_wrappers(words)
     if words and words[0] == "[":
         # the test command: its operands are not a program, and the command
         # after the `]` is (`if [ -d x ]; then touch y; fi`)
@@ -3126,9 +3488,9 @@ def decision(tool, inp, cwd, session_id=None, record=True, agent=None):
     # one. A shell command that writes a file through a redirect or `tee` is a
     # write here too: the rules below read its target from `write_paths`, the
     # reader `capture` and the PostToolUse row already share - unless all it
-    # writes is its own scratch (`scratch_target`), such as a `> /tmp/check.log`.
+    # writes is its own scratch (`_scratch`), such as a `> /tmp/check.log`.
     writes = t in WRITE_TOOLS or (t in BASH_TOOLS and any(
-        not scratch_target(p, cwd) for p in write_paths(inp)))
+        not _scratch(p, cwd) for p in write_paths(inp)))
     if writes and RACE_REFUSE:
         reason = race_reason(inp, session_id, cwd)
         if reason:
@@ -3151,8 +3513,12 @@ def decision(tool, inp, cwd, session_id=None, record=True, agent=None):
         # `.tezgah/plans/open/` and parses a plan, and this path is every write of
         # every session. Reads and non-write tools pay nothing.
         task = _UNRESOLVED
+        _WORKTREE_TASKS.clear()
         if tezgah_task is not None and t in WRITE_TOOLS + BASH_TOOLS:
-            task = tezgah_task.active(cwd, base)
+            # held: with every phased plan held by its worktree the record rule
+            # still refuses a direct write to it, and the scope rules hold a
+            # target outside the plan worktrees to none (`_owners`)
+            task = tezgah_task.active(cwd, base, held=True)
         if writes:
             reason = task_record_reason(inp, cwd, base, task)
             if reason: