agent-runtime-py 0.1.1__tar.gz → 0.2.1__tar.gz

agent_runtime_py-0.2.1/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.2.1
+
+- Fix: a Claude input that native Claude folded into a turn started by something else (a peer message, a background task) never settled, because that turn's result carries the other origin. The worker then took no further input and never exited on idle. A result now settles the active input when the input's echo arrived before it.
+- Fix: a turn that native Claude runs for another origin (a peer message) counts as work: the worker reports `turn.started` when that message arrives, not at the first assistant text, and does not exit on idle while the turn runs.
+- Fix: the Claude worker starts with `-P`, so the session's working folder is not on its import path.
+
+## 0.2.0
+
+- Breaking: requires typed-agent-hooks 0.3. Run the hooks with `agent_runtime.hooks.app.main()` and the host name (`codex` or `claude`) as the only argument; the host hook file sets the timeout. The `agent-runtime-hooks` console script is removed.
+- Breaking: the Claude Agent SDK moves to the `claude` extra. `ClaudeRuntime` needs `agent-runtime-py[claude]`.
+- Fix: a monitor worker whose command exceeded the output limit never exited and ignored SIGTERM.
+- Fix: a Claude SessionStart, which carries no permission mode, kept the mode empty; it now keeps the mode that the same live Claude process reported.

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/PKG-INFO

@@ -1,21 +1,22 @@
 Metadata-Version: 2.5
 Name: agent-runtime-py
-Version: 0.1.1
+Version: 0.2.1
 Summary: Reconnectable native agent workers with durable input receipts and events
 Project-URL: Repository, https://github.com/nimashoghi/agent-runtime
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.11
-Requires-Dist: claude-agent-sdk==0.2.159
 Requires-Dist: filelock<4,>=3.16
 Requires-Dist: platformdirs<5,>=4
 Requires-Dist: psutil<8,>=7
-Requires-Dist: typed-agent-hooks
+Requires-Dist: typed-agent-hooks<0.4,>=0.3
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk==0.2.159; extra == 'claude'
 Description-Content-Type: text/markdown
 
 # Agent runtime
 
-`agent-runtime-py` provides detached Claude Code workers that applications can reconnect to after restarting. Import it as `agent_runtime`. It uses the official Claude Agent SDK and your installed Claude Code executable, loading native user and project settings, hooks, skills, and MCP servers.
+`agent-runtime-py` provides detached Claude Code workers that applications can reconnect to after restarting. Import it as `agent_runtime`. The workers need the `claude` extra (`agent-runtime-py[claude]`), which installs the Claude Agent SDK; the hooks, monitors and peer messages do not. It uses the official Claude Agent SDK and your installed Claude Code executable, loading native user and project settings, hooks, skills, and MCP servers.
 
 This repository is under active development. The current implementation supports macOS and Linux and has been exercised with Claude Code 2.1.281 and Claude Agent SDK 0.2.159. Windows is not supported.
 
@@ -49,7 +50,7 @@ The default permission mode is Claude's ordinary permission behavior. Pending ap
 
 ## Monitors and local peer messages
 
-Install `agent-runtime-hooks` using a typed-agent-hooks `Collection` for both providers. The hooks register native process identities and current permission modes. Claude hooks start a private delivery child whose inherited native inbox token remains in memory; it is never written to the registry or used for messages to another session.
+Run the hooks from an executable PEP 723 script with an exact `agent-runtime-py` pin and a `[tool.uv] exclude-newer` date, whose body is `from agent_runtime.hooks import app` and `if __name__ == "__main__": app.main()`. Register that script for SessionStart, UserPromptSubmit and PreToolUse in each host's hook file, with the host name (`codex` or `claude`) as its only argument and a timeout of 10 seconds. End each command with `|| true`: uv exits nonzero when it cannot start the script (2, for example, when the package index is unreachable), and both hosts read exit 2 on UserPromptSubmit and PreToolUse as a block. The hooks register native process identities and current permission modes. Claude hooks start a private delivery child whose inherited native inbox token remains in memory; it is never written to the registry or used for messages to another session.
 
 `agent_runtime.operations` supplies `monitor_start`, `monitor_list`, `monitor_get`, `monitor_stop`, `monitor_events`, `agents`, and `send`. Codex operations delegate to the installed `codexr` CLI. Claude monitors run a detached foreground Bash command and retain stdout observations in SQLite; stderr goes to a private log. A 1 MiB output limit stops an overly verbose monitor. Delivery batches retain each monitor's launch permission class. Native Claude receives these as peer context and applies its own admission policy, including holding messages if permission modes require approval. `transport-written` confirms only a socket write, not admission or model processing. Interrupted writes remain uncertain and are not replayed automatically.
 

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/README.md

@@ -1,6 +1,6 @@
 # Agent runtime
 
