pikuri-tasks 0.0.6 → 0.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ceab6f3f6999fb22176982adb511db13d445cba7044a435492071f2308f4eae
-  data.tar.gz: da032f405772ada2943df18113c1b4670799003069c5f329676d4bdc765d4397
+  metadata.gz: 113302bc63d0e9bd10c56550592d8e0aee68212fd1ee2cfe4032b8d1f2836b2c
+  data.tar.gz: 7d9e4351247953a5b7d7f5e54acbd68ace82404966bdeca47389b81804f2714e
 SHA512:
-  metadata.gz: 7e74049b277b94b546f6e7a6a237e0e595aee40c7bd78fb7029bdb75c9eca36d52144ea97cd71f7215dfcf7a1dbea8c8270c6ef6f8125bd256b27c413d8a2566
-  data.tar.gz: 8a46f113b26b1014b34b434fe8b2a79eccef7c2a587dc4ffff8ead471b96ebbf5f8c4cb642934938ef244b39cc5cde6ea4f6ac9a0d272322edbccff05c5a5e24
+  metadata.gz: b287b65b9b99bd77966901c622aa503942cd02b09bbc8b10a2a43451dac01754136666bb7df53473990d31eed5ff2a5bd41213bdff08635bfe9657d92bce1412
+  data.tar.gz: 760eed62da11196fd09c3bcbb5bd8036e3697683bedd6d7c3eeb86ed5ce1aa2baeaf325b1780bb9ab285ef38ee12d8ec3b65773b794945cbf6ff76898b17b64f

data/README.md

@@ -5,19 +5,19 @@ In-memory task list + four LLM-facing tools for the
 
 Provides:
 - `Pikuri::Tasks::List` — per-Agent in-memory list of
-  `(content, status)` items. Status is one of `pending`,
+  `(id, content, status)` items. Status is one of `pending`,
   `in_progress`, `completed`. Nothing is written to disk.
 - Four tool classes, all sharing one `List` instance:
   - `Pikuri::Tasks::Create` (`task_create`) — mass-create pending
-    items from a newline-separated `items` string. Atomic: if any
-    line is a duplicate (within the batch or already on the list),
-    nothing is added.
+    items from a JSON array of strings. Atomic: if any element is
+    blank or a duplicate (within the batch or already on the
+    list), nothing is added.
   - `Pikuri::Tasks::InProgress` (`task_in_progress`) — mark an item
-    as `in_progress` by content.
+    as `in_progress` by numeric id.
   - `Pikuri::Tasks::Completed` (`task_completed`) — mark an item as
-    `completed` by content.
+    `completed` by numeric id.
   - `Pikuri::Tasks::Delete` (`task_delete`) — remove an item by
-    content.
+    numeric id.
 - `Pikuri::Tasks::Extension` — wires the four tools + a brief
   `<tasks_usage>` workflow snippet into a `Pikuri::Agent` via the
   `c.add_extension(...)` block API.
@@ -25,10 +25,12 @@ Provides:
 Two shape choices worth flagging:
 - **Status is baked into the tool name** (no `status:` parameter
   with an enum). Removes the `"in-progress"` vs `"in_progress"`
-  vs `"inprogress"` typo failure mode on smaller models.
-- **Content doubles as identifier** across the three update tools
-  (no item IDs to bookkeep). Duplicates are rejected on
-  `task_create` so the identifier stays unique.
+  vs `"inprogress"` typo failure mode.
+- **Items are addressed by numeric id** — assigned on create,
+  shown in every rendered list, never reused after a delete. A
+  near-miss when re-typing the task's content cannot lock the
+  model out of its own list; duplicates are still rejected on
+  `task_create` because they are almost always a mistake.
 
 ## Install
 
@@ -59,9 +61,9 @@ so the LLM always sees fresh state without a separate read tool:
 
 ```
 <tasks>
-- [pending] Add dark mode toggle
-- [in_progress] Write unit tests
-- [completed] Update README
+- #1 [pending] Add dark mode toggle
+- #2 [in_progress] Write unit tests
+- #3 [completed] Update README
 </tasks>
 ```
 

