@r1z4x/tezgah 1.7.0 → 1.8.2

package/hooks/tezgah_task.py

@@ -52,6 +52,7 @@ out to git and read omp transcripts; the Stop rule reads `pending` (fail open).
 import contextlib
 import os
 import re
+import shlex
 
 TASK_PHASES = ("discovery", "implementation", "verification")
 WRITE_PHASES = ("implementation", "verification")
@@ -61,12 +62,15 @@ def repo_root(cwd, base):
     """The git top-level at or above cwd and under base, else the first path
     component below base. Walks up for a `.git` entry (dir or file: a worktree's
     is a file); no subprocess. Same answer as tezgah_context.repo_root without
-    importing the context module into the gate's hot path."""
+    importing the context module into the gate's hot path; inside `.tezgah` the
+    project around it (`tezgah_paths.project_top`)."""
+    from tezgah_paths import project_top
     cwd = os.path.realpath(cwd)
     inside = os.path.realpath(base) if base else None
     cur = cwd
     while True:
         if os.path.exists(os.path.join(cur, ".git")):
+            cur = project_top(cur)
             if inside and _under(cur, inside):
                 return cur
             break
@@ -164,6 +168,10 @@ _MARKER = re.compile(r"unverifiable(?![-\w])", re.I)
 # names the word ("either the command or the word `unverifiable` followed by
 # why") has no separator there and is not a declaration.
 _SEPARATORS = ":,;(-"
+# An unticked item the owner accepted as not met: `UNMET:` and the reason, upper
+# case so prose that names the word is not a marker. `close NNN done` lets
+# such an item through and refuses every other open box (open_items).
+_UNMET = re.compile(r"(?<!\w)UNMET:\s*(\S.*)")
 _SPAN = re.compile(r"`([^`\n]+)`")
 # A runner whose test entry point is a bare subcommand: `pnpm test`, `cargo
 # test`, `uv run pytest` carry no option and no path, yet each is the command.
@@ -276,6 +284,14 @@ def acceptance_gap(text):
     return unproven(acceptance_items(text))
 
 
+def open_items(text):
+    """The plan's unticked Acceptance items that carry no `UNMET: <reason>`, as
+    (number counted from 1, item) pairs: what `close NNN done` refuses on. Plan
+    095 closed done with an open box because close read only the review."""
+    return [(n, item) for n, item in enumerate(acceptance_items(text), 1)
+            if not item["checked"] and not _UNMET.search(item["text"])]
+
+
 # The `checkpoint:` values a plan can carry: a commit sha (the tree was clean at
 # the phase move, so the boundary is already real), or `pending <sha>` while the
 # tree still holds work no commit names - `<sha>` being the `HEAD` the commit the
@@ -314,13 +330,15 @@ def slug(path):
     return name[:-3] if name.endswith(".md") else name
 
 
-def checkpoint_command(path):
+def checkpoint_command(path, worktree=None):
     """The one command that makes a plan's boundary real: a commit whose message
     marks where the risky work starts. Named by the CLI's note and by the gate's
     refusal - the same string, from the same caller-visible place - and running it
     is also what clears the refusal: it moves HEAD off the sha the record wrote
-    (`checkpoint_sha`)."""
-    return 'git add -A && git commit -m "checkpoint: before %s"' % slug(path)
+    (`checkpoint_sha`). A plan held by its own worktree (`branch_task`) commits
+    there, so the command names that checkout."""
+    git = "git -C %s" % shlex.quote(worktree) if worktree else "git"
+    return '%s add -A && %s commit -m "checkpoint: before %s"' % (git, git, slug(path))
 
 
 def spike_unanswered(text):
@@ -452,20 +470,53 @@ def parallel(rows):
     return picked if len(picked) > 1 else []
 
 
