1 +#
Goldfish Implementation Plan 3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Replace useless `forget` with `goldfish`, an automatic task-gated tool-use experiment that maps work to task segments.
7 +**Architecture:** `goldfish` is a Pi extension with one LLM-facing `task` tool, visible normal tools, hard `tool_call` enforcement while idle, and a persistent `aboveEditor` widget. State is persisted as custom session entries and replayed on `session_start` like `notes`.
9 +**Tech Stack:** TypeScript Pi extension API, Pi custom widgets, Vitest, existing `test/harness`, `mise` tasks.
11 +**Research basis:** Tool-use papers point toward explicit state and constrained/gated tool availability: ToolDec shows finite-state constraints beat prompt-only tool syntax; ToolSandbox emphasizes stateful tool execution and intermediate milestones. Goldfish applies that locally: finite task state, dynamic tool menu, hard gate, and milestone check command.
15 +**Phase:** Single-plan implementation
21 +- Delete: `extensions/forget/`
22 +- Create: `extensions/goldfish/index.ts`
23 +- Create: `extensions/goldfish/package.json`
24 +- Create: `extensions/goldfish/README.md`
25 +- Create: `extensions/goldfish/__tests__/goldfish.test.ts`
26 +- Create: `extensions/goldfish/__tests__/harness.test.ts`
27 +- Modify: `package-lock.json` via `npm install --package-lock-only --ignore-scripts`
29 +##
Tool/state contract 34 +type TaskStatus = "idle" | "active" | "done" | "abandoned";
36 +type GoldfishTask = {
39 + doneCommand
: string;
40 + doneTimeoutSeconds
: number;
46 + lastResult
?: string;
52 +- `task({ action: "create", title, doneCommand, doneTimeoutSeconds? })`
53 +- `task({ action: "check" })`
54 +- `task({ action: "abandon", reason })`
56 +Done command contract:
58 +- exit `0` => task closes as done.
59 +- exit `1` => task remains active.
60 +- exit `2+`, signal, timeout, spawn error => task closes as abandoned.
61 +- timeout default: `60s`, hard cap: `300s`.
65 +- When idle, normal tools stay visible for same-turn SDK compatibility.
66 +- Hard gate blocks non-task tool calls while idle even if the model emits stale tool calls.
67 +- When active, all normal tools and `task` are allowed.
68 +- Tool descriptions are stateful and imperative: "Before any other tool, create a task with a done command.".
69 +- Widget mirrors state so the human always sees why tools are hidden/allowed.
71 +##
Task 1: Delete `forget` and add empty `goldfish` shell 75 +- Delete: `extensions/forget/`
76 +- Create: `extensions/goldfish/package.json`
77 +- Create: `extensions/goldfish/README.md`
78 +- Create: `extensions/goldfish/index.ts`
79 +- Test: `extensions/goldfish/__tests__/harness.test.ts`
81 +- [ ] **Step 1: Delete old extension**
86 +rm -rf extensions/forget
89 +- [ ] **Step 2: Create package metadata**
91 +Write `extensions/goldfish/package.json`:
95 + "name":
"@bugabinga/pi-ext-goldfish",
99 + "devDependencies": {
100 + "@marcfargas/pi-test-harness":
"^0.6.1",
103 + "peerDependencies": {
104 + "@earendil-works/pi-coding-agent":
"*" 107 + "description":
"Task-gated Pi tool use experiment.",
108 + "keywords": [
"pi",
"pi-extension"],
113 +- [ ] **Step 3: Create README**
115 +Write `extensions/goldfish/README.md`:
120 +Task-gated Pi tool-use experiment.
122 +When no task is active, normal tools stay visible but are hard-blocked.
123 +The agent must create a task with a done command before using them.
125 +The widget shows current state above the editor.
128 +- [ ] **Step 4: Write failing harness test**
130 +Write `extensions/goldfish/__tests__/harness.test.ts`:
133 +import { afterEach, describe, expect, it }
from "vitest";
134 +import { createTestSession, type TestSession }
from "../../../test/harness";
135 +import goldfishExtension
from "../index";
137 +describe(
"goldfish pi-test-harness", ()
=> {
138 + let t
: TestSession | undefined;
145 + it(
"loads in real Pi extension runtime",
async ()
=> {
146 + t
= await createTestSession({ extensionFactories: [goldfishExtension] });
148 + expect(t.session.extensionRunner.extensions).
toHaveLength(
1);
156 +mise run test
-- extensions/goldfish/__tests__/harness.test.ts
159 +Expected: fail because `extensions/goldfish/index.ts` does not exist.
161 +- [ ] **Step 5: Create minimal extension**
163 +Write `extensions/goldfish/index.ts`:
166 +import type { ExtensionAPI }
from "@earendil-works/pi-coding-agent";
168 +export default function goldfishExtension(_pi
: ExtensionAPI)
: void {}
174 +mise run test
-- extensions/goldfish/__tests__/harness.test.ts
179 +##
Task 2: State machine and replay 183 +- Modify: `extensions/goldfish/index.ts`
184 +- Test: `extensions/goldfish/__tests__/goldfish.test.ts`
186 +- [ ] **Step 1: Write failing state tests**
190 +- empty state is idle.
191 +- create event opens active task.
192 +- done event closes current task.
193 +- abandon event closes current task.
194 +- replay returns latest active task.
199 +mise run test
-- extensions/goldfish/__tests__/goldfish.test.ts
202 +Expected: fail because helpers are missing.
204 +- [ ] **Step 2: Implement pure state helpers**
206 +Add event types, `createState()`, `applyEvent()`, `replayGoldfish()`, `currentTask()`, and export them under `__test`.
211 +mise run test
-- extensions/goldfish/__tests__/goldfish.test.ts
216 +##
Task 3: Task tool schema, execution, and render UI 220 +- Modify: `extensions/goldfish/index.ts`
221 +- Test: `extensions/goldfish/__tests__/goldfish.test.ts`
223 +- [ ] **Step 1: Write failing tool tests**
227 +- collapsed result for `create` shows status, title, command, timeout only.
228 +- expanded result includes full details.
229 +- check exit `0` marks done.
230 +- check exit `1` keeps active.
231 +- check exit `2` abandons.
232 +- check timeout abandons.
234 +- [ ] **Step 2: Implement `goldfish` tool**
236 +Use a single `task` tool with `action` enum.
237 +Return structured `details`.
238 +Render result like built-ins:
240 +- collapsed: one bounded status line.
241 +- expanded: full task context and check output.
242 +- expansion hint uses `keyHint("app.tools.expand", "to expand")` if available in current imports/patterns.
244 +- [ ] **Step 3: Verify tests**
249 +mise run test
-- extensions/goldfish
254 +##
Task 4: Dynamic hide + hard gate 258 +- Modify: `extensions/goldfish/index.ts`
259 +- Test: `extensions/goldfish/__tests__/goldfish.test.ts`
261 +- [ ] **Step 1: Write failing visibility tests**
263 +Test a fake `ExtensionAPI` with active tools:
265 +- idle => normal tools visible but blocked by hard gate.
266 +- active => normal tools plus `task` allowed.
267 +- active tool baseline excludes tools not active at session start.
269 +- [ ] **Step 2: Write failing hard-gate tests**
271 +Test `beforeToolCall`/`tool_call` handler logic:
273 +- idle non-task returns blocked result.
274 +- idle task is allowed.
275 +- active non-task is allowed.
277 +- [ ] **Step 3: Implement visibility and gate**
279 +Use `pi.getActiveTools()` / `pi.setActiveTools()`.
280 +Capture baseline after registering `task` on `session_start`.
281 +Use `pi.on("tool_call", ...)` for hard blocking.
286 +mise run test
-- extensions/goldfish
291 +##
Task 5: Persistent widget 295 +- Modify: `extensions/goldfish/index.ts`
296 +- Test: `extensions/goldfish/__tests__/goldfish.test.ts`
298 +- [ ] **Step 1: Write failing widget tests**
302 +- idle compact line says tools blocked and task required.
303 +- active compact line shows active task and check command.
304 +- expanded lines show id, title, done command, timeout, checks, tool calls, last result.
305 +- widget output truncates to width.
307 +- [ ] **Step 2: Implement widget**
309 +Follow `notes` and `goal`:
311 +- `ctx.ui.setWidget("goldfish", () => ({ invalidate() {}, render(width) { ... } }), { placement: "aboveEditor" })`.
312 +- compact by default.
313 +- expanded toggle shortcut: `alt+f`.
314 +- auto-expanded when tools are blocked.
319 +mise run test
-- extensions/goldfish
324 +##
Task 6: Prompt/guidance steering 328 +- Modify: `extensions/goldfish/index.ts`
329 +- Test: `extensions/goldfish/__tests__/goldfish.test.ts`
331 +- [ ] **Step 1: Write failing guidance tests**
333 +Test generated guidance text:
335 +- idle: imperative, short, says `task.create` is required first.
336 +- active: says current task and done command.
337 +- blocked tool response tells model exact next allowed action.
339 +- [ ] **Step 2: Inject guidance at correct time**
341 +Use `before_agent_start` or `context` event to prepend/append a short state block.
342 +Keep it under 12 lines.
343 +Do not duplicate stale guidance.
348 +mise run test
-- extensions/goldfish
353 +##
Task 7: Real-life `pi --print --no-session` smoke loop 357 +- Modify as failures indicate.
359 +- [ ] **Step 1: Run smoke without active task**
364 +pi --print --no-session -e ./extensions/goldfish
"list files in this repo" 367 +Expected: model must call `task.create` before file tools are usable.
369 +- [ ] **Step 2: Run smoke with achievable task**
374 +pi --print --no-session -e ./extensions/goldfish
"check whether package.json exists" 377 +Expected: task is created, normal tool is used, check closes.
379 +- [ ] **Step 3: Iterate until smoke behavior is sane**
381 +If the model fails to create tasks, strengthen guidance and hidden-tool behavior.
382 +If rendering is noisy, tighten collapsed render output.
383 +If it loops, lower check retry caps.
385 +##
Task 8: Final verification 390 +mise run test
-- extensions/goldfish
394 +If `mise run check` fails due unrelated dirty `q` work, report exact blocker and keep targeted verification evidence.
402 +Expected: only goldfish deletion/addition, package lock, and pre-existing unrelated dirty work.