fix(tools): normalize Cursor TodoWrite shape and compact failed todo cards

Boundary-normalize content→title before SetTodoList validation, persist
canonical title-only session state, and render validation failures as
compact actionable errors instead of a fake persisted todo tree.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: elkaix

CHANGELOG.md

@@ -29,7 +29,8 @@ GitHub Releases page; `0.8.0` is the new starting line.
   hidden/deferred tools exist (pythinker loads no tools lazily), removing the prompt
   that primed the loop in the first place.
 - **Output-token-limit nudge text aligned with reference.** The system-reminder injected when a response is cut off by the output token limit now matches the reference byte-exactly: "Output token limit hit. Resume directly — no apology, no recap of what you were doing. Pick up mid-thought if that is where the cut happened. Break remaining work into smaller pieces."
-- **`SetTodoList` accepts Cursor-style todo payloads.** Todo items sent with `content` instead of `title` (the shape models learn from Cursor/Claude `TodoWrite`) now validate and persist correctly instead of failing with missing-`title` errors.
+- **`SetTodoList` accepts Cursor-style todo payloads.** Todo items sent with `content` instead of `title` (the shape models learn from Cursor/Claude `TodoWrite`) are normalized at the validation boundary (`content` → `title` when `title` is absent; canonical `title` wins; `content` is dropped) and persist as title-only session state instead of failing with missing-`title` errors.
+- **Failed `SetTodoList` cards stay compact.** Validation failures no longer render a broken todo tree with blank labels plus a raw Pydantic dump; the card shows a short actionable summary (with full detail only when expanded).
 - **ToolSearch scrollback suppression.** Consecutive `ToolSearch` probes during deferred tool discovery are now collapsed: only the last probe in each run is shown in the transcript, mirroring the blackbox `isAbsorbedSilently` contract. Intermediate discovery calls no longer produce repeated "Tools(…)" lines.
 - **Bare skill/flow slash names.** The slash menu now matches `skill:`/`flow:`
   commands on their bare segment, so typing `/designer` (or `/design`) surfaces

src/pythinker_code/tools/todo/__init__.py

@@ -21,21 +21,47 @@
 }
 
 
+def normalize_set_todo_list_args(args: dict[str, Any]) -> dict[str, Any]:
+    """Accept Cursor/Claude TodoWrite shape while keeping internal state canonical.
+
+    Supported external aliases:
+    - ``content`` -> ``title``, only when ``title`` is missing
+
+    Deliberately does not:
+    - invent titles
+    - coerce invalid status values
+    - accept random aliases like text/name/label
+    - mutate the input dict
+    """
+    todos = args.get("todos")
+    if not isinstance(todos, list):
+        return args
+
+    normalized: list[Any] = []
+
+    for raw in cast("list[Any]", todos):
+        if not isinstance(raw, dict):
+            normalized.append(raw)
+            continue
+
+        item = dict(cast(dict[str, Any], raw))
+
+        title = item.get("title")
+        content = item.get("content")
+
+        if title is None and content is not None:
+            item["title"] = content
+
+        item.pop("content", None)
+        normalized.append(item)
+
+    return {**args, "todos": normalized}
+
+
 class Todo(BaseModel):
     title: str = Field(description="The title of the todo", min_length=1)
     status: TodoStatus = Field(description="The status of the todo")
 
-    @model_validator(mode="before")
-    @classmethod
-    def _normalize_todo_write_shape(cls, data: Any) -> Any:
-        """Accept Cursor/Claude TodoWrite shapes that use ``content`` instead of ``title``."""
-        if not isinstance(data, dict):
-            return data
-        values = dict(cast(dict[str, Any], data))
-        if "title" not in values and "content" in values:
-            values["title"] = values["content"]
-        return values
-
     @field_validator("status", mode="before")
     @classmethod
     def _normalize_status(cls, v: Any) -> Any:
@@ -54,6 +80,13 @@ class Params(BaseModel):
         ),
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def _normalize_todo_write_args(cls, data: Any) -> Any:
+        if not isinstance(data, dict):
+            return data
+        return normalize_set_todo_list_args(cast(dict[str, Any], data))
+
     @field_validator("todos", mode="before")
     @classmethod
     def _parse_todos_string(cls, v: Any) -> Any:

src/pythinker_code/ui/shell/tool_renderers/todo.py

@@ -10,12 +10,14 @@
 
 from __future__ import annotations
 
+import re
 from typing import Any, cast
 
 from rich.console import Group, RenderableType
 from rich.table import Table
 from rich.text import Text
 
