@ethlete/agent-rules 0.1.0-next.14 → 0.1.0-next.15

package/content/hooks/context-warning.py

@@ -1,21 +1,40 @@
 #!/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 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.
 
+Registered on four 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.
+
 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. The two differ in three ways
-that matter here, all captured in AGENT_PROFILES:
+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
@@ -23,7 +42,7 @@ that matter here, all captured in AGENT_PROFILES:
   * 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().
+    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
@@ -34,8 +53,21 @@ 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.
+
 Warns once per tier per session (state kept in a temp file); re-arms itself
-if the context shrinks again (e.g. after a compaction).
+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"]}.
@@ -43,7 +75,8 @@ 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
@@ -54,12 +87,38 @@ 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
@@ -72,7 +131,7 @@ CODEX_PREMIUM_BOUNDARIES = (
 )
 
 # 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),
@@ -80,7 +139,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),
@@ -88,6 +147,13 @@ 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
+
 AGENT_PROFILES = {
     "claude": {
         "premium_boundary": PREMIUM_BOUNDARY,
@@ -101,11 +167,17 @@ AGENT_PROFILES = {
         "recommend": "recommend the user run /{handoff} to save state and start a fresh session",
         "suggest": "suggest the user run /{handoff} to save state and start a fresh session",
         "save_now": (
-            "run the handoff skill's save mode right now (finish only an in-flight atomic "
-            "edit first, nothing new). Then tell the user exactly which handoff file 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."
+            "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": {
@@ -132,10 +204,15 @@ AGENT_PROFILES = {
             "continuing in a 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). Then tell the user "
-            "exactly which handoff file was written and that they should start a fresh "
-            "codex session and resume from it."
+            "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"
         ),
     },
 }
@@ -145,7 +222,7 @@ 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
+    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.
     """
@@ -165,7 +242,7 @@ def resolve_profile(profile, skill):
 
 
 def agent_name(argv):
-    """The --agent value, defaulting to claude — older registrations pass no flag."""
+    """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]
@@ -233,35 +310,62 @@ def premium_boundary_for(profile, model):
     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):
+    """(usage, model) from the newest main-chain assistant message in `lines`, or (None, None)."""
+    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 obj.get("isSidechain"):
+            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):
-    """(tokens, model, window) from the last main-chain assistant message.
+    """(tokens, model, window, thread id, is sub-agent) from the main-chain assistant message.
 
-    tokens ≈ 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.
+    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.
     """
-    last_usage = None
-    last_model = None
-    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, None
-    tokens = (
-        last_usage.get("input_tokens", 0)
-        + last_usage.get("cache_read_input_tokens", 0)
-        + last_usage.get("cache_creation_input_tokens", 0)
-    )
-    return tokens, last_model, None
+    limit = TAIL_BYTES
+    while True:
+        lines, complete = tail_lines(transcript_path, limit)
+        usage, model = claude_usage_in(lines)
+        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, False
+        if complete or limit >= MAX_TAIL_BYTES:
+            return 0, None, None, None, False
+        limit *= GROWTH_FACTOR
 
 
 def find_token_usage_info(node):
@@ -286,20 +390,29 @@ def find_token_usage_info(node):
 
 
 def codex_context_state(transcript_path):
-    """(tokens, model, window) from the last token_count event in a Codex rollout.
+    """(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()`
+    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_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") == "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
@@ -307,72 +420,265 @@ def codex_context_state(transcript_path):
             if info:
                 last_info = info
     if not last_info:
-        return 0, last_model, None
+        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
+    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}
 
 
+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%."
+    )
+
+
 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: at the critical tier, escalates from "recommend a handoff" to
-    "save it now" — see the module docstring for why.
+    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"
+    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"
+        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."
+            f"The context is at {k} tokens - {pct}% of the {budget_k} long-context "
+            f"pricing boundary, {left} left."
         )
+        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"
+            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 == 2:
-        threshold = f" (critical, ≥{int(CRITICAL_FRACTION * 100)}%)"
-        detail = detail if priced else f"{detail}{threshold}."
-        pressure = (
-            "Past it every request is billed at the premium rate. "
-            if priced
-            else ""
+    if tier >= 3:
+        gone = (
+            f"The finish-first choice from the last warning is gone: {left} does not "
+            f"cover another task."
         )
-        tail = "" if priced else " — auto-compact is imminent"
         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"🔴 {headline}{tail}. {profile['act_now']}",
+            f"[context-warning hook] {detail} {pressure}{gone} Stop after the current tool "
+            f"call, then {profile['recommend']}.",
+        )
+
+    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 — {profile['save_now']}",
+                f"just recommend a handoff. Choose one of two, and tell the user which. "
+                f"{FINISH_FIRST} Otherwise {profile['save_now']}",
             )
         return (
             f"🔴 {headline}{tail}. {profile['act_now']}",
-            f"[context-warning hook] {detail} {pressure}Finish only the immediate step, "
-            f"then {profile['recommend']}. Do not start new sub-tasks.",
+            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.",
         )
 
-    threshold = f" (≥{int(WARN_FRACTION * 100)}%)"
-    detail = detail if priced else f"{detail}{threshold}."
-    pressure = "Past it every request is billed at the premium rate. " if priced else ""
     return (
         f"🟡 {headline}. At the next natural stopping point, {profile['act_later']}.",
-        f"[context-warning hook] {detail} {pressure}When the current task reaches a "
-        f"natural stopping point, {profile['suggest']}. Keep working normally until then.",
+        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}"
+    )
+
+
+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 = (
+        "Finish only the immediate step, then send the parent agent detailed findings, "
+        "completed work, and remaining work, and stop."
+        if tier >= 2
+        else "Keep working normally; at the next natural stopping point, send detailed progress "
+        "and any remaining work to the parent agent."
+    )
+    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_reminder(tokens, budget, priced):
+    return (
+        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} from the state file; zeroes when absent or unreadable."""
+    try:
+        with open(path, encoding="utf-8") as f:
+            raw = f.read().strip()
+    except OSError:
+        return {"tier": 0, "stop_tier": 0}
+    try:
+        state = json.loads(raw)
+        if isinstance(state, dict):
+            return {"tier": int(state.get("tier", 0)), "stop_tier": int(state.get("stop_tier", 0))}
+    except (ValueError, TypeError):
+        pass
+    try:
+        return {"tier": int(raw or 0), "stop_tier": 0}
+    except ValueError:
+        return {"tier": 0, "stop_tier": 0}
+
+
+def write_state(path, state):
+    try:
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(state, f)
+    except OSError:
+        pass
+
+
 def main():
     agent = agent_name(sys.argv[1:])
     profile = AGENT_PROFILES.get(agent)
