Skip to content

CLI for SidePulse

Python

Handle Codex interrupt hooks

Peter Kuhar6744439d8e82
diff --git a/README.md b/README.md
index ebf3012..a8264ff 100644
--- a/README.md
+++ b/README.md
@@ -452,6 +452,11 @@ By default, `Tool Running` events are not time-limited, so genuinely long tools
remain visible. If a provider drops completion hooks and you want protection
against stale tool starts, set `--tool-running-timeout`.
+Codex's `Interrupt` hook clears Working, Tool Running, and Ask when a turn is
+interrupted. The session returns to Idle / Ready without being marked completed;
+the next prompt makes it active again. Reinstall the Codex hooks after upgrading
+to register this event. Transcript monitoring is not required.
+
`PostToolUse` means the tool returned, not that the whole turn is finished. The
monitor keeps it as Working for a short settling window while the assistant
writes the response, then treats it as Done if no newer hook event arrives. This
diff --git a/src/sidepulse/collector.py b/src/sidepulse/collector.py
index 529dd08..c0d087a 100644
--- a/src/sidepulse/collector.py
+++ b/src/sidepulse/collector.py
@@ -1061,6 +1061,9 @@ def status_from_event(record: HookEvent, metadata: StatusMetadata | None = None)
def mode_for_event(record: HookEvent) -> AgentMode | None:
event = record.event_name
raw = record.raw
+ if event == "Interrupt":
+ # An interrupted turn is inactive, but has not completed its work.
+ return AgentMode.IDLE_READY
explicit_mode = explicit_mode_for_record(record)
if explicit_mode is not None:
return explicit_mode
@@ -1378,7 +1381,7 @@ def track_pending_permissions(
pending_permissions_by_key.pop(record.status_key, None)
return
- if record.event_name in {"Stop", "SessionEnd", "UserPromptSubmit"}:
+ if record.event_name in {"Stop", "Interrupt", "SessionEnd", "UserPromptSubmit"}:
pending_permissions_by_key.pop(record.status_key, None)
diff --git a/src/sidepulse/install.py b/src/sidepulse/install.py
index 0d2ed8e..edc390e 100644
--- a/src/sidepulse/install.py
+++ b/src/sidepulse/install.py
@@ -653,6 +653,7 @@ def codex_hook_block(
f"[[hooks.{event_name}.hooks]]",
'type = "command"',
f"command = '''{command}'''",
+ *(['timeout = 3'] if event_name == "Interrupt" else []),
"",
]
)
diff --git a/src/sidepulse/providers.py b/src/sidepulse/providers.py
index 7180801..d7e5c42 100644
--- a/src/sidepulse/providers.py
+++ b/src/sidepulse/providers.py
@@ -27,6 +27,7 @@ CODEX_EVENTS = (
"SubagentStart",
"SubagentStop",
"Stop",
+ "Interrupt",
)
CLAUDE_EVENTS = (
diff --git a/tests/test_sidepulse.py b/tests/test_sidepulse.py
index d735acd..c017cb6 100644
--- a/tests/test_sidepulse.py
+++ b/tests/test_sidepulse.py
@@ -90,6 +90,7 @@ from sidepulse.lid_sleep import (
from sidepulse.models import AgentMode, AgentStatus, AggregateStatus
from sidepulse.origin import ProcessInfo, origin_from_processes
from sidepulse.providers import (
+ detect_codex_config_from_text,
detect_grok_config,
default_log_path,
default_state_dir,
@@ -695,6 +696,39 @@ class AgentMonitorTests(unittest.TestCase):
self.assertEqual(reloaded.snapshot().aggregate.mode, AgentMode.TOOL_RUNNING)
self.assertEqual(reloaded.snapshot().statuses[0].origin, "Codex UI")
+ def test_codex_interrupt_clears_active_status_and_permissions(self) -> None:
+ for active_event in ("UserPromptSubmit", "PreToolUse", "PermissionRequest"):
+ with self.subTest(active_event=active_event), tempfile.TemporaryDirectory() as tmp:
+ latest = Path(tmp) / "latest.json"
+ monitor = LiveAgentMonitor(latest_state_path=latest)
+
+ def ingest(event_name):
+ record = parse_log_line("codex", json.dumps({
+ "logged_at": datetime.now(timezone.utc).isoformat(),
+ "event": {
+ "hook_event_name": event_name,
+ "session_id": "interrupted-session",
+ "turn_id": "interrupted-turn",
+ "tool_name": "Bash",
+ "tool_input": {"command": "sleep 100"},
+ },
+ }))
+ self.assertIsNotNone(record)
+ monitor.ingest_record(record)
+
+ ingest(active_event)
+ self.assertEqual(monitor.snapshot().aggregate.active_count, 1)
+ ingest("Interrupt")
+ self.assertEqual(monitor.snapshot().aggregate.active_count, 0)
+ self.assertEqual(monitor.pending_permissions_by_key, {})
+ status = monitor.statuses_by_key["codex:session:interrupted-session"]
+ self.assertEqual(status.mode, AgentMode.IDLE_READY)
+ self.assertEqual(status.event_name, "Interrupt")
+ reloaded = LiveAgentMonitor(latest_state_path=latest)
+ self.assertEqual(reloaded.snapshot().aggregate.active_count, 0)
+ ingest("UserPromptSubmit")
+ self.assertEqual(monitor.snapshot().aggregate.mode, AgentMode.WORKING)
+
def test_live_sidepulse_recovers_stop_missed_during_restart(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
base = Path(tmp)
@@ -3242,6 +3276,11 @@ class AgentMonitorTests(unittest.TestCase):
self.assertIn("--provider codex", text)
self.assertIn(str(log), text)
self.assertNotIn("echo old", text)
+ self.assertIn("[[hooks.Interrupt]]", text)
+ self.assertIn("timeout = 3", text.split("[[hooks.Interrupt.hooks]]")[1])
+ self.assertIn("Interrupt", detect_codex_config_from_text(config, text).hook_events)
+ install_codex_hooks(log_path=log, config_path=config, python_executable="python3")
+ self.assertEqual(config.read_text().count("[[hooks.Interrupt]]"), 1)
def test_codex_installer_refreshes_managed_hook_trust_hashes(self) -> None:
with tempfile.TemporaryDirectory() as tmp: