subtask-mcp 0.2.7__tar.gz → 0.2.9__tar.gz

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subtask-mcp
-Version: 0.2.7
+Version: 0.2.9
 Summary: Background sub-agents for Claude Code, Codex, Kimi and OpenCode, over MCP or CLI, with a spend cap
 License: MIT
 Project-URL: Homepage, https://github.com/tedin7/subtask
@@ -70,7 +70,7 @@ The distribution is `subtask-mcp` (the PyPI name `subtask` is an unrelated
 project). Full guide, per client, with native commands: [docs/install.md](docs/install.md).
 
 ```sh
-uv tool install "git+https://github.com/tedin7/subtask@v0.2.7"   # or: uv tool install /path/to/checkout
+uv tool install "git+https://github.com/tedin7/subtask@v0.2.9"   # or: uv tool install /path/to/checkout
 subtask install --client all          # prints the plan for every detected client
 subtask install --client all --yes    # applies it: MCP server + skill
 subtask doctor --client all           # checks app, config entry and a real handshake

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/README.md

@@ -39,7 +39,7 @@ The distribution is `subtask-mcp` (the PyPI name `subtask` is an unrelated
 project). Full guide, per client, with native commands: [docs/install.md](docs/install.md).
 
 ```sh
-uv tool install "git+https://github.com/tedin7/subtask@v0.2.7"   # or: uv tool install /path/to/checkout
+uv tool install "git+https://github.com/tedin7/subtask@v0.2.9"   # or: uv tool install /path/to/checkout
 subtask install --client all          # prints the plan for every detected client
 subtask install --client all --yes    # applies it: MCP server + skill
 subtask doctor --client all           # checks app, config entry and a real handshake

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/subtask/__init__.py

@@ -1,3 +1,3 @@
 """subtask: background sub-agents for coding agents."""
 
-__version__ = "0.2.7"
+__version__ = "0.2.9"

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/subtask/cli.py

@@ -65,6 +65,9 @@ def main() -> int:
     sp.add_argument("--how", required=True)
     sp.add_argument("--decision", action="append", dest="decisions")
     sub.add_parser("steps")
+    sub.add_parser(
+        "narrate-hook", help="Claude Code PreToolUse hook: automatic step announcement (reads JSON on stdin)"
+    )
     sub.add_parser("spend")
     sub.add_parser("engines")
     install_commands.add_parsers(sub)
@@ -83,6 +86,10 @@ def main() -> int:
     wa.add_argument("--interval", type=float, default=2.0)
     a = p.parse_args()
 
+    if a.cmd == "narrate-hook":
+        from . import stephook
+
+        return stephook.main()
     if a.cmd in ("install", "uninstall") or (a.cmd == "doctor" and a.client):
         return install_commands.run(a)
 

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/subtask/core.py

