@dumbmice/pi-todo-loop 0.2.0 → 0.2.1

package/AGENTS.md

@@ -84,7 +84,11 @@ adding a `CHANGELOG.md` line — all in the same commit.
 - **The only *variable* agent-facing text is the nudge.** One of two fixed sentences, appended once
   per continuation. No state block, no reminder, no per-request rewrite: the list is the agent's to
   read with the todo tool. The tool declaration (`todo_loop_block`) is constant and carries no task
-  state, but it is in every request — count it in cost claims. The non-assistant constraint is pi's `turn_end` projection check, not the request (register
+  state, but it is in every request — count it in cost claims: the declaration plus the one-line
+  `<tools>` snippet and the `<rules>` guideline it earns (a few hundred characters together). It
+  declares a `promptSnippet` and a guideline that names it, because pi only shows a tool in the
+  prompt's `<tools>` list when a snippet exists; without one the exit is in the tool array but absent
+  from that summary. The non-assistant constraint is pi's `turn_end` projection check, not the request (register
   item 3) — do not re-derive a coupling between the two.
 - **One entry per continuation is a floor, not a choice.** pi has no `resume()` that appends nothing.
   Do not try to reach zero entries; keep the single `custom_message` with `display: false`.
@@ -123,7 +127,9 @@ adding a `CHANGELOG.md` line — all in the same commit.
   continues, but the loop would then stop silently — inert is better than loud.
 - **Nothing is written.** No files, no network, no process execution. The only reads are the optional
   config, the two kill-switch paths and the session branch.
-- **The kill switch is checked in both hooks and in `todo_loop_block`'s `execute`.** Disabling takes effect on the next request, without
+- **The kill switch is checked in both hooks and in `todo_loop_block`'s `execute`.** It cannot remove
+  the tool from the prompt: pi builds `<tools>`/`<rules>` from the registration, so a disabled session
+  still advertises an exit that will be refused. Disabling takes effect on the next request, without
   `/reload`.
 - **No pi type import; `pi: any` at the registration boundary.** Contexts the file reads are typed
   structurally (`SessionContext`). Adding the pi types would make a dependency out of a package that
@@ -169,6 +175,7 @@ introduces an edge.
 | the block's tool turn costs no round, and no marker is written after it | `state machine: the block call's tool turn costs no round, and the settle after it stops` |
 | a model-authored reason is flattened and bounded | `a reason is flattened to one line and bounded` |
 | the kill switch silences the block tool too | `the kill switch also silences todo_loop_block` |
+| the block tool declares a prompt snippet and a self-naming guideline, so pi lists it in `<tools>`/`<rules>` | `the block tool declares a prompt snippet and a self-naming guideline` |
 | a paused loop refuses the block tool and stays silent | `a paused loop refuses todo_loop_block and stays silent` |
 | a stall clause that lands on the cap round is reported, not dropped | `state machine: cap stays shut across a repeated settle under the same message`, `a stale list stops on the cap with a reason that says so` |
 | the next human message clears the block and the stale `last:` | `the human's next message clears the block` |