-def active(cwd, base):
-    """The active task as a dict, or None. Scans `<repo_root>/.tezgah/plans/open/*.md`
-    sorted by name, first file whose frontmatter carries a valid `phase`.
-    Dict: {"id","title","phase","allowed_paths","checkpoint","path"}: id/title are
-    the frontmatter values (id falls back to the filename's NNN), checkpoint is
-    the frontmatter value or None when the plan carries none, path is the file.
+def active(cwd, base, held=False):
+    """The active task as a dict, or None. A linked worktree on a `plan/NNN-...`
+    branch answers plan NNN when that plan carries a phase (`branch_task`), so
+    two plans can run at once, one per worktree. Anywhere else - the main
+    checkout, or a worktree on another branch - it reads the main checkout's
+    `.tezgah/plans/open/*.md` sorted by name: the first plan carrying a valid
+    `phase` that no linked worktree holds (`plan_holders`). When every phased
+    plan is held there is none: a held plan's scope is its worktree's, and a
+    checkout outside it reading that scope held its writes to the wrong plan
+    (plan 097, D6). `held` answers the first phased plan then instead, marked
+    `"held": True`: the plan bin/tezgah-task's `phase`, `allow`, `stop` and
+    `status` act on from the main checkout, and the record the gate still
+    refuses a direct write to - while it holds no write to that plan's scope
+    outside its worktree. The context line never passes it.
+    Dict: {"id","title","phase","allowed_paths","checkpoint","branch","path"}:
+    id/title are the frontmatter values (id falls back to the filename's NNN),
+    checkpoint is the frontmatter value or None when the plan carries none,
+    path is the file.
     Never raises: an unreadable directory or file means None (readers fail
     open)."""
     root = repo_root(cwd, base)
+    own = branch_task(root)
+    if own:
+        return own
+    from tezgah_paths import linked_main
+    main = linked_main(root) or root
+    records = _phased(main)
+    branches = _worktree_branches(main) if records else {}
+    for record in records:
+        if not any(_binds(record["id"], b) for b in branches):
+            return record
+    if not held or not records:
+        return None
+    records[0]["held"] = True
+    return records[0]
+
+
+def _phased(root, ident=None):
+    """Every open plan under `root` carrying a valid phase - plan `ident` only,
+    when one is named - as active()'s dicts, in name order; [] when there is
+    none or a plan file cannot be read."""
     directory = os.path.join(root, ".tezgah", "plans", "open")
     try:
         names = sorted(os.listdir(directory))
     except OSError:
-        return None
+        return []
+    out = []
     for name in names:
         if not name.endswith(".md"):
             continue
@@ -474,29 +525,158 @@ def active(cwd, base):
             with open(path, "r", encoding="utf-8") as fh:
                 text = fh.read()
         except OSError:
-            return None
+            return []
         fields = frontmatter(text)
         if fields.get("phase") not in TASK_PHASES:
             continue
-        # A plan the repository shipped is data, not the user's task: its phase
-        # and allowlist would lock writes in a cloned repo (audit L-16). Only
-        # positive evidence turns the rule off - the index tracks `.tezgah` -
-        # never a can't-tell, which would switch the user's own guard off in
-        # silence (review R2); the answer is cached on the index's stat.
-        from tezgah_paths import workspace_tracked
-        if workspace_tracked(root):
-            return None
-        return {"id": fields.get("id") or name.split("-")[0],
-                "title": fields.get("title", ""),
-                "phase": fields["phase"],
-                "allowed_paths": allowed_paths(text),
-                # read from the frontmatter already in hand, so the gate's
-                # checkpoint rule costs this module no second read of the plan
-                "checkpoint": fields.get("checkpoint"),
-                "path": path}
+        ident_here = fields.get("id") or name.split("-")[0]
+        if ident is not None and ident_here != ident:
+            continue
+        out.append({"id": ident_here,
+                    "title": fields.get("title", ""),
+                    "phase": fields["phase"],
+                    "allowed_paths": allowed_paths(text),
+                    # read from the frontmatter already in hand, so the gate's
+                    # checkpoint rule costs this module no second read of the plan
+                    "checkpoint": fields.get("checkpoint"),
+                    "branch": fields.get("branch", ""),
+                    "path": path})
+    # A plan the repository shipped is data, not the user's task: its phase
+    # and allowlist would lock writes in a cloned repo (audit L-16). Only
+    # positive evidence turns the rule off - the index tracks `.tezgah` -
+    # never a can't-tell, which would switch the user's own guard off in
+    # silence (review R2); the answer is cached on the index's stat.
+    from tezgah_paths import workspace_tracked
+    if out and workspace_tracked(root):
+        return []
+    return out
+
+
+_PLAN_BRANCH = re.compile(r"plan/(\d+)(?:-|$)")
+
+
+def worktree_branch(top):
+    """The branch the linked worktree `top` checks out, read from its admin
+    `HEAD` without a fork (the gate asks on every write); None for a detached
+    HEAD, a plain checkout or anything unreadable."""
+    try:
+        with open(os.path.join(top, ".git"), encoding="utf-8") as fh:
+            admin = fh.readline().strip()[len("gitdir:"):].strip()
+        with open(os.path.join(top, admin, "HEAD"), encoding="utf-8") as fh:
+            head = fh.readline().strip()
+    except (OSError, UnicodeDecodeError):
+        return None
+    prefix = "ref: refs/heads/"
+    return head[len(prefix):] if head.startswith(prefix) else None
+
+
+def plan_of_branch(branch):
+    """The plan id a `plan/NNN-slug` branch names, else None."""
+    found = _PLAN_BRANCH.match(branch or "")
+    return found.group(1) if found else None
+
+
+def _binds(ident, branch):
+    """Does `branch` hold plan `ident`? It has to name the plan: `plan/NNN-...`.
+    A plan's declared `branch:` is one of those, and the slices it fans out to
+    run on others (`plan/097-records` beside `plan/097-workspace-integrity`):
+    each slice is held to its plan's scope, never to another plan's, which is
+    what a first-unheld-plan reading gave it (plan 097, D6)."""
+    return bool(branch) and plan_of_branch(branch) == ident
+
+
+def _worktree_branches(main):
+    """{branch: top} for every linked worktree of the main checkout `main`."""
+    from tezgah_paths import worktrees
+    out = {}
+    for top in worktrees(main)[1:]:
+        branch = worktree_branch(top)
+        if branch:
+            out[branch] = top
+    return out
+
+
+def plan_holders(main):
+    """{plan id: worktree top} for every open plan under the main checkout
+    `main` that a linked worktree on one of its branches (`_binds`) holds, phase
+    or not. Of several, the worktree on the plan's declared `branch:` holds it -
+    the checkout its checkpoint, review and diff are read in - else the first
+    by branch name."""
+    branches = _worktree_branches(main)
+    out = {}
+    if not branches:
+        return out
+    for name, _, text in _plan_files(main, "open"):
+        fields = frontmatter(text)
+        ident = _plan_id(fields, name)
+        held = sorted(b for b in branches if _binds(ident, b))
+        if held:
+            declared = fields.get("branch", "")
+            out[ident] = branches[declared if declared in held else held[0]]
+    return out
+
+
+def branch_task(top):
+    """Plan NNN's record (active()'s dict, plus "worktree": `top`, the checkout
+    whose HEAD and tree its checkpoint is read against) when `top` is a linked
+    worktree on a `plan/NNN-...` branch (`_binds`) and plan NNN, open under the
+    main checkout, carries a phase. None otherwise - another branch, a plan with
+    no phase, an unknown mapping - and the caller reads the main checkout's task
+    (plan 093)."""
+    ident = plan_of_branch(worktree_branch(top))
+    if ident is None:
+        return None
+    from tezgah_paths import linked_main
+    main = linked_main(top)
+    for record in _phased(main, ident) if main else ():
+        record["worktree"] = top
+        return record
     return None
 
 
+def worktree_task(path, cwd, base):
+    """The record a write to `path` is held to when it lands in a sibling linked
+    worktree on a plan branch (`branch_task`), else None. A path under cwd's own
+    root is active()'s to answer, so it pays one realpath and nothing more."""
+    root = repo_root(cwd, base)
+    path = os.path.expanduser(path)
+    real = os.path.realpath(path if os.path.isabs(path) else os.path.join(cwd, path))
+    if _under(real, root):
+        return None
+    top = _sibling_worktree(real, root)
+    return branch_task(top) if top else None
+
+
+def main_relative(path, cwd, base):
+    """`path` (absolute or relative to cwd) as a posix path relative to the main
+    checkout of cwd's repository - the checkout that keeps `.tezgah/plans` -
+    or None outside it. A session in a linked worktree reads the same records
+    as one in the main checkout."""
+    from tezgah_paths import linked_main
+    root = repo_root(cwd, base)
+    main = linked_main(root) or root
+    path = os.path.expanduser(path)
+    real = os.path.realpath(path if os.path.isabs(path) else os.path.join(cwd, path))
+    if real == main or not _under(real, main):
+        return None
+    return real[len(main) + 1:].replace(os.sep, "/")
+
+
+def phased_record(root, rel):
+    """True when `rel` (relative to the main checkout `root`) is an open plan
+    carrying a valid phase - a record only bin/tezgah-task writes, whichever
+    plan the main checkout reads as active. Matched without case, since a
+    case-insensitive filesystem opens `.TEZGAH/PLANS/open/x.md` as the record."""
+    parts = (rel or "").split("/")
+    if (len(parts) != 4 or "/".join(parts[:3]).casefold() != ".tezgah/plans/open"
+            or not parts[3].casefold().endswith(".md")):
+        return False
+    for name, _, text in _plan_files(root, "open"):
+        if name.casefold() == parts[3].casefold():
+            return frontmatter(text).get("phase") in TASK_PHASES
+    return False
+
+
 def match(rel, pattern):
     """Glob match for one allowlist pattern against a repo-relative posix path.
     `**` crosses separators, `*` does not, everything else is literal."""
