What configuration model should the extension expose for named subagents, prompts, tools, models, defaults, and project overrides while keeping the extension itself policy-free?
Decisions
Extension-wide defaults live in dedicated JSON config files.
Global config path is ~/.pi/agent/subagents.json.
Project config path is .pi/subagents.json using Pi's CONFIG_DIR_NAME rather than hardcoding .pi in implementation.
Project config is honored only when project trust is active.
Project config overrides global config.
Named subagent definitions live only as Markdown files.
User named definitions live under ~/.pi/agent/agents/*.md.
Project named definitions live under .pi/agents/*.md using Pi's CONFIG_DIR_NAME in implementation.
subagents.json does not define named agents inline.
subagents.json is reserved for extension defaults, optional UI behavior, concurrency, timeouts, and guardrails.
Named subagent frontmatter requires only name and description.
The Markdown body is the subagent prompt or instructions.
All other frontmatter fields are optional and inherit from config defaults when absent.
Version-one optional frontmatter fields are context, model, thinking, tools, allowedContexts, and hidden.
thinking controls the Pi reasoning or effort level for the subagent when the selected model supports it.
Agent frontmatter tools references a named tool profile.
Tool profiles are defined in subagents.json and compile down to Pi active tools plus optional tool-call gates.
The extension may provide in-code built-in tool profiles as fallback defaults, but it must not write a default config file without an explicit user command.
Built-in neutral tool profile names are reserved in version one.
User config may add custom tool profiles and choose the default profile, but may not overwrite built-in profile names.
Version one ships reserved built-in tool profiles none, read-only, read-only-with-safe-bash, and full-tools.
read-only is local-only and includes read, grep, find, and ls.
read-only-with-safe-bash is local-only and adds bash with a read-only command allowlist.
full-tools means the normal full local Pi tool surface rather than a sandbox permission level.
full-tools is not guarded by an extension confirmation prompt during the subagent run.
Version one does not add special restrictions preventing full-tools from being used as a global default, agent default, or spawn override.
If a request is ambiguous about whether full-tools is appropriate, the main agent may ask the user before spawning, but the extension does not enforce that policy.
Built-in profiles do not include web or network access except insofar as full-tools exposes ordinary bash.
The in-code default tool profile is read-only when no config overrides it.
The default tool profile is configurable in subagents.json.
Trusted project .pi/subagents.json may loosen or tighten global defaults.
This follows Pi extension convention: project config overrides global config after trust.
Version one should not implement special tighten-only merge semantics.
Optional built-in UI settings live under ui in subagents.json.
UI settings gate only the extension-provided UI components, not the status data model, status endpoints, neutral events, or durable child records.
The spawn tool uses a single prompt field for the actual delegated work request instead of splitting prose across task and instructions fields.
A spawn request may optionally reference a named agent as a base definition.
If agent is absent, prompt is sufficient for an ad hoc runtime subagent.
If agent is present, prompt is the per-call request sent with that agent's base prompt.
Version one exposes both single-spawn and batch-spawn tool surfaces.
The single-spawn surface handles one subagent request.
The batch-spawn surface accepts multiple subagent requests.
All subagent spawns are non-blocking in version one.
Spawn tools return after spawn acceptance with child ids and initial metadata.
Subagent results arrive later through the status data model, neutral events, and durable milestone entries.
The main agent decides whether and when it makes sense to wait for, poll, or retrieve subagent results.
The extension should avoid over-prescribing waiting behavior.
Version one exposes explicit post-spawn control tools: subagent_list, subagent_status, subagent_result, and subagent_cancel.
subagent_list shows active subagents plus a bounded recent terminal history by default.
The default recent terminal history should be small, such as the last 10 completed, failed, cancelled, or timed-out subagents in the current parent session.
Results and status persist through Pi session state and child session storage only in version one.
Version one does not write separate result files or artifact files.
A later web-research style profile can be user-defined when an explicit web tool or bash-network policy exists.
Version one supports both named Markdown subagents and ad hoc runtime subagents.
The spawn tool uses prompt for the delegated request in both named and ad hoc spawns.
A spawn call may optionally reference a named agent as a base definition.
If agent is absent, the spawn is an ad hoc runtime subagent driven by prompt.
If agent is present, the named definition supplies the base prompt and defaults, while prompt supplies the per-call request.
Ad hoc runtime subagents are not persisted as named definitions and inherit global defaults unless the spawn call explicitly overrides context, model, thinking, or tools.
Status should label ad hoc runtime subagents with a generated short label such as ad-hoc plus the child id.
Exact tool names are deferred to the implementation specification.
