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 6db60d3 docs(secure-agent-setup): document global ~/.claude/ install
option for claude-iso (#14)
6db60d3 is described below
commit 6db60d30242861a9193194b161c3d142b38f05fc
Author: Jarek Potiuk <[email protected]>
AuthorDate: Wed Apr 29 20:46:39 2026 +0200
docs(secure-agent-setup): document global ~/.claude/ install option for
claude-iso (#14)
Adopters can now choose between sourcing tools/agent-isolation/claude-iso.sh
directly from the framework checkout (per-repo) or copying it into
~/.claude/agent-isolation/ and sourcing from there (global). The global
option survives branch/worktree changes and travels with the rest of
~/.claude/ when dotfiles sync across machines, at the cost of a manual
re-copy when the upstream wrapper changes.
Generated-by: Claude Code (Claude Opus 4.7)
---
secure-agent-setup.md | 45 +++++++++++++++++++++++++++++++++++++++++----
1 file changed, 41 insertions(+), 4 deletions(-)
diff --git a/secure-agent-setup.md b/secure-agent-setup.md
index 4a8ed00..abeb356 100644
--- a/secure-agent-setup.md
+++ b/secure-agent-setup.md
@@ -295,13 +295,45 @@ Layer 0 — strip credential-shaped env vars from the
parent shell
before invoking `claude` — is implemented by
[`tools/agent-isolation/claude-iso.sh`](tools/agent-isolation/claude-iso.sh).
-Source it from your shell rc:
+There are two valid ways to make `claude-iso` available on your
+shell. Pick whichever matches how you use Claude Code; the wrapper
+behaviour is identical either way.
+
+**Per-repo install** — source the script directly from the
+framework checkout. Simplest, always tracks the wrapper version in
+the repo (so a `git pull` of the framework updates the wrapper),
+but only works on hosts where the framework path resolves.
```bash
# ~/.bashrc or ~/.zshrc
source /path/to/airflow-steward/tools/agent-isolation/claude-iso.sh
```
+**Global (user-scope) install** — copy the script into
+`~/.claude/agent-isolation/` and source from there. Survives
+branch / worktree / repo-path changes, travels with the rest of
+`~/.claude/` when you sync dotfiles between machines, and works
+regardless of whether the framework repo happens to be checked
+out on a given host.
+
+```bash
+# one-time install (re-run to pick up an upstream wrapper change)
+mkdir -p ~/.claude/agent-isolation
+cp /path/to/airflow-steward/tools/agent-isolation/claude-iso.sh \
+ ~/.claude/agent-isolation/claude-iso.sh
+
+# ~/.bashrc or ~/.zshrc — guarded so it's a no-op until the file exists
+[ -f "$HOME/.claude/agent-isolation/claude-iso.sh" ] \
+ && . "$HOME/.claude/agent-isolation/claude-iso.sh"
+```
+
+Trade-off: the global install decouples the wrapper from the
+repo's pinned copy. If a future framework release changes the
+wrapper (new passthrough vars, security fix), you need to
+re-`cp` it into `~/.claude/agent-isolation/` by hand. Diff the
+two paths periodically — or schedule it via `/schedule` — to
+surface drift.
+
Then use `claude-iso` instead of `claude` whenever you start a
session in the tracker repo:
@@ -346,9 +378,14 @@ the secure setup into your tracker's working tree:
- The `permissions.ask` list — add any project-specific
write-side commands you want to confirm explicitly (e.g. a
custom release-publishing CLI).
-3. Source `tools/agent-isolation/claude-iso.sh` from your shell rc.
- The path is
`<your-tracker>/.apache-steward/apache-steward/tools/agent-isolation/claude-iso.sh`
- when the framework is consumed via the standard submodule path.
+3. Make `claude-iso` available on your shell — either per-repo
+ (sourcing the script from the framework checkout) or globally
+ (copying the script to `~/.claude/agent-isolation/` and
+ sourcing from there). Both options are documented in
+ [The clean-env wrapper](#the-clean-env-wrapper). When the
+ framework is consumed via the standard submodule path, the
+ per-repo source path is
+
`<your-tracker>/.apache-steward/apache-steward/tools/agent-isolation/claude-iso.sh`.
4. Decide whether to gitignore `.claude/settings.local.json` in your
tracker repo — Claude Code does this by default; verify with
`git check-ignore .claude/settings.local.json`.
