Shell Write Detection
Relevant source files
The following files were used as context for generating this wiki page:
Shell Write Detection is a critical security and architectural guardrail within the opencode-swarm project, primarily implemented through the Write Blocked Protocol (#519 v6.71.1). Its purpose is to ensure that automated agents (specifically the Coder agent) strictly adhere to the file-scope boundaries declared by the Architect. It prevents agents from using shell commands or system utilities to bypass write-authority checks that are enforced at the tool level.
The system operates on the principle that write-authority is tool-scoped, not syscall-scoped. If a primary editing tool (like Edit, Write, or Patch) is denied access to a path, the agent is prohibited from using any alternative mechanism—such as shell redirection or in-place editors—to modify that path.
Sources: src/agents/coder.ts:130-153, AGENTS.md:38-46
Write Blocked Protocol
The core logic of Shell Write Detection is triggered when an Edit, Write, or Patch tool returns a "WRITE BLOCKED" status. This status indicates that the target file path was not included in the agent's declared scope. Upon receiving this block, the agent must immediately stop and is strictly forbidden from attempting any workaround.
Forbidden Mechanisms
The protocol enumerates several categories of shell-based and utility-based indirection that are prohibited for bypassing scope restrictions:
- Shell Redirection: Use of
>,>>,tee, or here-docs (<<HEREDOC). - File Utilities: Commands like
cp,mv,install,rsync, orln. - In-place Editors: Use of
sed -i,perl -pi,awk, or interpreters likenode -eorbun -e. - Patch/Binary Tools:
git apply,git restore,xxd -r, orbase64. - Network-sourced Writes:
curl -o,wget -O, orsshpipes. - Indirection Wrappers:
eval,bash -c, or subshells.
Sources: src/agents/coder.ts:133-146
Reporting and Resolution Flow
When a write is blocked, the agent must report the state using a specific format, prompting the Architect to either expand the scope or correct the target path.
The diagram above illustrates the decision flow when an agent encounters a blocked path, emphasizing the "Stop" requirement to prevent scope bypass.
Sources: src/agents/coder.ts:131-151
Subprocess and Runtime Invariants
Shell Write Detection is supported by global engineering invariants that govern how subprocesses are spawned and how the .swarm/ directory is contained. These rules ensure that shell executions are bounded and do not produce undeclared side effects.
Invariant 3: Subprocess Constraints
To maintain portability and safety, all subprocesses must follow these rules:
- Array-form Spawn: No shell-string commands are allowed unless specifically justified; this prevents shell injection and accidental redirection.
- Explicit CWD: Processes must not rely on inherited working directories.
- Stdin/Stdout Management:
stdinmust be set toignoreto prevent hanging processes, and stdout/stderr must be bounded. - Timeouts: Mandatory timeouts for all external binaries (e.g.,
git,npm,bun).
Sources: AGENTS.md:58-69
Invariant 4: .swarm Containment
Runtime state must live exclusively under the .swarm/ directory. No tool is permitted to create files or directories outside of this boundary unless they are version-controlled deliverables authored by the docs agent.
Sources: AGENTS.md:73-83
Execution Guardrails
The system-enhancer hook injects specific instructions into agent prompts to prevent unauthorized command execution that could lead to unmonitored file writes or system instability.
Command Prohibitions
Agents like the Coder and Test Engineer are explicitly instructed NOT to run certain commands that perform significant I/O or verification, as these are reserved for the Reviewer:
- Build/Verification:
npm run build,bun test,npx tsc,eslint. - Full Test Suites: Running broad test commands without explicit file paths is prohibited to avoid crashing the plugin host.
Sources: src/hooks/system-enhancer.ts:575-600
Summary of Component Roles
| Component | Responsibility in Write Detection | Source |
|---|---|---|
| Architect | Declares file scope via declare_scope. | src/config/constants.ts:160 |
| Coder Agent | Executes the Write Blocked Protocol; reports blocked paths. | src/agents/coder.ts:130 |
| Reviewer Agent | Performs post-hoc "Substance Verification" to detect "Import Theater" or stubs. | src/agents/reviewer.ts:167-185 |
| System Enhancer | Injects runtime guardrails and security warnings into system prompts. | src/hooks/system-enhancer.ts:101 |
Post-hoc Detection and Verification
Since bash/shell tools are opaque to static scope analysis, the project relies on secondary coverage via the Reviewer agent and diff tools.
Substance Verification
The Reviewer agent scans for "vaporware"—code that appears complete but uses placeholders or stubs to bypass implementation requirements. Indicators include high comment-to-code ratios or new imports that are never utilized.
Sources: src/agents/reviewer.ts:167-180
Diff-Scope Verification
The Architect uses the diff and diff_summary tools to detect "undeclared diffs"—changes made to files that were not in the agent's declared scope. This provides a backstop if an agent successfully uses a shell workaround to modify a file.
Sources: src/agents/coder.ts:152-153, src/config/constants.ts:250
Conclusion
Shell Write Detection in opencode-swarm is a multi-layered defense system. It combines pre-emptive tool-level blocks (Write Blocked Protocol), strict subprocess execution rules (Invariant 3), and post-execution verification (Reviewer substance checks) to maintain the integrity of the project's architectural boundaries. This ensures that every file modification is explicitly authorized, documented, and reviewed.