-`agent-runtime-py` provides detached Claude Code workers that applications can reconnect to after restarting. Import it as `agent_runtime`. It uses the official Claude Agent SDK and your installed Claude Code executable, loading native user and project settings, hooks, skills, and MCP servers.
+`agent-runtime-py` provides detached Claude Code workers that applications can reconnect to after restarting. Import it as `agent_runtime`. The workers need the `claude` extra (`agent-runtime-py[claude]`), which installs the Claude Agent SDK; the hooks, monitors and peer messages do not. It uses the official Claude Agent SDK and your installed Claude Code executable, loading native user and project settings, hooks, skills, and MCP servers.
 
 This repository is under active development. The current implementation supports macOS and Linux and has been exercised with Claude Code 2.1.281 and Claude Agent SDK 0.2.159. Windows is not supported.
 
@@ -34,7 +34,7 @@ The default permission mode is Claude's ordinary permission behavior. Pending ap
 
 ## Monitors and local peer messages
 
-Install `agent-runtime-hooks` using a typed-agent-hooks `Collection` for both providers. The hooks register native process identities and current permission modes. Claude hooks start a private delivery child whose inherited native inbox token remains in memory; it is never written to the registry or used for messages to another session.
+Run the hooks from an executable PEP 723 script with an exact `agent-runtime-py` pin and a `[tool.uv] exclude-newer` date, whose body is `from agent_runtime.hooks import app` and `if __name__ == "__main__": app.main()`. Register that script for SessionStart, UserPromptSubmit and PreToolUse in each host's hook file, with the host name (`codex` or `claude`) as its only argument and a timeout of 10 seconds. End each command with `|| true`: uv exits nonzero when it cannot start the script (2, for example, when the package index is unreachable), and both hosts read exit 2 on UserPromptSubmit and PreToolUse as a block. The hooks register native process identities and current permission modes. Claude hooks start a private delivery child whose inherited native inbox token remains in memory; it is never written to the registry or used for messages to another session.
 
 `agent_runtime.operations` supplies `monitor_start`, `monitor_list`, `monitor_get`, `monitor_stop`, `monitor_events`, `agents`, and `send`. Codex operations delegate to the installed `codexr` CLI. Claude monitors run a detached foreground Bash command and retain stdout observations in SQLite; stderr goes to a private log. A 1 MiB output limit stops an overly verbose monitor. Delivery batches retain each monitor's launch permission class. Native Claude receives these as peer context and applies its own admission policy, including holding messages if permission modes require approval. `transport-written` confirms only a socket write, not admission or model processing. Interrupted writes remain uncertain and are not replayed automatically.
 

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/pyproject.toml

@@ -4,22 +4,22 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-runtime-py"
-version = "0.1.1"
+version = "0.2.1"
 description = "Reconnectable native agent workers with durable input receipts and events"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
 requires-python = ">=3.11"
 dependencies = [
-  "claude-agent-sdk==0.2.159",
   "filelock>=3.16,<4",
   "platformdirs>=4,<5",
   "psutil>=7,<8",
-  "typed-agent-hooks",
+  "typed-agent-hooks>=0.3,<0.4",
 ]
 
-[project.scripts]
-agent-runtime-hooks = "agent_runtime.hooks:main"
+[project.optional-dependencies]
+# Only the detached Claude worker (`ClaudeRuntime`) uses the SDK; hooks and monitors do not.
+claude = ["claude-agent-sdk==0.2.159"]
 
 [project.urls]
 Repository = "https://github.com/nimashoghi/agent-runtime"
@@ -28,7 +28,7 @@ Repository = "https://github.com/nimashoghi/agent-runtime"
 packages = ["src/agent_runtime"]
 
 [dependency-groups]
