@ethlete/agent-rules 0.1.0-next.3 → 0.1.0-next.31

package/content/hooks/context-warning.py

@@ -1,43 +1,151 @@
 #!/usr/bin/env python3
-"""UserPromptSubmit hook: warn when the context window is getting large.
+"""Context-budget hook: keep the agent aware of how much context it may still spend.
 
 Reads the hook input JSON from stdin, estimates the current context size from
-the last main-chain assistant message in the session transcript, and emits a
-warning (visible to both the user and Claude) when it crosses a threshold.
-Recommends the /handoff skill so work can continue in a fresh session.
+the session transcript, and emits a warning (visible to both the user and the
+agent) when it crosses a threshold. Recommends the handoff skill so work can
+continue in a fresh session.
 
-The thresholds are fractions of a token budget, and the budget is capped at the
-200k long-context pricing boundary: on models with a larger window, every
-request past that point bills the entire context at the premium rate, which
-costs far more than handing off into a fresh session ever would.
+Registered on five events, because a warning the agent cannot see while it works
+is not a warning:
+
+  * SessionStart - states the budget and how to scope work to it, before the
+    first request. Nothing else tells the model what its budget is.
+  * UserPromptSubmit - the tiered warning, plus a short reminder on every later
+    prompt.
+  * PostToolBatch - the same tiered warning, delivered mid-run. This is the only
+    event that fires between an agent's own model requests, so without it a long
+    autonomous run never learns its token count until the user types something.
+  * Stop - fires as the agent tries to end its turn. Its additionalContext is
+    delivered to the model and the conversation continues, so the decision to
+    finish or hand off happens without the user having to ask for it.
+
+Inside a Claude sub-agent, PostToolBatch fires with `agent_id` set and the parent's
+`transcript_path`, so the sub-agent's own transcript is read instead and it gets the
+same tiers. Its end of turn arrives as SubagentStop, whose block `reason` becomes its
+next instruction: at the critical tier, hand back a report with the exact remaining
+steps, which is the only handoff a sub-agent has.
+
+Runs under both Claude Code and Codex, selected by `--agent` on the command
+line rather than sniffed from the payload - the generator writes the flag, so
+the two never have to be told apart at runtime. Codex has only UserPromptSubmit;
+the other three events are registered for Claude alone. The two differ in three
+ways that matter here, all captured in AGENT_PROFILES:
+
+  * Transcript format. Claude writes one JSON object per message with
+    `message.usage`; Codex writes a rollout stream whose `token_count` events
+    carry a TokenUsageInfo. Codex's rollout format is explicitly not a stable
+    interface, so the parser searches each line for the usage object instead of
+    walking a fixed path.
+  * Sub-agents. Codex gives each sub-agent its own rollout and thread id while
+    retaining the root session id. Warnings identify that thread explicitly and
+    tell it to report back to its parent instead of making the main agent hand
+    off its session.
+  * Context budget. Claude's budget is capped at its 200k long-context pricing
+    boundary. Codex uses the model-specific pricing boundary where OpenAI
+    documents one, and the reported window otherwise. Crossing either boundary
+    costs far more than handing off into a fresh session ever would.
+  * How a handoff is invoked. Claude has a slash command and /clear; Codex has
+    neither and reads the skill from disk. The skill's own name differs per repo
+    (`ethlete-handoff` where the generator installed it, `handoff` where the repo
+    ships its own copy), so it is resolved at runtime - see handoff_skill().
+
+At the critical tier, if the session's permission_mode is "auto", the
+instruction escalates from "recommend" to "just do it": auto mode already
+means the user wants the agent acting without stopping to ask, and clearing +
+resuming can't be triggered programmatically (no hook or tool can submit
+input to a running session), so the best available automation is to save the
+handoff file itself immediately rather than waiting for a natural stopping
+point. Codex's permission_mode value set is undocumented, so its profile lists
+no auto modes and the escalation stays off there.
+
+Neither the critical tier nor the Stop event forces a handoff. A session is
+often a step or two from done when they fire, and some sessions hold reasoning
+that no handoff file survives - crossing the boundary is then the cheaper
+choice. So the Stop event offers three options and demands the agent name the
+one it took: finish, hand off, or continue past the boundary for a reason it
+states in one sentence. A third tier at 95% withdraws only the "finish" option,
+because a budget that small covers no task.
+
+Goes quiet while a handoff is being saved: from a prompt that requests save mode, or the
+auto-mode save this hook ordered, until the next prompt; and for the rest of a turn in
+which the agent invoked the handoff skill or wrote a handoff file. A save that is told to
+choose between finishing and handing off again never ends. `resume` is not a save.
 
 Warns once per tier per session (state kept in a temp file); re-arms itself
-if the context shrinks again (e.g. after /compact).
+if the context shrinks again (e.g. after a compaction). The Stop event keeps its
+own per-tier counter, so crossing a tier mid-run costs at most one notice while
+working and one demand at the end of the turn. Every prompt after the first
+warning carries a short reminder instead: how much budget is left, and how to
+work so that either ending stays cheap. One warning at 70% is stale by the time
+it matters, and the agent cannot see its own token count.
 
 Can be disabled per machine via a gitignored ethlete-agents.config.local.json
 at the repo root: {"disableHooks": true} or {"disableHooks": ["context-warning"]}.
+To keep the tiered warnings but drop just the auto-mode auto-save escalation,
+use {"disableAutoHandoffSave": true} instead - the critical tier then falls
+back to recommending a handoff, same as non-auto mode.
 
