#Tools & Approval

During conversation in Hunea, the model can call a set of built-in tools to read files, edit files, execute commands, search code, view images, and more, then continue generating replies after multiple rounds of calls.

This page explains what users encounter: which tools exist, which require approval, how path scope is restricted, and how to operate the approval panel.

Tool usage guidelines participate in prompt assembly in /prompt; context usage also shows a Tool definitions entry in /context. This page complements the runtime capability itself.

#Workspace boundaries

Read-only tools (read / list_dir / view_image / grep / find) can access paths inside the workspace as well as existing paths outside the workspace. Paths can be relative to the workspace, or absolute paths; paths that don't exist outside the workspace fail.

Write tools (write / edit) and bash are still strictly limited to the current workspace: bash executes inside the workspace by default, and you can specify workdir, but it still must fall within the workspace.

Therefore, it's recommended to launch Hunea in the project directory you actually need to operate on, rather than in an unrelated parent directory.

#Built-in tool list

Usage notes:

• Prefer grep / find / list_dir / read for what they can handle, rather than always using bash. Specialized tools have clear path boundaries and output truncation strategies; bash is better for pipelines, environment variables, and commands that specialized tools don't cover.
• Before using write / edit on an existing file, you generally need to read the full file first. This reduces the risk of direct rewriting without reading the complete content.
• For image files, use view_image, not read.
• bash output has an upper limit (about the last 2000 lines or 50KB). When truncated, the full output is saved to a temp file when possible.
• grep prefers rg from system PATH or managed, and falls back to the built-in Rust backend when neither is available; find always uses the built-in Rust backend and requires no extra fd install. Installing rg on the system is recommended for faster grep search, see Getting Started.

#Approval panel

Permission strategy is roughly two categories:

• Always: execute directly, no approval popup (read, search, list dir, view image).
• Ask: popup approval first, execute after approval (bash / write / edit).

When an Ask tool pops up, common options are:

1. Yes — approve only this one time
2. Yes, allow similar requests during this session — allow similar requests directly for the rest of the session
3. No — reject only this one time
4. No, reject similar requests during this session — reject similar requests directly for the rest of the session

Operations:

• ↑ / ↓ or number keys switch options; Enter / y confirm the current selection; n for reject options (follow the panel highlight)
• Esc cancels this approval interaction; the request won't execute
• write / edit shows a file diff preview; for long content you can enter full-screen preview and scroll

Note: the approval panel is at the end of the document. If the viewport is scrolled up to see historical messages, the panel may not be visible temporarily.

#Left attention pill

When the viewport isn't at the bottom, a persistent pill appears on the left to tell you there's unread content below, so you don't act blindly when the options aren't in view:

• New-message count: new assistant messages have finished while you were reading up higher.

  

• Approval pending: a tool approval panel is open but currently not visible (covered by a fullscreen layer, or off-screen because you're not at the bottom).

  

Both pills are clickable with the left mouse button to jump straight back to the bottom: clicking first closes any non-approval fullscreen layer in the way, then scrolls the viewport back to the bottom (restoring bottom-following) and clears that pill; clicking the approval pending pill also brings the inline approval panel back into view and gives it input focus. See Keep viewport + attention pill for more.

The debug /tool-debug (requires debug.enabled = true) can preview the approval panel UI, but it's not a regular usage path; it may be removed or improved later.

#Turn limit

In one user request, the Agent can make multiple consecutive rounds of tool calls. If you need to limit the number of rounds, configure:

[runtime]
# Default is unlimited; set to a positive integer to terminate the request after exceeding this number of rounds
tool_max_turns = 32

See the [runtime] section in config.toml for request retry, idle timeout, and other instructions.

#Relationship to prompts and context

• Which tools are currently enabled, and their guideline content: see the Tools tab in /prompt. The On column enables/disables each tool (a disabled tool won't appear in the tool list sent to the model), and the Guide column controls whether that tool's usage guidelines are injected; the state is persisted and mainly targets the next new session. See Per-tool enable / disable.
• Context usage from tool definitions: see /context.
• Tool results enter the session tree, so you can see tool nodes in /tree; but /copy by default only lists user messages and assistant replies, it doesn't include tool / reasoning in the copy list.

#Usage tips

• When first using, start with read-only operations (read files, search) and observe whether the model prefers read / grep.
• When modifying files, check the diff preview. Yes, allow similar… reduces repeated confirmations and allows subsequent similar writes in this session — choose based on your scenario.
• For harmless repeated commands, you can use session-level allow; for destructive operations like deleting files, git push --force, changing permissions, it's recommended to keep per-request confirmation.
• Conversation content and workspace files are sent to third-party LLM services. For sensitive directories or secret files, please avoid or constrain them in your instruction files.