threadkeeper 0.17.5__tar.gz → 0.17.7__tar.gz

{threadkeeper-0.17.5 → threadkeeper-0.17.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.17.5
+Version: 0.17.7
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT
@@ -137,6 +137,9 @@ config, copies hooks to
 each CLI's per-user instructions file (`CLAUDE.md` / `AGENTS.md` /
 `copilot-instructions.md` — Claude Desktop and VS Code
 have no global instructions file, so that step is skipped for them).
+The generated MCP entry pins imports to this configured installation, so an
+agent launched inside another thread-keeper checkout cannot load that checkout's
+unmerged code against the live memory database.
 
 Restart your CLI of choice. Hook-capable clients inject a brief on the first
 message; hookless clients such as Codex and Antigravity CLI either follow the
@@ -217,7 +220,7 @@ read/act split, plus MCP elicitation for host-native confirmations:
 
 | Primitive | Control | What thread-keeper exposes | When to use |
 |---|---|---|---|
-| **Tools** | model-controlled (may act) | the full surface — `brief`, `note`, `spawn`, `search`, `curator_review`, … | the agent decides to call them |
+| **Tools** | model-controlled (may act) | the full surface — `brief`, `note`, `spawn`, `search`, `curator_review`, `wikilink_health`, … | the agent decides to call them |
 | **Resources** | application-controlled, read-only | `memory://brief`, `memory://context`, `memory://dashboard`, `memory://agent-status` | the **host** attaches/pulls them automatically |
 | **Prompts** | user-controlled templates | `review_recent_threads`, `run_library_curation`, `audit_threadkeeper` | the user runs them (Claude Code: `/mcp__thread-keeper__<name>`) |
 
@@ -351,7 +354,10 @@ repair partial work, and continue rather than restart blindly.
 `THREADKEEPER_SPAWN_TIMEOUT_RETRY_LIMIT` (default 3; 0 disables) bounds the
 retry chain, with `THREADKEEPER_SPAWN_TIMEOUT_RETRY_DELAY_S` available for a
 non-zero delay. Timed-out children are surfaced as `tasks_timed_out` in
-`mp_dashboard` and `timed_out` in `agent_status`.
+`mp_dashboard` and `timed_out` in `agent_status`. `agent_status` and
+`tk-agent-status` are observation-only and never terminate or respawn a
+child; timeout enforcement and the continuation retry live solely in the
+spawn-budget daemon.
 
 `tk-agent-status` exposes autonomous learning loop status as structured JSON
 or compact text for external monitors:
@@ -614,6 +620,11 @@ routed to the incumbent lesson or surfaced for curation instead of minting a
 sibling lesson. A clear new directive or debunk also flags older permissive
 lessons on the same concrete practice for patch, cross-link, or supersession
 review.
+Before a genuinely new fallback lesson is written,
+`lesson_neighbors(title, body, summary, k=3)` shows the nearest existing lesson
+slugs (semantic, with a lexical fallback). Shadow and candidate reviewers use
+that preflight to patch/consolidate an incumbent or add a `[[slug]]` cross-link
+to a related, distinct lesson while its body is still editable.
 
 #### 3. Extract daemon
 
@@ -718,6 +729,14 @@ non-forced direct `curator_review()` calls return `not_due` inside the
 configured interval and record that status without spawning. A manual
 `curator_review(force=True)` bypasses the interval but still respects the lock.
 
+When a Curator reviews a lesson pair and deliberately keeps both, it records a
+structured `keep_both` merge verdict with the two slugs and a short reason.
+Later inventories show those prior verdicts and each lesson's current
+bidirectional `[[wikilink]]` adjacency (`links=[...]`), including for the
+relevant side of a multi-batch review. This preserves intentional
+general/specific and prevention/recovery layering without making a child
+re-read both lesson bodies to rediscover it.
+
 For automation-created skills, the audit keeps foreground consultation separate
 from maintenance: a background-review skill with `fg_uses=0` after 14 days is
 still a false-positive prune candidate even if automatic review or sync loops
@@ -852,10 +871,16 @@ runs as **two alternating phases**, never co-granting web research and
 shell/`bypassPermissions` to the same child:
 
 - **research phase** — a read-only child with `WebSearch`/`WebFetch` and
