# Todo 16 Tool Error Isolation Plan

**Status:** done

## 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

Result:

- Red run passed as expected: direct EventAgent raised `RuntimeError("boom")`, and runtime output collection timed out waiting for a missing tool reply.
- `uv run pytest tests/test_event_agent.py tests/test_debug_runtime.py` passed: 14 tests.
- `uv run pytest` passed: 37 tests, 1 existing Starlette deprecation warning.

## Evaluation

- `EventAgent.handle()` now catches tool handler `Exception` and returns a structured tool reply with `{"tool": name, "error": "tool handler failed: ..."}`.
- Runtime receives that reply through the input queue, emits `tool_result`, and continues to the next ChatAgent call.