feat(graph): add session todo list tool and documentation

Add the `SessionTodoTool` as a simpler model-facing interface over the existing todo store, alongside documentation explaining its usage and differences from the kanban board. The session list uses a single-call write model keyed by thread ID, with all argument problems returned as recoverable tool errors rather than fatal run errors.

Auto-committed-on: macbook

Author: senamakel

crates/tinyagents-graph/src/todos/test.rs

@@ -664,7 +664,11 @@ mod session_list_tests {
         }
     }
 
-    async fn run(tool: &SessionTodoTool, thread: Option<&str>, args: serde_json::Value) -> ToolResult {
+    async fn run(
+        tool: &SessionTodoTool,
+        thread: Option<&str>,
+        args: serde_json::Value,
+    ) -> ToolResult {
         let context = ThreadContext(thread.map(str::to_owned));
         tool.execute_with_context(args, Default::default(), Some(&context))
             .await
@@ -711,7 +715,11 @@ mod session_list_tests {
         )
         .await;
         let p = raw(&rewritten);
-        assert_eq!(p["todos"].as_array().unwrap().len(), 1, "a write is the whole list");
+        assert_eq!(
+            p["todos"].as_array().unwrap().len(),
+            1,
+            "a write is the whole list"
+        );
         assert_eq!(p["todos"][0]["status"], "completed");
 
         let cleared = run(&tool, Some("t"), json!({ "todos": [] })).await;
@@ -721,8 +729,12 @@ mod session_list_tests {
     #[tokio::test]
     async fn lists_are_keyed_by_thread() {
         let tool = SessionTodoTool::new(store());
-        run(&tool, Some("a"), json!({ "todos": [{ "content": "only a", "status": "pending" }] }))
-            .await;
+        run(
+            &tool,
+            Some("a"),
+            json!({ "todos": [{ "content": "only a", "status": "pending" }] }),
+        )
+        .await;
         let b = run(&tool, Some("b"), json!({})).await;
         assert!(raw(&b)["todos"].as_array().unwrap().is_empty());
     }
@@ -734,10 +746,19 @@ mod session_list_tests {
     async fn bad_input_is_a_tool_error_not_an_err() {
         let tool = SessionTodoTool::new(store());
         for (args, expect) in [
-            (json!({ "todos": [{ "content": "  ", "status": "pending" }] }), "content"),
-            (json!({ "todos": [{ "content": "x", "status": "someday" }] }), "invalid status"),
+            (
+                json!({ "todos": [{ "content": "  ", "status": "pending" }] }),
+                "content",
+            ),
+            (
+                json!({ "todos": [{ "content": "x", "status": "someday" }] }),
+                "invalid status",
+            ),
             (json!({ "todos": "not a list" }), "invalid `todos`"),
-            (json!({ "cards": [{ "content": "x", "status": "todo" }] }), "pass `todos`"),
+            (
+                json!({ "cards": [{ "content": "x", "status": "todo" }] }),
+                "pass `todos`",
+            ),
             (
                 json!({ "todos": [
                     { "content": "a", "status": "in_progress" },

docs/modules/graph/todos.md

@@ -85,3 +85,31 @@ Unit tests in `crates/tinyagents-graph/src/todos/test.rs` (types, store invarian
 end-to-end model-driven tool run in `tests/e2e_graph_todos.rs`; feature coverage
 for the run lifecycle in `tests/feature_graph_task_runs.rs`; and the full
 dispatch loop in `tests/e2e_graph_task_dispatch.rs`.
+
+## Session todo list (`todos::session_list`)
+
+Not every host wants a dispatchable kanban board. `SessionTodoTool` is the
+other model-facing shape over the same store: the session todo list Claude
+Code and Codex use.
+
+- One call writes the whole list: `{"todos": [{"content": "...", "status":
+  "pending" | "in_progress" | "completed"}]}`. An empty list clears it; a call
+  with no arguments reads it back. There is no `op`, no ids, no approval
+  gate, evidence, plan or blocker.
+- It shares `store::replace` / `store::list`, so ordering, the
+  single-`in_progress` invariant and the markdown rendering are the board's.
+  Board-only states fold on the way out (`ready`/`awaiting_approval`/
+  `blocked` → `pending`, `rejected` → `completed`).
+- The list is keyed by `ToolRunContext::thread_id`. A host that scopes lists
+  by something else (an agent session id, say) calls
+  `session_list::call(store, key, &args)` or `write` / `read` with its own
+  key instead of the `Tool` entry point.
+- Every argument problem — wrong key (`cards`), a non-array, empty content,
+  an unknown status, two `in_progress` items — is a `ToolResult::error` the
+  model can correct. It is never an `Err`: an `Err` out of a tool dispatch is
+  fatal to the run, and a host lost a turn exactly that way when a model sent
+  the retired `{"cards": …}` shape to a host-side copy of this tool.
+
+Register with `register_session_todo_tool(&mut registry, store)` in place of
+`register_todo_tools`; the two share the name `todo`, so a registry holds one
+or the other.