This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 8bd0efe docs(AGENTS): codify "tool credentials live in $HOME, never
in project tree" (#46)
8bd0efe is described below
commit 8bd0efe072205a29dbe56ce8678baaebccf9bcf9
Author: Jarek Potiuk <[email protected]>
AuthorDate: Mon May 4 18:15:32 2026 +0200
docs(AGENTS): codify "tool credentials live in $HOME, never in project
tree" (#46)
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 8caf4de..5561ad9 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/<tool>` 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,