-  read-only repo reads but **no shell, no `bypassPermissions`, and no GitHub
-  access**. It distills external findings into a digest file under
-  `~/.threadkeeper/evolve-research/`. With no `Bash`/`gh`/network-write tool it
-  has no exfiltration channel, so the untrusted pages it reads cannot act.
+  read-only repo reads but **no shell, no generic `Write`, no
+  `bypassPermissions`, and no GitHub access**. Before dispatch, the parent
+  registers one pass ID, owner child, and digest target. The child can submit
+  only that pass through `evolve_research_handoff(...)`; it cannot choose a
+  path. The handoff is one-shot, capped at 12,000 characters / 400 lines,
+  atomically persisted with a SHA-256, and records rejected, failed, expired,
+  and tampered outcomes in Evolve telemetry. The later audit reads only a
+  fresh accepted handoff whose final file still matches that hash. With no
+  `Bash`/`gh`/network-write tool it has no exfiltration channel, so the
+  untrusted pages it reads cannot act.
 - **audit phase** — the privileged child (`bypassPermissions` + `Bash`/`Edit`/
   `Write`) that audits the repo, opens the `docs/ROADMAP.md` PR, and creates or
   updates GitHub issues. It holds **no web tools**; it consumes the research

{threadkeeper-0.17.5 → threadkeeper-0.17.7}/README.md

@@ -93,6 +93,9 @@ config, copies hooks to
 each CLI's per-user instructions file (`CLAUDE.md` / `AGENTS.md` /
 `copilot-instructions.md` — Claude Desktop and VS Code
 have no global instructions file, so that step is skipped for them).
+The generated MCP entry pins imports to this configured installation, so an
+agent launched inside another thread-keeper checkout cannot load that checkout's
+unmerged code against the live memory database.
 
 Restart your CLI of choice. Hook-capable clients inject a brief on the first
 message; hookless clients such as Codex and Antigravity CLI either follow the
@@ -173,7 +176,7 @@ read/act split, plus MCP elicitation for host-native confirmations:
 
 | Primitive | Control | What thread-keeper exposes | When to use |
 |---|---|---|---|
-| **Tools** | model-controlled (may act) | the full surface — `brief`, `note`, `spawn`, `search`, `curator_review`, … | the agent decides to call them |
+| **Tools** | model-controlled (may act) | the full surface — `brief`, `note`, `spawn`, `search`, `curator_review`, `wikilink_health`, … | the agent decides to call them |
 | **Resources** | application-controlled, read-only | `memory://brief`, `memory://context`, `memory://dashboard`, `memory://agent-status` | the **host** attaches/pulls them automatically |
 | **Prompts** | user-controlled templates | `review_recent_threads`, `run_library_curation`, `audit_threadkeeper` | the user runs them (Claude Code: `/mcp__thread-keeper__<name>`) |
 
@@ -307,7 +310,10 @@ repair partial work, and continue rather than restart blindly.
 `THREADKEEPER_SPAWN_TIMEOUT_RETRY_LIMIT` (default 3; 0 disables) bounds the
 retry chain, with `THREADKEEPER_SPAWN_TIMEOUT_RETRY_DELAY_S` available for a
 non-zero delay. Timed-out children are surfaced as `tasks_timed_out` in
-`mp_dashboard` and `timed_out` in `agent_status`.
+`mp_dashboard` and `timed_out` in `agent_status`. `agent_status` and
+`tk-agent-status` are observation-only and never terminate or respawn a
+child; timeout enforcement and the continuation retry live solely in the
+spawn-budget daemon.
 
 `tk-agent-status` exposes autonomous learning loop status as structured JSON
 or compact text for external monitors:
@@ -570,6 +576,11 @@ routed to the incumbent lesson or surfaced for curation instead of minting a
 sibling lesson. A clear new directive or debunk also flags older permissive
 lessons on the same concrete practice for patch, cross-link, or supersession
 review.
+Before a genuinely new fallback lesson is written,
+`lesson_neighbors(title, body, summary, k=3)` shows the nearest existing lesson
+slugs (semantic, with a lexical fallback). Shadow and candidate reviewers use
+that preflight to patch/consolidate an incumbent or add a `[[slug]]` cross-link
+to a related, distinct lesson while its body is still editable.
 
 #### 3. Extract daemon
 
