Subagents

A subagent is a second agent your agent can hand a task to. In OpenStation they need no platform support at all: they are Claude Code's own subagents, so a subagent is another .md file in .claude/agents/ and nothing else.

That means the whole feature is one file and one permission.

The one that runs, and the ones it can call

Every file in .claude/agents/ is a subagent definition. The manifest picks which one is the running agent:

agents:
  main: # -> .claude/agents/main.md becomes the agent answering messages
    identity: agent:main
    executor: claude-cli
    claudeSettings: main

Everything else in that directory stays available for delegation. So this workspace has one agent on the channel and one delegate behind it:

.claude/
  agents/
    main.md          # the manifest names this one — it answers messages
    researcher.md    # never addressed directly; main hands work to it
  settings.main.json

researcher.md needs no manifest entry. Adding one would make it a second OpenStation agent — a different thing, covered at the end.

The subagent file

An ordinary Claude Code agent file. The description is load-bearing: it is how the running agent decides whether to delegate, so write it as instructions for the caller, not a title.

---
name: researcher
description: Reads files and reports what they contain. Use for any lookup task.
tools: Read, Glob
---

You are a researcher. Report exactly what you find, and say so plainly when you find nothing.

tools: narrows what this subagent may use within what the session already permits. It can only subtract — a subagent cannot grant itself something the settings file denies.

You must allow `Task`

Delegation happens through the Task tool, so the running agent needs it in the settings file that claudeSettings: names:

{
  "permissions": {
    "allow": ["Read", "Glob", "Task"]
  }
}

The scaffolded settings file does not include it. openstation create writes ["Read", "Glob", "Grep", "Skill", "Edit(okf/**)", "Write(okf/**)"], so a fresh workspace cannot delegate until you add Task.

Leaving it out does not fail cleanly. Measured on a real run: with Task denied, the agent did not stop — it tried Bash(ls .claude/agents/), then a workflow tool, was denied both, and finally did the work itself, reporting "I could not use the researcher subagent, so I read the file myself." That took 13 model turns and $0.50, against 2 turns and $0.30 for the same request with Task allowed. A missing grant is not a cheap no-op; it is a more expensive turn that reaches a worse answer.

What a subagent inherits

Inherits	Does not inherit
The settings file — one gate for the whole session, subagents included	A profile. `.openstation/profiles/` addenda apply to the running agent only
The workspace root as cwd	Its own session. The delegation happens inside the caller's turn
The turn's budget, which the whole turn shares	A separate budget. A delegating turn is one turn

The important row is the first. Permission is a property of the session, not of who is acting inside it, so a subagent cannot exceed the running agent's gate — and equally, anything you allow for the running agent is allowed for every subagent it calls. If a delegate should be unable to write, deny writes at the settings file; narrowing tools: in the subagent file is a routing hint, not a boundary.

Cost

Delegation is not free. Every subagent call is a fresh model context: the same measured workspace cost $0.30 for one delegating turn, against $0.02–$0.18 for ordinary turns. If you added getting started's budget: { maxUsd: 0.50 }, a single delegating turn can come close to it, and a failed delegation can hit it outright.

Raise the ceiling deliberately if an agent delegates as a matter of course:

budget:
  maxUsd: 2.00

Subagent, or a second OpenStation agent?

Both put a second .md in .claude/agents/. The difference is who addresses it.

	Subagent	Second OpenStation agent
Addressed by	the running agent, mid-turn	a person, in a channel
Declared in	nothing — the file is enough	`agents:` in the manifest
Has its own	`tools:` narrowing	settings file, policy, budget, channels
Conversation	none; it is part of one turn	its own sessions

Use a subagent when the work is a step: research this, summarize that, check the thing. Use a second OpenStation agent when the work has its own audience — a different team, a different channel, a different permission story.

One caveat before you split an agent in two: per-message channel routing is not wired yet. One process serves one agent regardless of channels:, so a second manifest agent needs a second serve process today. A subagent has no such limitation, which is often the deciding factor. See internal/roadmap.md.

Checking it works

openstation dev and ask for something that should be delegated. The turn log names the tool call, so a successful delegation is visible:

assistant: I'll dispatch the researcher subagent to look for it.
result turns=2 cost=$0.3027 duration=42.4s

If the agent answers directly and mentions it could not use the subagent, the Task grant is missing. If it never mentions the subagent at all, the description is not telling it when to delegate.