@@ -306,7 +306,12 @@ def _delta(job_ids: list[str], since: str) -> tuple[str, str]:
 
 
 def wait(
-    job_ids: list[str], timeout: int = 50, any_: bool = False, results: bool = True, since: str | None = None
+    job_ids: list[str],
+    timeout: int = 50,
+    any_: bool = False,
+    results: bool = True,
+    since: str | None = None,
+    count: bool = True,
 ) -> str:
     """Block until all jobs end (or the first one, with any_), or timeout.
 
@@ -320,7 +325,8 @@ def wait(
     unknown = [j for j in job_ids if not known(j)]
     if unknown:
         return "unknown job: " + ", ".join(unknown)
-    telemetry.count_call(job_ids, "wait")
+    if count:  # servers poll wait() every second inside one tool call: count that call once
+        telemetry.count_call(job_ids, "wait")
     deadline = time.time() + max(0, min(timeout, 600))
     while True:
         ended = [j for j in job_ids if jobs.status(j).get("state") in jobs.FINAL]
@@ -590,6 +596,7 @@ def step(
         out = f"STEP: {entry['title']}\n{explained}"
         entry["narrator"] = "model"
     entry["announcement"] = out
+    entry["epoch"] = time.time()
     config.HOME.mkdir(parents=True, exist_ok=True)
     with STEPS.open("a", encoding="utf-8") as fh:
         fh.write(json.dumps(entry, ensure_ascii=False) + "\n")

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/subtask/fastserver.py

@@ -89,8 +89,10 @@ def _wait(
             if core.known(job_id):
                 call.reporter.add(job_id)
         call.reporter.poll()
+    first = True
     while True:
-        out = core.wait(ids, 0, any, since=since)
+        out = core.wait(ids, 0, any, since=since, count=first)
+        first = False
         if not out.startswith("still running") or time.monotonic() >= deadline:
             if call.reporter:
                 call.reporter.poll()

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/subtask/narrate.py

@@ -81,7 +81,7 @@ def observed_activity(repo: str, limit: int = 5) -> str:
     return "\n".join(lines)
 
 
-def _call(spec: tuple[str, float, float], system: str, user: str) -> str:
+def _call(spec: tuple[str, float, float], system: str, user: str, timeout: float = 60) -> str:
     """One Messages API call, booked in the ledger. Raises on any failure."""
     model, price_in, price_out = spec
     secrets = config.load_secrets()
@@ -112,7 +112,7 @@ def _call(spec: tuple[str, float, float], system: str, user: str) -> str:
         req = urllib.request.Request(
             "https://api.anthropic.com/v1/messages", data=json.dumps(body).encode(), headers=headers
         )
-        with urllib.request.urlopen(req, timeout=60) as resp:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
             data = json.load(resp)
         usage = data.get("usage", {})
         cost = (usage.get("input_tokens", 0) * price_in + usage.get("output_tokens", 0) * price_out) / 1e6

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/subtask/server.py

@@ -16,7 +16,7 @@ from . import core
 mcp = FastMCP(
     "subtask",
     instructions=(
-        "Background sub-agents for parallel, long or review work; small edits do yourself. "
+        "Delegate long work to cheap engines; do small things yourself (measured: small tasks cost 2-3x). "
         "Pattern: ONE start_many([...]) with every job, then ONE wait(ids): it blocks and returns "
         "the summaries. Never poll status(); call wait() again only if it said 'still running'. "
         "result(id, full/evidence) only when the summary is not enough. "
@@ -77,12 +77,14 @@ async def wait(
 
         reporter = Reporter(send, [i for i in ids if core.known(i)])
     deadline = loop.time() + max(1, min(timeout, 600))
+    first = True
     while True:
         if reporter:
             reporter.poll()
             while pending:
                 await pending.pop(0)  # never after the result: progress stops at completion
-        out = core.wait(ids, 0, any, since=since)
+        out = core.wait(ids, 0, any, since=since, count=first)
+        first = False
         if not out.startswith("still running") or loop.time() >= deadline:
             return out
         await asyncio.sleep(1)

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/subtask/skill/SKILL.md

@@ -17,6 +17,12 @@ Delegate when one of these is true:
 - complex code needs a reviewer who did not write it (concurrency, saved data
   or migrations, security, money, logic shared by many callers).
 
+Measured (docs/benchmark.md): on small tasks delegating cost 2-3x the money
+and time for the same result; on long, many-step pieces given to cheaper
+engines (haiku-api, opencode-go, kimi) it cost 38-57 % less with about half
+the parent context, but took 2-8x longer. So: delegate long work to cheap
+engines; do small things yourself.
+
 Do NOT delegate when:
 - the change is small (a few lines, one file) or you already know the fix;
 - it needs what is in your context right now (a decision you just made with
@@ -73,6 +79,12 @@ Do NOT delegate when:
 
 ## Announce every significant step
 
+With the Claude Code plugin installed, a hook announces steps automatically
+before file changes and commits (at most every 20 minutes per repository),
+shown only to the user: you spend no turn on it. Call `step` yourself only for
+a decision that is not a file change (a choice of approach, a release).
+
+
 Before each significant step (new phase, choice of approach, a change with
 risk, a merge or release) call `step(title, path, how, decisions)` and show
 the returned text to the user verbatim. A separate cheap model reads your

subtask_mcp-0.2.9/subtask/stephook.py

@@ -0,0 +1,180 @@
+"""Automatic step announcements from a Claude Code PreToolUse hook, without the agent.
+
+The agent does not have to call step(): before a file change or a commit, the hook
+reads three facts and has the cheap narrator explain them to the user:
+
+- the user's latest request (the "why"), from the session transcript;
+- what the agent did so far (files read, commands run), from the transcript;
+- the exact change about to happen (Edit/Write content, or the git command).
+
+The explanation is returned as a hook `systemMessage`: shown to the user in the chat,
+never sent to the agent, so the agent spends no turn and no token. At most once per
+SUBTASK_STEP_EVERY_MIN minutes (default 20) per repository; a manual step() also counts.
+Any failure lets the tool call through silently (logged in steps.jsonl).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+EVERY_S = float(os.environ.get("SUBTASK_STEP_EVERY_MIN", "20")) * 60
+TIMEOUT_S = float(os.environ.get("SUBTASK_STEP_HOOK_TIMEOUT_S", "10"))
+EDIT_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+MAX_CHANGE = 2500
+SYSTEM = (
+    "You are an independent observer of a coding agent. You did not plan its work. "
+    "From the facts below, explain to the operator, who is smart but not technical, what is about "
+    "to happen and why: what the user asked, what the agent has done so far, what this change "
+    "does. Short sentences, plain words, no em dashes, at most 5 bullets. Base every statement on "
+    "the facts given; if the reason for the change is not clear from them, say so. If the change "
+    "does not fit the user's request, say it first. Write in this language: {lang}."
+)
+
+
+def _text(content: object) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return " ".join(b.get("text", "") for b in content if isinstance(b, dict) and b.get("type") == "text")
+    return ""
+
+
+def read_transcript(path: str | None, max_bytes: int = 400_000) -> tuple[str, list[str]]:
+    """(last user request, recent agent actions) from a Claude Code session transcript."""
+    if not path or not Path(path).is_file():
+        return "", []
+    with open(path, "rb") as fh:
+        fh.seek(0, 2)
+        fh.seek(max(0, fh.tell() - max_bytes))
+        lines = fh.read().decode("utf-8", errors="replace").splitlines()
+    request, actions = "", []
+    for line in lines:
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        msg = row.get("message") if isinstance(row, dict) else None
+        if not isinstance(msg, dict):
+            continue
+        content = msg.get("content")
+        if row.get("type") == "user":
+            is_tool_result = isinstance(content, list) and any(
+                isinstance(b, dict) and b.get("type") == "tool_result" for b in content
+            )
+            text = _text(content).strip()
+            if text and not is_tool_result and not text.startswith("<"):
+                request, actions = text, []  # a new request starts a new chain of actions
+        elif row.get("type") == "assistant" and isinstance(content, list):
+            for b in content:
+                if isinstance(b, dict) and b.get("type") == "tool_use":
+                    actions.append(_action(b.get("name", ""), b.get("input") or {}))
+    return request[-2000:], [a for a in actions if a][-12:]
+
+
+def _action(name: str, args: dict) -> str:
+    target = args.get("file_path") or args.get("path") or args.get("pattern") or args.get("command") or ""
+    return f"{name} {str(target)[:120]}".strip()
+
+
+def describe_change(tool: str, args: dict) -> str | None:
+    if tool in EDIT_TOOLS:
+        path = args.get("file_path") or args.get("notebook_path") or "?"
+        if tool == "Write":
+            body = f"new content:\n{str(args.get('content', ''))[:MAX_CHANGE]}"
+        elif tool == "MultiEdit":
+            parts = [
+                f"- {e.get('old_string', '')[:300]}\n+ {e.get('new_string', '')[:300]}"
+                for e in args.get("edits", [])
+            ]
+            body = "\n".join(parts)[:MAX_CHANGE]
+        else:
+            body = f"- {str(args.get('old_string', ''))[: MAX_CHANGE // 2]}\n+ {str(args.get('new_string', ''))[: MAX_CHANGE // 2]}"
+        return f"{tool} {path}\n{body}"
+    if tool == "Bash":
+        cmd = str(args.get("command", ""))
+        if "git commit" in cmd or "git merge" in cmd or "git push" in cmd:
+            return f"Bash: {cmd[:MAX_CHANGE]}"
+    return None
+
+
+def _recent(repo: str) -> bool:
+    from .core import STEPS
+
+    if not STEPS.is_file():
+        return False
+    with STEPS.open("rb") as fh:
+        fh.seek(0, 2)
+        fh.seek(max(0, fh.tell() - 200_000))
+        lines = fh.read().decode("utf-8", errors="replace").splitlines()
+    now = time.time()
+    for line in reversed(lines):
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if row.get("repo") != repo:
+            continue
+        ts = row.get("epoch") or time.mktime(time.strptime(row["ts"], "%Y-%m-%d %H:%M:%S"))
+        return now - float(ts) < EVERY_S
+    return False
+
+
+def _log(entry: dict) -> None:
+    from . import config
+    from .core import STEPS
+
+    config.HOME.mkdir(parents=True, exist_ok=True)
+    with STEPS.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+
+def handle(event: dict) -> dict | None:
+    """The hook's JSON answer, or None to stay silent."""
+    from . import narrate
+    from .core import _repo_of
+    from .redact import redact
+
+    change = describe_change(str(event.get("tool_name", "")), event.get("tool_input") or {})
+    if not change:
+        return None
+    args = event.get("tool_input") or {}
+    path = args.get("file_path") or args.get("notebook_path") or event.get("cwd") or os.getcwd()
+    repo = _repo_of(str(path)) or _repo_of(str(event.get("cwd") or "")) or str(event.get("cwd") or "")
+    if not repo or _recent(repo):
+        return None
+    request, actions = read_transcript(event.get("transcript_path"))
+    facts = (
+        f"User's latest request:\n{request or '(not found)'}\n\n"
+        f"Agent's recent actions:\n" + ("\n".join(actions) or "(none recorded)") + "\n\n"
+        f"Change about to happen:\n{change}\n\nRepository state:\n{narrate.repo_context(repo)}"
+    )
+    lang = os.environ.get("SUBTASK_STEP_LANG", "Italian")
+    entry = {"ts": time.strftime("%Y-%m-%d %H:%M:%S"), "epoch": time.time(), "repo": repo, "source": "hook",
+             "title": change.splitlines()[0][:100], "path": str(path), "how": "automatic (PreToolUse hook)"}  # fmt: skip
+    t0 = time.monotonic()
+    try:
+        text = narrate._call(narrate.EXPLAINER, SYSTEM.format(lang=lang), redact(facts), timeout=TIMEOUT_S)
+    except Exception as exc:  # noqa: BLE001 - the work must never be blocked by the narrator
+        _log({**entry, "narrator": "failed", "error": f"{type(exc).__name__}: {exc}"[:200]})
+        return None
+    entry.update(narrator="model", narrator_ms=round((time.monotonic() - t0) * 1000), announcement=text)
+    _log(entry)
+    return {"systemMessage": f"STEP · {Path(repo).name}\n{text}", "suppressOutput": True}
+
+
+def main() -> int:
+    try:
+        event = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+    try:
+        answer = handle(event) if isinstance(event, dict) else None
+    except Exception:  # noqa: BLE001 - a hook must exit 0 so the tool call proceeds
+        answer = None
+    if answer:
+        print(json.dumps(answer, ensure_ascii=False))
+    return 0

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/subtask/tools.json

