Introduced a ToolCallRegistry as the single source of truth for tool call lifecycle data and migrated session todos to typed TodoItem storage with explicit serialization. This removes duplicated tool call tracking and aligns runtime todo state with canonical types.
Context
Tool calls were tracked in separate runtime lists and arg caches, while todos were stored as ad-hoc dicts. Both patterns increased drift risk and made lifecycle semantics inconsistent across the session.
Changes
Tool registry: Added ToolCallRegistry and wired tool dispatch, tool execution failure tracking, and tool return completion updates to the registry.
Runtime state: Removed tool_calls and tool_call_args_by_id, replacing them with runtime.tool_registry.
Todo alignment: Stored todos as TodoItem instances, updated todo tools to emit typed items, and normalized session serialization/deserialization.
Docs: Refreshed codebase-map and refactor docs to reflect registry ownership and typed todos.
Behavioral Impact
What users notice:
Tool lifecycle data is consistent across executions and JSON export paths.
Todo state is typed and validated consistently in todowrite/todoread.
What didn't change:
Tool execution flow and message history semantics remain the same.
Legacy session files still load via dict-to-TodoItem conversion.
Related Cards
[[orphaned-retry-prompt-dangling-cleanup]]
1---2name: 547-2026-01-25-tool-registry-todo-alignment-77ea7dea3description: Summary4---56## Summary78Introduced a ToolCallRegistry as the single source of truth for tool call lifecycle data and migrated session todos to typed TodoItem storage with explicit serialization. This removes duplicated tool call tracking and aligns runtime todo state with canonical types.910## Context1112Tool calls were tracked in separate runtime lists and arg caches, while todos were stored as ad-hoc dicts. Both patterns increased drift risk and made lifecycle semantics inconsistent across the session.1314## Changes1516- **Tool registry**: Added `ToolCallRegistry` and wired tool dispatch, tool execution failure tracking, and tool return completion updates to the registry.17- **Runtime state**: Removed `tool_calls` and `tool_call_args_by_id`, replacing them with `runtime.tool_registry`.18- **Todo alignment**: Stored todos as `TodoItem` instances, updated todo tools to emit typed items, and normalized session serialization/deserialization.19- **Docs**: Refreshed codebase-map and refactor docs to reflect registry ownership and typed todos.2021## Behavioral Impact2223**What users notice:**24- Tool lifecycle data is consistent across executions and JSON export paths.25- Todo state is typed and validated consistently in todowrite/todoread.2627**What didn't change:**28- Tool execution flow and message history semantics remain the same.29- Legacy session files still load via dict-to-TodoItem conversion.3031## Related Cards3233- [[orphaned-retry-prompt-dangling-cleanup]]
Run npx skillmds@latest add tools-only/547-2026-01-25-tool-registry-todo-alignment-77ea7dea in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Summary It is listed under Productivity on SkillMD.
This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
tools-only (@tools-only) published this skill. Their other Agent Skills are listed on their SkillMD profile.
tools-only