Tools and safety

Heya runs one streaming function-calling loop. The model asks for a tool, Heya runs it, and the result goes back into the loop. The safety model is simple and visible.

What runs without asking, and what asks first

Reads run on their own. Anything that changes the world asks first.

• Runs on its own: read_file, search_files, list_files, read_guidance, read_log, web_search, web_fetch, browser reads, memory reads.
• Asks first: write_file, run_command, run_wp_cli, wp_playground, kill_command, and browser clicks and typing.

Approve a prompted action once, approve it for the session, or decline it. With --auto-approve, the prompted tools run without asking. Use that only in a sandbox you trust.

The allow-list

The file and command tools are confined to an allow-list of folders. The current directory is always allowed; add more with --allow DIR or the [workspace] config. A path that escapes the allow-list is rejected. Commands always carry a timeout.

The tools

• Files and shell: read_file, write_file, search_files, run_command, check_command, kill_command.
• Guidance: read_guidance reads internal guidance, a bundled baseline plus your own folders, so answers follow your standards and voice.
• Web: web_search and web_fetch (a page returned as readable text).
• Browser: a real headless Chromium through Playwright. Navigate, click, type, screenshot, and pull console and network errors to reproduce a bug.
• WordPress: read_log, run_wp_cli, and wp_playground to boot a disposable WordPress for a clean-room reproduction.
• Sub-agents: spawn_agent for a single delegated task, spawn_agents to fan read-only children out in parallel.
• Memory: remember, update_memory, forget, read_memory. Facts of type project live in the project's own .heya/memory store and load only there; the rest stay global. Sub-agents can read memory but never write it: the write tools are not offered to them, and the store refuses writes even if asked.
• Knowledge base: read_knowledge and search_knowledge over the note folders in [knowledge] config. Strictly read-only: the folders are never added to the write allow-list, and notes are treated as reference text, not instructions. See the configuration reference for setup.
• Code review: review_changes.
• Diagnostics: the reproduce, diagnose, remediate, and triage tools described in the diagnostic workflow.
• Skills: Skill to load one of your installed skills.
• MCP: any tools exposed by the Model Context Protocol servers you connect.

How tools behave

Tools never raise into the agent loop. On a problem they return a short Error: ... string, so a single failing tool never crashes a task. Long tool output is truncated with an explicit marker, never a silent cut.

Sub-agents

A sub-agent is a fresh agent with its own context. It sees only the task you give it, not your conversation. Parallel sub-agents are read-only by design: they get the read-only tool surface and the shared browser and WordPress sessions are withheld, so several can run at once with no races.

Git

Three git tools are read-only: git_status, git_log, and git_diff run without asking and return repository state. git_commit is gated (it asks before committing) and strips any AI-attribution footer from the message before writing the commit, so no "Co-Authored-By: Claude" or "Generated with" lines can slip in.

Heya commits only when you ask. It never auto-commits at the end of a task. Pull requests go through gh pr create via the gated run_command, so you approve the push and PR creation before anything is sent to the remote.

Web and domain diagnostics

Four read-only tools query public infrastructure to answer questions about domains and sites without guessing:

• dns_lookup, domain_info, and check_domains query public DNS-over-HTTPS and RDAP endpoints. They do not make arbitrary-host fetches; each tool targets a fixed public registry service.
• site_tech fetches the target URL and infers the stack from response headers and HTML fingerprints. It respects the same metadata guard as web_fetch, blocking requests to link-local addresses such as instance-metadata endpoints.

None of these tools modify anything. See the bundled web-diagnostics guidance (read_guidance('web-diagnostics')) for how to read RDAP dates, status flags, and common WordPress hosting fingerprints.

Web safety

web_fetch and browser_navigate reach any real site. By default they block link-local addresses (including 169.254.169.254, where cloud instance-metadata lives). Loopback and private network addresses are allowed, so local dev sites work fine. You can turn this off by setting block_metadata = false under [web], but there is rarely a reason to.

Checkpoints

Before every file write, Heya snapshots the prior content of the affected file. If the file did not exist yet, that fact is recorded too, so an undo can remove it cleanly. Snapshots live under ~/.config/heya/checkpoints/ and are never written into your project tree or your git history.

Three slash commands expose the checkpoint store:

• /checkpoints: list every checkpoint recorded this session, newest first, with its sequence number, the prompt that triggered it, and how many files it covers.
• /undo: revert all file changes from the most recent turn and remove that checkpoint.
• /rewind: pick a checkpoint from a list (arrow keys, type to filter) and roll back to it, restoring every checkpoint from that point forward. /rewind <id> targets a sequence number from /checkpoints directly.

run_command side effects (database writes, test runs, external API calls) are not captured. Checkpoints cover only files that Heya's file tools wrote.

To disable checkpoints entirely, add this to your config.toml:

[checkpoints]
enabled = false

Plan mode

Plan mode is a read-only session state. When it is on, Heya blocks writes, commands, and site actions in code: the tools themselves return an error rather than asking, so nothing slips through. The model can still read files, search, fetch pages, check DNS, and run read-only sub-agents. It uses that access to research the problem and return a concrete, step-by-step plan for you to review.

Start a session in plan mode with the --plan flag:

heya --plan

Toggle plan mode on or off at any time during an interactive session:

/plan

The typical flow: start with --plan (or /plan) to get a full picture of what needs to change before any file is touched. Review the proposed steps. When you are satisfied, type /plan again to switch to act mode and let Heya carry out the work.

Privacy

Heya is local-first. With a local model, nothing leaves your machine. With a cloud model, only what you send to that model's API leaves. Heya resolves a key from the environment variable you name in api_key_env first; if that is unset, it reads from the locked credentials file (~/.config/heya/credentials.toml, mode 0600) that heya init writes. A key is never stored in config.toml.