@@ -674,6 +685,14 @@ non-forced direct `curator_review()` calls return `not_due` inside the
 configured interval and record that status without spawning. A manual
 `curator_review(force=True)` bypasses the interval but still respects the lock.
 
+When a Curator reviews a lesson pair and deliberately keeps both, it records a
+structured `keep_both` merge verdict with the two slugs and a short reason.
+Later inventories show those prior verdicts and each lesson's current
+bidirectional `[[wikilink]]` adjacency (`links=[...]`), including for the
+relevant side of a multi-batch review. This preserves intentional
+general/specific and prevention/recovery layering without making a child
+re-read both lesson bodies to rediscover it.
+
 For automation-created skills, the audit keeps foreground consultation separate
 from maintenance: a background-review skill with `fg_uses=0` after 14 days is
 still a false-positive prune candidate even if automatic review or sync loops
@@ -808,10 +827,16 @@ runs as **two alternating phases**, never co-granting web research and
 shell/`bypassPermissions` to the same child:
 
 - **research phase** — a read-only child with `WebSearch`/`WebFetch` and
-  read-only repo reads but **no shell, no `bypassPermissions`, and no GitHub
-  access**. It distills external findings into a digest file under
-  `~/.threadkeeper/evolve-research/`. With no `Bash`/`gh`/network-write tool it
-  has no exfiltration channel, so the untrusted pages it reads cannot act.
+  read-only repo reads but **no shell, no generic `Write`, no
+  `bypassPermissions`, and no GitHub access**. Before dispatch, the parent
+  registers one pass ID, owner child, and digest target. The child can submit
+  only that pass through `evolve_research_handoff(...)`; it cannot choose a
+  path. The handoff is one-shot, capped at 12,000 characters / 400 lines,
+  atomically persisted with a SHA-256, and records rejected, failed, expired,
+  and tampered outcomes in Evolve telemetry. The later audit reads only a
+  fresh accepted handoff whose final file still matches that hash. With no
+  `Bash`/`gh`/network-write tool it has no exfiltration channel, so the
+  untrusted pages it reads cannot act.
 - **audit phase** — the privileged child (`bypassPermissions` + `Bash`/`Edit`/
   `Write`) that audits the repo, opens the `docs/ROADMAP.md` PR, and creates or
   updates GitHub issues. It holds **no web tools**; it consumes the research

