@pi-archimedes/sudo

Safe privileged execution for the Pi coding agent: a dedicated sudo_exec tool with a masked password prompt, plus a guard that keeps the ordinary bash tool from driving interactive sudo.

What you get

• sudo_exec tool — runs a privileged command via sudo -S, showing the exact command and reason for confirmation before any credential is requested; on timeout/abort the kill applies to the command's entire process group, so privileged (root) descendants are killed too, not just the direct sudo process — except a command that intentionally detaches itself into its own session (setsid/daemonizing), which leaves the group by definition and is beyond any user-space kill (the same reach as tmux kill-pane): give such commands a managed lifecycle flag (e.g. --foreground) instead
• Masked password prompt — the password is entered only through a masked UI, cached in memory for the session, and passed to sudo via stdin only — never in argv, env, logs, or files
• Defensive scrubbing — command output lines containing the password are redacted before they appear in tool results
• Credential lifecycle — single in-memory cache with TTL (default 15 min, ttlMs); cleared on auth failure, session_start/session_shutdown, and /sudo forget
• Headless sessions blocked — subagent/headless sessions get a clear error from sudo_exec instead of a prompt; the masked prompt only ever appears in a human's TUI
• Bash guard — active tool_call veto (ADR 0010): interactive sudo through the built-in bash tool is blocked, funneling privileged execution through sudo_exec
• /sudo + /sudo forget — report the credential-cache state or clear it from memory

Install

pi install npm:@pi-archimedes/sudo

Usage

The sudo_exec tool

{
  "command": "apt install ripgrep", // exact argv string — no leading 'sudo'; no shell syntax (pipes, &&, redirects, env assignments)
  "reason": "ripgrep is needed for the search tooling", // required — shown to the user before execution
  "timeoutMs": 120000 // optional override of config.defaultTimeoutMs
}

The tool uses pi's built-in renderCall/renderResult; command output is surfaced as plain text, scrubbed with the password masked.

The bash guard

A pure, exhaustively-tested scanner vetoes tool_call events on the built-in bash tool:

• Blocked: sudo in command position without a no-prompt flag — including through runner wrappers (env, nohup, timeout, xargs, …), nested shells (bash -c, su -c), eval, compound keywords, and heredoc bodies
• Allowed: non-interactive sudo (sudo -n, -l, -v, -K, -k, --non-interactive) — these cannot prompt and pass through untouched

The guard is a heuristic with accepted residual bypasses documented in the ADR 0010 design notes (e.g. cross-token variable indirection, and sudo inside $(...)/backtick interpolation whose text the word-position model cannot see). Over-blocking is the safe direction; the tested no-prompt flag set is a stable contract.

Commands

• /sudo — report whether a credential is cached
• /sudo forget — clear the credential from memory

Settings

Setting	Type	Default	Description
ttlMs	number	900000	Password cache TTL in milliseconds (default 15 minutes)
defaultTimeoutMs	number	120000	sudo_exec default command timeout in milliseconds (default 120 seconds)

On/off is managed by the suite: toggle via /plugins (archimedes.sudo.enabled, default on). Config is JSON-only in the archimedes.sudo namespace of ~/.pi/agent/settings.json — there is no settings-panel UI in v1.

Credential limitation on sudoers that retain no reusable ticket

On sudoers policies that retain no reusable credential ticket (e.g. timestamp_timeout=0 plus strict Defaults), an authenticated command failure is indistinguishable from an authentication failure to any non-interactive check — so the tool uses a two-consecutive-failure rule: the first failure keeps the cached password (with a visible warning), the second clears it. A wrong password on such a sudo is therefore detected on the second failure rather than the first — the bounded cost of a policy that exposes no ticket to verify against.

Integration

When installed via pi-archimedes (the meta package), the sudo package is registered and gated by the suite's plugin manifest (ADR 0012); the bash guard and sudo_exec are loaded in both the main session and subagent children — the guard still vetoes there, while sudo_exec itself refuses to run headless. Standalone installs work independently.

← Back to pi-archimedes