From 8802352fab2b3e7e7c0ed45eed8a5bbd728451eb Mon Sep 17 00:00:00 2001 From: Prad Nukala Date: Sat, 17 Oct 2026 20:06:04 -0400 Subject: [PATCH] agent: global AGENTS.md with agent-root root-access rules --- .gitignore | 1 + agent/AGENTS.md | 15 +++++++++++++++ 2 files changed, 16 insertions(+) create mode 100644 agent/AGENTS.md diff --git a/.gitignore b/.gitignore index 7706732..accd48c 100644 --- a/.gitignore +++ b/.gitignore @@ -7,6 +7,7 @@ !/agent/ /agent/* +!/agent/AGENTS.md !/agent/config.yml !/agent/mcp.json !/agent/keybindings.yml diff --git a/agent/AGENTS.md b/agent/AGENTS.md new file mode 100644 index 0000000..323f491 --- /dev/null +++ b/agent/AGENTS.md @@ -0,0 +1,15 @@ +# 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 "" ` (`~/.local/bin/agent-root`, from [jankeesvw/agent-root](https://github.com/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="" yay --sudo agent-root -S --noconfirm ` (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.