@@ -574,15 +754,67 @@ def _sibling_worktree(real, root):
     return top if os.path.realpath(back) == os.path.join(top, ".git") else None
 
 
+@contextlib.contextmanager
+def plans_lock(path):
+    """Hold the exclusive lock every plan record writer takes, on the `plans/`
+    directory above the plan file `path`, across its whole read-modify-write:
+    two writers in two checkouts lost one write in 40 rounds without it (plan
+    097, E7). The directory itself is locked, so no lock file is left for the
+    private repository's `add -A` to commit (review of plan 097, F6). Raises
+    OSError when the directory cannot be opened."""
+    try:
+        import fcntl
+    except ImportError:
+        # ponytail: Windows has no fcntl, so writers run unlocked there; the
+        # rename in _write still keeps every read whole, but two concurrent
+        # writers can lose one write. msvcrt.locking is the fuller version.
+        fcntl = None
+    if fcntl is None:
+        yield
+        return
+    fd = os.open(os.path.dirname(os.path.dirname(os.path.realpath(path))), os.O_RDONLY)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        os.close(fd)  # closing the descriptor releases the lock
+
+
+def _write(path, text):
+    """Replace the file at `path` with `text` whole: written to a temp file
+    beside it, then renamed over it, so a reader sees the old record or the new
+    one and never a truncated one - which read as no frontmatter, so no active
+    task, and opened the gate (29 torn reads in 40, plan 097 E7). Keeps the
+    file's mode. Raises OSError."""
+    import tempfile
+    path = os.path.realpath(path)
+    folder, name = os.path.split(path)
+    fd, tmp = tempfile.mkstemp(prefix="." + name + ".", suffix=".tmp", dir=folder)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        os.chmod(tmp, os.stat(path).st_mode & 0o7777)
+        os.replace(tmp, path)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+
 def set_fields(path, **fields):
