docs: document agent pair and todo tools

.claude/skills/docs/watermark

@@ -1 +1 @@
-6f3275f2be085b1e94f4f82b7cb76f826e9e00e3
+462f6982a8a78dbd63f1af24ce70401db6c2dd21

docs/public/agents/mcp.mdx

@@ -32,6 +32,7 @@ Pass `--server` when the MCP client should connect to a specific Fabro server, o
 | `fabro_run_search` | Search runs by ID, parent, workflow, labels, status, archive state, and creation time. |
 | `fabro_run_interact` | Get, start, message, cancel, archive, unarchive, link or unlink a parent, inspect questions, or answer a run. |
 | `fabro_run_gather` | Wait for runs to reach terminal states, returning current state on timeout. |
+| `fabro_run_pair` | Inspect, start, message, end, or read transcript for a live run pairing session. |
 | `fabro_run_events` | List, inspect, or search stored events for a run. |
 
 For a simple create call, `fabro_run_create` accepts a workflow selector string:
@@ -61,6 +62,16 @@ Use `goal` for inline goal text or `goal_file` to read the run goal from a file.
 
 Run summaries returned by the MCP server include parent metadata. Use `parent_id` on `fabro_run_create` to create a child run, `parent_id` on `fabro_run_search` to list direct children, and the `link_parent` or `unlink_parent` actions on `fabro_run_interact` to change an existing run's parent.
 
+Use `fabro_run_pair` when an MCP client needs to pair with an active API-mode agent stage. The tool can inspect current pair status, start a pair session for a selected stage, send messages, end the session, and read transcript entries.
+
+```json
+{
+  "action": "start",
+  "run_id": "01K...",
+  "stage_id": "implement@1"
+}
+```
+
 ## Fabro agents as MCP clients
 
 When an agent session starts with MCP servers configured, Fabro:

docs/public/agents/tools.mdx

@@ -31,6 +31,8 @@ Some tools are only available with certain LLM providers:
 |---|---|---|
 | `edit_file` | Anthropic, Gemini | Replace a string in a file (find-and-replace) |
 | `apply_patch` | OpenAI | Apply a v4a-format patch to modify files |
+| `update_plan` | OpenAI | Maintain a multi-step plan for the current task |
+| `TaskCreate`, `TaskUpdate`, `TaskList` | Anthropic | Maintain a shared task list for the root agent session |
 | `read_many_files` | Gemini | Read multiple files in a single call |
 | `list_dir` | Gemini | List directory contents with depth control |
 
@@ -173,6 +175,27 @@ Lists directory contents with optional depth control. Available for Gemini.
 
 Directories are suffixed with `/` in the output.
 
+### update_plan
+
+Maintains the current task plan. Available for OpenAI providers.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `plan` | object[] | yes | Full ordered list of plan steps |
+| `plan[].step` | string | yes | Step text; step text must be unique within the plan |
+| `plan[].status` | string | yes | `pending`, `in_progress`, or `completed` |
+| `explanation` | string | no | Short note explaining why the plan changed |
+
+The submitted list replaces the current plan for that OpenAI session. Fabro reconciles steps by exact step text, emits `todo.created`, `todo.updated`, and `todo.deleted` events for changes, and projects the current list into run state.
+
+### TaskCreate, TaskUpdate, and TaskList
+
+Maintains a shared task list for Anthropic providers. The list is scoped to the root agent session, so sub-agents share the same task projection.
+
+`TaskCreate` creates a task with `subject`, `description`, optional `activeForm`, and optional metadata. `TaskUpdate` changes an existing task by `taskId`; setting `status` to `deleted` removes it from the projection. `TaskList` returns the current shared task list.
+
+Like `update_plan`, task changes are persisted as `todo.created`, `todo.updated`, and `todo.deleted` events and replay into run state.
+
 ## Read-before-write guardrail
 
 Fabro wraps every sandbox in a `ReadBeforeWriteSandbox` decorator that tracks which files the agent has seen. The rules are:

docs/public/execution/observability.mdx

@@ -25,6 +25,7 @@ Event names use lowercase dot notation, for example:
 - `agent.tool.started`
 - `agent.tool.completed`
 - `sandbox.ready`
+- `todo.updated`
 - `parallel.branch.completed`
 
 ### Envelope format
@@ -92,6 +93,7 @@ Common categories include:
 | Run lifecycle | `run.started`, `run.completed`, `run.failed`, `run.notice` |
 | Stage lifecycle | `stage.started`, `stage.completed`, `stage.failed`, `stage.retrying` |
 | Agent activity | `agent.message`, `agent.tool.started`, `agent.warning`, `agent.sub.spawned` |
+| Agent todo state | `todo.created`, `todo.updated`, `todo.deleted` |
 | Routing | `edge.selected`, `loop.restart`, `parallel.started` |
 | Git and checkpoints | `checkpoint.completed`, `git.commit`, `git.push` |
 | Setup and sandbox | `sandbox.initializing`, `sandbox.ready`, `setup.started` |