Scope Enforcement
Relevant source files
The following files were used as context for generating this wiki page:
Scope Enforcement is a security and operational integrity mechanism within the opencode-swarm project designed to restrict the file modification capabilities of autonomous agents, specifically the Coder agent. It implements the "Prime Directive" of preserving runtime contracts while ensuring that automated code changes remain bounded and safe across various execution contexts.
The system requires an Architect agent to explicitly declare the permissible file scope for a specific task before delegating implementation to a Coder. This prevents "scope creep," unintended side effects in unrelated files, and unauthorized access to sensitive system or project configuration files.
Sources: src/agents/architect.ts:251-265, AGENTS.md:12-25
Architecture and Components
The Scope Enforcement system operates through three primary layers: Declaration, Persistence, and Guarding.
1. Scope Declaration
Before any coder delegation, the Architect must invoke the declare_scope tool. This tool validates the requested paths against security constraints (e.g., path traversal, null bytes) and verifies that the task exists and is not already completed.
Key features of declaration include:
- Task Binding: Scopes are tied to a specific
taskIdfrom the project plan. - Path Normalization: Absolute paths are converted to relative paths to prevent prefix matching failures in downstream checks.
- Symlink Prevention: The system performs an
lstatcheck to reject any declared path that contains a symlink, preventing writes from being redirected outside the project directory.
Sources: src/tools/declare-scope.ts:100-240, tests/unit/hooks/write-lstat-authority.test.ts:210-250
2. Scope Persistence
To support cross-process delegation (where a Coder might start in a separate process from the Architect), the declared scope is persisted to disk under the .swarm/scopes/ directory.
The diagram above illustrates how the scope moves from declaration to enforcement across process boundaries.
Sources: src/tools/declare-scope.ts:314-325, src/scope/scope-persistence.ts:15-35
3. Scope Guard Hook
The scope-guard is a runtime hook that intercepts tool calls before execution (toolBefore). It monitors write-capable tools (e.g., write, edit, patch, create_file). If a non-Architect agent attempts to modify a file, the guard verifies the path against the declaredCoderScope in the active session or the on-disk fallback.
Sources: src/hooks/scope-guard.ts:45-80, src/hooks/scope-guard.test.ts:40-60
Enforcement Logic
Scope enforcement follows a strict protocol to ensure that the Coder respects the boundaries set by the Architect.
Path Verification
The function isFileInScope determines if a target path is permissible. A path is considered in scope if:
- It is an exact match for a declared file.
- It is contained within a declared directory.
- It has been normalized to remove traversal sequences like
...
Sources: src/hooks/scope-guard.ts:125-150, src/hooks/scope-guard.test.ts:220-250
Write Blocked Protocol
If the Scope Guard denies a write, the tool returns a "WRITE BLOCKED" error. The Coder agent is strictly prohibited from using shell-based workarounds (like sed, echo >, or cat >>) to bypass this block.
Sources: src/agents/coder.ts:150-175, src/agents/architect.ts:255-265
| Feature | Description | File |
|---|---|---|
| Mechanical Completeness | Ensures all code paths are handled before submission. | src/agents/coder.ts:210 |
| Symlink Guard | Blocks writes through symlinks to prevent directory escape. | src/hooks/guardrails.ts:85-110 |
| Path Traversal Protection | Rejects paths containing .. during scope declaration. | src/tools/declare-scope.ts:55-65 |
| Universal Deny | Globally prohibits access to sensitive paths like .env or secrets/. | tests/unit/hooks/write-lstat-authority.test.ts:140-160 |
Interaction Flow
The following sequence diagram shows the interaction between the Architect, the Coder, and the Scope Enforcement mechanism during a standard task implementation.
Configuration and Constraints
Scope enforcement is subject to the following technical constraints:
- Tool-Layer Limitation: Currently, scope is enforced at the Edit/Write/Patch tool layer. Bash-based writes (e.g.,
echo > file.txt) bypass these checks, though they are strictly prohibited by agent system prompts. - Maximum Path Length: File paths are capped at 4096 characters to prevent buffer-related vulnerabilities.
- Non-Architect Restriction: The Architect agent is exempted from scope guard checks to allow for plan management and project orchestration, though it is still prohibited from editing source code directly by its own identity prompt.
Sources: src/tools/declare-scope.ts:70-75, src/tools/declare-scope.ts:327-335, src/hooks/scope-guard.test.ts:80-95
Conclusion
Scope Enforcement is a critical safety boundary in opencode-swarm. By combining proactive path validation, secure persistence, and runtime interception, the system ensures that autonomous agents operate within strictly defined project areas. This architecture balances the need for agent autonomy with the necessity of maintainable and secure automated development workflows.