hive.terminal-tools-foundations

terminal-tools — foundations

These tools give you a real terminal: foreground exec with smart envelopes, background jobs with offset-based log streaming, persistent PTY shells, and filesystem search. Bash-only on POSIX.

Tool preference (read first)

The terminal is your file system: reading, writing, editing, and searching files all go through terminal-tools. Reach for a higher-level tool only where it clearly fits (browser, web search). Terminal tools default their cwd/path to your session workdir when you omit it — relative paths Just Work; pass an absolute path to operate elsewhere.

• Reading files → terminal_exec("cat PATH") (page large output with terminal_output_get)
• Editing files → terminal_exec("sed -i ...") / awk, or rewrite the whole file with a heredoc
• Writing files → heredoc: terminal_exec("cat > PATH <<'EOF' ... EOF")
• Searching → terminal_rg (content / regex grep) and terminal_glob (find files by name)
• Browser / web pages → gcu-tools.browser_* for rendered pages — NOT terminal_exec("curl ...")
• Web search → hive_tools.web_search — NOT scraping
• System operations (process exec, jobs, PTYs) → terminal-tools. This is its territory.

The standard envelope

Every spawn-style call (terminal_exec, the auto-promoted job state) returns this shape:

{
  "exit_code": 0,                    // null when auto-backgrounded or pre-spawn error
  "stdout": "...",                   // decoded, truncated to max_output_kb (default 256 KB)
  "stderr": "...",
  "stdout_truncated_bytes": 0,       // > 0 means more is in output_handle
  "stderr_truncated_bytes": 0,
  "runtime_ms": 42,
  "pid": 12345,
  "output_handle": null,             // "out_<hex>" when truncated — paginate with terminal_output_get
  "timed_out": false,
  "semantic_status": "ok",           // "ok" | "signal" | "error" — read THIS, not just exit_code
  "semantic_message": null,          // e.g. "No matches found" for grep exit 1
  "warning": null,                   // e.g. "may force-remove files" for rm -rf
  "auto_backgrounded": false,
  "job_id": null,                    // set when auto_backgrounded=true
  "shell_kind": "bash"               // interpreter that ran it: "bash" | "powershell" | "cmd" | "direct"
}