VBW uses three layers of Claude Code’s permission system to enforce what each agent can and cannot do. The key property of this design is that the strictest constraints are enforced by the Claude Code runtime itself — not by prompt instructions that an agent might summarize away during context compaction.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/swt-labs/vibe-better-with-claude-code-vbw/llms.txt
Use this file to discover all available pages before exploring further.
Three layers of control
tools — an explicit allowlist. Only the listed tools are available to the agent. This is the primary mechanism for scoping agent capabilities to what they actually need.
disallowedTools — a platform-enforced denylist. These tools are blocked by Claude Code itself, not by the agent’s instructions. An agent cannot use a disallowedTools entry even if its compressed context tells it to try.
permissionMode — controls whether an agent can apply changes autonomously:
plan— read-only; the agent can propose changes but cannot apply themacceptEdits— the agent can propose and apply changes without per-edit approval
Per-agent permission matrix
| Agent | Permission mode | Platform-denied tools |
|---|---|---|
| Scout | plan | Bash, Edit, NotebookEdit, Task |
| Architect | acceptEdits | Edit, WebFetch, Bash |
| Lead | acceptEdits | Edit |
| Dev | acceptEdits | — (full access) |
| QA | plan | Write, Edit, NotebookEdit |
| Debugger | acceptEdits | — (full access) |
| Docs | acceptEdits | — |
Why platform enforcement matters
Prompt instructions can be compressed or forgotten during context compaction. If an agent’s constraints live only in its system prompt, a long session can erode them.disallowedTools in YAML frontmatter is enforced by the Claude Code runtime at the tool-call level. The agent cannot invoke those tools regardless of what its compressed context says. This is the difference between a behavioral constraint and a hard block.
VBW uses
disallowedTools for the constraints that matter most — the ones that prevent agents from modifying source code outside their designated scope, or from spawning subagents that could escape the team structure.Agent-specific notes
Scout’s research boundary
Scout has the most restrictive permission set. ItsdisallowedTools blocks Bash, Edit, NotebookEdit, and Task. Scout can read files and write research artifacts to .vbw-planning/ — but it cannot modify source code, run shell commands, or spawn sub-agents.
This boundary is intentional. Scout’s job is to analyze the codebase and produce findings. It has no business touching implementation files, and the platform enforces that.
QA’s write path
QA runs inplan mode with Write and Edit in disallowedTools. It cannot write directly to any file. The one exception is VERIFICATION.md: QA persists its verification results through the deterministic write-verification.sh script, invoked via Bash.
This design prevents QA from accidentally modifying source code while running verification, while still giving it a controlled path to record results.
Architect’s restricted tools
Architect is planning-only and excluded from the team execution and shutdown protocol. ItsdisallowedTools blocks Edit, WebFetch, and Bash — keeping it focused on architecture decisions and plan documents rather than implementation or web research.
--dangerously-skip-permissions and VBW
When you run claude --dangerously-skip-permissions, Claude Code stops prompting for tool approval at the session level. VBW’s platform-enforced disallowedTools still apply.
Scout still cannot run Bash. QA still cannot write directly to files. The session-level approval prompts are suppressed; the per-agent platform constraints remain active.
Security filter
In addition to the per-agent permission matrix, asecurity-filter.sh PreToolUse hook intercepts Read, Glob, Grep, Write, and Edit calls for all agents. It blocks access to:
.envand.env.*files- Private keys (
.pem,.key) - Certificates (
.cert,.p12,.pfx) - Credential files (
credentials.json,secrets.json,service-account-*.json) node_modules/,.git/,dist/,build/directories
jq is unavailable or input is unparseable, the hook blocks the call.
See Hooks for the full list of PreToolUse handlers.