@@ -278,8 +285,10 @@ grep -c 'todo-loop:continue' ~/.pi/agent/sessions/<project>/*.jsonl   # one per
 
 ## Release canary
 
-The one failure this suite cannot see is pi changing how a `display: false` `custom_message` projects,
-or tightening `canContinue`. Drafts are committed before the continuation is validated, so that change
+Two failures this suite cannot see. The first is pi changing how a `display: false` `custom_message`
+projects, or tightening `canContinue`; the second is how pi renders a custom tool into the system
+prompt, since the harness stub never builds one — a tool without a `promptSnippet` was silently dropped
+from `<tools>` in pi 1.5.0. Drafts are committed before the continuation is validated, so that change
 would persist a marker, drop the continuation, and leave `/todoloop` reporting `continuing: round n/12`
 until it reports `round cap` with zero continuations — while every test here stays green, because the
 harness drives a stub `pi`.
@@ -287,12 +296,21 @@ harness drives a stub `pi`.
 Before every version bump, on the *new* pi, run the documented live check once:
 
 ```bash
-pi -e . -p "create two todos 'a' and 'b', then reply ok" --tools todo
+# `-ne` because the released copy registers the same tool name: `pi -e .` next to the installed
+# version fails with `Tool "todo_loop_block" conflicts with …`.
+pi -ne -e . -p "create two todos 'a' and 'b', then reply ok" --tools todo
 grep -c 'todo-loop:continue' ~/.pi/agent/sessions/--<project>--/*.jsonl   # 0 is a failure
 ```
 
-and read the pi changelog for `custom_message`, `display`, `canContinue`, plus rpiv-todo's for
-`reminder` (upstream PR #190 would put a second task block in the request).
+For the prompt half, run with `--mode json` and confirm the tool reached the system prompt section:
+
+```bash
+pi -ne -e . --mode json -p "reply ok" | grep -o 'todo_loop_block: Stop the todo loop'
+```
+
+and read the pi changelog for `custom_message`, `display`, `canContinue`, `promptSnippet`,
+`promptGuidelines`, plus rpiv-todo's for `reminder` (upstream PR #190 would put a second task block in
+the request).
 
 ## Known limitations to revisit
 

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-11-05
+
+### Changed
+
+- `todo_loop_block` now declares a `promptSnippet` and a `promptGuidelines` bullet, so pi lists it in the
+  system prompt's `<tools>` section and its guideline in `<rules>`. Before this the tool was in the
+  request's tool array but absent from the prompt summary, so an agent could only find it through the
+  nudge. The guideline also tells the model to pick a reasonable option and state its assumption when a
+  choice is its own, rather than asking a person.
+
 ## [0.2.0] - 2026-11-05
 
 ### Added

package/README.md

@@ -77,9 +77,9 @@ placeholders, and a list that is never updated looks the same as one that is fin
 is the only thing that stops it, so the list has to mean something to you.
 
 The extension never edits your prompt. The only *variable* text it gives the model is a one-line nudge —
-*continue, and read or update the list with the todo tool* — plus one constant tool declaration
-(`todo_loop_block`, which carries no task state), so the list stays the agent's to maintain and the
-conversation stays yours.
+*continue, and read or update the list with the todo tool* — plus one constant tool declaration and the
+prompt entry pi derives from it (`todo_loop_block`; neither carries task state), so the list stays the
+agent's to maintain and the conversation stays yours.
 
 ## Configuration
 

package/docs/behaviour.md

@@ -52,8 +52,10 @@ outside — and one of them must not be punished.
   `todo_loop_block` with the reason."* It is offered **once per stall**; tool work re-arms it, so a
   second, separate stall after real progress is a new question.
 - A **tool turn** clears `stalled`. Work is progress even when the list was not touched.
-- **`todo_loop_block`** is the agent's own exit. It takes a reason, stores `{reason, anchor}` in memory
-  and stops continuations for that message. The human is notified, `/todoloop` shows
+- **`todo_loop_block`** is the agent's own exit. It is advertised in the prompt from the first turn —
+  pi lists it in `<tools>` and carries its guideline in `<rules>`, because the tool declares a
+  `promptSnippet` — and the nudge is the timed offer, not the only way to learn it exists. It takes a
+  reason, stores `{reason, anchor}` in memory and stops continuations for that message. The human is notified, `/todoloop` shows
   `waiting for you: <reason>`, and the human's next message is a new anchor, so the block clears itself
   — there is no unblock call.
 - A block with an empty reason is refused, and the loop keeps running: the reason is the whole point.
@@ -158,9 +160,11 @@ clamped so a typo cannot defeat the cap it configures: `maxRounds` ≤ 1000.
   number of continuations × session size. `maxRounds` caps continuations, not turns — tool turns are
   pi's own and unbounded, so a long tool-heavy stretch can be many turns for one round. That is the
   dominant term.
-- The extension adds one short marker per continuation (~40 tokens) plus one constant tool declaration
-  (`todo_loop_block`, a few hundred characters of description and schema) that pi puts in every
-  request. Neither carries task state, and there is no per-request block. Whatever the model needs it reads with the `todo` tool, and that result
+- The extension adds one short marker per continuation (~40 tokens), plus one constant tool declaration
+  and the prompt entries pi derives from it — `<tools>` line, `<rules>` guideline, description and
+  schema, roughly 700 characters together, in every request. None of it carries task state, and there
+  is no per-request block. Neither the snippet nor the guideline is gated by the kill switch or
+  `/todoloop pause`; only the hooks and the call itself are. Whatever the model needs it reads with the `todo` tool, and that result
   is part of its own conversation rather than a parallel copy.
 - `context` walks the branch and returns `undefined` unless a marker actually has to be removed, so on
   a normal turn it costs one projection pass. `turn_end` reads the config, probes the kill switches and

package/docs/pi-api-alignment.md

@@ -71,7 +71,10 @@ full. Items that produce no signal in the transcript are marked _(silent)_.
 9. **`sendUserMessage` and `Agent.prompt` are deliberately not used.** `sendUserMessage` would add a
    visible user-role message per continuation and pollute the transcript; calling the agent directly
    bypasses `AgentSession` lifecycle handling (busy state, queuing, retry, abort).
-10. **The kill switch is checked in both hooks and in the block tool, not once at load.** Removing it or creating the file
+10. **The kill switch is checked in both hooks and in the block tool, not once at load.** It cannot
+    withdraw the tool's prompt entry: pi renders `<tools>`/`<rules>` from the registration, so a
+    disabled session still shows an exit whose call is then refused with "not running". Removing it
+    would need `pi.setActiveTools` from a hook — a new coupling we did not take for this. Removing it or creating the file
    takes effect on the next request, without `/reload`.
 11. **No dependency on `@earendil-works/pi-coding-agent`, and no peer declaration for it.** Nothing
     here imports the package: the boundary is typed `pi: any` and contexts are typed structurally

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dumbmice/pi-todo-loop",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Keep pi working while a todo list still has open tasks, and stop when the agent asks for a person.",
 	"type": "module",
 	"license": "MIT",

package/src/index.ts

@@ -127,6 +127,13 @@ export default function todoLoop(pi: any, options: TodoLoopOptions = {}): void {
 		label: "Block the todo loop",
 		description:
 			"Stop the automatic continuation loop for the rest of this message because you need a person: a decision, a review, a credential or information only the human has. The human is shown your reason and their next message resumes the loop. Use it only when you cannot proceed on the open tasks without them.",
+		// Without a snippet pi leaves the tool out of the prompt's `<tools>` summary; it is
+		// still in the request's tool array, but a model reading the prompt summary does not
+		// see the exit until the nudge names it. The exit must not be hidden that way.
+		promptSnippet: "Stop the todo loop for this message and ask the human for what you need",
+		promptGuidelines: [
+			"Use todo_loop_block when you cannot proceed on the open todo tasks without a person — a decision, a review, a credential or information only they have. If the choice is yours to make, pick the reasonable option and say what you assumed instead. Do not use it to end work you could finish yourself.",
+		],
 		parameters: {
 			type: "object",
 			properties: {