data/lib/pikuri/tasks/completed.rb

@@ -2,25 +2,25 @@
 
 module Pikuri
   module Tasks
-    # The +task_completed+ tool: mark the item whose +content+ exactly
-    # matches as +completed+. Same shape and rationale as
-    # {InProgress} — the status is baked into the tool name to remove
-    # the enum-typo failure mode small models hit on
-    # +"completed"+ / +"complete"+ / +"done"+.
+    # The +task_completed+ tool: mark the item with the given +id+ as
+    # +completed+. Same shape and rationale as {InProgress} — the
+    # status is baked into the tool name to remove the enum-typo
+    # failure mode (+"completed"+ / +"complete"+ / +"done"+), and the
+    # item is addressed by the numeric +#id+ from the rendered list.
     #
-    # Returns the rendered current list via {List#render} on success,
-    # or +"Error: no such task: '<content>'"+ when the content does
-    # not match.
+    # Returns the rendered current list via {List#render} on success.
+    # On a bad id returns +"Error: no such task id: <id>"+ plus the
+    # current list, so the LLM can pick the right id in one turn.
     class Completed < Pikuri::Tool
       # @return [String]
       DESCRIPTION = <<~DESC
         Mark a task as `completed` once the work — including any required verification — is actually done.
 
         Usage:
-        - Pass the exact `content` string the task was created with.
+        - Pass the task's numeric `id` as shown in the rendered list (`- #3 [in_progress] ...` → id 3).
         - Do NOT mark `completed` based on intent; mark it only after the underlying work is verified.
         - If the work is partially done or blocked, leave the task `in_progress` and add a follow-up via `task_create`.
-        - On `Error: no such task: ...` the call did nothing — read the returned list in any subsequent tool's output to pick the right name.
+        - On `Error: no such task id: ...` the call did nothing — the error includes the current list; pick the right id from it.
         - On success the full current list is returned for you to read back.
       DESC
 
@@ -31,24 +31,24 @@ module Pikuri
           name: 'task_completed',
           description: DESCRIPTION,
           parameters: Pikuri::Tool::Parameters.build { |p|
-            p.required_string :content,
-                              'Exact content of the existing task to mark as ' \
-                              'completed, e.g. "Add dark mode toggle".'
+            p.required_integer :id,
+                               'Numeric id of the existing task to mark as ' \
+                               'completed, as shown in the rendered list, e.g. 3.'
           },
-          execute: lambda { |content:|
-            Completed.execute(list: list, content: content)
+          execute: lambda { |id:|
+            Completed.execute(list: list, id: id)
           }
         )
       end
 
       # @param list [List]
-      # @param content [String]
+      # @param id [Integer]
       # @return [String]
-      def self.execute(list:, content:)
-        list.set_status(content: content, status: 'completed')
+      def self.execute(list:, id:)
+        list.set_status(id: id, status: 'completed')
         list.render
       rescue ItemNotFound
-        "Error: no such task: '#{content}'"
+        "Error: no such task id: #{id}. Current list:\n#{list.render}"
       end
     end
   end

data/lib/pikuri/tasks/create.rb

@@ -3,22 +3,27 @@
 module Pikuri
   module Tasks
     # The +task_create+ tool: mass-create pending items in a single
-    # call from a newline-separated +items+ string. Why
-    # newline-separated rather than a JSON array: it stays within
-    # pikuri's scalar-only +Tool::Parameters+ DSL (no array support
-    # to extend), and a smaller model never has to balance brackets
-    # or escape quotes — fewer formatting failure modes on the burst
-    # of items that opens most multi-step work.
+    # call from a JSON array of strings — a native +items+ array
+    # parameter, the shape every mainstream harness's task tool uses
+    # and therefore the shape the model's training prior produces
+    # unprompted. (An earlier newline-separated-string design tried to
+    # spare small models the bracket-balancing; in practice models
+    # sent JSON arrays anyway — the prior beats the parameter
+    # description — and the splitter turned `[`, `"foo",`, `]` into
+    # garbage tasks. Match the prior instead of fighting it.)
     #
