[FEATURE] Roles: one committed, selectable bundle of agent, settings, instructions and write scope per team role

Status Open

Maintainer reply None cached

Activity 3 comments · opened Sep 28, 2026

Re-filing #81615, which the inactivity bot closed. Several features shipped since then now cover part of it, so this version is shorter and builds on them. #81615 has the full spec.

Problem Statement

One repository and one clone, used by a mixed team: developers, QA, DevOps, and a business analyst who keeps specs in the repo. Claude Code loads the same CLAUDE.md, skills and permissions for all of them. The BA asks "does the implementation match this spec?", and Claude, following developer-oriented project memory, starts editing source files. A QA engineer asks for a bug repro and ends up with a migration run against staging.

Most of the pieces for roles now exist:

claude --agent qa (or "agent": "qa" in settings) runs the session as an agent definition, with that agent's tools, model, permissionMode, preloaded skills, hooks and MCP servers.
claude --settings .claude/roles/qa.json adds a committed settings file with Edit(...) and Bash(...) rules.

What's missing is what would make them a role:

One switch. Today a role means two flags on every launch. "agent" can be persisted in settings.local.json, but persisting the settings half per person means copying its rules there, where they are no longer shared or reviewed.
A write allow-list. Rules are evaluated deny → ask → allow, so "this role edits only docs/** and specs/**" has to be written as a deny list of every other directory, and that list goes stale as the tree grows. dontAsk comes close, but it also auto-denies every Bash command that isn't pre-approved. In agent frontmatter, a path rule in disallowedTools removes the whole tool (#97212).
Role instructions. An agent's body replaces the default system prompt, and CLAUDE.md still loads in full for everyone. There's no role-level CLAUDE.md that loads after the shared one.

Proposed Solution

// .claude/settings.json: shared and reviewed in PRs
{
  "roles": {
    "ba": { "agent": "ba", "settings": ".claude/roles/ba.json", "writeScope": ["docs/**", "specs/**"] },
    "qa": { "agent": "qa", "settings": ".claude/roles/qa.json", "writeScope": ["tests/**", "fixtures/**"] }
  }
}

Selection: claude --role qa, /role qa, or "role": "qa" in settings.local.json.
writeScope: edits outside it are denied wherever Edit(...) rules already apply (file tools, recognized Bash file commands, redirections), and at the OS level by the sandbox when it's enabled.
Instructions: .claude/roles/<role>/CLAUDE.md loads after the project CLAUDE.md.
Only narrows: a role can restrict project settings but never widen them.
Visible: the active role appears in the startup header and in the status line input.

Skills, hooks and MCP servers already come through the agent and the settings file, so they need nothing new.

Alternative Solutions

--agent + --settings today. Works, but it's two flags per launch, with no write allow-list and no role-level instructions (see above).
Per-person ~/.claude or CLAUDE_CONFIG_DIR. Not shared, not reviewed, and it drifts.
A "who are you?" skill at session start. It's model-driven and fades after compaction. It's an instruction, not enforcement.

Additional Context

Related: #92643 (directory allow-list / default-deny for file tools), #92615 (no single syntax for "only these paths"), #90818 (settings profiles in VS Code), #89509 (role guardrails for Agent Teams).

View original on GitHub ↗

3 Comments

RomanKryvolapov · 12 days ago

Update after a discussion on r/ClaudeCode, where several people run mixed teams on one repo. Most of this can already be assembled, which narrows what the request needs to cover.

What works today:

Write allow-list: a PreToolUse hook on Edit|Write in the agent's own frontmatter that checks the path against the role's folders and exits 2 otherwise. Frontmatter hooks also run when the agent is the main session (--agent or the agent setting), and new folders are denied by default.
One switch: "agent": "qa" in each person's .claude/settings.local.json. With the hooks in the agent file, the separate --settings file is often unnecessary.
Outside Claude Code: QA sessions run with a read-only staging user, so a migration fails at the database whatever the model decides.

What is still missing:

Bash. The hook covers Edit|Write, while sed -i, redirects and scripts need a second hook or Bash kept on ask for the role. A declarative write scope that Claude Code enforces on every write path (file tools, recognized Bash writes, the sandbox) would replace per-team hook scripts.
Role instructions. omitClaudeMd is ignored for the main session, so the shared CLAUDE.md loads for everyone. A nested src/CLAUDE.md doesn't help either: it loads as soon as Claude reads src/, which is exactly what "does the implementation match this spec?" makes it do. The workaround today is a role-neutral CLAUDE.md, with dev guidance moved into the dev agent or a skill.

So the request narrows to two things: a declarative write scope per agent that also covers Bash, and per-agent instructions loaded after the shared CLAUDE.md (or omitClaudeMd honoured for main-session agents).

RomanKryvolapov · 1 day ago

A data point on where this would live: agent frontmatter keeps gaining per-agent settings, most recently autoCompactWindow in 2.1.296, next to tools, permissionMode, hooks and mcpServers. A writeScope field enforced on every write path, Bash included, would sit naturally beside them and replace the per-team PreToolUse scripts described in my previous comment.

#101650 is another example of why this needs enforcement rather than instructions: an orchestrating session ignored the project's written agent and batch limits.

bellowsai · 22 hours ago

Disclosure: I'm Rob, and I built this.

Bellows shipped exactly this bundle this week, for every agent: a desktop app (Windows, macOS, Linux) that runs Claude, Codex, Gemini CLI, Qwen Code and any ACP agent.

Roles… sets up one role per kind of person on the team: the agent, the model, the permission mode, the instructions, and the paths that role may change ("test/", "docs/specs/"). The roles are saved in .bellows/roles.json, so one commit and the whole team has them. Start work with New session as a role**; the agent is told its role first.

The write scope holds, Bash included:

An edit outside the role's paths is refused before anyone is asked, with the reason, so the agent can do it another way.
After every turn, anything changed outside those paths by any route, shell commands included, is put back and listed in the session.
Every refusal and every file put back is on the audit trail.

So your BA asks "does the implementation match this spec?" and the agent can read everything but only touch docs/; your QA role reproduces bugs under test/ and cannot run its way into a source change.

How it works: https://bellowsai.app/guides/roles-for-coding-agents?utm_source=github&utm_medium=reply

Give it a try and tell me what your team needs from it next. We act fast on feedback.