Built-in Tools

Nehanda CLI ships with 21 built-in tools, 4 declarative safety checkers, and an MCP client that can discover tools from external servers. This page documents every built-in tool, its schema, and its phase availability.

Phase Availability

File Operations

Read

Read a file from the filesystem. Returns line-numbered content. Supports pagination with offset and limit.

Limits: Files larger than 1 MB are truncated. Each read is capped at 1,048,576 bytes.

Write

Create or overwrite a file. Parent directories are created automatically. Path is validated to stay within the working directory.

Security: Paths outside the working directory are rejected. Fires a FileChanged hook on write.

Edit

Find and replace text in a file. By default, old_string must match exactly once — if it matches multiple locations, the tool returns an error asking for more context.

Behavior: If old_string matches >1 location and replace_all is not set, the tool returns the match count and asks the model to provide more context to make the match unique. Fires a FileChanged hook.

Discovery

Glob

Find files matching a glob pattern. Walks the directory tree, skipping node_modules and .git. Returns up to 100 results.

Supported patterns: * (single segment), ** (recursive), ? (single character). Hidden files (starting with .) are skipped unless the pattern starts with ..

Grep

Search file contents with a regular expression. Supports three output modes.

Shell Execution

Bash

Run a shell command in a subprocess. The command is executed via /bin/bash -c (or bash -c on systems without /bin/bash).

Bash Guard: Every command is validated by the bash guard before execution. It blocks:

• Commands targeting paths outside the working directory (e.g. rm -rf /)
• Known destructive patterns

CWD tracking: The engine appends a marker to detect directory changes. If the command changes directory (e.g. cd src), the engine updates process.cwd() and fires a CwdChanged hook. The new CWD persists for subsequent tool calls within the same turn.

Output limits: stdout and stderr are each capped at 1 MB. If exceeded, output is truncated with [SDLC_TRUNCATED].

Web Access

WebFetch

Fetch content from a URL. Returns the response body (capped at 1 MB). Uses a 30-second timeout.

WebSearch

Search the web using DuckDuckGo Lite. Returns up to 8 results with title, URL, and snippet.

User Interaction

AskUserQuestion

Prompt the user with a question and wait for a text response. Returns the user’s answer as a string.

Note: In pipe mode (non-TTY), this tool returns (no response) since there is no interactive input.

Brief

Display a message to the user in the terminal. The message is rendered directly by the TUI — it is not sent to the model.

Task Management

TodoWrite

Create or update todo items. Each todo has an id, content/title, and status. Fires TaskCreated or TaskCompleted hooks.

TaskOutput

Record task output to the events table. Used by the model to checkpoint progress.

TaskStop

Stop a background task by sending SIGTERM.

Notebook

NotebookEdit

Edit a Jupyter notebook cell. The notebook is parsed as JSON, the target cell is found by cell_id (or a new cell is prepended), and its source is replaced.

Agent & Skills

Agent

Spawn a subagent that runs an isolated turn within the same process. The subagent gets its own session but shares the conversation. The subagent’s output is collected and returned as the tool result.

Skill

Load a skill definition from the filesystem. Searches for .ona/skills/<name>/SKILL.md or .ona/skills/<name>.md (also checks .claude/skills/ and ~/.ona/skills/).

ToolSearch

Search for available tools by name or description.

Git Worktrees

EnterWorktree

Create a git worktree for isolated work. The engine changes directory to the worktree path.

ExitWorktree

Exit the current worktree. Can either keep or remove it.

MCP Resources

ListMcpResources

List resources from a configured MCP server (or all servers).

ReadMcpResource

Read a specific resource from an MCP server.

Safety Checkers

Safety checkers are declarative tools registered from JSON configs in lib/tools/. They are mandatory in the test phase — the system prompt explicitly instructs the model: “After tests pass, you MUST run these mandatory safety checks. Do NOT skip them. If any fail, fix the issues and re-run.”

Adding a New Safety Checker

1. Create a JSON config in lib/tools/:

{
  "name": "MyChecker",
  "description": "What the checker does.",
  "input_schema": {
    "type": "object",
    "properties": {
      "target": { "type": "string", "description": "Target path" }
    }
  },
  "phases": {
    "explore_only": false,
    "planning_blocked": false,
    "mandatory_in": ["test"]
  },
  "prompt": {
    "mandatory_instruction": "Run MyChecker on the workspace.",
    "available_hint": "Checks for X, Y, and Z"
  },
  "execution": {
    "runtime": "python3",
    "script": "lib/scripts/my-checker.py",
    "args": [""],
    "default_timeout": 120000,
    "max_timeout": 600000
  }
}

1. Place the script at lib/scripts/my-checker.py. Arguments are interpolated from the args template using `` syntax.

2. No JavaScript changes needed. The tool is discovered and registered automatically on startup.

The script receives arguments on the command line and runs with cwd set to the target workspace. Exit code 0 = pass, exit code 1 = fail. Stdout is returned as the tool result.