# TOOLS.md - Available Capabilities

You already have these tools. Schemas are attached. NEVER ASK to use them.

## Files / VFS

- `read_file` — UTF-8, optional offset/limit numbered slices.
- `write_file` — create or overwrite (parents created).
- `edit_file` / `search_replace` — unique `old_string` unless `replace_all`.
- `apply_patch` — Codex/Grok `*** Begin Patch` multi-file edits (Add / Delete / Update / Move).
- `create_directory`, `list_directory` (`tree=true` for a bounded BFS tree), `file_stat`, `glob_files`.
- `grep` — VFS-native regex search (glob, ignore_case, context, `output_mode` content | files_with_matches | count). Prefer over `search_files` / `run_command grep`.
- `find_symbol` — definition-oriented search (function/class/const/def/fn).
- `search_files` — `grep -Rnl` via the guest shell (legacy).
- `move_path`, `copy_path`, `diff_files`, `delete_path` — enabled. Base system is read-only.
- `list_bin` — guest `/bin` utilities (POSIX-in-JS, not GNU).
- `git_status` — `git status --short`, `diff --stat`, recent log.
- `git_log` / `git_show` / `git_blame` — prefer these over raw `run_command git`.

Prefer `list_directory` / `glob_files` / `file_stat` / `grep` over `ls` / `find` / shell grep.

## Code / harness

- `run_command` — any guest shell line (`cwd` optional; last cwd persisted). `command_deny` empty by default.
- `run_js_script` — required for agent-authored JS. Node is not installed. Writes `~/.agent/_tmp_agent_run.mjs` and runs it on the Bare kernel. Prefer `async function run(ctx, argv)`.
- `run_js_script_at_path` — existing absolute `.mjs`.
- `todo_write` — session todos (`merge=true` to update by id).
- `enter_plan_mode` / `exit_plan_mode` — plan mode is read-only except `~/.agent/plan.md`.
- `memory_search` / `memory_get` / `memory_append` / `remember` — MEMORY.md and daily logs.
- `list_skills` / `read_skill` / `create_skill` — catalog, full SKILL.md, or author a new workspace skill.
- Project skills are also walked from `.grok/skills`, `.agents/skills`, `.claude/skills`, `.cursor/skills`.
- `schedule_task` / `unschedule_task` / `list_scheduled` — guest timers (`agent-*.timer`).
- `fuzzy_find` — filename search when you remember part of a name.
- `read_many` — several files in one call.
- `wait_for` — poll a file or command until a regex matches (sync, timeout).
- `undo_last_edit` — restore the last snapshot from `~/.agent/edits.json`.
- `git_diff` — `git diff` / `--stat`.
- `history_search` — keyword search of this session's history.
- `rewind_session` — Grok `/rewind`: drop the last N user turns from `~/.agent/history.json`.
- `export_session` — Grok `/export`: write a Markdown transcript (default `~/.agent/export.md`).
- glob/grep honor `.gitignore`, `.agentignore`, and `.grokignore` at the walk root.
- `edit_agent_config` — shallow merge of known `~/.agent/config.json` keys.

## Kernel / ops

- `read_proc_file` — any `/proc` path. Live features: `/proc/bare_os/features` or `features.json`, plus `capabilities.json`.
- `runtime_diagnostic_bundle` — one-shot ctx + `/proc/bare_os` snapshot. Prefer this over many separate reads.
- `get_system_info`, `get_resource_limits`, `get_swarm_peers`.
- `list_services`, `service_status`, `get_initd_graph`, `read_unit_journal`.
- `list_timers`, `read_cron_log`, `read_audit_log`.
- `read_boot_policy`, `read_kernel_extension_resolution`.
- `inspect_ipc_backpressure`, `get_network_summary`, `tail_telemetry_streams`, `pkg_index_lookup`.

Man pages (`read_man_page`, `apropos_man`) are documentation search only — never infer live kernel state from them.

## Checks (guest wrappers + host hints)

- `list_verification_scripts`, `run_maintenance_gate`, `run_contract_checks`, `summarize_build_drift`.
- `verification_hints` — suggests host-checkout `npm` / `node` checks. Does not run them here.

## Bridge / web

- `web_search` — DuckDuckGo instant answers (same HTTP policy as wget/curl). Then `web_fetch` promising URLs.
- `web_fetch` — http(s) via `ctx.httpFetch` (same host allow/deny as wget/curl).
- `get_hrpc_bridge_health`, `get_hrpc_allowlist_status`.
- `emit_host_notification`, `request_host_action` — enabled by default. `emergency_stop_mutations` can still block.

## Autonomy

- `autonomous_run` / `autonomous_run_status` / `autonomous_run_stop` / `update_goal`.
- Guardrails are denylists only (`autonomous_deny_ops` empty by default). Keep the tool loop going.

## Other

- `ask_user_question` — product choice only, never permission.
- `task_complete` — call when the user task is done.

## Policy toggles (`~/.agent/config.json`)

- `access_policy`: `full` (default) or `restricted`.
- `allow_delete`, `allow_bridge_mutations`, `allow_host_notifications`, `allow_host_actions`: **true**.
- `command_deny`, `autonomous_deny_ops`: empty by default.
- `mutate_deny_prefixes`: read-only base-system prefixes.
- `emergency_stop_mutations`: kill switch for mutating bridge tools.

## Reasoning / process visibility

Configured in `~/.agent/config.json` (`show_reasoning`, `reasoning_mode`, `reasoning_max_chars`, `reasoning_include_tools`). Progress UI is automatic from `~/.agent/progress.txt`. Use `edit_agent_config` to toggle.

- REST `xai`: `https://api.x.ai/v1`. Prefer trace mode when summaries are unavailable.
- REST `groq`: `https://api.groq.com/openai/v1`; tool loops use `parallel_tool_calls` and `max_completion_tokens`.