-dev = ["pytest>=8.4,<9", "pytest-asyncio>=1.1,<2", "ruff>=0.12,<1", "basedpyright>=1.31,<2", "build>=1.3,<2"]
+dev = ["agent-runtime-py[claude]", "pytest>=8.4,<9", "pytest-asyncio>=1.1,<2", "ruff>=0.12,<1", "basedpyright>=1.31,<2", "build>=1.3,<2"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/src/agent_runtime/claude.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 import hashlib
+import importlib.util
 import json
 import math
 import os
@@ -77,6 +78,8 @@ class ClaudeRuntime:
     """The client owns no worker lifetime and can reconnect after a service restart."""
 
     def __init__(self, directory: Path) -> None:
+        if importlib.util.find_spec("claude_agent_sdk") is None:
+            raise RuntimeError("ClaudeRuntime needs the claude extra: agent-runtime-py[claude]")
         self.store = Store(directory)
 
     def inspect(self, execution_id: str) -> dict[str, Any]:
@@ -174,6 +177,9 @@ class ClaudeRuntime:
                     child = subprocess.Popen(
                         [
                             sys.executable,
+                            # The worker's cwd is the session's folder, which the agent
+                            # writes; it must not be on the worker's import path.
+                            "-P",
                             "-m",
                             "agent_runtime.worker",
                             str(self.store.root),

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/src/agent_runtime/hooks.py

@@ -14,15 +14,18 @@ from agent_runtime.sessions import Registry, own_claude_registration
 app = shared.HookApp(name="agent-runtime")
 
 
-def register(event) -> None:
+def register(
+    event: shared.events.SessionStarted
+    | shared.events.PromptSubmitted
+    | shared.events.ToolCallProposed,
+) -> None:
     context = event.context
     if context.agent_id:
         return
     registry = Registry()
-    provider = context.provider.value
-    if provider == "codex":
+    if context.host == "codex":
         registry.update(
-            provider, context.session_id, cwd=context.cwd, permission_mode=context.permission_mode
+            "codex", context.session_id, cwd=context.cwd, permission_mode=context.permission_mode
         )
         return
     with FileLock(str(registry.store.root / f"bridge-start-{context.session_id}.lock"), timeout=5):
@@ -59,24 +62,6 @@ def register(event) -> None:
         )
 
 
-@app.on(shared.events.SessionStarted, timeout=10)
-def session_started(event: shared.events.SessionStarted) -> None:
-    register(event)
-
-
-@app.on(shared.events.PromptSubmitted, timeout=10)
-def prompt_submitted(event: shared.events.PromptSubmitted) -> None:
-    register(event)
-
-
-@app.on(shared.events.ToolCallProposed, timeout=10)
-def tool_call_proposed(event: shared.events.ToolCallProposed) -> None:
-    register(event)
-
-
-def main() -> None:
-    app.main()
-
-
-if __name__ == "__main__":
-    main()
+app.on(shared.events.SessionStarted)(register)
+app.on(shared.events.PromptSubmitted)(register)
+app.on(shared.events.ToolCallProposed)(register)

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/src/agent_runtime/monitor_worker.py

@@ -14,6 +14,18 @@ from agent_runtime.claude import process_alive
 from agent_runtime.monitors import Monitors
 
 
+async def exited(child: asyncio.subprocess.Process, timeout: float) -> bool:
+    """Wait until the child exits, but not for its pipes to close.
+
+    `Process.wait()` called before the child exits returns only after stdout
+    and stderr close, and a pipe that no reader drains never closes.
+    """
+    deadline = time.monotonic() + timeout
+    while child.returncode is None and time.monotonic() < deadline:
+        await asyncio.sleep(0.05)
+    return child.returncode is not None
+
+
 async def run(directory: Path, identity: str) -> None:
     monitors = Monitors(directory)
     value = monitors.get(identity)
@@ -93,17 +105,17 @@ async def run(directory: Path, identity: str) -> None:
             if stop.is_set():
                 if process_alive({"pid": child.pid, "process_created_at": child_created}):
                     os.killpg(child.pid, signal.SIGTERM)
-                    try:
-                        await asyncio.wait_for(child.wait(), timeout=5)
-                    except TimeoutError:
-                        if process_alive({"pid": child.pid, "process_created_at": child_created}):
-                            os.killpg(child.pid, signal.SIGKILL)
+                    if not await exited(child, 5) and process_alive(
+                        {"pid": child.pid, "process_created_at": child_created}
+                    ):
+                        os.killpg(child.pid, signal.SIGKILL)
                 break
             for reader in readers:
                 if reader.done() and (error := reader.exception()) is not None:
                     raise error
             await asyncio.sleep(0.1)
-        await child.wait()
+        # Stop can win the race with a normal exit; record the exit code then too.
+        await exited(child, 5)
         try:
             await asyncio.wait_for(asyncio.gather(*readers), timeout=5)
         except TimeoutError as error:
@@ -134,7 +146,7 @@ async def run(directory: Path, identity: str) -> None:
         if child is not None and child.returncode is None:
             if process_alive({"pid": child.pid, "process_created_at": child_created}):
                 os.killpg(child.pid, signal.SIGKILL)
-            await child.wait()
+            await exited(child, 5)
         for reader in readers:
             reader.cancel()
         await asyncio.gather(*readers, return_exceptions=True)

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/src/agent_runtime/sessions.py

@@ -114,7 +114,18 @@ def own_claude_registration(
     process = psutil.Process(pid)
     if process.uids().real != os.getuid():
         raise RuntimeError("native Claude process belongs to a different user")
-    return (registry or Registry()).update(
+    registry = registry or Registry()
+    # Claude's SessionStart payload has no permission mode. Keep the mode that
+    # this same live process reported; a resumed session in a new process has
+    # none until a prompt or tool call reports one.
+    if permission_mode is None:
+        try:
+            previous = registry.get("claude_code", session_id)
+        except KeyError:
+            previous = {}
+        if previous.get("pid") == pid and process_alive(previous):
+            permission_mode = previous.get("permission_mode")
+    return registry.update(
         "claude_code",
         session_id,
         cwd=cwd,

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/src/agent_runtime/worker.py

@@ -100,6 +100,17 @@ class Worker:
             if isinstance(message, UserMessage) and message.uuid:
                 if admitted := self.store.admit(self.execution_id, message.uuid):
                     self.emit("input.delivered", message_id=admitted, native_uuid=message.uuid)
+                    if self.active and self.active["id"] == admitted:
+                        self.active["acknowledged"] = True
+                elif (
+                    (message.origin or {}).get("kind", "human") != "human"
+                    and message.parent_tool_use_id is None
+                    and not self.presentation_started
+                ):
+                    # A message from another origin (a peer session, a background task)
+                    # starts a turn that no input of this runtime asked for.
+                    self.emit("turn.started", origin="native")
+                    self.presentation_started = True
             elif isinstance(message, AssistantMessage) and message.parent_tool_use_id is None:
                 if not self.presentation_started:
                     self.emit("turn.started", origin="native")
@@ -113,7 +124,15 @@ class Worker:
                 if message.session_id != self.session_id:
                     raise RuntimeError("native Claude returned a different session ID")
                 human = message.origin is None or message.origin.get("kind") == "human"
-                active = self.active if human else None
+                # Native Claude can fold an input into a turn that something else started
+                # (a peer message, a background task); that turn's result carries the other
+                # origin. The turn that follows the input's echo is the one that consumed it.
+                # A non-human result before the echo belongs to an earlier turn.
+                active = (
+                    self.active
+                    if self.active and (human or self.active.get("acknowledged"))
+                    else None
+                )
                 status = "failed" if message.is_error else "completed"
                 if message.terminal_reason in {"aborted_streaming", "aborted_tools"}:
                     status = "interrupted"
@@ -243,6 +262,8 @@ class Worker:
                 if (
                     timeout
                     and self.active is None
+                    # A turn that native Claude runs for another origin is work too.
+                    and not self.presentation_started
                     and not self.background_tasks
                     and time.monotonic() - self.last_activity >= timeout
                     and not any(

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/tests/test_claude_runtime.py

@@ -24,10 +24,11 @@ if "--version" in sys.argv:
 def emit(value):
     print(json.dumps(value), flush=True)
 session = next(a.split("=", 1)[1] for a in sys.argv if a.startswith(("--session-id=", "--resume=")))
-def result(text):
+PEER = {"kind":"peer","from":"unknown"}
+def result(text, origin={"kind":"human"}):
     emit({"type":"result", "subtype":"success", "is_error":False,
           "duration_ms":1,"duration_api_ms":1,"num_turns":1,"session_id":session,
-          "result":text,"origin":{"kind":"human"},"usage":{}})
+          "result":text,"origin":origin,"usage":{}})
 pending = None
 for line in sys.stdin:
     message = json.loads(line)
@@ -40,7 +41,25 @@ for line in sys.stdin:
             log.write(json.dumps({"text": text, "uuid":message["uuid"], "session": session}) + "\n")
         if text == "crash-before-echo":
             raise SystemExit(23)
+        if text == "folded-into-peer-turn":
+            # Native Claude, observed 2026-11-10: a peer message's turn ends, a second peer
+            # message starts a turn, the queued human input joins that turn, and the turn's
+            # result carries the peer origin.
+            result("first peer turn", PEER)
+            emit({"type":"user","uuid":"peer-message","message":{"role":"user","content":"peer"},"origin":PEER})
+            emit({"type":"user","uuid":message["uuid"],"message":{"role":"user","content":text},"origin":{"kind":"human"}})
+            result("answer to both", PEER)
+            continue
         emit({"type":"user","uuid":message["uuid"],"message":{"role":"user","content":text},"origin":{"kind":"human"}})
+        if text == "then-a-peer-turn":
+            # The input's own turn ends; a peer message then starts a turn that works
+            # in silence for longer than the idle timeout.
+            import time
+            result("echo: " + text)
+            emit({"type":"user","uuid":"peer-message","message":{"role":"user","content":"peer"},"origin":PEER})
+            time.sleep(1.5)
+            result("peer turn done", PEER)
+            continue
         if text == "permission":
             pending = text
             emit({"type":"control_request","request_id":"permission-1",
@@ -164,3 +183,63 @@ async def test_permission_waits_for_durable_explicit_answer(tmp_path, native):
             runtime.store.answer(eid, requests[0]["id"], {"decision": "allow"})
     finally:
         await runtime.stop(eid)
+
+
+async def test_input_folded_into_a_peer_turn_settles_with_that_turn(tmp_path, native):
+    runtime = ClaudeRuntime(tmp_path / "runtime")
+    opts = options(tmp_path, native)
+    value = await runtime.start(
+        "folded-into-peer-turn", message_id="m1", options=opts, launch_id="folded"
+    )
+    sid, eid = value["session_id"], value["execution_id"]
+
+    def settled():
+        return [
+            e["event"] for e in runtime.store.events(sid) if e["event"]["type"] == "work.settled"
+        ]
+
+    try:
+        await wait_for(lambda: len(settled()) >= 2)
+        # The first result came before the input's echo, so it is not the input's result.
+        assert [event["message_ids"] for event in settled()] == [[], ["m1"]]
+        assert settled()[1]["message"] == "answer to both"
+        # The worker is free again: it takes the next input.
+        await runtime.submit(sid, "next", message_id="m2", options=opts, resume=False)
+        await wait_for(lambda: len(settled()) >= 3)
+        assert settled()[2]["message_ids"] == ["m2"]
+    finally:
+        await runtime.stop(eid)
+
+
+async def test_a_turn_for_another_origin_is_not_ended_by_the_idle_timeout(tmp_path, native):
+    runtime = ClaudeRuntime(tmp_path / "runtime")
+    opts = LaunchOptions(
+        cwd=tmp_path,
+        claude=native,
+        idle_timeout_seconds=0.5,
+        environment={"FAKE_CLAUDE_LOG": str(tmp_path / "inputs.jsonl")},
+    )
+    value = await runtime.start("then-a-peer-turn", message_id="m1", options=opts, launch_id="peer")
+    sid, eid = value["session_id"], value["execution_id"]
+    try:
+        await wait_for(lambda: runtime.inspect(eid)["result"])
+        events = [e["event"] for e in runtime.store.events(sid)]
+        kinds = [
+            e["type"]
+            for e in events
+            if e["type"] in {"turn.started", "work.settled", "worker.exited"}
+        ]
+        # The worker saw the peer turn start and waited for its result before its idle exit.
+        assert kinds == [
+            "turn.started",
+            "work.settled",
+            "turn.started",
+            "work.settled",
+            "worker.exited",
+        ]
+        assert events[-1]["reason"] == "idle_timeout"
+        settled = [e for e in events if e["type"] == "work.settled"]
+        assert [e["message_ids"] for e in settled] == [["m1"], []]
+        assert settled[1]["message"] == "peer turn done"
+    finally:
+        await runtime.stop(eid)

agent_runtime_py-0.2.1/tests/test_hooks.py

@@ -0,0 +1,179 @@
+"""The hooks against hand-written payloads in the native Codex and Claude shapes."""
+
+import json
+import socket
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+from pathlib import Path
+
+import pytest
+
+from agent_runtime.claude import process_alive
+from agent_runtime.hooks import app
+from agent_runtime.sessions import Registry, own_claude_registration
+
+
+def wait_for(predicate, timeout=15):
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if result := predicate():
+            return result
+        time.sleep(0.05)
+    raise AssertionError("condition did not become true")
+
+
+def codex_payload(event: str, session_id: str, **fields) -> dict:
+    payload = {
+        "session_id": session_id,
+        "transcript_path": None,
+        "cwd": "/repo",
+        "hook_event_name": event,
+        "model": "gpt-5",
+        "permission_mode": "default",
+    }
+    if event == "SessionStart":
+        payload["source"] = "startup"
+    elif event == "UserPromptSubmit":
+        payload.update(turn_id="t", prompt="hello")
+    elif event == "PreToolUse":
+        payload.update(
+            turn_id="t", tool_name="Bash", tool_use_id="u", tool_input={"command": "echo ok"}
+        )
+    return {**payload, **fields}
+
+
+@pytest.mark.parametrize("event", ["SessionStart", "UserPromptSubmit", "PreToolUse"])
+def test_codex_events_register_the_session(tmp_path, monkeypatch, event):
+    monkeypatch.setenv("AGENT_RUNTIME_DIRECTORY", str(tmp_path))
+    session_id = str(uuid.uuid4())
+
+    assert app.handle("codex", codex_payload(event, session_id)) is None
+
+    record = Registry(tmp_path).get("codex", session_id)
+    assert record["cwd"] == "/repo"
+    assert record["permission_mode"] == "default"
+
+
+@pytest.mark.parametrize("host", ["codex", "claude"])
+def test_subagent_events_do_not_register(tmp_path, monkeypatch, host):
+    monkeypatch.setenv("AGENT_RUNTIME_DIRECTORY", str(tmp_path))
+    monkeypatch.delenv("CLAUDE_PID", raising=False)
+    payload = codex_payload("PreToolUse", "parent", agent_id="a", agent_type="explore")
+    if host == "claude":
+        payload["transcript_path"] = str(tmp_path / "t.jsonl")
+
+    assert app.handle(host, payload) is None
+
+    for provider in ("codex", "claude_code"):
+        with pytest.raises(KeyError):
+            Registry(tmp_path).get(provider, "parent")
+
+
+def test_hooks_do_not_import_the_claude_sdk():
+    # Hook environments install agent-runtime-py without the `claude` extra.
+    code = "import sys, agent_runtime.hooks; print('claude_agent_sdk' in sys.modules)"
+    result = subprocess.run(
+        [sys.executable, "-c", code], capture_output=True, text=True, check=True
+    )
+    assert result.stdout == "False\n"
+
+
+def test_hook_command_reads_host_argument_and_stdin(tmp_path):
+    session_id = str(uuid.uuid4())
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            "from agent_runtime.hooks import app\nif __name__ == '__main__':\n    app.main()",
+            "codex",
+        ],
+        input=json.dumps(codex_payload("SessionStart", session_id)),
+        env={"AGENT_RUNTIME_DIRECTORY": str(tmp_path), "PATH": "/usr/bin:/bin"},
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+
+    assert (result.stdout, result.stderr) == ("", "")
+    assert Registry(tmp_path).get("codex", session_id)["cwd"] == "/repo"
+
+
+def test_claude_session_start_starts_one_delivery_bridge(tmp_path, monkeypatch):
+    session_id = str(uuid.uuid4())
+    payload = {
+        "session_id": session_id,
+        "transcript_path": str(tmp_path / "t.jsonl"),
+        "cwd": "/repo",
+        "hook_event_name": "SessionStart",
+        "source": "startup",
+        "model": "claude",
+    }
+    owner = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(300)"])
+    try:
+        with (
+            tempfile.TemporaryDirectory(prefix="ar-hook-", dir="/tmp") as temporary,
+            socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as inbox,
+        ):
+            inbox.bind(str(Path(temporary) / "inbox.sock"))
+            inbox.listen()
+            for name, value in {
+                "AGENT_RUNTIME_DIRECTORY": str(tmp_path),
+                "CLAUDE_CODE_SESSION_ID": session_id,
+                "CLAUDE_PID": str(owner.pid),
+                "CLAUDE_CODE_MESSAGING_SOCKET": str(Path(temporary) / "inbox.sock"),
+                "CLAUDE_CODE_MESSAGING_TOKEN": "fixture-token",
+            }.items():
+                monkeypatch.setenv(name, value)
+
+            assert app.handle("claude", payload) is None
+            registry = Registry(tmp_path)
+            # The hook records the bridge before it returns.
+            bridge = registry.get("claude_code", session_id)["bridge"]
+            assert bridge["native_pid"] == owner.pid
+            assert process_alive(bridge)
+
+            prompt = {
+                **payload,
+                "hook_event_name": "UserPromptSubmit",
+                "prompt": "hi",
+                "permission_mode": "default",
+            }
+            assert app.handle("claude", prompt) is None
+            assert registry.get("claude_code", session_id)["bridge"] == bridge
+
+            # SessionStart after compaction has no permission mode.
+            assert app.handle("claude", {**payload, "source": "compact"}) is None
+            assert registry.get("claude_code", session_id)["permission_mode"] == "default"
+    finally:
+        owner.terminate()
+        owner.wait(timeout=5)
+    # The bridge exits when its native owner exits.
+    wait_for(lambda: not process_alive(bridge))
+
+
+def test_permission_mode_belongs_to_the_native_process(tmp_path, monkeypatch):
+    registry = Registry(tmp_path)
+    monkeypatch.setenv("CLAUDE_CODE_MESSAGING_SOCKET", str(tmp_path / "inbox.sock"))
+    monkeypatch.delenv("CLAUDE_CODE_SESSION_ID", raising=False)
+    sleeper = [sys.executable, "-c", "import time; time.sleep(300)"]
+    first = subprocess.Popen(sleeper)
+    try:
+        monkeypatch.setenv("CLAUDE_PID", str(first.pid))
+        own_claude_registration("s", "/repo", "default", registry=registry)
+        # SessionStart after compaction: same process, no mode in the payload.
+        own_claude_registration("s", "/repo", None, registry=registry)
+        assert registry.get("claude_code", "s")["permission_mode"] == "default"
+    finally:
+        first.terminate()
+        first.wait(timeout=5)
+    resumed = subprocess.Popen(sleeper)
+    try:
+        monkeypatch.setenv("CLAUDE_PID", str(resumed.pid))
+        own_claude_registration("s", "/repo", None, registry=registry)
+        assert registry.get("claude_code", "s")["permission_mode"] is None
+    finally:
+        resumed.terminate()
+        resumed.wait(timeout=5)

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/tests/test_monitors.py

@@ -1,6 +1,8 @@
 """Real detached shell monitors and native inbox frames at a local socket boundary."""
 
 import json
+import os
+import signal
 import socket
 import subprocess
 import sys
@@ -8,6 +10,7 @@ import tempfile
 import threading
 import time
 import uuid
+from contextlib import suppress
 from pathlib import Path
 
 import psutil
@@ -50,7 +53,7 @@ def inbox(tmp_path, monkeypatch):
                         data += block
                     frames.append([json.loads(line) for line in data.splitlines()])
 
-        thread = threading.Thread(target=receive)
+        thread = threading.Thread(target=receive, daemon=True)
         thread.start()
         owner = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(300)"])
         sid = str(uuid.uuid4())
@@ -75,9 +78,18 @@ def inbox(tmp_path, monkeypatch):
         finally:
             for monitor in monitors.list(sid):
                 monitors.stop(monitor["monitor_id"])
-            wait_for(
-                lambda: all(m["status"] not in {"starting", "running"} for m in monitors.list(sid))
-            )
+            deadline = time.monotonic() + 15
+            while time.monotonic() < deadline and any(map(process_alive, monitors.list(sid))):
+                time.sleep(0.05)
+            # Kill a stuck worker and its command, so that a failing test leaks
+            # no process, and fail after the rest of the cleanup.
+            stuck = [m for m in monitors.list(sid) if process_alive(m)]
+            for monitor in stuck:
+                with suppress(psutil.NoSuchProcess):
+                    worker = psutil.Process(monitor["pid"])
+                    for process in [*worker.children(recursive=True), worker]:
+                        with suppress(psutil.NoSuchProcess):
+                            process.kill()
             if owner.poll() is None:
                 owner.terminate()
             owner.wait(timeout=5)
@@ -85,6 +97,7 @@ def inbox(tmp_path, monkeypatch):
             stopped.set()
             thread.join(timeout=2)
             sock.close()
+            assert not stuck, f"monitor workers did not exit: {[m['monitor_id'] for m in stuck]}"
 
 
 def test_shell_output_failure_and_truthful_peer_mode(inbox):
@@ -121,7 +134,7 @@ def test_deadline_and_stop_kill_foreground_process_group(inbox, tmp_path):
     monitor = monitors.start(
         f"sleep 30 & echo $! > {pidfile}; wait", description="stop tree", persistent=True
     )
-    wait_for(pidfile.exists)
+    wait_for(lambda: pidfile.exists() and pidfile.read_text().strip())
     child = psutil.Process(int(pidfile.read_text()))
     identity = {"pid": child.pid, "process_created_at": child.create_time()}
     monitors.stop(monitor["monitor_id"])
@@ -190,3 +203,25 @@ def test_excessive_output_stops_with_inspectable_error(inbox):
         lambda: m if (m := monitors.get(monitor["monitor_id"]))["status"] == "failed" else None
     )
     assert "exceeded 1 MiB" in done["error"]
+    # The unread output must not keep the worker waiting for its command.
+    wait_for(lambda: not process_alive(done))
+
+
+def test_worker_stops_its_command_and_exits_on_sigterm(inbox, tmp_path):
+    monitors, _sid, _, _, _ = inbox
+    pidfile = tmp_path / "command.pid"
+    monitor = monitors.start(
+        f"echo $$ > {pidfile}; exec sleep 300", description="sigterm", persistent=True
+    )
+    wait_for(lambda: pidfile.exists() and pidfile.read_text().strip())
+    command = psutil.Process(int(pidfile.read_text()))
+    command_identity = {"pid": command.pid, "process_created_at": command.create_time()}
+    worker = wait_for(
+        lambda: m if (m := monitors.get(monitor["monitor_id"]))["status"] == "running" else None
+    )
+
+    os.kill(worker["pid"], signal.SIGTERM)
+
+    wait_for(lambda: not process_alive(worker))
+    assert not process_alive(command_identity)
+    assert monitors.get(monitor["monitor_id"])["status"] == "stopped"

{agent_runtime_py-0.1.1 → agent_runtime_py-0.2.1}/uv.lock

@@ -1,26 +1,31 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = ">=3.11"
 resolution-markers = [
     "python_full_version >= '3.14'",
     "python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform == 'emscripten'",
-    "(python_full_version < '3.14' and sys_platform != 'emscripten') or (python_full_version < '3.12' and sys_platform == 'emscripten')",
+    "python_full_version < '3.12' or (python_full_version >= '3.12' and python_full_version < '3.14' and sys_platform != 'emscripten')",
 ]
 
 [[package]]
 name = "agent-runtime-py"
-version = "0.1.1"
+version = "0.2.1"
 source = { editable = "." }
 dependencies = [
-    { name = "claude-agent-sdk" },
     { name = "filelock" },
     { name = "platformdirs" },
     { name = "psutil" },
     { name = "typed-agent-hooks" },
 ]
 
+[package.optional-dependencies]
+claude = [
+    { name = "claude-agent-sdk" },
+]
+
 [package.dev-dependencies]
 dev = [
+    { name = "agent-runtime-py", extra = ["claude"] },
     { name = "basedpyright" },
     { name = "build" },
     { name = "pytest" },
@@ -30,15 +35,17 @@ dev = [
 
 [package.metadata]
 requires-dist = [
-    { name = "claude-agent-sdk", specifier = "==0.2.159" },
+    { name = "claude-agent-sdk", marker = "extra == 'claude'", specifier = "==0.2.159" },
     { name = "filelock", specifier = ">=3.16,<4" },
     { name = "platformdirs", specifier = ">=4,<5" },
     { name = "psutil", specifier = ">=7,<8" },
-    { name = "typed-agent-hooks" },
+    { name = "typed-agent-hooks", specifier = ">=0.3,<0.4" },
 ]
+provides-extras = ["claude"]
 
 [package.metadata.requires-dev]
 dev = [
+    { name = "agent-runtime-py", extras = ["claude"] },
     { name = "basedpyright", specifier = ">=1.31,<2" },
     { name = "build", specifier = ">=1.3,<2" },
     { name = "pytest", specifier = ">=8.4,<9" },
@@ -294,30 +301,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/71/44/711e61f7d014be825ef79b285b047292d1bf893732ac1bc030a351fb517f/cryptography-50.0.1-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:693c99b49bd37d0d096e4334c10232c77248c415b98d35236094cdf96d57258b", size = 3824006, upload-time = "2026-08-25T19:45:37.281Z" },
 ]
 
-[[package]]
-name = "cyclopts"
-version = "4.25.3"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "attrs" },
-    { name = "docstring-parser" },
-    { name = "rich" },
-    { name = "rich-rst" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/c1/08/a444f3cca86cb27bc256831fc8c42b578390f4087bf6631cccb5334bd9ed/cyclopts-4.25.3.tar.gz", hash = "sha256:7d3a067bc7699a1a65fe2ea0b092a925855bb711a05adc1e65c5b9ba307acea4", size = 202814, upload-time = "2026-09-17T16:25:16.892Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/a9/cc/e879da3d54cf727f90e6d90118e132672c3913338b566740486f8797190d/cyclopts-4.25.3-py3-none-any.whl", hash = "sha256:40e76b3153ea90e885abd8d3a4d8184db5a5eec2fde8540025aae8d72fc973fc", size = 242748, upload-time = "2026-09-17T16:25:15.509Z" },
-]
-
-[[package]]
-name = "docstring-parser"
-version = "0.18.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e0/4d/f332313098c1de1b2d2ff91cf2674415cc7cddab2ca1b01ae29774bd5fdf/docstring_parser-0.18.0.tar.gz", hash = "sha256:292510982205c12b1248696f44959db3cdd1740237a968ea1e2e7a900eeb2015", size = 29341, upload-time = "2026-04-14T04:09:19.867Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/a7/5f/ed01f9a3cdffbd5a008556fc7b2a08ddb1cc6ace7effa7340604b1d16699/docstring_parser-0.18.0-py3-none-any.whl", hash = "sha256:b3fcbed555c47d8479be0796ef7e19c2670d428d72e96da63f3a40122860374b", size = 22484, upload-time = "2026-04-14T04:09:18.638Z" },
-]
-
 [[package]]
 name = "filelock"
 version = "3.32.7"
@@ -420,18 +403,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" },
 ]
 
-[[package]]
-name = "markdown-it-py"
-version = "4.2.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "mdurl" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/06/ff/7841249c247aa650a76b9ee4bbaeae59370dc8bfd2f6c01f3630c35eb134/markdown_it_py-4.2.0.tar.gz", hash = "sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49", size = 82454, upload-time = "2026-05-07T12:08:28.36Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" },
-]
-
 [[package]]
 name = "mcp"
 version = "2.2.0"
@@ -470,15 +441,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8f/d7/6ffba5d8cd5dd9b8a19478875c50e04945314ba5074e84d749283f27f62d/mcp_types-2.2.0-py3-none-any.whl", hash = "sha256:ea476b73ee86709ab5abc9452385ed36cc05907e582355622e294595c9a04f13", size = 69106, upload-time = "2026-09-07T16:06:21.461Z" },
 ]
 
