Built-in Tools Reference
Relevant source files
The following files were used as context for generating this wiki page:
Built-in tools in the OpenCode Swarm project provide the core functional capabilities that agents utilize to perform codebase analysis, implementation, and quality assurance. These tools are registered within the plugin architecture and are subject to strict permission mappings based on agent roles. They facilitate operations ranging from low-level filesystem modifications to high-level architectural oversight and documentation indexing.
The system distinguishes between "Your Tools" (Architect-owned) and "Coder's Tools," ensuring a clear separation of concerns where only specific agents possess the authority to modify source code.
Sources: src/agents/architect.ts:84-100, src/config/constants.ts:168-300
Tool Architecture and Registration
The tool system is built on a modular architecture where each tool is defined using a factory-like pattern. Tools must be explicitly exported, registered in the plugin configuration, and mapped to specific agents in the canonical constants.
Tool Permission Model
The AGENT_TOOL_MAP defines which tools each agent can invoke. The Architect agent is unique as it holds permissions for the entire toolset, including specialized orchestration and council tools. Other agents, such as the Coder or Reviewer, are restricted to a subset of tools necessary for their specific domain.
The diagram shows the hierarchical permission mapping where the Architect has global access while subagents are restricted by role.
Sources: src/config/constants.ts:168-300, AGENTS.md:160-175
Core Tool Categories
The tools are categorized by their primary function within the implementation pipeline:
| Category | Key Tools | Description |
|---|---|---|
| Modification | write, edit, patch, create_file | Tools that alter file contents. Reserved for the Coder agent. |
| Analysis | search, symbols, imports, complexity_hotspots | Read-only tools for discovering codebase structure and patterns. |
| Validation | lint, syntax_check, build_check, test_runner | Gates that verify code quality and correctness. |
| Orchestration | save_plan, update_task_status, phase_complete | Tools used by the Architect to manage state and progress. |
| Documentation | doc_scan, doc_extract, lint_spec | Specialized tools for indexing and extracting requirements from docs. |
Sources: src/config/constants.ts:327-465, src/agents/architect.ts:65-71
Specialized Documentation Tools
Doc Scan and Extract (doc_scan, doc_extract)
The doc_scan tool indexes project documentation (README, CONTRIBUTING, etc.) to build a manifest. doc_extract then uses this manifest to find actionable constraints relevant to specific tasks.
- Logic: It scans root markdown files and
docs/directories, extracting titles and summaries while ignoring noise likenode_modulesor.git. - Knowledge Integration: Extracted constraints are stored as knowledge entries in
.swarm/knowledge/doc-constraints.jsonl.
Sources: src/tools/doc-scan.ts, src/agents/explorer.ts:145-185
Spec Linting (lint_spec)
The lint_spec tool performs static analysis on .swarm/spec.md. It validates the presence of Functional Requirements (FR-IDs) and obligation keywords (MUST, SHALL, SHOULD, MAY).
Logic flow of the lint_spec tool identifying requirements and scenarios in the specification.
Sources: src/tools/lint-spec.ts:80-160
Implementation and Security Gates
Write Authority and Guardrails
The project employs strict "Write Tool" definitions. Only a specific set of tools is allowed to modify file contents. Any attempt by an agent to use shell commands (e.g., sed, echo, cat) to bypass these tools is a violation of the "Write Blocked Protocol."
- Canonical Write Tools:
write,edit,patch,apply_patch,create_file,insert,replace,append,prepend. - Security Protocol: Agents must call
declare_scopebefore any coder delegation to whitelist the paths allowed for modification.
Sources: src/config/constants.ts:312-325, src/agents/coder.ts:133-160, AGENTS.md:75-95
Automated Verification (pre_check_batch)
The pre_check_batch tool is a parallel verification engine that runs multiple gates simultaneously to optimize the QA pipeline.
- Components: Combines
lint,secretscan,sast_scan, andquality_budget. - Outcome: Returns a
gates_passedboolean. If this fails, the Architect must return the task to the Coder for fixes before proceeding to human or agent review.
Sources: src/config/constants.ts:373-376, src/agents/architect.ts:130-145
State Management and Orchestration Tools
The Architect manages the project state via specialized JSON/JSONL ledger tools. Direct modification of these files by agents is prohibited to prevent state corruption.
| Tool | Purpose | Data Impact |
|---|---|---|
save_plan | Creates/restructures the implementation plan. | Writes to .swarm/plan.json. |
update_task_status | Marks individual tasks (e.g., [COMPLETE]). | Updates task objects in the ledger. |
phase_complete | Transitions the project to the next phase. | Finalizes phase evidence and status. |
checkpoint | Creates snapshots of the project state. | Stores project-wide state recovery points. |
Sources: src/agents/architect.ts:225-245, src/config/constants.ts:335-420, AGENTS.md:105-115
Summary
Built-in tools form the operational backbone of the swarm. By strictly mapping tools to agent roles and enforcing automated gates like pre_check_batch and lint_spec, the system ensures that codebase modifications are planned, scoped, and verified according to project-specific invariants. This architecture prevents "gold-plating" and unauthorized shell-based modifications, maintaining a portable and safe execution environment.
Sources: AGENTS.md:10-30, src/agents/architect.ts:40-60