Tool System

Everything an agent can do goes through the tool system: a central registry of functions with JSON-Schema specs, an executor that enforces mode/confirmation/rate-limit gates, and two pre-registered tool sets — 6 built-in tools plus 46 ported tools. The system plugs into the harness via harness.use(ToolSystem()) (model_harness/tools/system.py:46).

Architecture

• ToolSpec (model_harness/tools/dtos.py:117) — schema DTO for a tool: name, description, JSON-Schema parameters, required list, and the read_only flag. to_openai_tool() exports the OpenAI function-calling shape ({"type": "function", ...}).
• Tool (dtos.py:145) — a registered tool: spec + implementation callable + metadata (version, tags, timeout_sec, rate_limit_rpm, requires_confirmation, is_async).
• ToolRegistry (model_harness/tools/registry.py:27) — central catalog. Tools are stored as {name: {version: Tool}}; get(name) returns the latest semver. Registration is decorator-based (@registry.register(name=..., tags=..., read_only=..., ...)); parameter schemas are generated from type hints by schema_gen.generate_tool_spec. Supports tag-based filtering and bulk export via openai_tools().
• ToolExecutor (model_harness/tools/executor.py:73) — runs tools in a thread pool (sync) or awaits them (async) with a per-tool timeout, JSON-Schema argument validation, optional rate limiting, a best-effort memory cap via tracemalloc, and the mode / policy / confirmation gates described below.
• ToolSystem (system.py:35) — facade implementing the IToolSystem protocol; composes registry, executor, ToolCallHandler (conversation injection), and ToolVersionManager. The constructor registers builtins and ported tools (register_builtins defaults to True; register_ported follows it). It also bridges MCP servers into the registry as proxied tools named "{server}__{tool}" (stdio only, fail-open — system.py:176).
• ToolExecutionResult (dtos.py:172) — per-call result: success, output, error, duration_ms, confirmed.

flowchart LR
  Agent[BaseAgent] -->|execute_tool name args mode confirm| TS[ToolSystem]
  TS --> Reg[ToolRegistry]
  TS --> Ex[ToolExecutor]
  Ex --> ModeGate[Mode gate]
  ModeGate --> Policy[Policy hook]
  Policy --> Confirm[Confirmation gate]
  Confirm --> Rate[Rate limit]
  Rate --> Run[Run with timeout and memory cap]
  Run --> Result[ToolExecutionResult]
  Reg -.registers.-> Builtins[6 builtin tools]
  Reg -.registers.-> Ported[46 ported tools]
  Reg -.bridges.-> MCP[MCP servers]

read_only vs requires_confirmation

Two independent flags control what a tool may do:

• read_only=True on the spec means no side effects (dtos.py:123). Read-only agent modes (EXPLORE, PLAN) only allow read_only tools.
• requires_confirmation=True on the Tool means the executor pauses the call and returns error="Confirmation required", confirmed=False unless invoked with confirm=True (executor.py:171).

Enforcement by mode (model_harness/agents/modes.py):

The executor is the enforcement point (executor.py:146): in a read-only mode, a non-read-only tool is rejected with a structured error — unless the mode policy declares scoped_write_dirs AND the tool is in the vetted _SCOPED_WRITE_TOOLS set (write_file, append_to_file, insert_lines, replace_in_file, move_file, copy_file, apply_diff, edit_file_line, remove_line_range — executor.py:54) AND every recognized path argument resolves inside a scoped directory. Tools without a caller-supplied path (execute_python, run_command, git mutations, snapshot_file, generate_image) stay fully blocked. The gate fails closed on any ambiguity (executor.py:337).

An optional policy_hook(tool, arguments) -> Optional[str] is consulted between the mode gate and the confirmation gate; a non-empty return vetoes the call, and hook exceptions fail open (executor.py:159).

