hive.terminal-tools-foundations

Just call terminal_exec normally; commands exceeding the 30-second auto-background budget are promoted to background jobs automatically. When the envelope returns auto_backgrounded=true with a job_id, poll with terminal_job_logs using wait_until_exit to block until completion.

Grep exit code 1 means no matches were found, which is not an error. The same applies to find, diff, and test. Always check the envelope's semantic_status field first; it reports "ok" for these informational exit-1 cases.

When stdout_truncated_bytes is greater than zero, the full output is stored under output_handle for 5 minutes. Paginate it with terminal_output_get, tracking next_offset across calls until eof is true.

On POSIX systems including macOS, terminal_exec always invokes /bin/bash regardless of the user's $SHELL. Explicit zsh requests are rejected for security reasons, and ZDOTDIR and ZSH_* environment variables are stripped before execution.

On Windows the shell resolves to Git Bash, PowerShell, or cmd in priority order, reported in the envelope's shell_kind field. If shell_kind is not bash, avoid coreutils idioms like grep or 2>/dev/null and use portable commands or PowerShell-native syntax.

The warning field flags commands matching known destructive patterns like rm -rf, DROP TABLE, or terraform destroy. The command still executed; the warning is informational, prompting you to verify the destructive action was intended before trusting dependent steps.