-Fail-safe: any error exits 0 with no output — the hook must never block a prompt.
+Fail-safe: any error exits 0 with no output - the hook must never block a prompt,
+a tool batch or the end of a turn.
 """
 
 import json
 import os
+import re
+import subprocess
 import sys
 import tempfile
 
 HOOK_NAME = "context-warning"
 LOCAL_CONFIG_FILE = "ethlete-agents.config.local.json"
 
-# Warn / critical fire at these fractions of the token budget.
+# Warn / critical / final fire at these fractions of the token budget.
 WARN_FRACTION = 0.70
 CRITICAL_FRACTION = 0.85
+FINAL_FRACTION = 0.95
+
+# How to work once the budget is tight - repeated on every prompt from the first
+# warning on, so it stays in view as the budget shrinks.
+HANDOFF_MODE = (
+    "Work in slices that each end in a committable state. Send bulky reads, searches and "
+    "test runs to a sub-agent so their output stays out of this context. Write down each "
+    "decision and dead end as you reach it, in the commit message or the handoff file. "
+    "Start nothing you cannot finish or hand off inside the remaining budget."
+)
+
+# Said once at session start, before anything has been read - the only point at which the
+# scope of the whole session is still open.
+SESSION_BUDGET = (
+    "Scope the session to it. Send bulky reads, searches and test runs to a sub-agent so "
+    "their output never enters this context. Commit in slices. A task that plainly does not "
+    "fit should be split now, not abandoned at 90%."
+)
+
+# The escape from a handoff at the critical tier, with the test that keeps it honest.
+FINISH_FIRST = (
+    "If you can name every step that is left, and they plainly fit the remaining budget, "
+    "finish the task, commit, and then apply the handoff skill's own save test - with "
+    "everything committed and no step left, write no handoff file and say so instead. "
+    "\"Nearly done\" means you can name the last steps now, not that the end feels close."
+)
 
 # On models with a window larger than this, tokens beyond it bill the whole
-# context at the long-context premium rate — so the budget never exceeds it.
+# context at the long-context premium rate - so the budget never exceeds it.
 PREMIUM_BOUNDARY = 200_000
 
+# Codex models whose long-context pricing starts above 272k input tokens. Models
+# without that pricing rule use their reported context window instead.
+CODEX_PREMIUM_BOUNDARIES = (
+    ("gpt-6.1", 500_000),
+    ("gpt-5.6", 272_000),
+    ("gpt-5.5", 272_000),
+    ("gpt-5.4-mini", None),
+    ("gpt-5.4", 272_000),
+)
+
 # Context window (tokens) per model, matched by substring against the model id
-# from the transcript — first match wins. Edit these as model windows change;
+# from the transcript - first match wins. Edit these as model windows change;
 # anything unmatched falls back to DEFAULT_WINDOW.
 CONTEXT_WINDOWS = (
     ("opus-5", 1_000_000),
@@ -45,7 +153,7 @@ CONTEXT_WINDOWS = (
     ("sonnet-4-5", 1_000_000),
     ("sonnet-5", 1_000_000),
     ("fable-5", 1_000_000),
-    # Generic fallbacks — keep these last: the first substring match wins, so a bare
+    # Generic fallbacks - keep these last: the first substring match wins, so a bare
     # "opus"/"sonnet" entry placed above would shadow every versioned entry below it.
     ("opus", 200_000),
     ("sonnet", 200_000),
@@ -53,20 +161,189 @@ CONTEXT_WINDOWS = (
 )
 DEFAULT_WINDOW = 200_000
 
+# Bytes read from the end of a Claude transcript to find the newest usage report. Read on
+# every tool batch, so a full parse of a multi-megabyte transcript would add latency to
+# every model request. Grows by GROWTH_FACTOR until a usage report is found.
+TAIL_BYTES = 256 * 1024
+MAX_TAIL_BYTES = 16 * 1024 * 1024
+GROWTH_FACTOR = 8
 
-def disabled_locally():
-    """True when the local config disables this hook (or all hooks) on this machine."""
-    root = os.environ.get("CLAUDE_PROJECT_DIR")
-    if not root:
+AGENT_PROFILES = {
+    "claude": {
+        "premium_boundary": PREMIUM_BOUNDARY,
+        "premium_boundaries": (),
+        # Claude's transcript reports no window, so it is resolved from the model id.
+        "default_window": None,
+        "auto_modes": ("auto",),
+        "emits_system_message": True,
+        "act_now": "Run /{handoff} now and continue in a fresh session.",
+        "act_later": "consider /{handoff} to continue in a fresh session",
+        "recommend": (
+            "first apply the handoff skill's save test yourself; if it calls for a file, "
+            "recommend the user run /{handoff} to save state and start a fresh session, "
+            "otherwise recommend /clear and say nothing is left to hand off, with a prompt to copy into the fresh session"
+        ),
+        "suggest": (
+            "first apply the handoff skill's save test yourself; if it calls for a file, "
+            "suggest the user run /{handoff} to save state and start a fresh session, "
+            "otherwise suggest /clear and say nothing is left to hand off, with a prompt to copy into the fresh session"
+        ),
+        "save_now": (
+            "run the handoff skill's save mode right now - finish only an in-flight atomic "
+            "edit first, nothing new. Apply its own test: with every change committed, no "
+            "step left and nothing running, write no file, say that instead, and recommend "
+            "/clear. If a file is warranted, tell the user exactly which one was written and "
+            "that they should run /clear, then '/{handoff} resume <slug>', to continue - "
+            "clearing and resuming can't be done programmatically, so this is the one step "
+            "still on them."
+        ),
+        "save_at_stop": (
+            "save a handoff with the handoff skill, then tell the user which file was "
+            "written and that they should run /clear, then '/{handoff} resume <slug>'"
+        ),
+    },
+    "codex": {
+        "premium_boundary": None,
+        "premium_boundaries": CODEX_PREMIUM_BOUNDARIES,
+        # Only reached if a rollout omits model_context_window; the CONTEXT_WINDOWS table
+        # holds Claude model ids and would never match a Codex one.
+        "default_window": 272_000,
+        # Codex's permission_mode values are undocumented; until one is confirmed to mean
+        # "never ask", no value enables the auto-save escalation.
+        "auto_modes": (),
+        # Only hookSpecificOutput.additionalContext is documented for Codex, so the
+        # user-facing line is folded into the model-facing text instead.
+        "emits_system_message": False,
+        "act_now": "Save a handoff now and continue in a fresh session.",
+        "act_later": "consider saving a handoff and continuing in a fresh session",
+        "recommend": (
+            "tell the user you are near the context limit, then follow "
+            ".agents/skills/{handoff}/SKILL.md to save a handoff and have them start a "
+            "fresh session; when its save test calls for no file, only tell them to start a "
+            "fresh session"
+        ),
+        "suggest": (
+            "first apply the save test in .agents/skills/{handoff}/SKILL.md yourself; if it "
+            "calls for a file, suggest saving a handoff and continuing in a fresh session, "
+            "otherwise suggest a fresh session and say nothing is left to hand off, with a prompt to copy into the fresh session"
+        ),
+        "save_now": (
+            "follow .agents/skills/{handoff}/SKILL.md and save a handoff right now - finish "
+            "only an in-flight atomic edit first, nothing new. Apply its own test: with "
+            "every change committed, no step left and nothing running, write no file and say "
+            "that instead. If a file is warranted, tell the user exactly which one was "
+            "written and that they should start a fresh codex session and resume from it."
+        ),
+        "save_at_stop": (
+            "save a handoff via .agents/skills/{handoff}/SKILL.md, then tell the user which "
+            "file was written and that a fresh session should resume from it"
+        ),
+    },
+}
+
+
+def handoff_skill(root):
+    """Name of the handoff skill installed in this repo.
+
+    The generator prefixes every skill it writes, so the command is /ethlete-handoff in a
+    consumer repo - but a repo that excludes the generated copy and ships its own (the SDK
+    itself) has a plain /handoff instead. Naming the wrong one sends the user to a slash
+    command that does not exist, so it is read off disk rather than assumed.
+    """
+    for name in ("ethlete-handoff", "handoff"):
+        for skills_dir in (".claude/skills", ".agents/skills"):
+            if os.path.isdir(os.path.join(root or ".", skills_dir, name)):
+                return name
+    return "ethlete-handoff"
+
+
+SELF_RESTART = (
+    "you run in an agent-sessions tmux session, so do not hand this step to the user: apply the {handoff} skill's save "
+    "test, save if it calls for a file, then follow its 'Clear and resume on your own' section "
+    "and restart this session yourself with the agent-sessions `restart` command - with no file, "
+    "restart with a prompt that names the next step"
+)
+USER_DIRECTED_KEYS = ("recommend", "suggest", "save_now", "save_at_stop")
+
+
+def can_self_restart(root):
+    """True only in a tmux session the agent-sessions `restart` command can find and drive."""
+    if not os.environ.get("TMUX") or not root:
+        return False
+    if not any(
+        os.path.isfile(os.path.join(root, ".agents/skills", name, "agent-sessions.mjs"))
+        for name in ("ethlete-agent-sessions", "agent-sessions")
+    ):
         return False
+    try:
+        session = subprocess.run(
+            ["tmux", "display-message", "-p", "#S"], capture_output=True, text=True, timeout=2
+        ).stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return session.endswith("@" + re.sub(r"[.:]", "-", os.path.basename(os.path.normpath(root))))
+
+
+def resolve_profile(profile, skill, self_restart=False):
+    """Fills the installed handoff skill's name into a profile's message fragments."""
+    resolved = {**profile, **{key: SELF_RESTART for key in USER_DIRECTED_KEYS}} if self_restart else profile
+    return {
+        key: value.replace("{handoff}", skill) if isinstance(value, str) else value
+        for key, value in resolved.items()
+    }
+
+
+def agent_name(argv):
+    """The --agent value, defaulting to claude - older registrations pass no flag."""
+    for index, arg in enumerate(argv):
+        if arg == "--agent" and index + 1 < len(argv):
+            return argv[index + 1]
+        if arg.startswith("--agent="):
+            return arg.split("=", 1)[1]
+    return "claude"
+
+
+def repo_root(data):
+    """Repo root: the env var the agent sets, else derived from this script's own location.
+
+    The script always lives at <root>/.<agent>/hooks/ethlete/context-warning.py, so walking
+    four levels up works for any agent that has no project-dir variable of its own.
+    """
+    for variable in ("CLAUDE_PROJECT_DIR", "CODEX_PROJECT_DIR"):
+        value = os.environ.get(variable)
+        if value:
+            return value
+    here = os.path.abspath(__file__)
+    derived = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(here))))
+    if os.path.isfile(os.path.join(derived, LOCAL_CONFIG_FILE)):
+        return derived
+    cwd = data.get("cwd")
+    return cwd if isinstance(cwd, str) and cwd else derived
+
+
+def load_local_config(root):
+    """Parsed ethlete-agents.config.local.json at the repo root, or {} if missing/unreadable."""
+    if not root:
+        return {}
     try:
         with open(os.path.join(root, LOCAL_CONFIG_FILE), encoding="utf-8") as f:
-            disabled = json.load(f).get("disableHooks")
+            config = json.load(f)
     except (OSError, ValueError, AttributeError):
-        return False
+        return {}
+    return config if isinstance(config, dict) else {}
+
+
+def disabled_locally(config):
+    """True when the local config disables this hook (or all hooks) on this machine."""
+    disabled = config.get("disableHooks")
     return disabled is True or (isinstance(disabled, list) and HOOK_NAME in disabled)
 
 
+def auto_handoff_save_disabled(config):
+    """True when the local config opts out of the auto-mode critical-tier auto-save."""
+    return config.get("disableAutoHandoffSave") is True
+
+
 def window_for(model):
     """Context window for a model id, by first substring match; DEFAULT_WINDOW otherwise."""
     if model:
@@ -76,135 +353,620 @@ def window_for(model):
     return DEFAULT_WINDOW
 
 
-def context_state(transcript_path):
-    """(tokens, model) from the last main-chain assistant message.
+def premium_boundary_for(profile, model):
+    """Model-specific pricing boundary, falling back to the agent-wide value."""
+    if model:
+        for needle, boundary in profile["premium_boundaries"]:
+            if needle in model:
+                return boundary
+    return profile["premium_boundary"]
+
+
+def tail_lines(path, limit):
+    """(lines newest-first, whole file read) for the last `limit` bytes of a file.
+
+    A partial first line is dropped, so every returned line is complete.
+    """
+    size = os.path.getsize(path)
+    start = max(size - limit, 0)
+    with open(path, "rb") as f:
+        f.seek(start)
+        chunk = f.read()
+    if start > 0:
+        newline = chunk.find(b"\n")
+        chunk = chunk[newline + 1 :] if newline != -1 else b""
+    return list(reversed(chunk.split(b"\n"))), start == 0
+
+
+def claude_usage_in(lines, sidechain=False):
+    """(usage, model) from the newest assistant message of the chain in `lines`, or (None, None).
+
+    A sub-agent's own transcript marks every entry `isSidechain`, so reading one needs `sidechain`.
+    """
+    for line in lines:
+        if not line.strip():
+            continue
+        try:
+            obj = json.loads(line)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            continue
+        if obj.get("type") != "assistant" or bool(obj.get("isSidechain")) != sidechain:
+            continue
+        message = obj.get("message") or {}
+        usage = message.get("usage")
+        if usage:
+            return usage, message.get("model")
+    return None, None
+
+
+def claude_context_state(transcript_path, sidechain=False):
+    """(tokens, model, window, thread id, is sub-agent) from the main-chain assistant message.
+
+    tokens is its total input tokens (fresh + cache read + cache creation). Claude reports no
+    window in the transcript, so it is resolved from the model id by the caller. Only the tail
+    of the transcript is read, growing until a usage report is found - this runs on every tool
+    batch, and a transcript reaches tens of megabytes.
+    """
+    limit = TAIL_BYTES
+    while True:
+        lines, complete = tail_lines(transcript_path, limit)
+        usage, model = claude_usage_in(lines, sidechain)
+        if usage:
+            tokens = (
+                usage.get("input_tokens", 0)
+                + usage.get("cache_read_input_tokens", 0)
+                + usage.get("cache_creation_input_tokens", 0)
+            )
+            return tokens, model, None, None, sidechain
+        if complete or limit >= MAX_TAIL_BYTES:
+            return 0, None, None, None, sidechain
+        limit *= GROWTH_FACTOR
+
+
+def find_token_usage_info(node):
+    """The deepest TokenUsageInfo-shaped dict in a parsed rollout line, or None.
+
+    Codex documents its rollout format as unstable, so this searches for the shape
+    (a dict carrying `last_token_usage`) rather than walking a fixed key path.
+    """
+    if isinstance(node, dict):
+        if isinstance(node.get("last_token_usage"), dict):
+            return node
+        for value in node.values():
+            found = find_token_usage_info(value)
+            if found:
+                return found
+    elif isinstance(node, list):
+        for value in node:
+            found = find_token_usage_info(value)
+            if found:
+                return found
+    return None
+
 