{threadkeeper-0.17.5 → threadkeeper-0.17.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadkeeper"
-version = "0.17.5"
+version = "0.17.7"
 description = "Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server."
 requires-python = ">=3.11"
 authors = [{ name = "thread-keeper contributors" }]

{threadkeeper-0.17.5 → threadkeeper-0.17.7}/tests/test_adapters.py

@@ -383,6 +383,7 @@ def test_codex_spawn_argv_skips_git_repo_check(tmp_path, monkeypatch):
     assert argv[:3] == ["/usr/local/bin/codex", "exec", "--skip-git-repo-check"]
     assert argv[-1] == "-"
     assert "-m" in argv and "gpt-5.5" in argv
+    assert 'mcp_servers.thread-keeper.env.PYTHONSAFEPATH="1"' in argv
     # Default (non-bypass) path still sandboxes.
     assert "--sandbox" in argv and "workspace-write" in argv
 

{threadkeeper-0.17.5 → threadkeeper-0.17.7}/tests/test_agent_status.py

@@ -784,3 +784,42 @@ def test_recent_failures_notify_flag_off_when_toggle_disabled(
     fails = {f["task_id"]: f for f in snap["recent_failures"]}
     assert "deadchild2" in fails                 # still listed in the menu
     assert fails["deadchild2"]["notify"] is False  # but no banner posted
+
+
+def test_agent_status_tool_default_read_does_not_enforce_lifecycle(
+    fresh_mp, monkeypatch
+):
+    pkg = fresh_mp
+    _insert_task(pkg, "tk_overdue", "Build a compact menu-bar status app.")
+    conn = pkg["db"].get_db()
+    conn.execute(
+        "UPDATE tasks SET started_at=? WHERE id=?",
+        (int(time.time()) - 10000, "tk_overdue"),
+    )
+    conn.commit()
+
+    import threadkeeper.spawn_budget as sb
+
+    reap_calls: list = []
+    respawn_calls: list = []
+    monkeypatch.setattr(
+        sb, "_reap_timed_out",
+        lambda conn, row, now: reap_calls.append(row["id"]) or True,
+    )
+    monkeypatch.setattr(
+        sb, "_respawn_timed_out",
+        lambda conn, row, age: respawn_calls.append(row["id"]),
+    )
+
+    result = _txt(_tool(pkg, "agent_status")())
+
+    assert reap_calls == []
+    assert respawn_calls == []
+    row = conn.execute(
+        "SELECT ended_at, return_code FROM tasks WHERE id='tk_overdue'"
+    ).fetchone()
+    assert row["ended_at"] is None
+    assert row["return_code"] is None
+    count = conn.execute("SELECT COUNT(*) FROM tasks").fetchone()[0]
+    assert count == 1
+    assert "tk_overdue" in result or "agents=1" in result

{threadkeeper-0.17.5 → threadkeeper-0.17.7}/tests/test_candidate_reviewer.py

@@ -203,6 +203,8 @@ def test_run_spawns_when_threshold_met(tmp_path, monkeypatch):
     assert "skill_manage" in allowed
     assert "accept_candidate" in allowed
     assert "reject_candidate" in allowed
+    assert "lesson_neighbors(title=<prospective>" in kw["prompt"]
+    assert "lesson_neighbors" in allowed
     assert "Bash" not in allowed
     # De-privileged (issue #76): no bare Read/Write/Edit — only the
     # path-scoped skill/lesson/candidate MCP tools.

{threadkeeper-0.17.5 → threadkeeper-0.17.7}/tests/test_curator.py

@@ -281,6 +281,64 @@ def test_collect_inventory_preview_truncates_large_store(tmp_path, monkeypatch):
     assert "live curator pass reviews complete bounded batches" in dump
 
 
+def test_curator_reuses_merge_verdicts_and_wikilink_adjacency(
+    tmp_path, monkeypatch,
+):
+    """A later pass receives durable keep-both context without body reads."""
+    pkg = _bootstrap(tmp_path, monkeypatch, min_lessons="2")
+    pkg["lessons"].append_lesson(
+        title="general-prevention",
+        body="The broad guard points to [[specific-recovery]].",
+        source="shadow",
+    )
+    pkg["lessons"].append_lesson(
+        title="specific-recovery",
+        body="The repair path points to [[general-prevention]].",
+        source="shadow",
+    )
+
+    import threadkeeper.tools.spawn as spawn_mod
+    captured: list[dict] = []
+
+    def fake_spawn(**kwargs):
+        captured.append(kwargs)
+        return f"spawn task_id=curator-{len(captured)} pid=0"
+
+    monkeypatch.setattr(spawn_mod, "spawn", fake_spawn)
+    assert "curator-1" in pkg["curator"].run_curator_pass(force=True)
+
+    from threadkeeper._mcp import mcp
+    verdict = mcp._tool_manager._tools["curator_merge_verdict"].fn
+    out = verdict(
+        "specific-recovery",
+        "general-prevention",
+        "prevention/recovery",
+    )
+    assert out == (
+        "ok merge_verdict=general-prevention,specific-recovery "
+        "decision=keep_both"
+    )
+
+    assert "curator-2" in pkg["curator"].run_curator_pass(force=True)
+    prompt = captured[-1]["prompt"]
+    assert "general-prevention" in prompt
+    assert "specific-recovery" in prompt
+    assert "links=[specific-recovery]" in prompt
+    assert "links=[general-prevention]" in prompt
+    assert "## PRIOR MERGE VERDICTS (n=1)" in prompt
+    assert "decision=keep_both reason=prevention/recovery" in prompt
+
+    conn = pkg["db"].get_db()
+    row = conn.execute(
+        "SELECT left_slug, right_slug, decision, reason "
+        "FROM curator_merge_verdicts"
+    ).fetchone()
+    assert tuple(row) == (
+        "general-prevention", "specific-recovery", "keep_both",
+        "prevention/recovery",
+    )
+
+
 # ──────────────────────────────────────────────────────────────────────
 # run_curator_pass — dispatch logic
 # ──────────────────────────────────────────────────────────────────────
@@ -364,6 +422,7 @@ def test_run_curator_pass_spawns_when_threshold_met(tmp_path, monkeypatch):
     assert "evolve_format" in allowed
     assert "Read" in allowed
     assert "curator_report_write" in allowed
+    assert "curator_merge_verdict" in allowed
     assert "Write" not in allowed
     assert "WebSearch" in allowed
     assert "WebFetch" in allowed
@@ -916,6 +975,68 @@ def test_skill_validate_tool_returns_post_change_contract(tmp_path, monkeypatch)
     }
 
 
+def test_wikilink_health_reports_dangling_lesson_and_skill_links(
+    tmp_path, monkeypatch,
+):
+    pkg = _bootstrap(tmp_path, monkeypatch)
+    pkg["lessons"].append_lesson(
+        title="valid lesson",
+        body="Available target.",
+        source="shadow",
+    )
+    pkg["lessons"].append_lesson(
+        title="lesson source",
+        body="See [[valid-lesson]] and [[missing-lesson]].",
+        source="shadow",
+    )
+    _write_audit_skill(
+        pkg["skills_dir"], "skill-source",
+        "See [[valid-lesson]] and [[missing-skill]].",
+    )
+    conn = pkg["db"].get_db()
+
+    from threadkeeper.link_health import scan_wikilink_health
+
+    result = scan_wikilink_health(conn)
+
+    assert result["summary"] == {
+        "lessons_scanned": 2,
+        "skills_scanned": 1,
+        "references_scanned": 4,
+        "dangling_references": 2,
+    }
+    assert result["dangling_references"] == [
+        {
+            "source_kind": "lesson",
+            "source": "lesson-source",
+            "target": "missing-lesson",
+        },
+        {
+            "source_kind": "skill",
+            "source": "skill-source",
+            "target": "missing-skill",
+        },
+    ]
+
+
+def test_wikilink_health_tool_exposes_checker_result(tmp_path, monkeypatch):
+    pkg = _bootstrap(tmp_path, monkeypatch)
+    pkg["lessons"].append_lesson(
+        title="lesson source", body="See [[missing-target]].", source="shadow",
+    )
+    from threadkeeper._mcp import mcp
+
+    result = mcp._tool_manager._tools["wikilink_health"].fn()
+    payload = json.loads(result)
+
+    assert payload["summary"]["dangling_references"] == 1
+    assert payload["dangling_references"] == [{
+        "source_kind": "lesson",
+        "source": "lesson-source",
+        "target": "missing-target",
+    }]
+
+
 def test_curator_report_write_is_path_scoped_and_replaceable(
     tmp_path, monkeypatch,
 ):

{threadkeeper-0.17.5 → threadkeeper-0.17.7}/tests/test_daemon_liveness.py

@@ -14,7 +14,7 @@ def test_daemon_health_is_additive_without_schema_version_bump(mp_with_cid):
     db = pkg["db"]
     conn = db.get_db()
     conn.execute("DROP TABLE daemon_health")
-    conn.execute("PRAGMA user_version = 4")
+    conn.execute(f"PRAGMA user_version = {db.CURRENT_SCHEMA_VERSION}")
     conn.commit()
     conn.close()
 
@@ -23,7 +23,9 @@ def test_daemon_health_is_additive_without_schema_version_bump(mp_with_cid):
 
     conn = db.get_db()
     try:
-        assert conn.execute("PRAGMA user_version").fetchone()[0] == 4
+        assert conn.execute("PRAGMA user_version").fetchone()[0] == (
+            db.CURRENT_SCHEMA_VERSION
+        )
         assert conn.execute(
             "SELECT 1 FROM sqlite_master "
             "WHERE type='table' AND name='daemon_health'"

{threadkeeper-0.17.5 → threadkeeper-0.17.7}/tests/test_evolve_daemon.py

@@ -103,23 +103,49 @@ def _add_evolve(conn, suggestion, rationale=None, applied=0, status="pending"):
 
 def _seed_research(pkg, conn, text="- idea: adopt Y\n  sources: https://ex.com\n"):
     """Make run_evolve_pass take the AUDIT branch on its next call: record a
-    prior research spawn so _last_spawn_phase()=='research', and write a fresh
-    digest file the audit phase will fence into its prompt."""
+    prior research spawn so _last_spawn_phase()=='research', and create a
+    fresh, accepted handoff that the audit phase may fence into its prompt."""
     now = int(time.time())
-    rdir = pkg["ed"]._research_dir()
-    rdir.mkdir(parents=True, exist_ok=True)
-    f = rdir / f"RESEARCH-{now}.md"
-    f.write_text(text, encoding="utf-8")
+    pass_id, f = pkg["ed"]._authorize_research_handoff(
+        conn, now, _FAKE_CID,
+    )
+    persisted = text.rstrip() + "\n"
+    f.write_text(persisted, encoding="utf-8")
+    digest = pkg["ed"].hashlib.sha256(persisted.encode("utf-8")).hexdigest()
+    conn.execute(
+        "UPDATE evolve_research_handoffs SET status='accepted', "
+        "content_sha256=?, content_chars=?, completed_at=? WHERE pass_id=?",
+        (digest, len(persisted), now, pass_id),
+    )
     conn.execute(
         "INSERT INTO events (session_id, kind, target, summary, created_at) "
         "VALUES (?, 'evolve_review_pass', ?, ?, ?)",
-        ("s_prev", str(now), "spawned research file=RESEARCH.md ok task=tk pid=1",
+        ("s_prev", str(now), "spawned research pass=seeded ok task=tk pid=1",
          now),
     )
     conn.commit()
     return f, text
 
 
+def _authorize_researcher(pkg, conn, now=None):
+    """Create the parent/task state a real researcher handoff requires."""
+    now = int(time.time()) if now is None else int(now)
+    pass_id, target = pkg["ed"]._authorize_research_handoff(
+        conn, now, _FAKE_CID,
+    )
+    conn.execute(
+        "INSERT INTO tasks "
+        "(id, pid, parent_cid, spawned_cid, cwd, prompt, started_at, role, write_origin) "
+        "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        (
+            f"tk_research_{pass_id[-6:]}", 0, "parent", _FAKE_CID,
+            str(target.parent), "research", now, "evolve_researcher", "evolve",
+        ),
+    )
+    conn.commit()
+    return pass_id, target
+
+
 def test_audit_prompt_uses_paginated_issue_dedup(tmp_path, monkeypatch):
     pkg = _bootstrap(tmp_path, monkeypatch)
     prompt = pkg["ed"].EVOLVE_AUDIT_PROMPT
@@ -475,7 +501,7 @@ def test_run_evolve_pass_force_spawns_research_first(
     pkg = _bootstrap(tmp_path, monkeypatch)
     calls = {}
     import threadkeeper.tools.spawn as spawn_mod
-    monkeypatch.setattr(spawn_mod, "spawn",
+    monkeypatch.setattr(spawn_mod, "_spawn_impl",
                         lambda **kw: calls.update(kw) or "ok task=tk_ev pid=1")
 
     out = pkg["ed"].run_evolve_pass(force=True)
@@ -513,7 +539,7 @@ def test_run_evolve_pass_below_min(tmp_path, monkeypatch):
     _add_evolve(conn, "only one")
     calls = {}
     import threadkeeper.tools.spawn as spawn_mod
-    monkeypatch.setattr(spawn_mod, "spawn",
+    monkeypatch.setattr(spawn_mod, "_spawn_impl",
                         lambda **kw: calls.update(kw) or "ok task=tk_ev pid=1")
 
     out = pkg["ed"].run_evolve_pass(force=True)
@@ -539,7 +565,7 @@ def test_run_evolve_pass_skips_legacy_backlog_until_interval(
     calls = {}
     import threadkeeper.tools.spawn as spawn_mod
     monkeypatch.setattr(
-        spawn_mod, "spawn",
+        spawn_mod, "_spawn_impl",
         lambda **kw: calls.update(kw) or "ok task=tk_ev pid=1",
     )
 
@@ -558,7 +584,7 @@ def test_run_evolve_pass_research_phase_is_read_only(tmp_path, monkeypatch):
     _add_evolve(conn, "suggestion alpha")
     calls = {}
     import threadkeeper.tools.spawn as spawn_mod
-    monkeypatch.setattr(spawn_mod, "spawn",
+    monkeypatch.setattr(spawn_mod, "_spawn_impl",
                         lambda **kw: calls.update(kw) or "ok task=tk_ev pid=1")
     out = pkg["ed"].run_evolve_pass(force=True)
     assert out.startswith("spawned research")
@@ -567,11 +593,128 @@ def test_run_evolve_pass_research_phase_is_read_only(tmp_path, monkeypatch):
     # web research yes; bypass/shell/GitHub-write no
     assert "WebSearch" in calls["extra_allowed_tools"]
     assert "WebFetch" in calls["extra_allowed_tools"]
+    assert "Write" not in calls["extra_allowed_tools"]
+    assert "evolve_research_handoff" in calls["extra_allowed_tools"]
+    assert calls["allowed_tools_override"] == (
+        "mcp__thread-keeper__broadcast",
+    )
     assert calls["permission_mode"] != "bypassPermissions"
     assert "Bash" not in calls["extra_allowed_tools"]
     assert "Edit" not in calls["extra_allowed_tools"]
     assert "evolve_decide" not in calls["extra_allowed_tools"]
     assert pkg["ed"]._last_evolve_ts(conn) > 0
+    handoff = conn.execute(
+        "SELECT owner_cid, status, target_path FROM evolve_research_handoffs"
+    ).fetchone()
+    assert handoff["owner_cid"] == calls["child_cid_override"]
+    assert handoff["status"] == "pending"
+    assert Path(handoff["target_path"]).name.startswith("RESEARCH-")
+
+
+def test_research_handoff_accepts_only_registered_owner_and_target(
+    tmp_path, monkeypatch,
+):
+    pkg = _bootstrap(tmp_path, monkeypatch)
+    conn = pkg["db"].get_db()
+    pass_id, target = _authorize_researcher(pkg, conn)
+    sentinel = tmp_path / "source.py"
+    sentinel.write_text("unchanged\n", encoding="utf-8")
+    monkeypatch.setenv("THREADKEEPER_SPAWNED_CHILD", "1")
+    monkeypatch.setenv("THREADKEEPER_WRITE_ORIGIN", "evolve")
+
+    out = _tool(pkg, "evolve_research_handoff")(
+        pass_id=pass_id,
+        content="- idea: scoped handoff\n  sources: https://example.test\n",
+    )
+
+    persisted = "- idea: scoped handoff\n  sources: https://example.test\n"
+    assert out.startswith("ok pass_id=")
+    assert target.read_text(encoding="utf-8") == persisted
+    assert sentinel.read_text(encoding="utf-8") == "unchanged\n"
+    row = conn.execute(
+        "SELECT status, content_chars, content_sha256 FROM evolve_research_handoffs "
+        "WHERE pass_id=?", (pass_id,),
+    ).fetchone()
+    assert row["status"] == "accepted"
+    assert row["content_chars"] == len(persisted)
+    assert row["content_sha256"] == pkg["ed"].hashlib.sha256(
+        persisted.encode("utf-8")
+    ).hexdigest()
+    assert pkg["ed"]._latest_research(int(time.time())) == (target, persisted)
+
+
+def test_research_handoff_rejects_wrong_owner_and_malformed_content(
+    tmp_path, monkeypatch,
+):
+    pkg = _bootstrap(tmp_path, monkeypatch)
+    conn = pkg["db"].get_db()
+    monkeypatch.setenv("THREADKEEPER_SPAWNED_CHILD", "1")
+    monkeypatch.setenv("THREADKEEPER_WRITE_ORIGIN", "evolve")
+
+    pass_id, target = _authorize_researcher(pkg, conn)
+    monkeypatch.setattr(pkg["ed"].identity, "_detect_self_cid", lambda: "other")
+    assert _tool(pkg, "evolve_research_handoff")(
+        pass_id=pass_id, content="- harmless\n",
+    ) == "ERR research_handoff_not_authorized"
+    assert not target.exists()
+    assert conn.execute(
+        "SELECT status FROM evolve_research_handoffs WHERE pass_id=?", (pass_id,)
+    ).fetchone()["status"] == "pending"
+
+    monkeypatch.setattr(pkg["ed"].identity, "_detect_self_cid", lambda: _FAKE_CID)
+    malformed_id, malformed_target = _authorize_researcher(pkg, conn)
+    out = _tool(pkg, "evolve_research_handoff")(
+        pass_id=malformed_id, content="bad\x00digest",
+    )
+    assert out == "ERR digest_malformed reason=malformed_nul"
+    malformed = conn.execute(
+        "SELECT status, failure FROM evolve_research_handoffs WHERE pass_id=?",
+        (malformed_id,),
+    ).fetchone()
+    assert malformed["status"] == "failed"
+    assert malformed["failure"] == "malformed_nul"
+    assert not malformed_target.exists()
+    telemetry = conn.execute(
+        "SELECT summary FROM events WHERE kind=? AND summary LIKE ? "
+        "ORDER BY id DESC LIMIT 1",
+        (pkg["ed"].EVOLVE_RESEARCH_HANDOFF_KIND, f"pass_id={malformed_id}%"),
+    ).fetchone()["summary"]
+    assert "status=failed reason=malformed_nul" in telemetry
+
+
+def test_research_handoff_rejects_oversize_and_audit_rejects_tampering(
+    tmp_path, monkeypatch,
+):
+    pkg = _bootstrap(tmp_path, monkeypatch)
+    conn = pkg["db"].get_db()
+    monkeypatch.setenv("THREADKEEPER_SPAWNED_CHILD", "1")
+    monkeypatch.setenv("THREADKEEPER_WRITE_ORIGIN", "evolve")
+
+    oversize_id, _ = _authorize_researcher(pkg, conn)
+    out = _tool(pkg, "evolve_research_handoff")(
+        pass_id=oversize_id,
+        content="x" * (pkg["ed"].EVOLVE_RESEARCH_MAX_CHARS + 1),
+    )
+    assert out == (
+        f"ERR digest_too_large max_chars={pkg['ed'].EVOLVE_RESEARCH_MAX_CHARS}"
+    )
+    assert conn.execute(
+        "SELECT status, failure FROM evolve_research_handoffs WHERE pass_id=?",
+        (oversize_id,),
+    ).fetchone()["failure"] == "too_large"
+
+    pass_id, target = _authorize_researcher(pkg, conn)
+    assert _tool(pkg, "evolve_research_handoff")(
+        pass_id=pass_id, content="- trusted before replacement\n",
+    ).startswith("ok pass_id=")
+    target.write_text("- replacement after handoff\n", encoding="utf-8")
+    assert pkg["ed"]._latest_research(int(time.time())) == (None, "")
+    tampered = conn.execute(
+        "SELECT status, failure FROM evolve_research_handoffs WHERE pass_id=?",
+        (pass_id,),
+    ).fetchone()
+    assert tampered["status"] == "tampered"
+    assert tampered["failure"] == "sha256_mismatch"
 
 
 def test_run_evolve_pass_audit_phase_no_web_consumes_fenced_research(
@@ -708,10 +851,12 @@ def test_web_research_and_privileged_write_never_cogranted(tmp_path, monkeypatch
     _add_evolve(conn, "suggestion alpha")
     captured = []
     import threadkeeper.tools.spawn as spawn_mod
-    monkeypatch.setattr(
-        spawn_mod, "spawn",
-        lambda **kw: captured.append(dict(kw)) or "ok task=tk_ev pid=1",
-    )
+    def capture(**kw):
+        captured.append(dict(kw))
+        return "ok task=tk_ev pid=1"
+
+    monkeypatch.setattr(spawn_mod, "spawn", capture)
+    monkeypatch.setattr(spawn_mod, "_spawn_impl", capture)
 
     # Phase 1 records a real "spawned research" pass, so phase 2 takes the audit
     # branch on the next forced call.
@@ -748,7 +893,7 @@ def test_run_evolve_pass_runs_reviewer_in_repo_root(tmp_path, monkeypatch):
     monkeypatch.setattr(pkg["ed"], "_ensure_repo_ready", lambda: (repo, ""))
     calls = {}
     import threadkeeper.tools.spawn as spawn_mod
-    monkeypatch.setattr(spawn_mod, "spawn",
+    monkeypatch.setattr(spawn_mod, "_spawn_impl",
                         lambda **kw: calls.update(kw) or "ok task=tk_ev pid=1")
 
     out = pkg["ed"].run_evolve_pass(force=True)
@@ -837,7 +982,7 @@ def test_run_evolve_pass_single_flight_lock_race(tmp_path, monkeypatch):
             errors.append(e)
             release_spawn.set()
 
-    monkeypatch.setattr(spawn_mod, "spawn", fake_spawn)
+    monkeypatch.setattr(spawn_mod, "_spawn_impl", fake_spawn)
 
     t = threading.Thread(target=run_pass)
     t.start()