28 Core Tools Catalog
Typed tool execution lifecycle, risk classes, and parameter schemas.
M31A provides 28 core typed tools across 15 capability families. Every tool defines strict JSON schemas generated by schemars.
Tool Execution Lifecycle
1. Schema Validation → Validate parameters against JSON schema contract
2. Policy Evaluation → 11-stage policy gate evaluation (ALLOW/DENY/ASK)
3. Budget Pre-Allocation → Two-phase reservation of tokens and memory
4. OS Confinement → Execution in cgroups v2, POSIX rlimits, clean env
5. Output Redaction → SecretRedactor scrubs API keys before persistence
Catalog of 28 Core Tools
| Tool Name | Category | Risk Class | Description |
|---|---|---|---|
| read_file | Filesystem | ReadOnly | Reads file content within workspace root with optional byte pagination. |
| write_file | Filesystem | WorkspaceMutation | Overwrites or creates a new file at specified workspace path. |
| edit_file | Filesystem | WorkspaceMutation | Applies targeted line/range substitutions to an existing file. |
| apply_patch | Filesystem | WorkspaceMutation | Applies a unified diff patch (git diff format) to workspace files. |
| list_files | Filesystem | ReadOnly | Lists entries in workspace directory with size and type attributes. |
| glob | Filesystem | ReadOnly | Finds workspace files matching a glob pattern (e.g. src/**/*.rs). |
| grep | Filesystem | ReadOnly | Searches file contents using regular expressions or literal strings. |
| repo_search | Repository | ReadOnly | Performs semantic or symbol-based search across repository codebase indexes. |
| repo_symbols | Repository | ReadOnly | Extracts AST definitions, functions, structs, traits, and enums from a file. |
| repo_dependencies | Repository | ReadOnly | Analyzes package dependencies from Cargo.toml or package manifests. |
| run_command | Process | HighRiskMutation | Spawns a synchronous child process under POSIX rlimits and cgroups confinement. |
| start_job | Process | HighRiskMutation | Launches an asynchronous background job with streaming spool output. |
| job_status | Process | ReadOnly | Inspects current status (Running, Completed, Failed) of a background job. |
| job_output | Process | ReadOnly | Reads streaming stdout/stderr output from a running or completed job. |
| job_stop | Process | HighRiskMutation | Sends SIGTERM / SIGKILL to a background job process tree. |
| git_status | Git | ReadOnly | Returns clean/dirty state, staged changes, and untracked files. |
| git_diff | Git | ReadOnly | Computes unified diff of working tree changes or specific commits. |
| git_log | Git | ReadOnly | Retrieves commit history with hashes, author info, and trailer blocks. |
| git_show | Git | ReadOnly | Shows detailed commit metadata, commit message, and full patch diff. |
| git_branch | Git | WorkspaceMutation | Lists, creates, or switches branches within the local repository. |
| git_checkout | Git | WorkspaceMutation | Checks out a branch or reverts specified files to HEAD revision. |
| git_add | Git | WorkspaceMutation | Stages specified file modifications or untracked files for commit. |
| git_commit | Git | WorkspaceMutation | Creates a new Git commit with RFC-compliant M31A attribution trailers. |
| run_tests | Verification | HighRiskMutation | Executes project test suites (cargo test, etc.) and parses structured test results. |
| run_formatter | Verification | WorkspaceMutation | Runs code formatting (cargo fmt, etc.) in check or modification mode. |
| run_linter | Verification | HighRiskMutation | Executes static analysis and linter suites (cargo clippy, etc.). |
| create_artifact | Artifacts | WorkspaceMutation | Stores an immutable content-addressed artifact with streaming quota checks. |
| read_artifact | Artifacts | ReadOnly | Retrieves content and metadata of a previously stored artifact by ID. |
Canonical Tool Error Taxonomy
Tools return strongly typed errors categorized into standard classifications: Validation, ResourceNotFound, PreconditionFailed, PermissionDenied, ExecutionFailed, ResourceExhausted, and CapabilityUnavailable.