+from pythinker_code.ui.shell.components import sanitize_ansi
 from pythinker_code.ui.shell.spacing import blank_row
 from pythinker_code.ui.shell.tool_renderers import (
     ToolRenderContext,
@@ -45,6 +47,42 @@
 _TREE_BRANCH = "├─"
 _TREE_LAST = "└─"
 
+_MISSING_TITLE_RE = re.compile(r"todos\.\d+\.title", re.MULTILINE)
+_UNTITLED_TODO = "Untitled todo"
+
+
+def _has_cursor_todowrite_shape(args: dict[str, Any]) -> bool:
+    """True when args look like Cursor/Claude TodoWrite ({content} without {title})."""
+    todos = args.get("todos")
+    if not isinstance(todos, list):
+        return False
+    for raw in cast("list[Any]", todos):
+        if not isinstance(raw, dict):
+            continue
+        item = cast(dict[str, Any], raw)
+        if "content" in item and "title" not in item:
+            return True
+    return False
+
+
+def _failed_todo_badge(todos: list[Any]) -> str:
+    count = len(todos)
+    noun = "item" if count == 1 else "items"
+    return f"update failed · {count} {noun}"
+
+
+def _summarize_todo_validation_error(text: str, args: dict[str, Any]) -> str:
+    """Return a short, actionable summary for SetTodoList validation failures."""
+    if "Error validating JSON arguments:" not in text:
+        return "Todo update failed: invalid arguments."
+    if _MISSING_TITLE_RE.search(text):
+        if _has_cursor_todowrite_shape(args):
+            return (
+                "Todo update failed: each item needs `title` (received `content` without `title`)."
+            )
+        return "Todo update failed: each item needs a `title` field."
+    return "Todo update failed: invalid todo arguments."
+
 
 def _icon_token(status: str) -> str:
     if status == "done":
@@ -56,16 +94,23 @@ def _icon_token(status: str) -> str:
     return "muted"
 
 
+def _clean_todo_title(raw_title: str) -> str:
+    cleaned = " ".join(sanitize_ansi(raw_title).split()).strip()
+    return cleaned or _UNTITLED_TODO
+
+
 def _todo_level_and_title(item: dict[str, Any]) -> tuple[int, str]:
     """Return display nesting level and a cleaned title."""
     raw_title = as_str(item.get("title")) or as_str(item.get("content")) or ""
     explicit = item.get("level", item.get("depth", item.get("indent")))
+    cleaned = _clean_todo_title(raw_title)
+
     if isinstance(explicit, int):
-        return max(0, min(explicit, 6)), raw_title.strip()
+        return max(0, min(explicit, 6)), cleaned
 
     leading_spaces = len(raw_title) - len(raw_title.lstrip(" "))
     level = max(0, min(leading_spaces // 2, 6))
-    return level, raw_title.strip()
+    return level, cleaned
 
 
 def _status_title(status: str, title: str) -> Text:
@@ -82,10 +127,24 @@ def _status_title(status: str, title: str) -> Text:
     return fg("tool_output", title)
 
 
+def _render_error_call(ctx: ToolRenderContext) -> RenderableType:
+    args = ctx.args or {}
+    todos = args.get("todos")
+    badge = "update failed"
+    if isinstance(todos, list):
+        badge = _failed_todo_badge(cast("list[Any]", todos))
+    header = tool_call_header("todos", fg("error", badge), style_token="error")
+    return running_spinner(
+        header, execution_started=ctx.execution_started, has_result=ctx.has_result
+    )
+
+
 def _render_call(ctx: ToolRenderContext) -> RenderableType:
     args = ctx.args or {}
+    if ctx.is_error:
+        return _render_error_call(ctx)
     todos = args.get("todos")
-    style_token = "error" if ctx.is_error else "success" if ctx.has_result else "muted"
+    style_token = "success" if ctx.has_result else "muted"
 
     if todos is None:
         header = tool_call_header("todos", fg("muted", "read"), style_token=style_token)
@@ -163,15 +222,18 @@ def _render_call(ctx: ToolRenderContext) -> RenderableType:
 def _render_result(ctx: ToolRenderContext, result: ToolResultPayload) -> RenderableType | None:
     if not result.text or not result.is_error:
         return None
+    summary = fg("error", _summarize_todo_validation_error(result.text, ctx.args or {}))
+    if not ctx.expanded:
+        return summary
     body, _ = format_lines_block(
         result.text,
         expanded=True,
         collapsed_max_lines=0,
         style_token="error",
     )
     if not body.plain:
-        return None
-    return body
+        return summary
+    return Group(summary, body)
 
 
 TODO_RENDERER = ToolRenderDefinition(

tests/tools/test_todo.py

@@ -8,7 +8,7 @@
 
 from pythinker_code.scratchpad import session_scratch_path
 from pythinker_code.soul.agent import Runtime
-from pythinker_code.tools.todo import Params, SetTodoList, Todo
+from pythinker_code.tools.todo import Params, SetTodoList, Todo, normalize_set_todo_list_args
 from pythinker_code.wire.types import TodoListUpdated
 
 
@@ -27,6 +27,76 @@ def set_todo_list_tool(runtime: Runtime) -> SetTodoList:
     return SetTodoList(runtime)
 
 
+class TestNormalizeSetTodoListArgs:
+    """Boundary normalization: one compatibility alias (content → title), strict elsewhere."""
+
+    def test_normalizes_cursor_todowrite_content_to_title(self):
+        args = {
+            "todos": [{"id": "1", "content": "Install framer-motion", "status": "in_progress"}]
+        }
+        out = normalize_set_todo_list_args(args)
+        assert out["todos"][0]["title"] == "Install framer-motion"
+        assert "content" not in out["todos"][0]
+
+    def test_title_wins_over_content(self):
+        args = {
+            "todos": [
+                {
+                    "title": "Canonical",
+                    "content": "Alias",
+                    "status": "pending",
+                }
+            ]
+        }
+        out = normalize_set_todo_list_args(args)
+        assert out["todos"][0]["title"] == "Canonical"
+        assert "content" not in out["todos"][0]
+
+    def test_normalizer_does_not_mutate_input(self):
+        args = {
+            "todos": [{"content": "Install framer-motion", "status": "pending"}]
+        }
+        original = {
+            "todos": [{"content": "Install framer-motion", "status": "pending"}]
+        }
+        normalize_set_todo_list_args(args)
+        assert args == original
+
+    def test_missing_title_still_fails_after_normalization(self):
+        args = {"todos": [{"id": "1", "status": "pending"}]}
+        out = normalize_set_todo_list_args(args)
+        assert "title" not in out["todos"][0]
+
+    def test_invalid_status_is_not_repaired(self):
+        args = {"todos": [{"content": "Install framer-motion", "status": "started"}]}
+        out = normalize_set_todo_list_args(args)
+        assert out["todos"][0]["title"] == "Install framer-motion"
+        assert out["todos"][0]["status"] == "started"
+
+    def test_non_list_todos_passthrough(self):
+        args = {"todos": {"title": "bad"}}
+        assert normalize_set_todo_list_args(args) == args
+
+    def test_params_title_wins_over_content(self):
+        params = Params(
+            todos=[{"title": "Use this", "content": "Do not use this", "status": "pending"}]  # type: ignore[list-item]
+        )
+        assert params.todos is not None
+        assert params.todos[0].title == "Use this"
+
+    def test_params_empty_title_fails_validation(self):
+        from pydantic import ValidationError
+
+        with pytest.raises(ValidationError):
+            Params(todos=[{"title": "", "status": "pending"}])  # type: ignore[list-item]
+
+    def test_params_invalid_status_fails_validation(self):
+        from pydantic import ValidationError
+
+        with pytest.raises(ValidationError):
+            Params(todos=[{"content": "Install framer-motion", "status": "started"}])  # type: ignore[list-item]
+
+
 class TestParamsJsonStringCoercion:
     """Regression: LLM occasionally passes todos as a JSON-encoded string instead of a list."""
 
@@ -68,6 +138,53 @@ def test_todo_write_merge_field_is_ignored(self):
         assert params.todos is not None
         assert params.todos[0].title == "Task A"
 
+    async def test_cursor_todowrite_shape_persists_normalized_title(
+        self, set_todo_list_tool: SetTodoList, runtime: Runtime
+    ):
+        """Cursor/Claude payloads must normalize ``content`` → ``title`` and persist."""
+        from pythinker_code.session_state import load_session_state
+
+        params = Params(
+            todos=[{"id": "1", "content": "Install framer-motion", "status": "in_progress"}]  # type: ignore[list-item]
+        )
+        result = await set_todo_list_tool(params)
+
+        assert not result.is_error
+        state = load_session_state(runtime.session.dir)
+        assert len(state.todos) == 1
+        assert state.todos[0].title == "Install framer-motion"
+        assert state.todos[0].status == "in_progress"
+
+    async def test_callable_tool_call_accepts_content_shape(
+        self, set_todo_list_tool: SetTodoList
+    ):
+        """``CallableTool2.call`` must accept raw JSON with ``content`` items."""
+        result = await set_todo_list_tool.call(
+            {
+                "todos": [
+                    {"id": "1", "content": "Install framer-motion", "status": "in_progress"},
+                ]
+            }
+        )
+        assert not result.is_error
+        assert "Todo list updated" in result.output
+
+    async def test_validation_failure_does_not_mutate_session(
+        self, set_todo_list_tool: SetTodoList, runtime: Runtime
+    ):
+        """Failed SetTodoList must not change persisted todo state."""
+        from pythinker_code.session_state import load_session_state
+
+        await set_todo_list_tool(Params(todos=[Todo(title="Existing", status="pending")]))
+        result = await set_todo_list_tool.call(
+            {"todos": [{"content": "Replacement", "status": "started"}]}
+        )
+        assert result.is_error
+        state = load_session_state(runtime.session.dir)
+        assert len(state.todos) == 1
+        assert state.todos[0].title == "Existing"
+        assert state.todos[0].status == "pending"
+
     def test_todos_none_still_works(self):
         params = Params(todos=None)
         assert params.todos is None