-    """Rewrite these frontmatter keys in the plan file in place: replace the
+    """Rewrite these frontmatter keys in the plan file: replace the
     `key: value` line when present, insert it before the closing `---` when not.
     `allowed_paths` takes a list and is written as a `- item` block, replacing an
     existing block. `updated` is not special-cased here: the CLI passes today's
     date under it, as it does for a research line's `created:`, so this module
-    needs no clock of its own. Raises OSError."""
-    with open(path, "r", encoding="utf-8") as fh:
-        lines = fh.read().split("\n")
+    needs no clock of its own. Under the plans lock, written whole (`_write`).
+    Raises OSError."""
+    with plans_lock(path):
+        _set_fields(path, fields)
+
+
+def _set_fields(path, fields):
+    lines = _lines(path)
     if not lines or lines[0].strip() != "---":
         lines = ["---", "---"] + lines
     close = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
@@ -603,8 +835,17 @@ def set_fields(path, **fields):
             end += 1
         block[head:end] = fresh
     lines[1:close] = block
-    with open(path, "w", encoding="utf-8") as fh:
-        fh.write("\n".join(lines))
+    _write(path, "\n".join(lines))
+
+
+def close_record(path, target, **fields):
+    """Write `fields` into the plan at `path` and move it to `target`, under
+    the plans lock: a tick racing the close then fails on the moved file instead
+    of writing it back into `open/`. Raises OSError."""
+    with plans_lock(path):
+        _set_fields(path, fields)
+        os.makedirs(os.path.dirname(target), exist_ok=True)
+        os.replace(path, target)
 
 
 def _field_lines(key, value):