-    # Each line is right- and left-stripped; blank lines are skipped.
-    # If any input is a duplicate (within the batch, or already in
-    # the list), the whole call aborts with an +"Error: ..."+ string
-    # and nothing is added — the LLM resends a corrected batch on the
+    # Each element is whitespace-stripped; a blank element aborts the
+    # call (it is always an LLM mistake, never intent). If any input
+    # is a duplicate (within the batch, or already in the list), the
+    # whole call likewise aborts with an +"Error: ..."+ string and
+    # nothing is added — the LLM resends a corrected batch on the
     # next turn. Atomic semantics keep the list in a coherent state
     # the LLM doesn't have to reconcile.
     #
-    # On success returns the rendered current list via {List#render},
-    # so the LLM always sees fresh state without a separate read tool.
+    # On success returns the rendered current list via {List#render} —
+    # including each new item's +#id+, which the three mutation tools
+    # address items by — so the LLM always sees fresh state without a
+    # separate read tool.
     class Create < Pikuri::Tool
       # @return [String] static description shown to the LLM,
       #   opencode-shape (summary + +Usage:+ bullets).
@@ -27,10 +32,9 @@ module Pikuri
 
         Usage:
         - Use at the start of a multi-step task to capture the plan.
-        - `items` is a single newline-separated string — one task per line. Blank lines are ignored.
-        - Duplicate content (within the batch or already on the list) aborts the whole call with `Error: ...` and adds nothing — resend a corrected batch.
-        - Empty input is rejected the same way.
-        - On success the full current list is returned for you to read back.
+        - `items` is a JSON array of strings — one task per element.
+        - A blank element, a duplicate (within the batch or already on the list), or an empty array aborts the whole call with `Error: ...` and adds nothing — resend a corrected batch.
+        - On success the full current list is returned, with each task's `#id` — use that id with `task_in_progress` / `task_completed` / `task_delete`.
       DESC
 
       # @param list [List] the shared per-Agent list, captured by
