From 09344e044f93efc861f573554c9fba1f72a8d4c6 Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Mon, 4 May 2026 16:25:09 +0200 Subject: [PATCH] docs(AGENTS): codify "tool credentials live in $HOME, never in project tree" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make the convention every existing framework tool already follows (Gmail OAuth at ~/.config/apache-steward/gmail-oauth.json, PonyMail session cookie at ~/.ponymail-mcp/session.json, GitHub auth via gh auth → ~/.config/gh/) explicit in AGENTS.md so future tool integrations follow the same pattern. Two reasons it's non-negotiable: (1) the standard sandbox denies reads on home-dir credential paths, so an in-tree credential silently bypasses that boundary — every credential read should be an explicit, visible sandbox-bypass moment, not a silent in-tree file slurp; (2) one credential file should serve every clone / worktree / project, not be re-acquired per checkout. Generated-by: Claude Code (Claude Opus 4.7) --- AGENTS.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8caf4de1b..5561ad9d9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -338,6 +338,28 @@ layered defence the framework dogfoods (`.claude/settings.json` sandbox + tool permissions + clean-env wrapper, with system tools pinned per-tool with a 7-day default upstream cooldown). +**Tool credentials live under `$HOME`, never in the project tree.** +Any persistent token, API key, OAuth refresh token, or session +cookie a framework tool needs goes under a well-known home-directory +path — `~/.config/apache-steward/` for tools the framework +owns, or whatever upstream convention the third-party tool already +uses. The existing exemplars: Gmail OAuth at +`~/.config/apache-steward/gmail-oauth.json` (see +[`tools/gmail/oauth-draft/src/oauth_draft/credentials.py`](tools/gmail/oauth-draft/src/oauth_draft/credentials.py)), +PonyMail session cookie at `~/.ponymail-mcp/session.json`, GitHub +auth via `gh auth` (`~/.config/gh/`). Two reasons this is +non-negotiable: (1) the standard sandbox +([`docs/setup/secure-agent-setup.md`](docs/setup/secure-agent-setup.md)) +denies reads on home-dir credential paths, so an in-tree credential +silently bypasses that boundary — every credential read becomes an +explicit, visible sandbox-bypass moment instead of a silent in-tree +file slurp; (2) one credential file serves every clone / worktree / +project, not re-acquired per checkout. New tool integrations MUST +follow the pattern. If a credential is found in-tree (legacy, +copy-paste from upstream docs, generated to a temp scratch path), +relocate it to a home-dir path and update the tool to read from +there — never leave it in place "because it's already there". + This repository uses [`prek`](https://github.com/j178/prek) (a fast, Rust-based drop-in replacement for `pre-commit`) to run pre-commit hooks that keep the documentation consistent — regenerating the `doctoc` tables of contents, stripping trailing whitespace,