82 lines
6.1 KiB
Markdown
82 lines
6.1 KiB
Markdown
---
|
|
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.
|