@@ -1,5 +1,5 @@
 {
- "instructions": "Background sub-agents for parallel, long or review work; small edits do yourself. Pattern: ONE start_many([...]) with every job, then ONE wait(ids): it blocks and returns the summaries. Never poll status(); call wait() again only if it said 'still running'. result(id, full/evidence) only when the summary is not enough. Call step() before each significant step.",
+ "instructions": "Delegate long work to cheap engines; do small things yourself (measured: small tasks cost 2-3x). Pattern: ONE start_many([...]) with every job, then ONE wait(ids): it blocks and returns the summaries. Never poll status(); call wait() again only if it said 'still running'. result(id, full/evidence) only when the summary is not enough. Call step() before each significant step.",
  "tools": [
   {
    "name": "start",

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/subtask_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subtask-mcp
-Version: 0.2.7
+Version: 0.2.9
 Summary: Background sub-agents for Claude Code, Codex, Kimi and OpenCode, over MCP or CLI, with a spend cap
 License: MIT
 Project-URL: Homepage, https://github.com/tedin7/subtask
@@ -70,7 +70,7 @@ The distribution is `subtask-mcp` (the PyPI name `subtask` is an unrelated
 project). Full guide, per client, with native commands: [docs/install.md](docs/install.md).
 
 ```sh
-uv tool install "git+https://github.com/tedin7/subtask@v0.2.7"   # or: uv tool install /path/to/checkout
+uv tool install "git+https://github.com/tedin7/subtask@v0.2.9"   # or: uv tool install /path/to/checkout
 subtask install --client all          # prints the plan for every detected client
 subtask install --client all --yes    # applies it: MCP server + skill
 subtask doctor --client all           # checks app, config entry and a real handshake

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/subtask_mcp.egg-info/SOURCES.txt

@@ -24,6 +24,7 @@ subtask/router.py
 subtask/runners.py
 subtask/schemacheck.py
 subtask/server.py
+subtask/stephook.py
 subtask/telemetry.py
 subtask/tools.json
 subtask/worker.py
@@ -57,8 +58,10 @@ tests/test_engines.py
 tests/test_falsify.py
 tests/test_independent_client.py
 tests/test_install.py
+tests/test_live.py
 tests/test_protocol.py
 tests/test_routing_results.py
 tests/test_schema.py
 tests/test_security.py
+tests/test_stephook.py
 tests/test_subtask.py

subtask_mcp-0.2.9/tests/test_live.py

@@ -0,0 +1,76 @@
+"""Live adapter checks: one tiny real job per engine, through subtask itself.
+
+Marked `live`: skipped by default (pytest.ini addopts "-m 'not live'"). Run with
+`pytest -m live` when spending is authorized. Each job is capped at 0.20 USD
+(paid engines) and asks for one shell command and a one-word answer, so the
+contract with the real CLI/SDK is exercised: argv accepted, events parsed,
+session id found, result written, cost booked.
+Engines that are not installed or not logged in are skipped, never faked.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.live
+
+TASK = "Run the shell command `echo subtask-live-ok` once, then answer with exactly that output."
+ENGINES = ["haiku-api", "opencode-go", "kimi", "codex"]
+
+
+def _cli(home: Path, *args: str, timeout: float = 300) -> str:
+    env = {**os.environ, "SUBTASK_HOME": str(home), "SUBTASK_MAX_RUNNING": "4"}
+    done = subprocess.run([sys.executable, "-m", "subtask.cli", *args], env=env, capture_output=True,
+                          text=True, timeout=timeout, check=False)  # fmt: skip
+    return done.stdout + done.stderr
+
+
+def _available(engine: str) -> str | None:
+    from subtask import config
+    from subtask.engines import registry
+
+    adapter = registry.get(engine)
+    if adapter is None or not adapter.available():
+        return f"{engine} not installed"
+    if (
+        adapter.capabilities.paid
+        and engine.endswith("-api")
+        and not config.load_secrets().get("ANTHROPIC_API_KEY")
+    ):
+        return "no ANTHROPIC_API_KEY in the subtask env file"
+    cap = adapter.capacity()
+    if cap.value is not None and cap.value < 10:
+        return f"{engine} has no quota left ({cap.note})"
+    return None
+
+
+@pytest.mark.parametrize("engine", ENGINES)
+def test_engine_runs_a_tiny_real_job(engine, tmp_path):
+    reason = _available(engine)
+    if reason:
+        pytest.skip(reason)
+    if shutil.which("git") is None:
+        pytest.skip("git missing")
+    work = tmp_path / "work"
+    work.mkdir()
+    out = _cli(tmp_path / "home", "start", TASK, "--engine", engine, "--cwd", str(work), "--max-usd", "0.2",
+               "--max-turns", "6", "--effort", "low")  # fmt: skip
+    assert " started " in out, out
+    job = out.split()[0]
+    t0 = time.time()
+    final = _cli(tmp_path / "home", "wait", job, "--timeout", "280")
+    assert " done " in final, final
+    env = json.loads(_cli(tmp_path / "home", "result", job, "--evidence"))
+    assert "subtask-live-ok" in env["summary"]["text"], env["summary"]
+    assert env["commands"]["seen"] >= 1, "no shell command observed: event format changed?"
+    if env["cost"]["reserved"] is not None:
+        assert 0 <= (env["cost"]["charged_total"] or 0) <= 0.2
+    assert time.time() - t0 < 300

{subtask_mcp-0.2.7 → subtask_mcp-0.2.9}/tests/test_protocol.py

@@ -262,3 +262,19 @@ def test_reporter_follows_the_latest_change_and_admits_missing_detail(home):
     assert rep._what(b) == progress.NO_DETAIL  # kimi plain output: no structured activity
     core.stop(a)
     core.stop(b)
+
+
+def test_a_long_wait_counts_as_one_round_trip(home):
+    """The server polls core.wait every second; that is not a parent round trip."""
+    from subtask import telemetry
+
+    fake_cli(home, "kimi", "sleep 4; echo done")
+    c = Client(_env())
+    c.send({"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+            "params": {"name": "start", "arguments": {"task": "x", "engine": "kimi", "cwd": str(home)}}})  # fmt: skip
+    job = c.until(1)[0]["result"]["content"][0]["text"].split()[0]
+    c.send({"jsonrpc": "2.0", "id": 2, "method": "tools/call",
+            "params": {"name": "wait", "arguments": {"ids": [job], "timeout": 30}}})  # fmt: skip
+    c.until(2, timeout=40)
+    c.close()
+    assert [x["tool"] for x in telemetry.calls(job)].count("wait") == 1

subtask_mcp-0.2.9/tests/test_stephook.py

@@ -0,0 +1,89 @@
+"""Automatic step announcements from the PreToolUse hook: facts in, user-only message out."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+
+
+def _transcript(tmp_path):
+    rows = [
+        {"type": "user", "message": {"role": "user", "content": "rendi più veloce il conteggio dei job"}},
+        {"type": "assistant", "message": {"content": [
+            {"type": "tool_use", "name": "Read", "input": {"file_path": "/r/subtask/admission.py"}},
+            {"type": "tool_use", "name": "Bash", "input": {"command": "pytest -q tests/test_x.py"}}]}},
+        {"type": "user", "message": {"role": "user", "content": [{"type": "tool_result", "content": "ok"}]}},
+    ]  # fmt: skip
+    path = tmp_path / "t.jsonl"
+    path.write_text("\n".join(json.dumps(r) for r in rows))
+    return path
+
+
+def _repo(tmp_path):
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    subprocess.run(["git", "init", "-q", str(repo)], check=True)
+    return repo
+
+
+def test_transcript_gives_request_and_actions_not_tool_results(tmp_path):
+    from subtask import stephook
+
+    request, actions = stephook.read_transcript(str(_transcript(tmp_path)))
+    assert request == "rendi più veloce il conteggio dei job"
+    assert actions == ["Read /r/subtask/admission.py", "Bash pytest -q tests/test_x.py"]
+
+
+def test_only_changes_and_commits_are_announced():
+    from subtask import stephook
+
+    assert stephook.describe_change("Read", {"file_path": "x"}) is None
+    assert stephook.describe_change("Bash", {"command": "ls"}) is None
+    assert "git commit" in stephook.describe_change("Bash", {"command": "git commit -m x"})
+    edit = stephook.describe_change("Edit", {"file_path": "/a.py", "old_string": "a", "new_string": "b"})
+    assert edit.startswith("Edit /a.py") and "- a" in edit and "+ b" in edit
+
+
+def test_hook_shows_the_explanation_to_the_user_once_per_window(home, tmp_path, monkeypatch):
+    from subtask import narrate, stephook
+
+    seen = {}
+
+    def fake_call(spec, system, user, timeout=60):
+        seen["user"] = user
+        return "- Hai chiesto un conteggio più veloce.\n- L'agente cambia admission.py."
+
+    monkeypatch.setattr(narrate, "_call", fake_call)
+    repo = _repo(tmp_path)
+    event = {"tool_name": "Edit", "tool_input": {"file_path": str(repo / "a.py"), "old_string": "x", "new_string": "y"},
+             "transcript_path": str(_transcript(tmp_path)), "cwd": str(repo)}  # fmt: skip
+    out = stephook.handle(event)
+    assert out["systemMessage"].startswith("STEP · repo") and "conteggio" in out["systemMessage"]
+    assert "rendi più veloce" in seen["user"] and "+ y" in seen["user"]
+    assert stephook.handle(event) is None  # inside the 20-minute window: silent, no second call
+
+
+def test_narrator_failure_never_blocks_and_is_logged(home, tmp_path, monkeypatch):
+    from subtask import core, narrate, stephook
+
+    monkeypatch.setattr(narrate, "_call", lambda *a, **k: (_ for _ in ()).throw(TimeoutError("slow")))
+    repo = _repo(tmp_path)
+    event = {
+        "tool_name": "Write",
+        "tool_input": {"file_path": str(repo / "b.py"), "content": "z"},
+        "cwd": str(repo),
+    }
+    assert stephook.handle(event) is None
+    assert '"narrator": "failed"' in core.STEPS.read_text()
+
+
+def test_cli_hook_exits_zero_and_prints_json_only(home, tmp_path):
+    repo = _repo(tmp_path)
+    event = {"tool_name": "Read", "tool_input": {"file_path": str(repo / "a.py")}, "cwd": str(repo)}
+    done = subprocess.run([sys.executable, "-m", "subtask.cli", "narrate-hook"], input=json.dumps(event),
+                          capture_output=True, text=True, timeout=30, check=False)  # fmt: skip
+    assert done.returncode == 0 and done.stdout == ""
+    bad = subprocess.run([sys.executable, "-m", "subtask.cli", "narrate-hook"], input="not json",
+                         capture_output=True, text=True, timeout=30, check=False)  # fmt: skip
+    assert bad.returncode == 0