@@ -624,36 +865,41 @@ def _lines(path):
         return fh.read().split("\n")
 
 
-def _write_lines(path, lines):
-    with open(path, "w", encoding="utf-8") as fh:
-        fh.write("\n".join(lines))
-
-
-def set_box(path, line, checked):
-    """Set the `- [ ]`/`- [x]` box on 1-based `line` (an acceptance item's
-    `line`). Raises OSError."""
-    lines = _lines(path)
-    lines[line - 1] = re.sub(r"- \[[ xX]\]", "- [x]" if checked else "- [ ]",
-                             lines[line - 1], count=1)
-    _write_lines(path, lines)
+def set_box(path, n, checked):
+    """Set the `- [ ]`/`- [x]` box of Acceptance item `n` (1-based, as `tick`
+    counts) and return the item, or None when the plan has no item `n`. The
+    item's line is found under the plans lock: read before it, a frontmatter
+    line another writer inserted moved the box ticked (review of plan 097,
+    F5). Raises OSError."""
+    with plans_lock(path):
+        lines = _lines(path)
+        items = acceptance_items("\n".join(lines))
+        if not 1 <= n <= len(items):
+            return None
+        line = items[n - 1]["line"] - 1
+        lines[line] = re.sub(r"- \[[ xX]\]", "- [x]" if checked else "- [ ]",
+                             lines[line], count=1)
+        _write(path, "\n".join(lines))
+        return items[n - 1]
 
 
 def set_section(path, heading, body):
     """Replace the body of the last `## <heading>` section - the newest, since
-    a plan appends a dated `## State (...)` - with `body` and one blank line.
-    Returns False, writing nothing, when the plan has no such section. Raises
-    OSError."""
-    lines = _lines(path)
-    heads = [i for i, line in enumerate(lines)
-             if re.match(r"## %s(\s|$)" % re.escape(heading), line.strip())]
-    if not heads:
-        return False
-    start = heads[-1] + 1
-    end = next((i for i in range(start, len(lines))
-                if lines[i].lstrip().startswith("## ")), len(lines))
-    lines[start:end] = body.strip("\n").split("\n") + [""]
-    _write_lines(path, lines)
-    return True
+    a plan appends a dated `## State (...)` - with `body` and one blank line,
+    under the plans lock. Returns False, writing nothing, when the plan has no
+    such section. Raises OSError."""
+    with plans_lock(path):
+        lines = _lines(path)
+        heads = [i for i, line in enumerate(lines)
+                 if re.match(r"## %s(\s|$)" % re.escape(heading), line.strip())]
+        if not heads:
+            return False
+        start = heads[-1] + 1
+        end = next((i for i in range(start, len(lines))
+                    if lines[i].lstrip().startswith("## ")), len(lines))
+        lines[start:end] = body.strip("\n").split("\n") + [""]
+        _write(path, "\n".join(lines))
+        return True
 
 
 # ---------------------------------------------------------------- slice journal
@@ -1072,6 +1318,10 @@ def worktree_clash(root, tool, inp, parent=""):
     return SHARED_WORKTREE % (", ".join(clash[0][1]), clash[0][0]) if clash else None
 
 
+# `plan 093` in a brief: the plan a slice works on when its checkout says none
+_BRIEF_PLAN = re.compile(r"(?i)\bplan\s+(\d{3})\b")
+
+
 def open_slice(root, sid, *, kind="agent", host="", agent="", brief="", parent="",
                cwd="", repo="", task="", child=""):
     """Open (or re-open) the record `sid` and return it. The worktree and branch