-[[package]]
-name = "mdurl"
-version = "0.1.2"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
-]
-
 [[package]]
 name = "nodejs-wheel-binaries"
 version = "24.19.0"
@@ -794,32 +756,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" },
 ]
 
-[[package]]
-name = "rich"
-version = "15.0.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "markdown-it-py" },
-    { name = "pygments" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/c0/8f/0722ca900cc807c13a6a0c696dacf35430f72e0ec571c4275d2371fca3e9/rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36", size = 230680, upload-time = "2026-04-12T08:24:00.75Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" },
-]
-
-[[package]]
-name = "rich-rst"
-version = "2.1.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "pygments" },
-    { name = "rich" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/e2/d6/d0b9fafc73b65767200da027acab1db1bdb1048f4fea5ebf659df01c700e/rich_rst-2.1.0.tar.gz", hash = "sha256:f4d117b49697f338769759fa5cacf5197da4888b347b9fda2e50aef5cd8d93bd", size = 302732, upload-time = "2026-07-05T02:59:44.308Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/2a/68/1fc93dd759605b5d00fc98b50200739e41ed32bd22d6ba35ca6c3932371b/rich_rst-2.1.0-py3-none-any.whl", hash = "sha256:7ecd1343ee12c879d0e7ae74c3eb6d263b023d2929c6d114212eb1fd91057255", size = 272987, upload-time = "2026-07-05T02:59:42.792Z" },
-]
-
 [[package]]
 name = "rpds-py"
 version = "2026.6.3"
