# Goal reference

Goals attach an objective to the current Pi session. An active goal can continue across turns until the agent verifies completion, the user pauses it, a budget is exhausted, or a continuation guard stops it.

## Editor indicator

The top right of the editor border shows `Pursuing goal (2m, 12.5K tokens)` for an unbudgeted goal or `Pursuing goal (12.5K / 50K tokens)` for a budgeted goal. Elapsed time updates while the goal runs. The indicator shares the border with Pi's working status on the left.

Stopped goals retain consumed tokens, for example `Goal paused (12.5K tokens, /goal resume)`, `Goal stalled (12.5K tokens, /goal resume)`, `Goal unmet (63.9K / 50K tokens)`, or `Goal achieved (2m, 12.5K tokens)`. Paused and stalled goals with budgets show consumed tokens against the budget. The labels follow Codex's composer indicator, with token consumption added in every state.

The extension wraps an existing custom editor factory and preserves its input handlers. When the border has insufficient room, the indicator uses a separate right-aligned row above the editor. Clearing the goal removes the indicator. The footer has no duplicate goal status.

## Commands

| Command | Behavior |
| --- | --- |
| `/goal` | Shows the objective, status, tokens used, optional token budget, and active execution time. |
| `/goal <objective>` | Creates or replaces the session goal and starts work when idle. Resets usage and removes any previous budget. |
| `/goal --tokens N <objective>` | Creates or replaces a goal with a positive integer token budget. |
| `/goal pause` | Pauses the goal and interrupts its running operation. |
| `/goal resume` | Resumes an active, paused, or blocked goal when its token budget permits. Resets the blocked audit. |
| `/goal clear` | Removes the current goal and prevents further automatic continuation. |
| `/goal edit` | Opens an editor for the objective. Requires an interactive UI. |
| `/goal edit <objective>` | Updates the objective while retaining usage and budget. A paused or blocked goal stays stopped. A completed goal becomes active when budget remains. |
| `/goal budget N` | Sets the current goal's total token budget. Does not automatically resume a stopped goal. |

Objectives contain 1 to 4000 Unicode characters after trimming whitespace. `pause`, `resume`, `clear`, `edit`, and `budget` are reserved command words. Goals have no token budget unless one is explicitly supplied.

When a budget is exhausted, increasing it and resuming requires two commands:

```text
/goal budget 100000
/goal resume
```

## Model tools

The extension registers `get_goal`, `create_goal`, and `update_goal` with Pi.

`get_goal` returns the current goal and remaining tokens. `create_goal` accepts an `objective` and optional `token_budget`. Its instructions permit creation only on an explicit user request. It refuses to replace an unfinished goal.

`update_goal` accepts `active`, `complete`, `blocked`, or `paused`. Its instructions require evidence for every requirement before completion. Blocking requires the same genuine blocker to persist for at least three consecutive goal turns with no useful action available. The extension enforces a minimum of three turns; the model audits whether the blocker remained the same.

The agent can infer a pause only when the user clearly intends to stop or take a break. The literal word "pause" is not required. Ordinary messages, corrections, questions, and guidance about tools or subagents steer the goal without pausing it. Needing a decision or running out of approaches does not authorize pausing. Genuine blockers use the blocked audit.

A new user message directing further work or providing guidance for continuing authorizes the agent to set `active` on a paused or blocked goal. For example, "you can use subagents btw" is guidance for continuing, so no resume confirmation is needed. Unrelated questions and acknowledgments alone do not authorize resuming. The extension requires a new user message after the pause before the tool can resume. It preserves usage and budget and resets the blocked audit. The tool cannot resume completed or budget-limited goals or change a budget. `/goal resume` remains available.

Goal tools return usage so the agent can report consumed tokens after completing a budgeted goal. Completion and blocker assessments depend on the model's evidence audit.

## Continuation and interruption

The extension records whether another goal turn is needed at Pi's `agent_before_settle` boundary, then lets the run finish. After `agent_settled`, a one-shot event-loop handoff gives every idle listener a chance to start maintenance before the next hidden continuation request. This allows compaction extensions that check their thresholds when Pi becomes idle to run between goal turns.

If compaction starts, continuation waits for `session_compact` and Pi to clear its busy state. A successful automatic compaction preserves an active goal and resumes its pending work. Failed compaction blocks the goal; cancelled compaction pauses it. Manual `/compact` aborts an active run in Pi, so a goal paused by that interruption stays paused until user direction or `/goal resume`.