On the agent side, BaseAgent (model_harness/agents/base.py) passes confirm=auto_confirm_tools (default False) and mode=self.mode into execute_tool (base.py:1270). When a call comes back confirmed=False and a confirmation_handler is installed by the web layer, the agent asks the user and re-executes with confirm=True on approval (base.py:1283). The mode's system_prompt_addendum is appended to the system message so the model knows its constraints.

Path-traversal safety

All filesystem tools resolve paths through _resolve_path() (builtin.py:52; ported tools use the mirrored helper in ported/common.py):

1. The workspace root is: request-scoped override (guest sandbox) → explicit WORKSPACE_ROOT → Path.cwd() dynamically (builtin.py:34).
2. Relative paths resolve against the workspace root; absolute paths must already be inside it.
3. resolved.relative_to(workspace) failing raises PathTraversalError (dtos.py:75, code PATH_TRAVERSAL).
4. The executor deliberately re-raises PathTraversalError instead of converting it to a tool error (executor.py:255) — a workspace escape is a security error that must propagate.

Built-in tools

Registered by register_builtin_tools() (builtin.py:200). All are path-traversal safe.

• read_file(filepath, max_lines) — read a UTF-8 text file; max_lines truncates and appends a "... (N more lines)" note. read_only (builtin.py:217).
• read_pdf(filepath, start_page=1, max_pages=40, max_chars=20000) — extract page-numbered text via pypdf (builtin.py:244). Long PDFs are read in multiple passes: output stops at max_pages/max_chars and the truncation note names the exact start_page for the next pass (start_page={end + 1}). Encrypted PDFs are tried with an empty password; scanned image-only PDFs return a plain "no extractable text, no OCR" message. read_only, 30 s timeout.
• write_file(filepath, content) — write UTF-8 text, creating parent directories. If the file already existed, the return string carries " (overwrote an existing file)" so the agent cannot silently clobber a file (builtin.py:340). requires_confirmation=True.
• list_files(directory, pattern, recursive) — glob listing with workspace-relative paths, sizes, and file/dir icons. read_only.
• web_search(query, top_k=5) — POSTs to the Tavily API (https://api.tavily.com/search) using TAVILY_API_KEY from the environment; returns numbered title/URL/snippet results (snippets truncated to 400 chars, top_k capped at 10). Without the key it returns an "unavailable" message instead of failing. read_only, 20 s timeout (builtin.py:384).
• execute_python(code, timeout_sec=15) — runs code in a restricted sandbox: exec with a globals dict whose __builtins__ is a whitelist of safe builtins — no __import__, no open, no eval/exec, no file I/O or network (SAFE_BUILTINS, builtin.py:119). Stdout is captured and returned. Ten known escape vectors are catalogued in SANDBOX_ESCAPE_VECTORS (builtin.py:90) for security tests. requires_confirmation=True, 30 s tool timeout. Note: this sandbox restricts builtins but is not a process/OS-level jail; the executor's timeout and memory cap still apply.

ask_user (schema only)

ask_user is not in the registry and never executes in the sandbox. Only its ToolSpec exists (ASK_USER_TOOL_SPEC, builtin.py:158), with question, optional choices, and multi parameters. BaseAgent appends the schema whenever a question_handler is installed (web-driven runs, all modes — base.py:662) and intercepts calls to route them through the handler (base.py:1255), which the web layer turns into an SSE question event plus a wait for the user's answer. Without a handler the tool reports itself unavailable.

Ported tools (46)

register_ported_tools() (ported/__init__.py:48) registers 46 tools adapted from the Kucatoo source app — plain synchronous functions that run in the executor's thread pool. Categories:

videogen (MiniMax video) lives in the ported package but is not an agent tool — renders take minutes; it is the web Video page entry point (ported/__init__.py:18).

Full tool table

The table below is generated by scripts/wiki_tables.py from the live registry (builtins + ported) — do not hand-edit it.

<!-- AUTO:tools -->

verified against code: 2026-08-09