@@ -1014,16 +950,14 @@ wheels = [
 
 [[package]]
 name = "typed-agent-hooks"
-version = "0.2.2"
+version = "0.3.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "cyclopts" },
     { name = "pydantic" },
-    { name = "pydantic-core" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/c3/f1/4ca2c710dc12d16cc80cf8484b2c5b8f13e01e3b86c6e0be7814c8fbddbd/typed_agent_hooks-0.2.2.tar.gz", hash = "sha256:dce21e3dc6ec274874d61b02f070a13e8bf00f770937c9b2b5e8e67867f0832f", size = 43992, upload-time = "2026-09-24T09:27:05.76Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/cc/0e/770d2d2cca62894fe170fc266f9b1fefbfde0e6ac03a8873a1ea5f6e33b4/typed_agent_hooks-0.3.0.tar.gz", hash = "sha256:344dd64d87b8b76044b96dae9fa4f0ad2430f1ed1597520b7394058a85e83a55", size = 16284, upload-time = "2026-10-27T20:32:39.757Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a3/8a/ce3318d12c87e0899d2bd371333424010ad596874a0cee90c75479cc1c27/typed_agent_hooks-0.2.2-py3-none-any.whl", hash = "sha256:4d89514fc9a2074fb73dab07106a1bb153201e1f608266b21a232a23fa6425af", size = 60031, upload-time = "2026-09-24T09:27:04.384Z" },
+    { url = "https://files.pythonhosted.org/packages/de/45/b374fadf78a07adaf99649c3d054d43495dc0038593c3aafcf382397bc5f/typed_agent_hooks-0.3.0-py3-none-any.whl", hash = "sha256:b41020aafc2c913da7f362dfd7570da1fc6b9039d403e8078ea5f5ece8ae5dd2", size = 22930, upload-time = "2026-10-27T20:32:38.47Z" },
 ]
 
 [[package]]