Agents
An agent is a role the session can play. Four things define one:
- A system prompt — the instructions for this role.
- A tool allow-list — which tools it can see. Omitted means all of them.
- A permission ruleset — what it may do without asking you.
- Optional model and temperature — a stage that should run on a different model says so here.
You pick one per session from the composer's dropdown, and it can change mid-session: a harness advances it, plan_enter swaps it, and the agent_handoff tool hands it forward.
Modes
Mode decides where an agent can be used, not what it can do.
| Mode | Pickable by you | Usable as a task sub-agent | Valid harness stage |
|---|---|---|---|
primary | yes | no | yes |
subagent | no | yes | no |
all | yes | yes | yes |
hidden | no | no | no |
hidden is for the runtime's own bookkeeping turns — summarising, titling, compacting. They never appear anywhere.
The built-in agents
| Agent | Mode | What it's for |
|---|---|---|
build | primary | The default. Full filesystem access; everything dangerous asks. |
plan | primary | Read-only planning. Investigates, writes a plan file for your approval, cannot modify code. |
orchestrator | primary | Decomposes a task, delegates to specialists, synthesizes the result. |
implement | all | Coding worker. Executes one scoped change end to end and returns a summary. |
debug | all | Root-causes a failure: reproduce, isolate, explain. Reports the cause, not a symptom patch. |
test | all | Writes and runs tests, reports real pass/fail output. |
review | all | Read-only adversarial review of a diff. Returns severity-ranked findings. |
explore | subagent | Read-only codebase search and analysis. |
research | subagent | Read-only web and codebase research, returns a cited answer. |
general | subagent | General-purpose delegate. Most tools, no recursive spawning. |
social | primary | Drafts and posts to configured social integrations. |
Four more — react-architect, react-scaffold, react-runner, and react-qa-brief — are stages of the built-in React JS harness rather than personas. They're valid stages in any chain, but they stay out of the agent picker. See harness-only agents.
Where definitions come from
| Source | Location | Editable |
|---|---|---|
| Native | Ships in the build | No — override specific fields via the config block |
| Global markdown | ~/.config/podcode/agent/<id>.md | Yes, from Settings → Agents or by hand |
| Workspace markdown | .podcode/agent/*.md, only when agent_autodiscover is on | By hand; belongs to the repo |
| Config block | agent.<id> in config.json | By hand |
Agent ids are global. Whichever source an agent comes from, its id has to be unique across all of them — which is why the React harness prefixes its stages react-.
Next
- Create an agent — the frontmatter format, field by field.
- Delegation vs handoff —
taskandagent_handoffare not the same tool. - Harnesses — chaining agents into a pipeline.