@henryqw/pi-goal

Give the agent one goal, and Pi continues the work after each stop. The loop ends when the agent gives evidence for each deliverable, or when a stop limit applies.

Install

pi install npm:@henryqw/pi-goal

Use

Type /goal to see the drop choice. /goal without arguments still shows the current goal.

Ask the agent to work toward a goal, for example: "Make this a goal: all tests pass and the README documents /export." The agent calls goal with action create. When the agent stops before completion, Pi sends a hidden continuation, and the agent continues.

The goal tool is available to the model only. Other tools, such as codemode, cannot call it.

Tool actions

When the goal has no deliverables, complete needs one evidence item with deliverable objective. The tool rejects missing, blank, duplicate, or unknown evidence items. The agent must get evidence from current state, such as files, command output, or tests. Memory of earlier turns is not evidence.

Flow

flowchart TD
    accTitle: Pi Goal continuation flow
    accDescr: A prompt starts work with hidden goal context. Each stop reads the goal from the current branch. Completion needs evidence for each deliverable; drop also ends the goal. Another extension can supply the next turn. Otherwise, continuation needs an active goal, a user interface, and a completed run. Abort, error, or compaction stops continuation. Budget and the 20-continuation limit apply before a wait for a live delegated result. Without a pending result, repeated tool activity stops continuation. Stop limits do not complete the goal.
    Prompt["User prompt"] --> Context["Add hidden goal context"]
    Context --> Work["Agent work; goal tool actions"]
    Work --> Stop["Agent stops; read branch goal"]
    Stop --> Shared{"Another extension continues?"}
    Shared -->|Yes| Work
    Shared -->|No| Eligible{"Active goal, interface, completed run?"}
    Eligible -->|No| Settle["Settle without goal continuation"]
    Eligible -->|Yes| Limit{"Budget used or 20 continuations?"}
    Limit -->|Yes| Hold["Settle; goal stays active"]
    Limit -->|No| Pending{"Live delegated result pending?"}
    Pending -->|Yes| Wait["Wait; no empty continuation"]
    Wait -->|Result or failure starts a turn| Work
    Pending -->|No| Progress{"Same tool activity twice?"}
    Progress -->|Yes| Hold
    Progress -->|No| Continue["Hidden continuation with goal context"]
    Continue --> Work

Read the static goal flow diagram on npm or without a Mermaid renderer.

1. Before each user prompt, Pi Goal adds the goal, the budget numbers, and the completion rules as hidden context.
2. When the agent stops, Pi Goal checks the stop limits. If no limit applies and no delegated result is pending, it adds a hidden continuation with the same goal context.
3. The agent continues in the same run. A successful complete or drop ends the loop.

Pi Goal does not add a continuation when another extension already continues the same stop. One continuation request then serves both extensions.

Pi Goal waits when Pi Subagent owns a live direct or isolated result that will start a turn in the current session. It adds no empty continuation or no-progress warning during this wait. Budget and maximum-continuation limits still apply. A result or failure restores normal goal handling. Retained, interrupted, unknown, or other-session work does not cause a wait.

Background-command notices do not start turns and do not cause a wait. Pi Subagent is optional; without it, the normal stop checks apply.

State and storage

Pi Goal keeps no goal state in memory or in files. It reads the latest goal record from the current conversation branch each time:

• goal tool results store the full goal in their details.
• /goal drop appends a pi-goal custom entry.
• Each continuation is a hidden pi-goal-continuation message.

Branch navigation, /tree, forks, resume, and /undo rewinds show the goal of the selected branch. A rewind to a point before create removes the goal from that branch.

Limits and recovery