/ docs

Tools + approval

File ops, shell, web, database, memory. And the approval model that gates them.

▶

Tools + approval — walkthrough

Video walkthrough coming soon.

Tools + approval — walkthrough

Tool categories

Read-only (auto-approved by default)

Tool	What it does
`read_file(path)`	Reads a workspace file. Path traversal refused.
`search_codebase(pattern, glob?)`	Ripgrep-style regex search, caps at 100 matches with truncation flag
`list_directory(path)`	Lists a workspace dir (excludes node_modules, .git, dist, etc)
`web_search(query)`	DuckDuckGo-backed, no key needed
`web_fetch(url)`	HTTPS fetch with SSRF guard (blocks private IPs + IMDS endpoints)
`read_sqlite(path, query)`	Read-only SQLite — SELECT / PRAGMA / EXPLAIN only

Modifying (per-call approval required)

`write_file(path, content)`	Overwrite or create. Path-traversal blocked. Uses `workspace.applyEdit` so changes land live in the editor + join the undo stack.
`edit_file(path, old_string, new_string)`	Surgical replacement, must match once.
`run_command(command, timeout_ms?)`	Shell via `cp.exec`. Default timeout 30 s, cap 5 min.
`query_database(connection_id, query)`	SQL against a registered connection (see DB Explorer). Read-only by default.
`update_memory(content, section?)`	Upserts a section into `.hypex/memory.md` (re-injected every turn).

Artifacts (agent-callable)

`artifact_create(kind, title?, id?, content)`	Kind: `html` / `svg` / `jsx` / `tsx` / `mermaid`. Opens the sandboxed preview panel with Preview / Code / Versions tabs. Auto-unescapes HTML entities if the model double-encodes content.
`artifact_update(id, content)`	Saves a new `v<n+1>.<ext>` in `.hypex/artifacts/<id>/` and reloads the panel.
`artifact_list()`	Lists every artifact the agent has built in this workspace.

Driver / Kernel (Windows, via WDK)

Added in beta.36. Lets the agent drive the full WDK workflow from chat — scaffold, build, sign — on Windows machines with the toolchain installed. All return clearly on macOS / Linux (Windows-only by nature of kernel-mode drivers). See Driver / Kernel build.

`wdk_check_status()`	Detect whether the Windows Driver Kit + MSBuild are installed. Returns version + whether the user can scaffold + build.
`wdk_scaffold_kmdf()`	Create a minimal KMDF project at `./HypexDriver` — proper GUIDs, `PnpLockdown=1`, ServiceType=1 kernel.
`wdk_scaffold_umdf()`	User-mode driver scaffold at `./HypexUmdfDriver`. Safer to iterate than ring-0 when you don't need the privileged path.
`wdk_build()`	Picks a `.vcxproj` in the workspace, asks Debug/Release, runs MSBuild on x64 in the integrated terminal.

Agent self-management

Added in beta.37. Lets the agent reach into Hypex's own state during a turn so it closes its loop without asking the user. Full autonomy on the context dimension.

`create_checkpoint(label)`	Snapshot the workspace before risky edits. User rewinds with `Ctrl`+`Alt`+`Z`.
`pin_context(path)`	Pin a workspace file so next turns see it inlined in the system prompt.
`cost_report()`	Return today's spend in USD + tokens + calls. Lets the agent budget before a long Opus run.
`memory_view()`	Read `.hypex/memory.md`. Always check before claiming ignorance — durable facts may already be there.
`memory_append(note)`	Add a durable fact the user told you (project conventions, gotchas, prior decisions). Timestamped, max 1000 chars per entry.

Desktop Control (Windows, gated)

Requires hypex.desktop.enabled = true (off by default). Ctrl+Shift+Esc is a global panic-stop. 500 actions / 10 min / workspace cap.

`desktop_screenshot()`	Primary display → base64 PNG saved under `.hypex/screenshots/`. No user auth — uses .NET `System.Drawing` via PowerShell.
`desktop_click(x, y, button?)`	Left / right / middle click at absolute pixel coords.
`desktop_double_click(x, y)`	Double left-click.
`desktop_move(x, y)`	Move cursor (hover, no click).
`desktop_scroll(x, y, deltaY)`	Wheel scroll. Positive = down.
`desktop_type(text)`	Type at current keyboard focus via SendKeys. Metachars escaped. 2000 char cap.
`desktop_key(combo)`	Key combo like `ctrl+s`, `alt+tab`, `escape`. `ctrl+alt+del` / `win+l` / `alt+f4` are blocked.
`desktop_wait(ms)`	Sleep 0-10000 ms — lets a UI settle between actions.

The approval card

Every modifying tool call renders as a card in the chat log:

⚙ Write file                          src/buggy.ts
  interface User {
    id: number;
    ...
  }

  [Deny]  [Always allow write_file]  [Allow]

Allow — runs this call, doesn't persist
Deny — aborts the turn
Always allow — adds the tool to hypex.autoApproveTools. High-risk tools (run_command, write_file, edit_file, update_memory) open a modal confirm before persisting — a misclick shouldn't grant perpetual shell access.

Configuring auto-approve

In settings.json:

"hypex.autoApproveTools": [
  "read_file",
  "search_codebase",
  "list_directory",
  "web_search",
  "web_fetch",
  "read_sqlite"
]

Default list is exactly the read-only set. Add write_file / edit_file there if you want a hands-off agent run — only recommended combined with checkpoints + a profile you trust.

Diff rendering in approval cards

For edit_file the card shows a line-by-line diff — minus rows red-tinted, plus rows green-tinted, hoverable. A −M ⁄ +N chip above the hunks shows size at a glance. For write_file the preview truncates at 800 chars with a (X more chars, Y total lines) suffix so you know what you're accepting.

Security

All file tools workspace-sandboxed — ../../ paths are refused.
web_fetch refuses 10/8, 127/8, 169.254/16 (AWS/GCP/Azure IMDS), 172.16/12, 192.168/16, multicast, IPv6 loopback/ULA. DNS-rebinding window is small but real — do not web_fetch arbitrary attacker-controlled URLs while signed in.
run_command uses a shell so pipes work; commands are NEVER auto-approved unless you opt in.

Telemetry

Every tool call logs to the Hypex Agent output channel.
Each tool call renders a collapsible card in the chat with running / done / error status.
Token usage from the LLM turn that requested the tool is attributed to the model id, not the tool.

Hard limits

Tool results are truncated to 100 KB so a run_command that dumps a log doesn't blow the context window.
Max 20 tool calls per turn before the loop aborts — prevents runaway agent loops.