# ADR-0007: Todo — Persistent Task Tracking

**Status:** Accepted
**Date:** 2026-05-13
**Extension:** `extensions/todo/index.ts` (374 lines)

## Problem

Multi-step tasks lose track of progress. Completed items fade after compaction. Agent repeats work or loses its place. Plain text todos in messages are lost after compaction.

## Decision

`todo` tool: `list`, `add`, `toggle`, `clear`. Key mechanism:

- State persisted in session state — survives compaction
- `reconstructState` replays session history to rebuild from scratch on every invocation — survives crashes
- Unique incrementing IDs per todo

## Alternatives

| Approach                 | Why Rejected          |
| ------------------------ | --------------------- |
| Text todos in messages   | Lost after compaction |
| External file (todos.md) | Extra file management |
| In-memory only           | Lost on crash/restart |

## Trade-offs

Session-scoped only — new session = new task scope. History replay on every call is O(n) in message count but n is small (<100 in practice).

## References

- arXiv 2604.18071: "file-persistent and hybrid strategies" favored
- [Agent Harness pattern](https://agentpatterns.ai/agent-design/agent-harness/) — handoff artifacts for session continuity
