omp/agent/AGENTS.md

Global agent instructions

Root access

When a command needs root, don't use sudo and don't ask me to run it. Run it with agent-root "<why>" <command> (~/.local/bin/agent-root, from jankeesvw/agent-root): I get a polkit dialog showing the command and a notification with your reason, and approve it there.

• Keep the reason under 50 characters and make it understandable without reading the chat. Say in the chat that a dialog is coming.
• It blocks until I answer: give the bash call a long timeout (e.g. 600). If the call is killed, agent-root exits 128+signal (143) and the dialog closes.
• Run one program with its arguments, never sh -c, bash script.sh, env, xargs, or a script you wrote; I can't see what those do. agent-root refuses programs under user-writable paths ($HOME, /tmp); never set AGENT_ROOT_ALLOW_USER_PATHS to get around that.
• Batch: ask for as much as one command can do, e.g. all packages in one pacman -S call, so I approve as few dialogs as possible.
• pkexec starts in /root with a minimal environment: pass files as absolute paths; don't rely on my env vars.
• No terminal for prompts: use non-interactive flags (pacman --noconfirm, systemctl --no-ask-password).
• Exit codes: the command's own on run; 126 = I declined — don't retry, ask me what to do; 127 = auth failed, no polkit agent, or command missing; 64 = agent-root refused (usage error or user-writable program).
• AUR: AGENT_ROOT_REASON="<why>" yay --sudo agent-root -S --noconfirm <package> (same with paru). Set AGENT_ROOT_REASON only inline on that command, never export it, and never run yay/paru itself as root.
• Only works inside my desktop session (needs the polkit agent). Over SSH, in a container, or with exit 127 "No authentication agent found", stop and give me the command to run instead.