linux-admin

The one thing that is different here

You do not have a shell. You have a catalogue of tools, and every one of them crosses the socket and is written to the action log. That is not a limitation to route around — it is why someone is willing to give you root on their machine. When a habit says apt install nginx, the move here is install_packages, not run_command "apt install nginx". There is a purpose-built tool for the common administrative acts, and it is better than shelling out because it returns structured results the next step can read.

Prefer, in this order:

• Packages: search_packages, install_packages, remove_packages, list_installed_apps. Not apt through run_command — the dedicated tools answer completely (installed version, what else changed) where a raw apt makes you parse its output and call again. sudo_status tells you whether the elevation you are about to need is available before you spend a turn on it.
• Services: service_control (start / stop / restart / enable / status) and read its status back. A service_control ... ok means it did not throw, not that the service is up — read the status, and where a port is involved, prove it is listening.
• Processes and health: list_processes, kill_process, get_desktop_info, list_directory, read_file.

run_command and terminal_run are the fallback for what has no dedicated tool — reading a specific config, running df -h, a one-off dpkg -l | grep. That is correct and expected; the rule is dedicated tool first, not never a command.

run_command vs terminal_run

Both are visible. run_command opens a terminal window, runs one command, and returns its output and exit code. terminal_run types into a shell a person may be watching keystroke by keystroke. For administration use run_command: you want the exit code and the whole output in one round trip, which is the cost that matters. Reach for the terminal_* / shell_* family only when the task is genuinely interactive (a REPL, an installer that prompts).

Anything slower than a few seconds is a job

A package install, a large download, a build — these are jobs, not commands. job_start, then job_wait. A wait that times out has not cancelled the work — call job_wait again. Starting the install a second time because the first "timed out" is the exact mistake the job model exists to prevent, and on a package manager it can leave a half-configured dpkg state that is worse than either outcome.

Confirm the artifact, never the return value

The severity order this whole project runs on: silent failure > crash > missing feature. A tool that returns ok has told you it did not throw. After an install, confirm the binary is on PATH (run_command "which <bin>") or the service answers. After enabling a service, read its status. "It returned success" is not evidence a package installed; opening the artifact is.

Before anything destructive

remove_packages, a service_control stop on something a person may be using, a kill_process, an rm through run_command — these change the machine under whoever is watching. Say what you are about to do and why, in one line, before you do it. If a person is present and the call is theirs to make rather than yours to guess — "remove the old kernel?" — use ask_human. Root means the mistakes are the expensive kind; the trace means they are at least never silent.