Tool System

Tool System

The SnCode agent has access to a set of sandboxed tools for interacting with your project files and running commands.

Available Tools

File Operations

Tool	Access	Description
list_files	Read	Lists files and directories at a given path. Returns name and type (file/dir). Filters out .git entries.
read_file	Read	Reads the full text content of a file. Maximum file size: 300 KB.
write_file	Write	Writes complete content to a file. Creates parent directories if needed.
edit_file	Write	Performs exact string replacement in a file. Requires a unique match unless replaceAll is set to true.

Search Operations

Tool	Access	Description
glob	Read	Finds files matching a glob pattern (e.g., **/*.ts). Uses picomatch. Returns up to 500 results.
grep	Read	Searches file contents using regular expressions. Returns up to 200 matches. Skips binary files. Lines capped at 500 characters.

Shell Commands

Tool	Access	Description
run_command	Exec	Runs a shell command in the project root directory. 90-second timeout. Output truncated at 200 KB stdout / 80 KB stderr.

Meta Tools

Tool	Access	Description
spawn_task	Meta	Launches a sub-agent for parallel work. See Sub-Agents & Tasks.
load_skill	Read	Loads a skill's SKILL.md content by ID. See Skills System.

Security Model

Path Traversal Protection

All file operations use resolveInsideProject() which:

1. Resolves the path relative to the project root
2. Verifies the resolved path is still within the project root
3. Rejects any path that would escape (e.g., ../../etc/passwd)

File Size Limits

Operation	Limit
read_file	300 KB
file:read IPC	500 KB
Untracked diff content	50 KB

Command Safety

The safeCommand() function automatically injects exclusion flags for common recursive search commands:

Command	Auto-Injected Flags
grep -r	--exclude-dir={node_modules,.git,...}
rg (ripgrep)	--glob=!{node_modules,.git,...}
find	-not \( -path ...node_modules -prune \) for each heavy dir

Output Truncation

Stream	Limit
stdout	200 KB
stderr	80 KB

If output exceeds the limit, it is truncated with a ... [truncated] marker.

Heavy Directory Exclusion

These directories are automatically skipped in file tree listings, glob searches, and command safety:

node_modules, .git, .next, .nuxt, dist, build, .output, __pycache__, .venv, venv, .tox, vendor, .bundle, coverage, .cache, .turbo, .parcel-cache

Shell Detection

SnCode detects the best available shell on each platform:

Platform	Priority
Windows	pwsh (PowerShell 7+) > powershell (5.1) > cmd.exe
macOS	$SHELL environment variable, or /bin/zsh
Linux	$SHELL environment variable, or /bin/bash

Tool Call Flow

1. The AI model returns one or more tool calls in its response
2. Sequential tools (list_files, read_file, write_file, edit_file, glob, grep, run_command, load_skill) execute one at a time
3. spawn_task calls are batched and run in parallel (up to maxConcurrentTasks)
4. Tool results are sent back to the model as tool result messages
5. The loop repeats until:
   • The model responds with only text (no tool calls)
   • The maxToolSteps limit is reached
   • The run is cancelled by the user