-    tokens ≈ its total input tokens (fresh + cache read + cache creation).
+def codex_context_state(transcript_path):
+    """(tokens, model, window, thread id, is sub-agent) from a Codex rollout.
+
+    tokens is the last request's `total_tokens` - Codex's own `tokens_in_context_window()`
+    is exactly that field, and `last_token_usage` is replaced per request while
+    `total_token_usage` accumulates across the whole session.
     """
-    last_usage = None
+    last_info = None
     last_model = None
+    thread_id = None
+    is_subagent = False
     with open(transcript_path, encoding="utf-8") as f:
         for line in f:
             try:
                 obj = json.loads(line)
             except json.JSONDecodeError:
                 continue
-            if obj.get("type") != "assistant" or obj.get("isSidechain"):
-                continue
-            message = obj.get("message") or {}
-            usage = message.get("usage")
-            if usage:
-                last_usage = usage
-                last_model = message.get("model") or last_model
-    if not last_usage:
-        return 0, last_model
-    tokens = (
-        last_usage.get("input_tokens", 0)
-        + last_usage.get("cache_read_input_tokens", 0)
-        + last_usage.get("cache_creation_input_tokens", 0)
+            if obj.get("type") == "session_meta":
+                payload = obj.get("payload") or {}
+                source = payload.get("source")
+                thread_id = payload.get("id") or thread_id
+                is_subagent = payload.get("thread_source") == "subagent" or (
+                    isinstance(source, dict) and isinstance(source.get("subagent"), dict)
+                )
+            model = (obj.get("payload") or {}).get("model") if isinstance(obj.get("payload"), dict) else None
+            if isinstance(model, str) and model:
+                last_model = model
+            info = find_token_usage_info(obj)
+            if info:
+                last_info = info
+    if not last_info:
+        return 0, last_model, None, thread_id, is_subagent
+    usage = last_info.get("last_token_usage") or {}
+    window = last_info.get("model_context_window")
+    return (
+        usage.get("total_tokens", 0),
+        last_model,
+        window if isinstance(window, int) else None,
+        thread_id,
+        is_subagent,
+    )
+
+
+CONTEXT_READERS = {"claude": claude_context_state, "codex": codex_context_state}
+
+
+HANDOFF_SKILLS = ("handoff", "ethlete-handoff")
+COMMAND_PATTERN = re.compile(r"<command-name>/?([^<]*)</command-name>")
+ARGS_PATTERN = re.compile(r"<command-args>([^<]*)</command-args>")
+
+
+def is_handoff_save(skill, args):
+    return skill in HANDOFF_SKILLS and not (args or "").strip().lower().startswith("resume")
+
+
+def handoff_save_requested(prompt):
+    """True for a prompt that runs the handoff skill in save mode - a slash command or a plain one."""
+    if not isinstance(prompt, str):
+        return False
+    command = COMMAND_PATTERN.search(prompt)
+    if command:
+        args = ARGS_PATTERN.search(prompt)
+        return is_handoff_save(command.group(1).strip(), args.group(1) if args else "")
+    words = prompt.strip().split(None, 1)
+    return bool(words) and is_handoff_save(words[0].lstrip("/").lower(), words[1] if len(words) > 1 else "")
+
+
+def is_turn_start(obj):
+    if obj.get("type") != "user" or obj.get("isSidechain") or obj.get("isMeta"):
+        return False
+    origin = obj.get("origin")
+    if isinstance(origin, dict):
+        return origin.get("kind") == "human"
+    content = (obj.get("message") or {}).get("content")
+    return isinstance(content, str)
+
+
+def starts_handoff(block):
+    if not isinstance(block, dict) or block.get("type") != "tool_use":
+        return False
+    tool_input = block.get("input") or {}
+    if block.get("name") == "Skill":
+        return is_handoff_save(tool_input.get("skill"), tool_input.get("args"))
+    path = tool_input.get("file_path")
+    return isinstance(path, str) and path.endswith(".md") and "handoffs" in path.replace("\\", "/").split("/")
+
+
+def subagent_transcript(data):
+    """The transcript of the Claude sub-agent a hook fired in, or None when it cannot be found.
+
+    Inside a sub-agent, `transcript_path` is the parent's. Only SubagentStop carries
+    `agent_transcript_path`; every other event is resolved through the layout Claude Code writes,
+    `<session>.jsonl` next to `<session>/subagents/agent-<agent_id>.jsonl`.
+    """
+    explicit = data.get("agent_transcript_path")
+    if explicit and os.path.isfile(explicit):
+        return explicit
+    parent = data.get("transcript_path")
+    agent_id = str(data.get("agent_id") or "")
+    if not parent or not agent_id:
+        return None
+    session = os.path.splitext(os.path.basename(parent))[0]
+    name = agent_id if agent_id.startswith("agent-") else f"agent-{agent_id}"
+    path = os.path.join(os.path.dirname(parent), session, "subagents", f"{name}.jsonl")
+    return path if os.path.isfile(path) else None
+
+
+def handoff_under_way_in_turn(transcript_path):
+    """True when the current Claude turn requested, invoked or wrote a handoff save."""
+    lines, _ = tail_lines(transcript_path, TAIL_BYTES)
+    for line in lines:
+        if not line.strip():
+            continue
+        try:
+            obj = json.loads(line)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            continue
+        if obj.get("isSidechain"):
+            continue
+        content = (obj.get("message") or {}).get("content")
+        if is_turn_start(obj):
+            return handoff_save_requested(content if isinstance(content, str) else None)
+        if obj.get("type") == "assistant" and isinstance(content, list) and any(map(starts_handoff, content)):
+            return True
+    return False
+
+
+def headroom(tokens, budget):
+    """How much budget is left, as a short human string."""
+    left = max(budget - tokens, 0)
+    return f"~{left // 1000}k tokens" if left >= 1000 else "under 1k tokens"
+
+
+def limit_name(priced):
+    return "long-context pricing boundary" if priced else "context window"
+
+
+def cost_of_crossing(priced):
+    """What the user pays for one more token past the budget."""
+    if priced:
+        return "every later request is billed at the premium rate"
+    return "auto-compact fires and the detail of this session is summarised away"
+
+
+def token_count(tokens):
+    """A token count as a short label: 1M rather than 1000k."""
+    if tokens >= 1_000_000 and tokens % 1_000_000 == 0:
+        return f"{tokens // 1_000_000}M"
+    return f"{tokens // 1000}k"
+
+
+def session_start_message(budget, window, model):
+    """The one line said before the first request, naming the budget and how to fit it.
+
+    A session that starts fresh has no assistant message yet, so the model - and with it the
+    window - is unknown. The budget is not: it is the pricing boundary either way.
+    """
+    budget_label = token_count(budget)
+    if not model:
+        frame = (
+            "past it a model with a larger window bills every request at the premium rate, and a "
+            f"{budget_label} model auto-compacts the session away"
+        )
+    elif budget < window:
+        frame = (
+            f"the long-context pricing boundary of this model's {token_count(window)} window; "
+            "past it every request is billed at the premium rate"
+        )
+    else:
+        frame = "this model's whole context window; past it auto-compact summarises the session away"
+    return (
+        f"[context-warning hook] Context budget for this session: {budget_label} tokens - {frame}. "
+        f"{SESSION_BUDGET} You will be warned at 70%, 85% and 95%."
     )
-    return tokens, last_model
 
 
-def messages(tier, tokens, budget, priced):
+def messages(profile, tier, tokens, budget, priced, auto_mode):
     """(systemMessage, additionalContext) for a tier.
 
-    priced: the budget is the pricing boundary, not the window — the reason to
+    priced: the budget is the pricing boundary, not the window - the reason to
     hand off is cost, not an imminent auto-compact.
+    auto_mode: from the critical tier on, escalates from "recommend a handoff"
+    to "save it now" - see the module docstring for why.
     """
     k = f"~{tokens // 1000}k"
     pct = round(tokens / budget * 100)
     budget_k = f"{budget // 1000}k"
-    if tier == 2 and priced:
-        return (
-            f"🔴 Context is at {k} tokens — about to cross the {budget_k} long-context "
-            f"pricing boundary, after which every request bills the whole context at the "
-            f"premium rate. Run /handoff now and continue in a fresh session.",
-            f"[context-warning hook] The context is at {k} tokens — {pct}% of the "
-            f"{budget_k} long-context pricing boundary. Past it every request is billed at "
-            "the premium rate. Finish only the immediate step, then recommend the user run "
-            "/handoff to save state and start a fresh session. Do not start new sub-tasks.",
+    left = headroom(tokens, budget)
+
+    if priced:
+        approach = "about to cross" if tier >= 2 else "approaching"
+        headline = f"Context is at {k} tokens - {approach} the {budget_k} long-context pricing boundary"
+        detail = (
+            f"The context is at {k} tokens - {pct}% of the {budget_k} long-context "
+            f"pricing boundary, {left} left."
         )
-    if tier == 2:
+        pressure = "Past it every request is billed at the premium rate. "
+        tail = ""
+    else:
+        headline = f"Context is at {k} tokens ({pct}% of the {budget_k} window)"
+        detail = (
+            f"The context window is at {k} tokens - {pct}% of this model's "
+            f"{budget_k} window, {left} left."
+        )
+        pressure = ""
+        tail = " - auto-compact is imminent" if tier >= 3 else " - auto-compact is close" if tier == 2 else ""
+
+    if tier >= 3:
+        gone = (
+            f"The finish-first choice from the last warning is gone: {left} does not "
+            f"cover another task."
+        )
+        if auto_mode:
+            return (
+                f"🔴 {headline}{tail}. Auto mode is active: saving a handoff now.",
+                f"[context-warning hook] {detail} {pressure}{gone} Auto mode is active, so "
+                f"{profile['save_now']}",
+            )
         return (
-            f"🔴 Context is at {k} tokens ({pct}% of the {budget_k} window) — "
-            f"auto-compact is imminent. Run /handoff now and continue in a fresh session.",
-            f"[context-warning hook] The context window is at {k} tokens — {pct}% of "
-            f"this model's {budget_k} window (critical, ≥{int(CRITICAL_FRACTION * 100)}%). "
-            "Finish only the immediate step, then recommend the user run /handoff to "
-            "save state and start a fresh session. Do not start new sub-tasks.",
+            f"🔴 {headline}{tail}. {profile['act_now']}",
+            f"[context-warning hook] {detail} {pressure}{gone} Stop after the current tool "
+            f"call, then {profile['recommend']}.",
         )
-    if priced:
+
+    if tier == 2:
+        if auto_mode:
+            return (
+                f"🔴 {headline}{tail}. Auto mode is active: finishing the task, or saving a handoff.",
+                f"[context-warning hook] {detail} {pressure}Auto mode is active, so don't "
+                f"just recommend a handoff. Choose one of two, and tell the user which. "
+                f"{FINISH_FIRST} Otherwise {profile['save_now']}",
+            )
         return (
-            f"🟡 Context is at {k} tokens, approaching the {budget_k} long-context "
-            f"pricing boundary. At the next natural stopping point, consider /handoff "
-            f"to continue in a fresh session.",
-            f"[context-warning hook] The context is at {k} tokens — {pct}% of the "
-            f"{budget_k} long-context pricing boundary, past which every request is "
-            "billed at the premium rate. When the current task reaches a natural "
-            "stopping point, suggest the user run /handoff to save state and start a "
-            "fresh session. Keep working normally until then.",
+            f"🔴 {headline}{tail}. {profile['act_now']}",
+            f"[context-warning hook] {detail} {pressure}Choose one of two, and tell the user "
+            f"which. {FINISH_FIRST} Otherwise finish only the immediate step, then "
+            f"{profile['recommend']}. Either way, start no new sub-tasks.",
         )
+
+    return (
+        f"🟡 {headline}. At the next natural stopping point, {profile['act_later']}.",
+        f"[context-warning hook] {detail} {pressure}Handoff mode is active from here on. "
+        f"{HANDOFF_MODE} Keep working; when the current task reaches a natural stopping "
+        f"point, {profile['suggest']}.",
+    )
+
+
+def stop_messages(profile, tier, tokens, budget, priced):
+    """(systemMessage, additionalContext) for a turn that is about to end over budget.
+
+    The turn continues after this, so the agent acts on it without the user having to
+    send a message. It is the only point where the agent is between tasks and can still
+    spend tokens, so the choice is put here in full - including the option to cross the
+    boundary on purpose, which some sessions are worth.
+    """
+    k = f"~{tokens // 1000}k"
+    pct = round(tokens / budget * 100)
+    budget_k = f"{budget // 1000}k"
+    left = headroom(tokens, budget)
+    options = [
+        f"Hand off: {profile['save_at_stop']}.",
+        (
+            "Cross the boundary on purpose: take this only for a reason you can name in one "
+            "sentence right now, for example the task is one step from done, or this session "
+            f"holds reasoning a handoff file would lose. Say the reason, say that "
+            f"{cost_of_crossing(priced)}, and keep working."
+        ),
+    ]
+    if tier < 3:
+        options.insert(0, f"Finish the task now: {FINISH_FIRST}")
+    numbered = " ".join(f"{index}. {text}" for index, text in enumerate(options, start=1))
+    withdrawn = (
+        ""
+        if tier < 3
+        else f" The finish-first option is withdrawn at this tier: {left} does not cover another task."
+    )
+    return (
+        f"🔴 Turn ending at {k} tokens ({pct}% of the {budget_k} {limit_name(priced)}). "
+        f"Deciding whether to hand off.",
+        f"[context-warning hook] This turn is about to end at {k} tokens - {pct}% of the "
+        f"{budget_k} {limit_name(priced)}, {left} left. Past it {cost_of_crossing(priced)}."
+        f"{withdrawn} Do not end the turn without taking one of these, and tell the user "
+        f"which you took. {numbered}",
+    )
+
+
+def reminder(tier, tokens, budget, priced):
+    """The short note repeated on every prompt after a tier was already warned about.
+
+    A single warning at 70% is stale by the time the budget is actually tight, and the
+    agent has no way to read its own token count between prompts.
+    """
+    stop = (
+        " You were already told to hand off. Do not take on new work."
+        if tier >= 2
+        else ""
+    )
+    return (
+        f"[context-warning hook] Handoff mode is active: {headroom(tokens, budget)} left of "
+        f"the {budget // 1000}k {limit_name(priced)}. {HANDOFF_MODE}{stop}"
+    )
+
+
+SUBAGENT_HAND_BACK = (
+    "Finish only the atomic edit in flight - start nothing new. Commit what is committable, "
+    "then end your run with the hand-back report to the parent agent: what is done (with the "
+    "commit), the findings, and the exact remaining steps - files, commands, what 'done' means "
+    "- so a fresh sub-agent can carry them out. That report is your handoff; a sub-agent cannot "
+    "hand off to a new session."
+)
+
+
+def subagent_message(tier, tokens, budget, priced):
+    k = f"~{tokens // 1000}k"
+    pct = round(tokens / budget * 100)
+    budget_k = f"{budget // 1000}k"
+    next_step = (
+        SUBAGENT_HAND_BACK
+        if tier >= 2
+        else "Wrap up: keep reads and tool output small, take no detours, and plan to hand back "
+        "to the parent agent before 85%. If the task will not fit, finish the current slice and "
+        "hand back the rest as exact remaining steps."
+    )
+    return (
+        f"[context-warning hook] This warning applies to a sub-agent thread, not the "
+        f"parent/main agent. This sub-agent is at {k} tokens - {pct}% of its {budget_k} "
+        f"{limit_name(priced)}. {next_step} Do not create a user-facing session handoff or "
+        f"claim that the main agent's context is full."
+    )
+
+
+def subagent_stop_message(tier, tokens, budget, priced):
+    return (
+        f"[context-warning hook] This sub-agent is at ~{tokens // 1000}k tokens - "
+        f"{round(tokens / budget * 100)}% of its {budget // 1000}k {limit_name(priced)}. "
+        f"Take on no further task work. {SUBAGENT_HAND_BACK} If your last message already is that "
+        f"report, repeat it unchanged and end."
+    )
+
+
+def subagent_reminder(tokens, budget, priced):
     return (
-        f"🟡 Context is at {k} tokens ({pct}% of the {budget_k} window). At the next "
-        f"natural stopping point, consider /handoff to continue in a fresh session.",
-        f"[context-warning hook] The context window is at {k} tokens — {pct}% of "
-        f"this model's {budget_k} window (≥{int(WARN_FRACTION * 100)}%). When the "
-        "current task reaches a natural stopping point, suggest the user run "
-        "/handoff to save state and start a fresh session. Keep working normally until then.",
+        f"[context-warning hook] Handoff mode is active for this sub-agent thread, not the "
+        f"parent/main agent: {headroom(tokens, budget)} left of its {budget // 1000}k "
+        f"{limit_name(priced)}. Keep findings compact and send them to the parent agent "
+        f"before the budget runs out. Do not create a user-facing session handoff."
     )
 
 
+def emit(event, additional_context, system_message=None):
+    payload = {
+        "hookSpecificOutput": {
+            "hookEventName": event,
+            "additionalContext": additional_context,
+        }
+    }
+    if system_message:
+        payload["systemMessage"] = system_message
+        payload["suppressOutput"] = True
+    print(json.dumps(payload))
+
+
+def read_state(path):
+    """{"tier": n, "stop_tier": n, "saving": bool} from the state file; zeroes when absent or unreadable."""
+    empty = {"tier": 0, "stop_tier": 0, "saving": False}
+    try:
+        with open(path, encoding="utf-8") as f:
+            raw = f.read().strip()
+    except OSError:
+        return empty
+    try:
+        state = json.loads(raw)
+        if isinstance(state, dict):
+            return {
+                "tier": int(state.get("tier", 0)),
+                "stop_tier": int(state.get("stop_tier", 0)),
+                "saving": state.get("saving") is True,
+            }
+    except (ValueError, TypeError):
+        pass
+    try:
+        return {**empty, "tier": int(raw or 0)}
+    except ValueError:
+        return empty
+
+
+def write_state(path, state):
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(state, f)
+    except OSError:
+        pass
+
+
 def main():
-    if disabled_locally():
+    agent = agent_name(sys.argv[1:])
+    profile = AGENT_PROFILES.get(agent)
+    if not profile:
         return
+
     data = json.load(sys.stdin)
-    transcript_path = data.get("transcript_path")
-    session_id = data.get("session_id", "unknown")
-    if not transcript_path or not os.path.isfile(transcript_path):
+    event = data.get("hook_event_name") or "UserPromptSubmit"
+    root = repo_root(data)
+    local_config = load_local_config(root)
+    if disabled_locally(local_config):
         return
 
-    tokens, model = context_state(transcript_path)
-    window = window_for(model)
-    budget = min(window, PREMIUM_BOUNDARY)
-    warn_tokens = int(budget * WARN_FRACTION)
-    critical_tokens = int(budget * CRITICAL_FRACTION)
-    tier = 2 if tokens >= critical_tokens else 1 if tokens >= warn_tokens else 0
+    profile = resolve_profile(profile, handoff_skill(root), self_restart=can_self_restart(root))
 
-    state_file = os.path.join(
-        tempfile.gettempdir(), f"claude-context-warning-{session_id}"
-    )
-    prev_tier = 0
-    try:
-        with open(state_file, encoding="utf-8") as f:
-            prev_tier = int(f.read().strip() or 0)
-    except (OSError, ValueError):
-        pass
+    claude_subagent = agent == "claude" and bool(data.get("agent_id"))
+    if claude_subagent:
+        if event not in ("PostToolBatch", "Stop", "SubagentStop"):
+            return
+        transcript_path = subagent_transcript(data)
+        session_id = f"{data.get('session_id', 'unknown')}-{data.get('agent_id')}"
+    else:
+        if event == "SubagentStop":
+            return
+        transcript_path = data.get("transcript_path")
+        session_id = data.get("session_id", "unknown")
+    auto_mode = data.get("permission_mode") in profile["auto_modes"] and not auto_handoff_save_disabled(local_config)
+    has_transcript = bool(transcript_path) and os.path.isfile(transcript_path)
 
-    if tier != prev_tier:
-        try:
-            with open(state_file, "w", encoding="utf-8") as f:
-                f.write(str(tier))
-        except OSError:
-            pass
+    # SessionStart fires before the first request, so it must not need a transcript to exist.
+    if not has_transcript and event != "SessionStart":
+        return
+
+    if has_transcript:
+        if claude_subagent:
+            tokens, model, reported_window, thread_id, is_subagent = claude_context_state(transcript_path, True)
+        else:
+            tokens, model, reported_window, thread_id, is_subagent = CONTEXT_READERS[agent](transcript_path)
+    else:
+        tokens, model, reported_window, thread_id, is_subagent = 0, None, None, None, False
+    window = reported_window or profile["default_window"] or window_for(model)
+    boundary = premium_boundary_for(profile, model)
+    budget = min(window, boundary) if boundary else window
+    priced = budget < window
+
+    if event == "SessionStart":
+        emit(event, session_start_message(budget, window, model))
+        return
+
+    tier = 0
+    for level, fraction in ((3, FINAL_FRACTION), (2, CRITICAL_FRACTION), (1, WARN_FRACTION)):
+        if tokens >= int(budget * fraction):
+            tier = level
+            break
+
+    state_id = thread_id or session_id
+    safe_state_id = "".join(char for char in str(state_id) if char.isalnum() or char in "-_")[:128]
+    state_file = os.path.join(tempfile.gettempdir(), f"{agent}-context-warning-{safe_state_id or 'unknown'}")
+    state = read_state(state_file)
+    prev_tier = state["tier"]
+
+    if event == "UserPromptSubmit":
+        saving = handoff_save_requested(data.get("prompt"))
+        if saving != state["saving"]:
+            state = {**state, "saving": saving}
+            write_state(state_file, state)
+        if saving:
+            return
+    elif tier and (
+        state["saving"] or (agent == "claude" and not is_subagent and handoff_under_way_in_turn(transcript_path))
+    ):
+        return
+
+    if claude_subagent and event in ("Stop", "SubagentStop"):
+        # A sub-agent's end of turn ends its run, so the critical tier blocks it once per tier
+        # and the reason becomes its next instruction: hand back, do not start new work.
+        if tier < 2 or tier <= state["stop_tier"]:
+            return
+        write_state(state_file, {**state, "stop_tier": tier})
+        print(json.dumps({"decision": "block", "reason": subagent_stop_message(tier, tokens, budget, priced)}))
+        return
+
+    if event == "Stop":
+        # Below the critical tier the mid-run notice is enough; interrupting the end of a turn
+        # at 70% costs more than it saves.
+        if tier < 2 or tier <= state["stop_tier"] or is_subagent:
+            return
+        write_state(state_file, {**state, "stop_tier": tier})
+        system_message, additional_context = stop_messages(profile, tier, tokens, budget, priced)
+        if profile["emits_system_message"]:
+            emit(event, additional_context, system_message)
+        else:
+            emit(event, additional_context)
+        return
+
+    orders_save = auto_mode and tier >= 2 and tier > prev_tier and not is_subagent
+    if tier != prev_tier or orders_save:
+        write_state(
+            state_file,
+            {**state, "tier": tier, "stop_tier": min(state["stop_tier"], tier), "saving": state["saving"] or orders_save},
+        )
 
     if tier <= prev_tier:
-        return  # already warned at this tier (or context shrank — state re-armed above)
-
-    system_message, additional_context = messages(tier, tokens, budget, budget < window)
-
-    print(
-        json.dumps(
-            {
-                "systemMessage": system_message,
-                "suppressOutput": True,
-                "hookSpecificOutput": {
-                    "hookEventName": "UserPromptSubmit",
-                    "additionalContext": additional_context,
-                },
-            }
+        # Below the first threshold, or the context shrank - the state was re-armed above.
+        if tier == 0:
+            return
+        # Only a prompt repeats the reminder. On a tool batch it would be re-injected before
+        # every model request, which costs more context than it saves.
+        if event != "UserPromptSubmit":
+            return
+        emit(
+            event,
+            subagent_reminder(tokens, budget, priced)
+            if is_subagent
+            else reminder(tier, tokens, budget, priced),
         )
+        return
+
+    if is_subagent:
+        emit(event, subagent_message(tier, tokens, budget, priced))
+        return
+
+    system_message, additional_context = messages(
+        profile, tier, tokens, budget, priced, auto_mode
     )
+    if profile["emits_system_message"]:
+        emit(event, additional_context, system_message)
+    else:
+        emit(event, f"{additional_context}\n\nTell the user: {system_message}")
 
 
 if __name__ == "__main__":