docs: plan tool error isolation

docs/plans/todo-16-tool-error-isolation.md

@@ -0,0 +1,60 @@
+# Todo 16 Tool Error Isolation Plan
+
+**Status:** in_progress
+
+## Goal
+
+Convert EventAgent tool handler exceptions into structured tool-result errors instead of aborting or hanging the debug session.
+
+## Why
+
+Dynamic EventAgent tools will eventually call real code. A single tool exception should be visible to the ChatAgent as a tool reply, not break the WebSocket session or leave the runtime waiting forever for a tool response.
+
+## Scope
+
+This todo covers:
+
+- Catch `Exception` from registry tool handlers.
+- Return a `ChatMessage(role="tool")` containing a JSON error payload.
+- Prove runtime continues to the next ChatAgent call after a failing tool.
+
+This todo does not cover:
+
+- Retry policies.
+- Tool timeout controls.
+- Full traceback exposure.
+
+## Files
+
+- Modify: `src/agent_lab/application/event_agent.py`
+- Modify: `tests/test_event_agent.py`
+- Modify: `tests/test_debug_runtime.py`
+- Modify: `docs/plans/todos.md`
+- Modify: this plan
+
+## Steps
+
+1. Add failing EventAgent test for a registry handler that raises `RuntimeError("boom")`.
+2. Add failing runtime test proving a failing handler emits `tool_result` and reaches `done`.
+3. Catch handler exceptions in `EventAgent.handle()` and return payload:
+
+```json
+{"tool": "handoff_note", "error": "tool handler failed: boom"}
+```
+
+4. Run:
+
+```bash
+uv run pytest tests/test_event_agent.py tests/test_debug_runtime.py
+uv run pytest
+```
+
+5. Update this plan and `docs/plans/todos.md`, then commit.
+
+## Verification
+
+Expected result:
+
+- Direct EventAgent tests prove structured tool errors.
+- Runtime tests prove the WebSocket stream contract stays structured.
+- Full suite passes.

docs/plans/todos.md

@@ -42,4 +42,4 @@
 | 13 | done | `docs/plans/todo-13-real-queue-websocket-loop.md` | Make runtime queues real producer/consumer boundaries and let WebSocket run separate upstream/downstream tasks. | `uv run pytest tests/test_debug_runtime.py tests/test_websocket_api.py`; `uv run pytest`. |
 | 14 | done | `docs/plans/todo-14-message-role-validation.md` | Reject provider-invalid API message roles and malformed tool replies before network calls. | `uv run pytest tests/test_websocket_api.py tests/test_event_agent.py`; `uv run pytest`. |
 | 15 | done | `docs/plans/todo-15-static-package-data.md` | Include static UI assets in installed package builds. | `uv run pytest tests/test_packaging.py`; `uv run pytest`; `uv build`; wheel inspection. |
-| 16 | pending | `docs/plans/todo-16-tool-error-isolation.md` | Convert EventAgent tool handler exceptions into structured tool-result errors instead of aborting the session. | Tests prove a failing tool returns an error payload and the WebSocket run stays structured. |
+| 16 | in_progress | `docs/plans/todo-16-tool-error-isolation.md` | Convert EventAgent tool handler exceptions into structured tool-result errors instead of aborting the session. | Tests prove a failing tool returns an error payload and the WebSocket run stays structured. |