---
status: done
claimed-by: "019fba91-eabf-76ae-b086-a37ac061d6e8"
claimed-at: "2026-07-31T21:47:35-04:00"
completed-at: "2026-07-31T22:17:24-04:00"
parent: "[[002-pi-subagents-map]]"
blocked-by:
  - "[[028-pi-subagents-agent-definition-conventions-research]]"
tags:
  - ticket/grill
---

# Subagent configuration boundary

## Question

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.