@@ -42,10 +46,9 @@ module Pikuri
           name: 'task_create',
           description: DESCRIPTION,
           parameters: Pikuri::Tool::Parameters.build { |p|
-            p.required_string :items,
-                              'Newline-separated list of task contents, e.g. ' \
-                              '"Add dark mode toggle\nWrite unit tests\nUpdate README". ' \
-                              'Blank lines are ignored.'
+            p.required_string_array :items,
+                                    'Task contents, one task per array element, e.g. ' \
+                                    '["Add dark mode toggle", "Write unit tests", "Update README"].'
           },
           execute: lambda { |items:|
             Create.execute(list: list, items: items)
@@ -57,12 +60,16 @@ module Pikuri
       # without constructing a tool instance.
       #
       # @param list [List]
-      # @param items [String] raw +items+ argument from the LLM.
+      # @param items [Array<String>] raw +items+ argument from the LLM
+      #   (already type-validated by {Pikuri::Tool::Parameters}).
       # @return [String] either {List#render} on success or an
       #   +"Error: ..."+ string the LLM can react to.
       def self.execute(list:, items:)
-        cleaned = items.lines.map(&:strip).reject(&:empty?)
-        return 'Error: task_create requires at least one non-blank item' if cleaned.empty?
+        return 'Error: task_create requires at least one item' if items.empty?
+
+        cleaned = items.map(&:strip)
+        blank = cleaned.index('')
+        return "Error: blank item at index #{blank} — every element must be non-blank task text" if blank
 
         seen_in_batch = {}
         cleaned.each do |c|

data/lib/pikuri/tasks/delete.rb

@@ -2,29 +2,31 @@
 
 module Pikuri
   module Tasks
-    # The +task_delete+ tool: remove the item whose +content+ exactly
-    # matches from the list. Used to drop items that turned out to be
-    # unnecessary, were created in error, or have been superseded —
-    # rather than leaving them sitting in +pending+ as visual noise.
+    # The +task_delete+ tool: remove the item with the given +id+ from
+    # the list. Used to drop items that turned out to be unnecessary,
+    # were created in error, or have been superseded — rather than
+    # leaving them sitting in +pending+ as visual noise.
     #
     # Distinct from {Completed}: +completed+ means the work was
     # actually done; +delete+ means the task should never have been
     # there. The list itself draws no such distinction once an item
     # is gone, but the LLM picks the right verb because the tool
-    # names make the intent clear.
+    # names make the intent clear. A deleted item's id is never
+    # reused (see {List#add}), so a stale id errors loudly instead of
+    # silently hitting a newer task.
     #
-    # Returns the rendered current list via {List#render} on success,
-    # or +"Error: no such task: '<content>'"+ when the content does
-    # not match.
+    # Returns the rendered current list via {List#render} on success.
+    # On a bad id returns +"Error: no such task id: <id>"+ plus the
+    # current list, so the LLM can pick the right id in one turn.
     class Delete < Pikuri::Tool
       # @return [String]
       DESCRIPTION = <<~DESC
         Remove a task from the list. Use this for items that turn out not to be needed, were created in error, or have been superseded.
 
         Usage:
-        - Pass the exact `content` string the task was created with.
+        - Pass the task's numeric `id` as shown in the rendered list (`- #3 [pending] ...` → id 3).
         - Use `task_completed` (not this) when the work was actually done.
-        - On `Error: no such task: ...` the call did nothing — read the returned list in any subsequent tool's output to pick the right name.
+        - On `Error: no such task id: ...` the call did nothing — the error includes the current list; pick the right id from it.
         - On success the full current list is returned for you to read back.
       DESC
 
@@ -35,24 +37,24 @@ module Pikuri
           name: 'task_delete',
           description: DESCRIPTION,
           parameters: Pikuri::Tool::Parameters.build { |p|
-            p.required_string :content,
-                              'Exact content of the existing task to remove, ' \
-                              'e.g. "Add dark mode toggle".'
+            p.required_integer :id,
+                               'Numeric id of the existing task to remove, ' \
+                               'as shown in the rendered list, e.g. 3.'
           },
-          execute: lambda { |content:|
-            Delete.execute(list: list, content: content)
+          execute: lambda { |id:|
+            Delete.execute(list: list, id: id)
           }
         )
       end
 
       # @param list [List]
-      # @param content [String]
+      # @param id [Integer]
       # @return [String]
-      def self.execute(list:, content:)
-        list.delete(content)
+      def self.execute(list:, id:)
+        list.delete(id)
         list.render
       rescue ItemNotFound
-        "Error: no such task: '#{content}'"
+        "Error: no such task id: #{id}. Current list:\n#{list.render}"
       end
     end
   end

data/lib/pikuri/tasks/extension.rb

@@ -3,13 +3,16 @@
 module Pikuri
   # Namespace for the in-memory task-list feature. Holds the
   # {List} value type, the four task tool classes ({Create},
-  # {InProgress}, {Completed}, {Delete}), and the {Extension} that
-  # wires them into an {Pikuri::Agent}.
+  # {InProgress}, {Completed}, {Delete}), the {ListChanged} domain
+  # event, and the {Extension} that wires them into an
+  # {Pikuri::Agent}.
   module Tasks
     # An {Pikuri::Agent::Extension} that auto-wires an in-memory
     # task list onto an agent: constructs a fresh {List}, registers
-    # the four task tool classes against it, and appends a brief
-    # workflow snippet to the system prompt.
+    # the four task tool classes against it, appends a brief
+    # workflow snippet to the system prompt, and (in {#bind}) arms
+    # {ListChanged} emission so listeners can observe every list
+    # mutation.
     #
     # == Usage
     #
@@ -51,14 +54,14 @@ module Pikuri
         You have an in-memory task list. Use it to plan and track multi-step work.
 
         Workflow:
-        - When a task has 3+ steps, call `task_create` once with the full plan (newline-separated items, all start as `pending`).
-        - Before starting an item, call `task_in_progress` with its exact content. Keep exactly one item `in_progress` at a time.
-        - When an item is fully done (including any required verification), call `task_completed` with its exact content.
+        - When a task has 3+ steps, call `task_create` once with the full plan (a JSON array of strings, all start as `pending`).
+        - Before starting an item, call `task_in_progress` with its numeric id. Keep exactly one item `in_progress` at a time.
+        - When an item is fully done (including any required verification), call `task_completed` with its numeric id.
         - Use `task_delete` to remove items that turn out not to be needed.
 
         Skip task tracking entirely for single-step or purely informational requests — it adds noise, not value.
 
-        Every mutation returns the full current list, so you do not need a separate read tool. Content doubles as identifier across the four tools: spelling and capitalization must match exactly.
+        Every mutation returns the full current list, with each task's id (`- #3 [pending] ...` → id 3), so you do not need a separate read tool. Ids never change and are never reused.
         </tasks_usage>
       PROMPT
 
@@ -71,9 +74,11 @@ module Pikuri
         @list = List.new
       end
 
-      # @return [List] the per-agent list, exposed for tests and for
-      #   hosts that want to render it in a UI (a future TUI could
-      #   surface +list.items+ in a sidebar).
+      # @return [List] the per-agent list, exposed for tests. UI
+      #   hosts should NOT read it from another thread — the list is
+      #   agent-thread-confined; consume the {ListChanged} events
+      #   wired by {#bind} instead (each carries an immutable
+      #   snapshot safe to render from anywhere).
       attr_reader :list
 
       # Construct the four tools (each sharing +@list+) and register
@@ -98,6 +103,20 @@ module Pikuri
         c.append_system_prompt(PROMPT_SNIPPET)
         nil
       end
+
+      # Arm {List#on_change} to emit a {ListChanged} (carrying a
+      # fresh {List#items} snapshot) onto the agent's listener
+      # stream after every mutation. This is what lets a UI listener
+      # observe the task list without ever touching the
+      # agent-thread-confined {List} — see the Concurrency note on
+      # {List}.
+      #
+      # @param ctx [Pikuri::Agent::ExtensionContext]
+      # @return [void]
+      def bind(ctx)
+        @list.on_change = -> { ctx.emit_event(ListChanged.new(items: @list.items)) }
+        nil
+      end
     end
   end
 end

data/lib/pikuri/tasks/in_progress.rb

@@ -2,26 +2,30 @@
 
 module Pikuri
   module Tasks
-    # The +task_in_progress+ tool: mark the item whose +content+
-    # exactly matches as +in_progress+. The status name is baked into
-    # the tool name rather than passed as a parameter — that takes
-    # one degree of freedom away from the LLM (no +"in-progress"+ vs
-    # +"in_progress"+ vs +"inprogress"+ typos) at the cost of one
-    # extra tool class.
+    # The +task_in_progress+ tool: mark the item with the given +id+
+    # as +in_progress+. The status name is baked into the tool name
+    # rather than passed as a parameter — that takes one degree of
+    # freedom away from the LLM (no +"in-progress"+ vs +"in_progress"+
+    # vs +"inprogress"+ typos) at the cost of one extra tool class.
     #
-    # Returns the rendered current list via {List#render} on success,
-    # or +"Error: no such task: '<content>'"+ when the content does
-    # not match — the LLM can read the returned list to find the
-    # closest match and re-call.
+    # Items are addressed by the numeric +#id+ shown in every rendered
+    # list (an earlier design used the content string as identifier;
+    # one near-miss in reproducing the exact bytes — a stray quote, a
+    # trailing comma — and the LLM is locked out of its own list. An
+    # id is two digits it just read back; nothing to mis-transcribe.)
+    #
+    # Returns the rendered current list via {List#render} on success.
+    # On a bad id returns +"Error: no such task id: <id>"+ plus the
+    # current list, so the LLM can pick the right id in one turn.
     class InProgress < Pikuri::Tool
       # @return [String]
       DESCRIPTION = <<~DESC
         Mark a task as `in_progress` immediately before you start working on it.
 
         Usage:
-        - Pass the exact `content` string the task was created with — content doubles as identifier; spelling and capitalization must match.
+        - Pass the task's numeric `id` as shown in the rendered list (`- #3 [pending] ...` → id 3).
         - Keep exactly one task `in_progress` at a time. Finish (or revert) the current one before starting another.
-        - On `Error: no such task: ...` the call did nothing — read the returned list in any subsequent tool's output to pick the right name.
+        - On `Error: no such task id: ...` the call did nothing — the error includes the current list; pick the right id from it.
         - On success the full current list is returned for you to read back.
       DESC
 
@@ -32,24 +36,24 @@ module Pikuri
           name: 'task_in_progress',
           description: DESCRIPTION,
           parameters: Pikuri::Tool::Parameters.build { |p|
-            p.required_string :content,
-                              'Exact content of the existing task to mark as ' \
-                              'in_progress, e.g. "Add dark mode toggle".'
+            p.required_integer :id,
+                               'Numeric id of the existing task to mark as ' \
+                               'in_progress, as shown in the rendered list, e.g. 3.'
           },
-          execute: lambda { |content:|
-            InProgress.execute(list: list, content: content)
+          execute: lambda { |id:|
+            InProgress.execute(list: list, id: id)
           }
         )
       end
 
       # @param list [List]
-      # @param content [String]
+      # @param id [Integer]
       # @return [String]
-      def self.execute(list:, content:)
-        list.set_status(content: content, status: 'in_progress')
+      def self.execute(list:, id:)
+        list.set_status(id: id, status: 'in_progress')
         list.render
       rescue ItemNotFound
-        "Error: no such task: '#{content}'"
+        "Error: no such task id: #{id}. Current list:\n#{list.render}"
       end
     end
   end

data/lib/pikuri/tasks/list.rb

@@ -3,17 +3,18 @@
 module Pikuri
   module Tasks
     # Raised by {List#add} when a new item's +content+ already appears
-    # in the list. Content doubles as identifier in the task tools, so
-    # duplicates would make +task_in_progress+ / +task_completed+ /
-    # +task_delete+ ambiguous. The exception carries the offending
-    # content string so the tool layer can surface it verbatim in the
-    # +"Error: ..."+ observation.
+    # in the list. Items are addressed by {Item#id}, so duplicates
+    # would not be ambiguous — they are rejected because a duplicate
+    # is almost always an LLM mistake (re-sending an already-captured
+    # plan), and catching it early keeps the list coherent. The
+    # exception carries the offending content string so the tool layer
+    # can surface it verbatim in the +"Error: ..."+ observation.
     class DuplicateItem < StandardError; end
 
     # Raised by {List#set_status} and {List#delete} when no item with
-    # the given +content+ exists. The four task tools rescue this and
-    # report +"Error: no such task: <content>"+ so the LLM can correct
-    # the name on the next turn.
+    # the given +id+ exists. The three mutation tools rescue this and
+    # report +"Error: no such task id: <id>"+ plus the current list
+    # render, so the LLM can pick the right id on the next turn.
     class ItemNotFound < StandardError; end
 
     # Allowed values for {Item#status}. Kept deliberately small — three
@@ -23,10 +24,11 @@ module Pikuri
     # fourth status.
     STATUSES = %w[pending in_progress completed].freeze
 
-    # One row in a {List}. +content+ is the LLM-visible string that
-    # also acts as identifier across the four task tools; +status+ is
+    # One row in a {List}. +id+ is the numeric identifier the mutation
+    # tools address the item by (assigned by {List#add}, never reused —
+    # see there); +content+ is the LLM-visible task text; +status+ is
     # one of {STATUSES}.
-    Item = Data.define(:content, :status)
+    Item = Data.define(:id, :content, :status)
 
     # An in-memory ordered list of {Item}s, scoped to a single
     # {Pikuri::Agent}. Held inside {Extension} and captured by closure
@@ -35,8 +37,13 @@ module Pikuri
     #
     # == Concurrency
     #
-    # The agent loop is single-threaded with respect to tool calls
-    # (ruby_llm dispatches them sequentially), so no locking. A future
+    # The list is confined to the agent's thread: the agent loop is
+    # single-threaded with respect to tool calls (ruby_llm dispatches
+    # them sequentially), so no locking. Other threads (e.g. a web UI
+    # rendering the list) must not touch a +List+ directly — they
+    # consume the {ListChanged} events {Extension#bind} wires onto
+    # the listener stream, whose +items+ payload is an immutable
+    # snapshot safe to hand across threads. A future
     # parallel-tool-execution feature would need a +Mutex+ here.
     #
     # == Persistence
@@ -48,8 +55,21 @@ module Pikuri
       # @return [List]
       def initialize
         @items = []
+        @next_id = 1
+        @on_change = nil
       end
 
+      # Optional zero-argument hook invoked after every successful
+      # mutation ({#add} / {#set_status} / {#delete}) — not on failed
+      # ones (a raise means nothing changed). Set by {Extension#bind}
+      # to emit a {ListChanged} onto the agent's listener stream;
+      # +nil+ (the default) disables notification. Runs on the
+      # mutating (agent) thread, synchronously inside the mutation
+      # call.
+      #
+      # @return [Proc, nil]
+      attr_accessor :on_change
+
       # @return [Array<Item>] a frozen snapshot of the current items,
       #   in insertion order. Callers cannot mutate the internal
       #   storage through this accessor.
@@ -67,63 +87,71 @@ module Pikuri
         @items.empty?
       end
 
-      # Append a new item with status +pending+. Content matching is
-      # exact (no case- or whitespace-folding) since the tools quote
-      # the content back to the LLM as the identifier.
+      # Append a new item with status +pending+ and the next id from a
+      # monotonic per-list counter. Ids are never reused: after a
+      # delete, the freed id stays dead, so a stale id held by the LLM
+      # errors loudly instead of silently resolving to a newer task.
       #
       # @param content [String] non-empty content; whitespace is the
       #   caller's responsibility.
       # @return [Item] the newly added item
       # @raise [DuplicateItem] if an item with the same +content+
-      #   already exists.
+      #   already exists (a duplicate is almost always an LLM mistake).
       def add(content)
-        raise DuplicateItem, content if find(content)
+        raise DuplicateItem, content if @items.any? { |i| i.content == content }
 
-        item = Item.new(content: content, status: 'pending')
+        item = Item.new(id: @next_id, content: content, status: 'pending')
+        @next_id += 1
         @items << item
+        @on_change&.call
         item
       end
 
-      # Update the status of the item whose +content+ matches.
+      # Update the status of the item whose +id+ matches.
       #
-      # @param content [String]
+      # @param id [Integer]
       # @param status [String] one of {STATUSES}.
       # @return [Item] the updated item (a fresh frozen +Data+
       #   instance — the old one is replaced in place).
       # @raise [ItemNotFound] if no matching item exists.
       # @raise [ArgumentError] if +status+ is not in {STATUSES}.
-      def set_status(content:, status:)
+      def set_status(id:, status:)
         unless STATUSES.include?(status)
           raise ArgumentError, "invalid status: #{status.inspect} (allowed: #{STATUSES.join(', ')})"
         end
 
-        idx = @items.index { |i| i.content == content }
-        raise ItemNotFound, content if idx.nil?
+        idx = @items.index { |i| i.id == id }
+        raise ItemNotFound, id.to_s if idx.nil?
 
-        @items[idx] = Item.new(content: content, status: status)
+        @items[idx] = @items[idx].with(status: status)
+        @on_change&.call
         @items[idx]
       end
 
-      # Remove the item whose +content+ matches.
+      # Remove the item whose +id+ matches. The id is not reused for
+      # later items (see {#add}).
       #
-      # @param content [String]
+      # @param id [Integer]
       # @return [Item] the removed item.
       # @raise [ItemNotFound] if no matching item exists.
-      def delete(content)
-        idx = @items.index { |i| i.content == content }
-        raise ItemNotFound, content if idx.nil?
+      def delete(id)
+        idx = @items.index { |i| i.id == id }
+        raise ItemNotFound, id.to_s if idx.nil?
 
-        @items.delete_at(idx)
+        removed = @items.delete_at(idx)
+        @on_change&.call
+        removed
       end
 
       # The canonical rendering returned as the observation by every
-      # task tool, so the LLM sees the latest full state on each call
-      # without needing a separate read tool. Format:
+      # task tool, so the LLM sees the latest full state — including
+      # each item's id — on each call without needing a separate read
+      # tool. Format:
       #
       #   <tasks>
-      #   - [pending] Add dark mode toggle
-      #   - [in_progress] Write unit tests
-      #   - [completed] Update README
+      #   - #1 [pending] Add dark mode toggle
+      #   - #2 [in_progress] Write unit tests
+      #   - #3 [completed] Update README
       #   </tasks>
       #
       # Empty list renders as +<tasks>(empty)</tasks>+ so the LLM gets
@@ -134,15 +162,9 @@ module Pikuri
       def render
         return '<tasks>(empty)</tasks>' if @items.empty?
 
-        lines = @items.map { |i| "- [#{i.status}] #{i.content}" }
+        lines = @items.map { |i| "- ##{i.id} [#{i.status}] #{i.content}" }
         "<tasks>\n#{lines.join("\n")}\n</tasks>"
       end
-
-      private
-
-      def find(content)
-        @items.find { |i| i.content == content }
-      end
     end
   end
 end

data/lib/pikuri/tasks/list_changed.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Pikuri
+  module Tasks
+    # Domain event emitted onto the agent's listener stream after
+    # every {List} mutation (add / status change / delete), wired by
+    # {Extension#bind} via
+    # {Pikuri::Agent::ExtensionContext#emit_event}. Carries a frozen
+    # point-in-time snapshot of the whole list ({List#items}'s
+    # shape), so a consumer needs no +List+ reference — render or
+    # serialize the payload as-is.
+    #
+    # Lands between the mutating tool's {Pikuri::Agent::Event::ToolCall}
+    # and {Pikuri::Agent::Event::ToolResult} in the stream (the
+    # +on_change+ hook fires inside the tool's +execute+). A batch
+    # +task_create+ emits one event per added item — consumers that
+    # render should treat the latest snapshot as authoritative
+    # (last-wins) rather than diffing event-by-event.
+    #
+    # Fired on the agent's thread. A listener feeding another thread
+    # (e.g. a web UI pushing over SSE) should serialize inside
+    # +on_event+ and hand off only the immutable result — see the
+    # Concurrency note on {List}.
+    ListChanged = Data.define(:items)
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: pikuri-tasks
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
 platform: ruby
 authors:
 - Martin Vysny
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pikuri-core
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.6
+        version: 0.0.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.0.6
+        version: 0.0.7
 description: |
   pikuri-tasks gives a pikuri-core agent an in-memory task list it
   can use to plan and track multi-step work. A +Pikuri::Tasks::List+
@@ -51,6 +50,7 @@ files:
 - lib/pikuri/tasks/extension.rb
 - lib/pikuri/tasks/in_progress.rb
 - lib/pikuri/tasks/list.rb
+- lib/pikuri/tasks/list_changed.rb
 homepage: https://codeberg.org/mvysny/pikuri
 licenses:
 - MIT
@@ -59,7 +59,6 @@ metadata:
   changelog_uri: https://codeberg.org/mvysny/pikuri/src/branch/master/CHANGELOG.md
   bug_tracker_uri: https://codeberg.org/mvysny/pikuri/issues
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -74,8 +73,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Per-session in-memory task list + tools for pikuri.
 test_files: []