@@ -380,6 +686,7 @@ def main():
         return
 
     data = json.load(sys.stdin)
+    event = data.get("hook_event_name") or "UserPromptSubmit"
     root = repo_root(data)
     local_config = load_local_config(root)
     if disabled_locally(local_config):
@@ -387,58 +694,89 @@ def main():
 
     profile = resolve_profile(profile, handoff_skill(root))
 
+    # PostToolBatch and Stop also fire inside an Agent-tool sub-agent, where the transcript
+    # read here belongs to the parent. Telling a sub-agent to hand off the user's session
+    # would be wrong, and its own token count is not available, so stay silent.
+    if data.get("agent_id") and event in ("PostToolBatch", "Stop"):
+        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)
-    if not transcript_path or not os.path.isfile(transcript_path):
+    has_transcript = bool(transcript_path) and os.path.isfile(transcript_path)
+
+    # SessionStart fires before the first request, so it must not need a transcript to exist.
+    if not has_transcript and event != "SessionStart":
         return
 
-    tokens, model, reported_window = CONTEXT_READERS[agent](transcript_path)
+    if has_transcript:
+        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
-    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
+    priced = budget < window
 
-    state_file = os.path.join(
-        tempfile.gettempdir(), f"{agent}-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
+    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 == "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
 
     if tier != prev_tier:
-        try:
-            with open(state_file, "w", encoding="utf-8") as f:
-                f.write(str(tier))
-        except OSError:
-            pass
+        write_state(state_file, {**state, "tier": tier, "stop_tier": min(state["stop_tier"], tier)})
 
     if tier <= prev_tier:
-        return  # already warned at this tier (or context shrank — state re-armed above)
+        # 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, budget < window, auto_mode
+        profile, tier, tokens, budget, priced, auto_mode
     )
-
-    if not profile["emits_system_message"]:
-        additional_context = f"{additional_context}\n\nTell the user: {system_message}"
-
-    payload = {
-        "hookSpecificOutput": {
-            "hookEventName": "UserPromptSubmit",
-            "additionalContext": additional_context,
-        }
-    }
     if profile["emits_system_message"]:
-        payload["systemMessage"] = system_message
-        payload["suppressOutput"] = True
-
-    print(json.dumps(payload))
+        emit(event, additional_context, system_message)
+    else:
+        emit(event, f"{additional_context}\n\nTell the user: {system_message}")
 
 
 if __name__ == "__main__":