Add todo tool with nag reminder injection

Author: ivan-magda

README.md

@@ -2,7 +2,7 @@
 
 Exploring the architecture of coding agents by rebuilding a Claude Code-style CLI from scratch in Swift.
 
-> **Current progress:** Stage 02 of 12 — tool dispatch with `read_file`, `write_file`, `edit_file`
+> **Current progress:** Stage 03 of 12 — todo tracking with nag reminder injection
 
 ![demo](demo.gif)
 
@@ -74,7 +74,7 @@ The minimum viable agent: a loop and a small set of good tools.
 | **00** | Bootstrap: SPM project, two-target layout, CI                          | `00-bootstrap`     |
 | **01** | Agent loop + bash tool                                                 | `01-agent-loop`    |
 | **02** | Tool dispatch: `read_file`, `write_file`, `edit_file` with path safety | `02-tool-dispatch` |
-| 03     | Todo tracking with nag reminder injection                              | —                  |
+| **03** | Todo tracking with nag reminder injection                              | `03-todo-write`    |
 
 ### Phase 2 — Product Mechanics
 

Sources/Core/API/JSONValue.swift

@@ -69,6 +69,13 @@ extension JSONValue {
     return nil
   }
 
+  public var arrayValue: [JSONValue]? {
+    if case .array(let value) = self {
+      return value
+    }
+    return nil
+  }
+
   public var intValue: Int? {
     if case .int(let value) = self {
       return value

Sources/Core/Agent.swift

@@ -1,14 +1,17 @@
 import Foundation
 
 public final class Agent {
-  public static let version = "0.2.0"
+  public static let version = "0.3.0"
+
+  private static let todoReminderThreshold = 3
 
   private let apiClient: any APIClientProtocol
   private let model: String
   private let systemPrompt: String
   private let workingDirectory: String
+
   private let shellExecutor: ShellExecutor
-  private var messages: [Message] = []
+  private let todoManager = TodoManager()
 
   public init(
     apiClient: APIClientProtocol,
@@ -26,7 +29,8 @@ public final class Agent {
   // MARK: - Agent loop
 
   public func run(query: String) async throws -> String {
-    messages.append(.user(query))
+    var messages: [Message] = [.user(query)]
+    var turnsWithoutTodo = 0
 
     while true {
       let request = APIRequest(
@@ -51,11 +55,17 @@ public final class Agent {
       }
 
       var results: [ContentBlock] = []
+      var didUseTodo = false
+
       for block in response.content {
         if case .toolUse(let id, let name, let input) = block {
           printToolCall(name: name, input: input)
           let toolResult = await executeTool(name: name, input: input)
 
+          if name == "todo" {
+            didUseTodo = true
+          }
+
           switch toolResult {
           case .success(let output):
             print("\(ANSIColor.dim)\(String(output.prefix(200)))\(ANSIColor.reset)")
@@ -68,6 +78,11 @@ public final class Agent {
         }
       }
 
+      turnsWithoutTodo = didUseTodo ? 0 : turnsWithoutTodo + 1
+      if turnsWithoutTodo >= Self.todoReminderThreshold && todoManager.hasOpenItems() {
+        results.append(.text("Update your todos."))
+      }
+
       messages.append(Message(role: .user, content: results))
     }
   }
@@ -79,6 +94,7 @@ public final class Agent {
 
     - Prefer read_file/write_file/edit_file over bash for file operations
     - Always check tool results before proceeding
+    - Use the todo tool to plan multi-step tasks. Mark in_progress before starting, completed when done.
     """
   }
 }
@@ -164,6 +180,31 @@ extension Agent {
         ]),
         "required": .array(["path", "old_text", "new_text"])
       ])
+    ),
+    ToolDefinition(
+      name: "todo",
+      description: "Update task list. Track progress on multi-step tasks.",
+      inputSchema: .object([
+        "type": "object",
+        "properties": .object([
+          "items": .object([
+            "type": "array",
+            "items": .object([
+              "type": "object",
+              "properties": .object([
+                "id": .object(["type": "string"]),
+                "text": .object(["type": "string"]),
+                "status": .object([
+                  "type": "string",
+                  "enum": .array(["pending", "in_progress", "completed"])
+                ])
+              ]),
+              "required": .array(["id", "text", "status"])
+            ])
+          ])
+        ]),
+        "required": .array(["items"])
+      ])
     )
   ]
 
@@ -172,7 +213,8 @@ extension Agent {
       "bash": executeBash,
       "read_file": executeReadFile,
       "write_file": executeWriteFile,
-      "edit_file": executeEditFile
+      "edit_file": executeEditFile,
+      "todo": executeTodo
     ]
 
     guard let handler = handlers[name] else {
@@ -294,6 +336,36 @@ extension Agent {
     }
   }
 
+  private func executeTodo(_ input: JSONValue) async -> Result<String, ToolError> {
+    guard let itemsArray = input["items"]?.arrayValue else {
+      return .failure(.missingParameter("items"))
+    }
+
+    var todoItems: [TodoItem] = []
+    for element in itemsArray {
+      guard let id = element["id"]?.stringValue else {
+        return .failure(.missingParameter("items[].id"))
+      }
+      guard let text = element["text"]?.stringValue else {
+        return .failure(.missingParameter("items[].text"))
+      }
+      guard let statusString = element["status"]?.stringValue else {
+        return .failure(.missingParameter("items[].status"))
+      }
+      guard let status = TodoStatus(rawValue: statusString) else {
+        return .failure(.executionFailed("Invalid status '\(statusString)' for item \(id)"))
+      }
+      todoItems.append(TodoItem(id: id, text: text, status: status))
+    }
+
+    do {
+      try todoManager.update(items: todoItems)
+      return .success(todoManager.render())
+    } catch {
+      return .failure(.executionFailed("\(error)"))
+    }
+  }
+
   // MARK: Helpers
 
   private func resolveSafePath(_ relativePath: String) -> Result<String, ToolError> {

Sources/Core/TodoManager.swift

@@ -0,0 +1,73 @@
+import Foundation
+
+public enum TodoStatus: String, Sendable, Equatable, Codable {
+  case pending
+  case inProgress = "in_progress"
+  case completed
+
+  public var marker: String {
+    switch self {
+    case .pending: "[ ]"
+    case .inProgress: "[>]"
+    case .completed: "[x]"
+    }
+  }
+}
+
+public struct TodoItem: Sendable, Equatable, Codable {
+  public let id: String
+  public let text: String
+  public let status: TodoStatus
+
+  public init(id: String, text: String, status: TodoStatus) {
+    self.id = id
+    self.text = text
+    self.status = status
+  }
+}
+
+public final class TodoManager {
+  public static let maxItems = 20
+  public private(set) var items: [TodoItem] = []
+
+  public enum ValidationError: Error, Equatable, Sendable {
+    case tooManyItems
+    case emptyText(String)
+    case multipleInProgress
+  }
+
+  public init() {}
+
+  public func update(items: [TodoItem]) throws {
+    if items.count > Self.maxItems {
+      throw ValidationError.tooManyItems
+    }
+
+    for item in items where item.text.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+      throw ValidationError.emptyText(item.id)
+    }
+
+    let inProgressCount = items.filter { $0.status == .inProgress }.count
+    if inProgressCount > 1 {
+      throw ValidationError.multipleInProgress
+    }
+
+    self.items = items
+  }
+
+  public func render() -> String {
+    if items.isEmpty {
+      return "No todos."
+    }
+
+    let completedCount = items.filter { $0.status == .completed }.count
+    var lines = items.map { "\($0.status.marker) \($0.text)" }
+    lines.append("(\(completedCount)/\(items.count) completed)")
+
+    return lines.joined(separator: "\n")
+  }
+
+  public func hasOpenItems() -> Bool {
+    items.contains { $0.status != .completed }
+  }
+}