@@ -1121,9 +1371,13 @@ def open_slice(root, sid, *, kind="agent", host="", agent="", brief="", parent="
         # one glob over every omp project at open, so `pending` - run on every
         # prompt and Stop - never globs (40 ms on 1393 project dirs, measured)
         rec["transcript_dir"] = _omp_session_dir(rec["parent"]) or ""
-    # the plan whose task was active when the slice opened: the review guard
-    # reads its own plan's records only
-    rec["plan"] = (active(main, main) or {}).get("id") or rec.get("plan") or ""
+    # the slice's own plan: the review guard reads its own plan's records only.
+    # Its worktree's plan branch, else the plan its task or shared brief names,
+    # else the tag a re-open already carries, else the task the main checkout
+    # reads - with two plans running that is only one of them
+    named = _BRIEF_PLAN.search(own) or _BRIEF_PLAN.search(brief or "")
+    rec["plan"] = (plan_of_branch(rec.get("branch")) or (named and named.group(1))
+                   or rec.get("plan") or (active(main, main) or {}).get("id") or "")
     rec.update(base=_git(main, "rev-parse", "HEAD") or "", status="open",
                failure="", updated=now)
     return _write_record(root, rec)
@@ -1264,12 +1518,10 @@ _ABS_PATH = re.compile(r"(?<![\w.~/-])/[^\s'\"`<>()\[\]{},;|*?]+")
 
 def main_repo(path):
     """The main checkout of the repository holding `path`, else None. A path
-    under a repository's own `.tezgah` - a private git repository of its own -
-    belongs to the repository around it, and a worktree to its main checkout."""
+    under a repository's own `.tezgah` belongs to the repository around it
+    (`_toplevel`), and a worktree to its main checkout."""
     from tezgah_paths import _toplevel
     top = _toplevel(os.path.realpath(path))
-    while top and os.path.basename(top) == ".tezgah":
-        top = _toplevel(os.path.dirname(top))
     return _journal_root(top) if top else None
 
 

package/hooks/tezgah_taste.py

@@ -27,7 +27,8 @@ import time
 
 import tezgah_integrity as ti
 import tezgah_paths
-from tezgah_paths import _toplevel, armed, root_for, workspace_from_repo
+from tezgah_paths import (_linked_main_at, _toplevel, armed, root_for,
+                          workspace_from_repo)
 
 ARM = "taste-on"
 LEARN_EVERY = 3600  # seconds between two background `learn` starts per repo
@@ -46,7 +47,8 @@ WHOLE_KEYS = ("content", "file_text", "text", "new_source")
 
 def enabled(cwd):
     """The git root taste rows for `cwd` go to, or None when capture is off
-    there. The marker is read first, so the default costs two stats."""
+    there: a linked worktree's rows go to its main checkout, the one `.tezgah`
+    of the repository. The marker is read first, so the default costs two stats."""
     try:
         if not cwd or not armed(ARM):
             return None
@@ -54,6 +56,7 @@ def enabled(cwd):
         if not root_for(real):
             return None
         top = _toplevel(real)
+        top = top and (_linked_main_at(top) or top)
         if not top or not os.path.isdir(os.path.join(top, ".tezgah")):
             return None
         from tezgah_context import repo_marks  # imports this module's callers
@@ -73,10 +76,11 @@ def _cut(text, limit):
 
 
 def _rel(root, path, cwd):
-    """`path` relative to `root`, or None when it resolves outside it."""
+    """`path` relative to the checkout holding `cwd` (a worktree's paths read
+    the same as main's), or None when it resolves outside it."""
     apath = os.path.realpath(
         str(path) if os.path.isabs(str(path)) else os.path.join(cwd, str(path)))
-    rel = os.path.relpath(apath, root)
+    rel = os.path.relpath(apath, _toplevel(os.path.realpath(cwd)) or root)
     return None if rel == ".." or rel.startswith(".." + os.sep) else rel
 
 

package/hosts/codex/hook.py

@@ -31,7 +31,7 @@ try:
         shell_kind)
     from tezgah_gate import cross_project_note, decision, graph_advice  # noqa: E402
     from tezgah_integrity import (  # noqa: E402
-        SUBAGENT_CHANNEL, bind_session, changed_files_notice, note_tool, ran_nothing,
+        SUBAGENT_CHANNEL, bind_session, changed_files_notice, note, note_tool, ran_nothing,
         report_bytes, stop_reason, untrusted_source)
     from tezgah_paths import HOST_DIRS, off, root_for  # noqa: E402
     from tezgah_taste import write_note  # noqa: E402
