0002-chat-only-tool-selection.md
0002-chat-only-tool-selection.md
Make Chat only a persisted resource policy
Pi Web treats an explicitly empty tool selection as Chat only, not merely as an AgentSession whose active tool array happens to be empty.
For a normal session, Chat only loads no extensions, skills, prompt templates,
themes, or Pi base system prompt. Its exact system prompt is the ordered content
of the context files discovered by Pi's default loader, including global and
project AGENTS.md, AGENTS.override.md, and CLAUDE.md files. Pi Web does not
add its own prefix, suffix, or current-working-directory text.
For a subagent whose resolved profile has no tools and has both resource-loading switches disabled, Chat only loads no extensions, skills, prompt templates, themes, context files, or Pi base system prompt. Its exact system prompt is the profile system prompt. If parent context inheritance is enabled, that context is included with the delegated user task instead of being appended to the system prompt. A profile may opt into skills or extensions independently. Extension tools are activated alongside the profile's built-in tools except for Pi Web's reserved subagent-control tools, which remain excluded to prevent nested Agent dispatch.
The host may resolve input_files before dispatch and include their UTF-8 text
in the delegated user task. This is input preparation, not a subagent tool: it
does not change the active tool list or the exact Chat-only system prompt.
Pi's native session format does not persist the active tool selection. Normal
sessions therefore append versioned pi-web:tool-selection custom entries:
{
"type": "custom",
"customType": "pi-web:tool-selection",
"data": { "version": 1, "tools": [] }
}
The latest valid entry is authoritative. No entry means a legacy session and
retains Pi's default behavior; an empty tools array means Chat only; a nonempty
array restores the selected built-in tools. The stored array is the user's
selection before extension tools are added. Subagents keep using
resourceSnapshot in their own metadata instead of duplicating this entry. The
snapshot records their active tools and the profile's skill and extension
loading switches so reopened sessions retain the same resource policy.
The persisted selection must be resolved before createAgentSessionServices()
so Chat only never imports or executes session extensions. The exact system
prompt must also be reapplied after Pi's before_agent_start phase, because the
SDK rebuilds its base prompt immediately before the model call.
Changing among nonempty tool presets can update an existing wrapper. Crossing the Chat-only boundary must append the new selection and rebuild the wrapper: normal wrappers have already loaded extensions, while Chat-only wrappers do not have those resources available to enable in place. Persisted sessions retain their id and JSONL file. An unpersisted empty composer session may be discarded and recreated with a new internal id.