docs: todo__ tools are unavailable in llm nodes (validation error); use agent nodes with auto_continue children for driven work

Graph-Agents.md

@@ -702,16 +702,27 @@ list; an unknown entry is a startup error.
 Coyote's built-in function families are not all governed by the `tools:`
 whitelist the same way:
 
-- **`user__*` and `todo__*` require explicit opt-in.** Inside an `llm` node
+- **`user__*` requires explicit opt-in.** Inside an `llm` node the
-  these interactive/turn-control builtins are only offered to the model if
+  interactive builtins are only offered to the model if the node's `tools:`
-  the node's `tools:` list names them (e.g. `tools: [user__select]`). A node
+  list names them (e.g. `tools: [user__select]`). A node that doesn't list
-  that doesn't list them never sees them. This is deliberate: graph nodes
+  them never sees them. This is deliberate: graph nodes usually run headless,
-  usually run headless, and a structured-output node calling `user__select`
+  and a structured-output node calling `user__select` ("Ready to finalize?")
-  ("Ready to finalize?") suspends the node as an escalation instead of
+  suspends the node as an escalation instead of producing its output. The
-  producing its output. The graph validator warns when a node with an
+  graph validator warns when a node with an `output_schema` explicitly opts
-  `output_schema` explicitly opts into `user__*` tools. Approval gates are
+  into `user__*` tools. Approval gates are unaffected — use a
-  unaffected — use a [`approval` node](#approval) for human sign-off, not an
+  [`approval` node](#approval) for human sign-off, not an `llm` node with
-  `llm` node with user tools.
+  user tools.
+- **`todo__*` is unavailable in `llm` nodes entirely**. Listing a todo tool
+  in a node's `tools:` is a validation **error**. The todo system drives chat
+  turn loops (`auto_continue`): the usage prompt, the incomplete-item check
+  at turn end, and the continuation nudge all live at the agent turn
+  boundary. An `llm` node has no turn boundary. Its continuation is owned
+  by the node's tool-call loop, `max_iterations`, and graph edges. So a
+  node-local todo list would never be driven to completion and its writes
+  would leak into agent/session state. For driven multi-step work inside a
+  graph, use an [`agent` node](#agent) whose agent sets
+  `auto_continue: true`: spawned children get a fresh todo list and are
+  pushed to completion normally.
 - **`agent__*`, `memory__*`, `job__*`, `skill__*`, and RAG builtins stay
   implicitly available** (subject to their usual gates: `can_spawn_agents`
   for spawning, the skill policy for skills, and so on) regardless of the