# TOOLS.md - Available Capabilities

## Core OS tools

- **VFS / Hyperdrive** — read/write paths via agent tools (`read_file`, `write_file`, `list_directory`, …) on system and personal drives.
- **Service and timer ops** — use `list_services`, `service_status`, and `list_timers` to inspect initd state and timer drop-ins without ad-hoc shell parsing.
- **Operational logs and policy** — use `read_cron_log`, `read_audit_log`, `read_boot_policy`, and `read_kernel_extension_resolution` for bounded diagnostics.
- **Extended ops diagnostics** — `get_initd_graph`, `read_unit_journal`, `inspect_ipc_backpressure`, `get_network_summary`, `tail_telemetry_streams`, and `pkg_index_lookup`.
- **Automation gates** — `list_verification_scripts`, `run_maintenance_gate`, `run_contract_checks`, and `summarize_build_drift` provide safer wrappers for maintenance workflows.
- **Bridge diagnostics/actions** — `get_hrpc_bridge_health` and `get_hrpc_allowlist_status` are read-focused; `emit_host_notification` and `request_host_action` are policy-gated mutations.
- **`web_fetch`** — live `http(s)` fetches **only** when the operator allows them (`ctx.httpFetch`, `BARE_OS_HTTP_ALLOWLIST` / denylist). Same policy as delegated `curl` / `wget`.
- **POSIX-style utilities** — via `run_command` in the guest shell (`/bin/*`); not full GNU.
- **Swarm / Protomux** — peer discovery and replication are host/booter concerns; you see them through `/proc` and tools like `get_swarm_peers` when exposed.
- **Identity / crypto** — only with explicit user approval; never exfiltrate keys or vault material.

## Reasoning / process visibility

- Runtime process visibility can be configured in `~/.agent/config.json`:
  - `show_reasoning` (boolean)
  - `reasoning_mode` (`off`, `summary`, `trace`)
  - `reasoning_max_chars` (bounded output)
  - `reasoning_include_tools` (include tool call/result traces in process output)
- Use `edit_agent_config` to toggle these safely during a session.
- For provider `xai`, keep `rest_base_url` at `https://api.x.ai/v1` and prefer trace mode when reasoning summaries are unavailable.
- For provider `groq`, keep `rest_base_url` at `https://api.groq.com/openai/v1`; tool loops use OpenAI-compatible `chat/completions` with `parallel_tool_calls` and `max_completion_tokens`.
- For Groq debugging, use trace mode and inspect process logs for provider request shape warnings.

## Max-autonomy policy toggles

- `allow_bridge_mutations`: master gate for bridge mutation tools.
- `allow_host_notifications`: required for `emit_host_notification`.
- `allow_host_actions`: required for `request_host_action`.
- `emergency_stop_mutations`: immediate kill switch for all mutating bridge tools.

## Autonomous coding runner

- `autonomous_run` starts autonomous project execution with a goal, runtime cap, and required checks.
- `autonomous_run_status` reports active state, elapsed/runtime budget, and quality gate configuration.
- `autonomous_run_stop` requests a safe stop at the next loop checkpoint.
- Autonomous done criteria require configured checks to pass (for example `coreutils-test`, parity, man coverage) before completion is accepted.
- Guardrails enforce a denylist for dangerous operations and path restrictions even during autonomous runs.

## Skills system

The agent has access to modular **skills** under `~/.agent/workspace/skills/` (and optionally shared skills under `~/.agent/skills/`).

- A **compact** list of skill ids + short descriptions is included in the system prompt.
- When a task matches a skill, call the **`read_skill`** tool to load the full `SKILL.md`, then follow it exactly.
- Prefer using skills over reinventing workflows.

## Host-checkout helpers (git workspace on the machine)

When the user is editing the Bare OS repo on the host (not only inside this guest):

- **`verification_hints`** — suggests `npm run …` / `node scripts/verify-*.mjs` from topic keywords or paths; does not run them here.
- At the repo root, **`npm run agent:path-hints`** takes path arguments; **`npm run agent:holepunch-index`** dumps a JSON index of local `holepunchto_repos` packages.

## One-shot diagnostics

- **`runtime_diagnostic_bundle`** — ctx API version, resource snapshot if available, and all allowlisted `/proc/bare_os/*` snapshots that exist (bounded).