@@ -108,7 +108,16 @@ def gate_reason(payload, cwd, session_id):
     inp = payload.get("tool_input")
     if not isinstance(inp, dict):
         inp = {}
-    return decision(gate_name(name), inp, cwd, session_id)
+    # a subagent's calls carry its `agent_id` (the child thread id; optional in
+    # pre-tool-use.command.input.schema.json): its repeat ceilings are its own
+    return decision(gate_name(name), inp, cwd, session_id, agent=subagent_id(payload))
+
+
+def subagent_id(payload):
+    """The child thread id Codex puts on a subagent's hook input, else None (a
+    root-agent call; codex-rs/hooks: "Add subagent identity to hook inputs")."""
+    aid = payload.get("agent_id")
+    return aid if isinstance(aid, str) and aid else None
 
 
 def verify_outcome(payload):
@@ -196,7 +205,11 @@ def main():
                  out_bytes=(report_bytes(result)
                             if untrusted_source(tool, inp) == SUBAGENT_CHANNEL
                             else result_size(result)),
-                 empty_run=ran_nothing(result))
+                 empty_run=ran_nothing(result),
+                 # the child's rows land in the root session's ledger (Codex's
+                 # session_id is the root thread's); the route report reads them
+                 # back by this id
+                 agent=subagent_id(payload))
         # The gate's graph line for a code-symbol search rides the same
         # non-blocking channel (tezgah_gate.graph_advice): a Codex PreToolUse
         # carries a deny and nothing else.
@@ -220,6 +233,13 @@ def main():
         return
     if event == "SubagentStart":
         safe(session_id, record, session_id, "orch")
+        # the child's typing row in the root ledger: SubagentStart requires
+        # agent_id and agent_type (codex-rs/hooks/schema/generated/
+        # subagent-start.command.input.schema.json)
+        kind = payload.get("agent_type")
+        if subagent_id(payload) and isinstance(kind, str) and root_for(cwd):
+            safe(session_id, note, session_id, "subagent_start", kind,
+                 agent=subagent_id(payload))
     if event == "Stop":
         out = {}
         # Codex's stop.input carries the same fields Claude's does

package/hosts/cursor/hook.py

@@ -388,6 +388,17 @@ def dispatch(payload):
         else:
             record(session_id, "orch")
             out = {"permission": "allow"}
+            # The child's ledger opens with its parent, as on omp and opencode:
+            # a Cursor subagent runs under its own conversation id (observed with
+            # cursor-agent 2026.10.01), and this event names it `subagent_id`
+            # beside `parent_conversation_id` (Cursor hooks docs, subagentStart).
+            # `host` marks the row whose id the report has not seen carried by
+            # the child's own calls (tezgah_models.route_report).
+            child, parent = payload.get("subagent_id"), payload.get("parent_conversation_id")
+            if isinstance(child, str) and child and isinstance(parent, str) and parent \
+                    and under(cwd):
+                safe(child, note, child, "spawned", "", parent=parent,
+                     agent=str(payload.get("subagent_type") or "") or None, host="cursor")
             # The delegate is a fresh context that must know the rules exist, so
             # it gets the same short brief every other host hands a subagent.
             # Cursor documents no context field on subagentStart (its output is