agent-ops-patterns / gallery / pi map / how it decides
How pi decides
In pi, the AI model chooses each next step and ends the run by replying without asking to use a tool; plain code checks and runs the tool calls but adds no check of its own that the work was done. By pi's stated design nobody is asked before a tool call runs unless an installed extension blocks it, and a shell command has no time limit unless the model sets one.
What it does without asking you
-
Is a person asked before a tool call the model issued runs?
Decided by plain code No, by pi's stated design. A call runs once its tool is found and its arguments are valid, unless an installed extension blocks it.
agent-session.ts:658-681· decision D1 in the full map -
Can anything block a tool call?
Decided by plain code Only an installed extension that handles tool calls: the first one that says block stops the call, and the model gets its reason as an error. pi ships no blocking policy; the two in its repository are examples.
runner.ts:1249-1267· decision D2 in the full map -
Should this project folder be trusted to load its own settings, extensions, skills and MCP servers?
Decided by a person When nothing earlier answered, the person chooses at startup in the terminal: trust, trust the parent folder, do not trust, or either answer for this session only. A lasting choice is saved.
project-trust.ts:25-45· decision D7 in the full map
How it decides it is done
-
Is the work finished, so the run may stop?
Decided by an AI model The model decides implicitly: a reply with no tool call normally ends the run unless messages are queued or an extension asks for more; a reply cut off at its length limit may first get one compact-and-retry. Code adds no check of its own.
agent-loop.ts:303-326· decision G1 in the full map -
Did the run end completed, in error, or aborted?
Decided by plain code Code labels it from the last reply: error and aborted as such, and everything else, a reply cut off at its length limit included, as completed.
agent-session.ts:850-851· decision G4 in the full map -
Does a one-shot text run report success?
Decided by plain code Code looks only at the last message: an error or abort exits 1, and a reply cut off at its output limit is printed and also exits 1.
print-mode.ts:139-160· decision A16 in the full map
Limits and memory
-
How long may a shell command run before it is killed?
Decided by an AI model The model passes a timeout or leaves it out; with none, the command can run until the person stops it.
bash.ts:42· decision E9 in the full map -
When must the conversation be compacted?
Decided by plain code When its estimated size passes the model's window minus a reserve (16,384 tokens by default), checked before each request and after each run.
compaction.ts:267-270· decision F1 in the full map -
What does the summary that replaces the older conversation say?
Decided by an AI model The session's model writes it with a fixed prompt of six headed sections; code rejects an error, a cut-off reply or a tool call, and otherwise stores the text as returned.
compaction.ts:696-753· decision F5 in the full map
Other judgments
-
What does the agent do next: answer, or call which tools?
Decided by an AI model The session model decides each turn, replying with text, tool calls, or both. Before any call runs, code checks the tool name and validates the arguments.
agent-loop.ts:412· decision C1 in the full map -
Do the tool calls of one reply run at the same time?
Decided by plain code By default yes, and results come back in order. A tool, or the agent, set to sequential makes them run one by one.
agent-loop.ts:518-533· decision E3 in the full map -
When an edit's old text does not match the file exactly, is a near match good enough?
Decided by plain code Code tries an exact match first, then one that ignores differences in line-end spaces, quotes, dashes, special spaces and Unicode forms. The match must be unique, and the lines a near match touches are written back in normalized form.
edit-diff.ts:300-362· decision E8 in the full map
Three problems in the code
-
1. Piped input and your message are joined with nothing between them
In a one-shot run, pi joins piped input, the text of @file arguments and the first message into one prompt with no separator between them, so the end of one part runs straight into the start of the next. pi's maintainers closed the report about this as not planned.
Reported; no linked fix found (#7863), checked 2026-11-01.
Where:
initial-message.ts:26-40. How we checked: the code was re-read at the source version named above; the sentences were checked by an independent AI reviewer from another company (OpenAI Codex, read-only) on 2026-11-01; every sentence it found too wide was rewritten or removed, and every rewrite was checked again. -
2. Cut-down output from your own shell command can be marked as not cut
When you run a command yourself with !, pi keeps only the tail of a long output. After older output has been dropped, the flag that says the output was cut can still read false.
Reported; a fix is proposed, not merged (#10165), checked 2026-11-01.
Where:
bash-executor.ts:92-98,bash-executor.ts:131-143. How we checked: the code was re-read at the source version named above; the sentences were checked by an independent AI reviewer from another company (OpenAI Codex, read-only) on 2026-11-01; every sentence it found too wide was rewritten or removed, and every rewrite was checked again. -
3. A "too long" error in unfamiliar wording is not recognized
When a request fails, pi recognizes that it overflowed the model's context by matching the error text against a list of known provider messages. Wording the list does not know is treated as an ordinary error, so pi does not compact the history and retry. pi's tracker has an open report about one such message.
Already tracked upstream (#10885), checked 2026-11-01.
Where:
overflow.ts:144-178,overflow.ts:39-69. How we checked: the code was re-read at the source version named above; the sentences were checked by an independent AI reviewer from another company (OpenAI Codex, read-only) on 2026-11-01; every sentence it found too wide was rewritten or removed, and every rewrite was checked again.