Queued messages and continuations from other extensions take priority. A new user message steers the goal. One stable goal header enters model context before the conversation on every request, including after compaction or an objective edit. Goal text is encoded as user-provided data. Routine usage changes do not change this header; current usage remains available in the indicator and `get_goal`.

The header keeps the latest tool result or user message at the end of context. Full goal reminders from older versions become short continuation requests in model context. The saved transcript remains unchanged. The instructions discourage repeated goal and usage recaps, while allowing brief reorientation after compaction and updates about new findings or blockers.

An automatic turn with no tool calls gets a recovery request to take concrete action or verify completion. After three consecutive automatic turns without tool calls, the goal becomes blocked and the indicator shows `Goal stalled`. Tool execution, fresh user input, or an explicit resume resets this count. `/goal resume` retries a stalled goal. Token budgets and interruptions still take precedence over recovery requests.

A provider or execution error that reaches final settlement blocks the goal. Escape pauses it. Continuation uses event handoffs without polling or a background worker. A UI timer redraws elapsed time while work runs.

`/goal clear` prevents further automatic turns but lets a running operation finish. `/goal pause` interrupts the running operation. Clearing or pausing does not undo tool actions.

## Usage and persistence

Token usage is Pi's uncached input plus cache-write input plus output, including reasoning when the provider includes it in output. Cache-read tokens are excluded, matching Codex's goal accounting. Usage counts responses whose provider request started while this goal was active. The request that creates a goal through `create_goal` precedes activation and is not charged.

The budget is a soft limit checked after each assistant response. A response can exceed it. Once exhausted, the extension blocks substantive goal tools and requests one summary turn. Summary requests after exhaustion are not charged to the goal. Later unrelated user requests can still use tools normally. Raising the budget does not reset consumed tokens.

Time usage counts active execution in this Pi process. It excludes paused time and time while a saved session is closed. Tokens and time persist in custom session entries. Ephemeral sessions retain those entries only in memory.

History restoration uses the active branch. Opening a session, navigating the session tree, or reloading restores an active goal as paused. This prevents history restoration from starting work without user direction. Give instructions to continue or use `/goal resume`.

## Codex implementation sources

This is an independent TypeScript implementation of Codex's goal behavior, adapted to Pi 1.3.0 extension hooks. The research used [OpenAI's goal guide](https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex) and the public [`openai/codex` source at revision `67f0994`](https://github.com/openai/codex/tree/67f0994b532b8740f14b5b738af7b7b2a915b1d6).

The relevant upstream files are:

- [Model tool contracts](https://github.com/openai/codex/blob/67f0994b532b8740f14b5b738af7b7b2a915b1d6/codex-rs/ext/goal/src/spec.rs).
- [Continuation and completion audit](https://github.com/openai/codex/blob/67f0994b532b8740f14b5b738af7b7b2a915b1d6/codex-rs/ext/goal/templates/goals/continuation.md).
- [Idle continuation dispatcher](https://github.com/openai/codex/blob/67f0994b532b8740f14b5b738af7b7b2a915b1d6/codex-rs/ext/goal/src/runtime.rs).
- [Token accounting](https://github.com/openai/codex/blob/67f0994b532b8740f14b5b738af7b7b2a915b1d6/codex-rs/ext/goal/src/accounting.rs).
- [Terminal goal summary](https://github.com/openai/codex/blob/67f0994b532b8740f14b5b738af7b7b2a915b1d6/codex-rs/tui/src/chatwidget/goal_menu.rs).
- [Composer indicator labels and right-side placement](https://github.com/openai/codex/blob/67f0994b532b8740f14b5b738af7b7b2a915b1d6/codex-rs/tui/src/bottom_pane/footer.rs).
- [Indicator usage and elapsed time](https://github.com/openai/codex/blob/67f0994b532b8740f14b5b738af7b7b2a915b1d6/codex-rs/tui/src/chatwidget/goal_status.rs).

Pi stores goals in session entries instead of Codex's thread database. This port supports in-memory chats, allows pauses and resumes based on user intent, adds `--tokens` and `budget` command syntax, and requires user direction after history restoration. It does not implement Codex-specific plan mode admission, account usage-limit detection, descendant-agent accounting, or goal attachments. Errors use the `blocked` status because Pi does not expose Codex's account-limit classification.