Roles
Built-in worker roles, harness and model selection, and project-defined role configuration.
A role is a reusable worker contract: its system prompt, tool restrictions, model default, MCP servers, permissions, and access to terminal tools. The role describes the job; the spawn chooses which installed harness runs it.
Built-in roles
| Role | Purpose | Editing and tools |
|---|---|---|
builder | Implement production-ready features. | Read/write. |
qa | Review a diff and give a verdict. | Write and Edit blocked on Claude; can still run commands. |
validator | Compare changes with the original specification. | Write and Edit blocked on Claude; can still run commands. |
backend | Work on APIs, services, and databases. | Read/write. |
frontend | Work on UI, client logic, and styling. | Read/write. |
devops | Work on CI/CD, infrastructure, Docker, and build tooling. | Read/write. |
security | Audit authentication, injection, secrets, and common vulnerabilities. | Reports only; Write and Edit blocked on Claude; can still run commands. |
Every role that can run commands also gets visible terminal tools, unless it sets terminalAccess: false, blocks Bash or PowerShell, or the worker runs in plan mode or Codex's read-only supervised mode. terminalAccess: true grants them in any mode.
Click the role chip in a worker's header to see what that role may do: its system prompt, which tools are allowed or blocked, whether it can open terminals, and any model, permission, turn or budget limits. A master can also invent a role label on the spot; when it does, it can pass a roleDescription that the chip shows instead, so you still know what the worker is for.
There is no built-in pr role. A project can define one in .agent-grid/roles.json; call list_roles to see the roles available in the active project.
Permission modes
A role's permissionMode sets how much its workers may do without asking. From AgentGrid 2.9.52, a worker starts in the mode its spawn asked for, else its role's mode, else Settings → Agents → Default permissions. That setting is a ceiling: no worker launches looser than it, and an agent can't start a worker looser than itself.
| Mode | Claude worker | Codex worker |
|---|---|---|
plan | Plans first; shell commands can still change files. | Read-only sandbox. |
default | Asks before edits and commands. | Full access, no sandbox. |
auto | Claude checks tool calls automatically and can ask for approval. | Writes only inside its working folder; risky commands are reviewed automatically. |
bypassPermissions | No checks. | Full access, no sandbox. |
Other harnesses map each mode to their closest option, and some don't offer every mode.
Read-only reviewers. The built-in qa, validator and security roles block Write and Edit on Claude only, and they can still run shell commands, which can change files. For a reviewer that can't change files, pick Read-only on the worker's access chip (Claude and Codex workers); see Access levels in composers. A lead can also set its own workers to Read-only, so you can ask it to make its reviewers Read-only; the level applies from the worker's next turn.
Builders in their own worktree. A Codex builder in auto can edit its worktree but can't git commit or git worktree add: Codex always protects .git, and a worktree's git data lives in the main checkout's .git. We're working on it. For now, let the lead create the worktree with create_worktree and make the commits.
Why leads have full access. Team leads run unattended, so they start at the most permissive mode their harness supports. To limit one, turn on Settings → Agents → Show per-pane permissions and pick a level from the access chip in its composer. See Access levels in composers.
Choose the harness and model at spawn time
Any master-capable harness can call spawn_role. Pass harness to run the role on any installed worker harness and optionally pass a harness-specific model.
spawn_role({
role: "qa",
harness: "codex",
model: "gpt-5.6-sol",
prompt: "Review the current diff and report file:line findings."
})If harness is omitted, the worker inherits the master's harness. A role’s pinned model takes precedence, then an explicit spawn model, then the saved harness default. An explicit model without remaining capacity is refused rather than silently replaced; project restrictions still apply. Use list_worker_harnesses for the installed catalog and current model suggestions. For Claude, that guidance points the hardest work at Opus 5.5 and suggests Fable only when you ask for it.
Claude backend selection
Claude workers can use one of two backends:
- SDK - streams a structured transcript through the Claude Agent SDK and can receive MCP servers.
- PTY - drives the interactive
claudeCLI and uses the configured Claude CLI account.
Roles that require MCP servers, such as roles that set terminalAccess: true, use the SDK. Other roles follow your backend choice. On PTY, Claude workers get AgentGrid's canvas tools and the terminal tools allowed by their role and access level, alongside your own MCP servers. Other harnesses use their registered worker runtime rather than the Claude backend setting.
Custom roles
Add .agent-grid/roles.json at the project root to define a role or override a built-in one. Definitions merge over the built-ins.
{
"pr": {
"systemPrompt": "Prepare a pull request and summarize its verification.",
"allowedTools": ["Read", "Bash"],
"disallowedTools": ["Write", "Edit"]
}
}The retired browser_qa role name still resolves to the qa role (its system prompt, with Write and Edit disallowed) so older workers stay read-only. create_role refuses the name, like a built-in. A browser_qa entry written by hand in .agent-grid/roles.json inherits every qa field it does not set, including the system prompt and the Write/Edit block.
Supported role fields include systemPrompt, allowedTools, disallowedTools, model, models, maxTurns, maxBudgetUsd, mcpServers, permissionMode, terminalAccess, writePathPrefixes, and backend.
A master can also define a role at runtime with the create_role MCP tool instead of hand-editing the file. It writes to the same .agent-grid/roles.json, whitelisting the same fields (mcpServers and backend are not settable this way). Pin models with models, keyed by worker harness; a bare model is accepted only from Claude masters. Built-in role names are immutable through this tool: a name matching a built-in (builder, qa, validator, backend, frontend, devops, security) always hard-rejects, even with overwrite: true — pick a different name. overwrite: true only bypasses a collision with an existing custom role, replacing it. Call list_roles first to see what is already defined; its entries include a source: "builtin" | "custom" field so you can tell the two apart.
writePathPrefixes is an advisory contract. The runtime reinforces it in the worker prompt, but it is not a filesystem sandbox. Use review and post-run auditing when a hard boundary matters.
Model overrides are scoped by harness so a Claude model cannot leak into a Codex worker:
{
"builder": {
"models": {
"claude": "claude-opus-4-8",
"codex": "gpt-5.6-sol"
}
}
}The legacy "model": "..." form remains supported for Claude roles. Use models for new configuration and whenever a role can run under more than one harness.
Related
- Orchestrating agents - spawn and review-loop patterns.
- Coding harnesses - available master and worker runtimes.
- The .agent-grid folder - project-local AgentGrid configuration.