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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: subtask-mcp
-Version: 0.2.8
+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.8"   # 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.8 → 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.8"   # 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.8 → subtask_mcp-0.2.9}/subtask/__init__.py

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

{subtask_mcp-0.2.8 → 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.8 → subtask_mcp-0.2.9}/subtask/core.py

@@ -596,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.8 → 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.8 → 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. "

{subtask_mcp-0.2.8 → 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.8 → 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.8 → 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.8
+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.8"   # 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.8 → 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
@@ -62,4 +63,5 @@ 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_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