Add agentic-ai/Claude/ — bypassPermissions + PreToolUse safety hooks

[ulises-c]

Summary

Adds agentic-ai/Claude/ as a version-controlled source of truth for ~/.claude/ config. Installs via bash agentic-ai/Claude/install.sh (idempotent, symlink-based).

What's included

Core config

• settings.json — bypassPermissions (no prompts), hooks wired up, sandbox config with denyRead/denyWrite/allowWrite staged for when the upstream AF_UNIX blocker ships, advisorModel: opus
• CLAUDE.md — @-imports hierarchical rules from rules/
• rules/common/general.md — coding style rules applied globally
• rules/common/agents.md — when to auto-spawn Plan/Explore/review/security-review agents
• rules/bash/style.md — bash scripting conventions

Hooks

PreToolUse validate-bash.sh blocks:

• Destructive filesystem operations on root/home
• dd to device nodes, mkfs
• Redirects to block devices
• Shell redirects to sensitive credential + system paths (~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh, /etc, /usr, /boot, /sys, /proc)
• curl/wget | sh/python/ruby/node/perl pipe execution
• Inline interpreter exec (python -c + os.system/subprocess, node -e + child_process/execSync, perl -e + system(/exec()
• Force-push to main/master
• sudo escalation
• git add -A / --all / . bulk staging

All policy checks that can match heredoc commit message bodies are scoped to $FIRST_LINE to prevent false positives.

PreToolUse validate-write.sh blocks Write/Edit/MultiEdit to the same sensitive paths.

PostToolUse post-edit-shellcheck.sh runs shellcheck on any .sh file after it's written or edited.

PostToolUse post-test-runner.sh runs the project's test suite after every Write/Edit on source files. Discovery order: .claude/test-cmd override → cargo test / go test ./... / pytest / npm test / make test. 60s timeout; warns on failure, silent on pass.

Stop driftcheck.sh compares the installed ~/.claude/ against the repo source at end of session and warns if they've drifted.

Railguard v0.5.1

Hook layer integrated; railguard-shell (bwrap) skipped — same AF_UNIX blocker as the built-in sandbox. Adds: encoding/obfuscation detection (Tier 1), behavioral evasion detection (Tier 3), memory write classification, per-edit rollback, structured audit trail, self-protection rules. railguard.yaml symlinked to ~/.railguard.yaml for global coverage.

Sandbox (disabled — upstream blocker)

setup-linux-sandbox.sh + SANDBOX.md document the bubblewrap sandbox config. Currently disabled (sandbox.enabled: false) because seccomp BPF unconditionally blocks AF_UNIX sockets (#44180), which kills GPG commit signing and SSH agent — both required for a provider-agnostic workflow across GitHub, Bitbucket, and Forgejo. The filesystem config is in place and ready to re-enable when #44180 ships.

install.sh

• Symlinks settings.json, CLAUDE.md, rules/, railguard.yaml, and all hooks/*.sh into ~/.claude/
• Ubuntu: warns if the bwrap AppArmor profile isn't set up

Activation

bash agentic-ai/Claude/install.sh

🤖 Generated with Claude Code

[ulises-c]

Other implementable tips from the article on Claude Code settings

We built Tip 3 (bypassPermissions + hook validation). Here's what else is worth doing, roughly in priority order:

---

Tip 4 — PostToolUse: auto-run tests after edits ⭐

Configure a PostToolUse hook that runs tests automatically after Claude modifies a file. The article does this for .sh files with bats, but the pattern generalizes. Hook returns {"decision": "block"} on failure, forcing Claude to fix before moving on — effectively enforced TDD.

Would add agentic-ai/Claude/hooks/post-edit-test.sh + a PostToolUse entry in settings.json.

---

Tip 6 — Hierarchical rules structure ⭐

Already stubbed in the planned directory structure as rules/. The idea: put language-agnostic principles in rules/common/ (e.g. prefer immutability, error handling style), then language-specific folders reference those instead of duplicating them. Prevents contradictions across 10+ rule files.

Would add agentic-ai/Claude/rules/common/ with shared principles, plus per-language subdirs.

---

Tip 5 — Stop hook: session-end drift check

A Stop hook runs driftcheck.sh when Claude finishes a session and validates project structure conventions — e.g. no stray root files, required docs/README.md present, filename patterns enforced. Catches structural debt before it compounds.

Would add agentic-ai/Claude/hooks/driftcheck.sh + a Stop entry in settings.json.

---

Tip 8 — Self-activating agents via rules

Define trigger conditions in a rules file so Claude auto-invokes agents without being asked: complex features → planner, code changes → code-reviewer, bug fixes → tdd-guide. Reduces the need to remember which agent to ask for.

Would live in agentic-ai/Claude/rules/common/agents.md.

---

Already covered / lower priority

• Tip 1 (context status line): Claude Code has a built-in /statusline skill that handles this.
• Tip 2 (permission allow list): Superseded by bypassPermissions — allow lists are for default mode.
• Tip 7 (global vs project skills): Already how Claude Code works; nothing to configure here.
• Tip 9 (MEMORY.md content strategy): Already in practice via the memory system.
• Tip 10 (selective plugins): Situational; worth revisiting if startup feels slow.

---

One gap in our current Tip 3 implementation

The article's validate-bash.sh also blocks sudo and git add -A / git add . — two patterns we didn't include. Worth adding in a follow-up commit:

• sudo — escalation should always be explicit
• git add -A / git add . — can silently stage secrets; Claude should always add specific files

[ulises-c]

Review notes — includes uncommitted settings.json change

---

Uncommitted change: ~/.config/gh moved from denyRead → allowWrite

The working-tree diff moves ~/.config/gh out of denyRead and into allowWrite. Two effects:

1. Write unblocked for Bash commands — gh auth login and similar commands can now write tokens to ~/.config/gh/hosts.yml inside the sandbox. That's clearly intentional.
2. Read no longer blocked — Claude can now cat ~/.config/gh/hosts.yml and read the OAuth token. If the sandbox should still prevent token exfiltration, ~/.config/gh needs to stay in denyRead alongside the allowWrite entry (the two keys aren't mutually exclusive).

Also: validate-write.sh still lists ~/.config/gh in SENSITIVE_PREFIXES, so Write/Edit tools remain blocked there. That's now inconsistent with the sandbox allowing writes — probably fine since bash (gh) is the only thing that needs to write there, but worth making explicit in a comment.

---

README doc drift

README.md lists ~/.gnupg as a blocked read path:

reads to ~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh are blocked

~/.gnupg is not in settings.json's denyRead. Either add it or update the README.

---

All hook scripts missing set -euo pipefail

install.sh has it; all four hook scripts (validate-bash.sh, validate-write.sh, post-edit-shellcheck.sh, driftcheck.sh) don't. The project's own rules/bash/style.md requires it for every non-trivial script.

Hooks intentionally control their own exit codes (0 / 2), but set -euo pipefail wouldn't conflict with that — it would just catch unexpected failures (e.g. jq not found, unbound variable) instead of silently exiting 0 and letting a bad command through.

---

Minor: validate-bash.sh pipes through cat unnecessarily

COMMAND=$(cat | jq -r '.tool_input.command // ""')

jq reads stdin directly; cat | adds a subshell for no reason. Per style rules, prefer:

COMMAND=$(jq -r '.tool_input.command // ""')

(The other hooks already do this correctly via INPUT=$(cat) then printf '%s' "$INPUT" | jq ....)

[ulises-c]

References & future work

Logging the resources that informed the current sandbox design and what's next. Full detail in PLAN.md.

Sources reviewed

• Stop Using Default Settings — 10 Claude Code Configs That Actually Work — basis for hooks, rules hierarchy, agent triggers
• Fixing gh CLI in Claude Code's Sandbox — macOS TLS issue with Go CLIs; Linux uses system CAs so not applicable, but enableWeakerNetworkIsolation flag documented
• Making Claude Code Actually Work Autonomously with Sandbox — 1Password credential pre-resolution pattern to remove ~/.config/gh from sandbox read surface
• Railguard — per-command policy engine using bwrap on Linux; more sophisticated than regex hooks (pipe analysis, secret content inspection, memory injection detection, session replay)
• Docker Claude Code Sandbox — containerized approach; credentials live outside sandbox entirely via OAuth proxy
• NVIDIA AI Workbench — Claude Code Quickstart — same bwrap + socat stack; surfaced denyWrite gap (Bash can still write to /etc etc.) and enableWeakerNestedSandbox for container deployments

Near-term items added to PLAN.md

• GPG agent socket — verify /run/user/$UID/gnupg/ is accessible inside bwrap (confirmed broken in this session)
• 1Password credential pre-resolution — inject GH_TOKEN at shell startup so ~/.config/gh can go back into denyRead
• Railguard evaluation — compare catch rate vs current hooks
• denyWrite for system paths — close the Bash-bypass gap on /etc, /usr, /boot, /sys, /proc
• enableWeakerNestedSandbox — document for future container workflows

[ulises-c]

Final summary — what this PR delivers and the sandbox decision

What's in the branch

• bypassPermissions + PreToolUse hooks — validate-bash.sh blocks catastrophic shell patterns (rm -rf /, dd to devices, mkfs, pipe-to-shell, force-push to main, sudo, bulk git add); validate-write.sh blocks Write/Edit tools from touching ~/.ssh, ~/.aws, ~/.gnupg, ~/.config/gh, and system paths
• PostToolUse: post-edit-shellcheck.sh — shellcheck on every edited .sh file; exits 2 to force fixes before Claude continues
• Stop hook: driftcheck.sh — validates shebang + exec bit on all tracked .sh files at session end
• Hierarchical rules — rules/common/general.md, rules/common/agents.md, rules/bash/style.md imported via CLAUDE.md
• install.sh — wires everything via symlinks so changes take effect immediately
• SANDBOX.md — full written record of the sandbox investigation (see below)

---

Sandbox: disabled, and why

sandbox.enabled: false. The bwrap sandbox was disabled because Claude Code's Linux sandbox uses seccomp BPF to unconditionally block all AF_UNIX socket syscalls. This kills two hard requirements:

What breaks	Requirement
gpg-agent (AF_UNIX socket)	Signed commits — required by work policy
ssh-agent (AF_UNIX socket)	SSH push — only auth method for GitHub, Bitbucket, Forgejo

Every workaround was evaluated and ruled out:

• excludedCommands — bypasses sandbox filesystem only, not seccomp (#10524)
• allowUnsandboxedCommands — same limitation; not per-command for seccomp
• seccomp config in settings.json — silently ignored (#24238)
• SSH signing format (gpg.format ssh, key file direct read) — would bypass the socket issue for signing, but non-GitHub VCS (Bitbucket, Forgejo) don't support SSH-format signatures; GPG required
• Docker sandbox — credentials live outside container by design; no SSH agent or GPG forwarding; appropriate for CI/untrusted-code, not personal dev
• NVIDIA AI Workbench — same bwrap + socat stack; enableWeakerNestedSandbox solves nested-container bwrap issues (not the AF_UNIX problem); also blocks credential access by design

Upstream blocker: #44180 — Linux: add allowUnixSockets equivalent for seccomp BPF. Open, no timeline. Was a regression introduced in v2.1.92 when apply-seccomp was bundled. macOS already has allowAllUnixSockets; Linux parity is what's needed.

---

Re-enable trigger

When #44180 ships, flip sandbox.enabled back to true — the denyRead/allowWrite filesystem config is already in place. Verify with:

git commit --allow-empty -S -m "sandbox gpg test"   # must sign
git push                                              # must push via SSH
gh api user                                          # must return GitHub user

If those pass without errors or prompts, the sandbox is viable. At that point also move ~/.config/gh to denyRead and store GH_TOKEN in settings.json env (see PLAN.md item 2).

---

Current security model (without sandbox)

Hooks are the primary guardrail. Claude runs as your user — same surface as any terminal session. The gaps relative to sandbox-enabled: Bash-level shell redirects to system paths aren't blocked, and denyRead isn't enforced. Both are theoretical risks on a single-user dev machine.

Full writeup with re-enable checklist, all evaluated workarounds, and upstream issue table: agentic-ai/Claude/SANDBOX.md.

[ulises-c]

Current status of affected files

All hooks confirmed working in a live test session on macOS (2026-05-22):

File	Status
install.sh	Simplified — GH_TOKEN prompt/merge removed; always symlinks settings.json. Idempotent, backs up any existing non-symlink settings.
settings.json	bypassPermissions + 4 hooks wired. Sandbox present but disabled (see below).
hooks/validate-bash.sh	Verified — blocked git add . via PreToolUse
hooks/validate-write.sh	Verified — blocked write to ~/.ssh/ via PreToolUse
hooks/post-edit-shellcheck.sh	Verified — blocked edit with SC2168 shellcheck error via PostToolUse
hooks/driftcheck.sh	Wired to Stop event; fires at session end (logic verified by inspection)
rules/common/general.md	Active — no comments, no premature abstraction, no backwards-compat shims
rules/common/agents.md	Active — proactive Plan/Explore/review/security-review agent invocation
rules/bash/style.md	Active — enforces shebang, set -euo pipefail, [[ ]], quoted vars, printf
setup-linux-sandbox.sh	Staged for Linux; no-op on macOS

Sandbox is disabled (sandbox.enabled: false). The denyRead/denyWrite/allowWrite filesystem config is in place for re-enablement; blocked by upstream issue #44180 (seccomp BPF blocks AF_UNIX sockets, breaking GPG signing and SSH agent).

---

Potential improvements (from PLAN.md)

Near-term

• Re-enable sandbox (#44180) — Flip sandbox.enabled: true once the upstream AF_UNIX fix ships. Run git commit --allow-empty -S + git push to verify GPG and SSH agent still work before closing.
• Railguard evaluation — Railguard adds pipe analysis, evasion detection, write-content secret scanning, and per-edit rollback. Worth a trial run against a test command corpus to compare catch rate vs. validate-bash.sh.
• enableWeakerNetworkIsolation — Leave unset on macOS (Go uses com.apple.trustd.agent; not needed here). Explicit decision documented in PLAN.md.

Longer-term

• validate-bash.sh regex hardening — Current patterns are line-oriented and miss compound commands (;, &&, $() subshells), base64 -d | sh, and inline python -c/node -e exec patterns. At some point this converges with Railguard (item above).
• PostToolUse test runner hook — Block on test failure after edits to test-eligible files. Needs per-project config (CLAUDE_TEST_CMD env var or .claude/test-cmd).
• Network allowlist — Explicit api.github.com, registry.npmjs.org, etc. in settings.json; block unknowns outright instead of prompting.
• Per-project sandbox overrides — Additive allowWrite in project-level .claude/settings.json for projects that write to non-standard paths (e.g., Docker volumes).

[ulises-c]

Final state — reference for after merge

This PR establishes the full agentic-ai/Claude/ hook and config layer. Everything listed below is active after running install.sh.

What's running

Layer	File	What it does
PreToolUse	validate-bash.sh	Blocks destructive shell patterns, piped exec, inline interpreter exec, sudo, bulk staging. All checks that can appear in commit message bodies scoped to $FIRST_LINE.
PreToolUse	validate-write.sh	Blocks writes to credential and system paths
PostToolUse	post-edit-shellcheck.sh	Shellcheck on every .sh edit
PostToolUse	post-test-runner.sh	Auto-discovers and runs project test suite after source edits
Stop	driftcheck.sh	Warns if ~/.claude/ has drifted from repo source
PreToolUse + PostToolUse + SessionStart	railguard v0.5.1	Encoding/obfuscation detection, behavioral evasion detection, memory guard, audit trail, self-protection

railguard-shell (bwrap) is intentionally not activated — same AF_UNIX blocker as the built-in sandbox.

Blocked on upstream

Both remaining items block on the same root cause: #44180 — seccomp BPF unconditionally blocks AF_UNIX sockets on Linux, killing gpg-agent and ssh-agent. Required for provider-agnostic git workflows (GitHub, Bitbucket, Forgejo).

1. Re-enable sandbox (sandbox.enabled: true) — filesystem config already in place; flip the flag and verify git commit -S + git push when #44180 ships
2. railguard-shell — revisit when #44180 ships or railguard adds --share-path /run/user/$UID

Known railguard behaviors to expect

• Editing railguard.yaml (or any file whose diff mentions railguard config) always requires approval — intentional self-protection
• After any blocked command, Tier 3 evasion detection flags similar follow-up commands for the rest of the session — known false positive, approve when prompted