[FrancesCoronel]

Before: AGENTS.md told agents not to run bootstrap.sh or init/*, but nothing enforced it, and cd init && sh .osx or source init/.osx would have gone straight through. Shell edits were only checked once CI ran, the zsh files weren't checked at all, and AGENTS.md still said .shellcheckrc was "once added".

After: in local and standalone cloud Claude Code sessions, a PreToolUse hook blocks the installers and system changes however the command is chained, and every edit to a shell file gets ShellCheck (or zsh -n) feedback in the same turn. AGENTS.md lists the exact check CI runs.

How:

• .claude/settings.json: allows shellcheck and zsh -n; denies bootstrap.sh, init/*, sudo, defaults write, brew and chsh. Wires up both hooks.
• .claude/hooks/guard-installers.sh (PreToolUse, Bash): splits the command on ;, &&, |, subshells and backticks, then exits 2 when a part runs an installer (directly or through sh/bash/source/./env/exec/xargs), or uses sudo, chsh, defaults write|delete|import, scutil --set or a mutating brew subcommand. Reading, grepping, diffing and ShellChecking those files still works. Deny rules are prefix matches and miss these cases, which is why there's a hook too.
• .claude/hooks/shellcheck-edited.sh (PostToolUse, Edit|Write): runs shellcheck --severity style on *.sh, *.bash and sh/bash shebang files, and zsh -n on zsh files, then exits 2 with the output when either fails. Skips quietly if the tool isn't installed.
• AGENTS.md: fixed the stale .shellcheckrc line (it disables SC1090 and SC1091), added a Checks section with the ShellCheck command CI runs (first-line shebang match, same as ci-shell.yml) and the zsh -n check, and said that Project threads don't load repo hooks, so the written rule is what applies there.
• .editorconfig: lf, final newline, 2-space indent and no trailing whitespace for the shell files. App-exported themes are left alone.

What I ran: ShellCheck at style severity on all 10 tracked shebang scripts plus both hooks (clean); zsh -n on .zshrc, .zprofile, .zshenv and zsh/.p10k.zsh (clean); jq empty .claude/settings.json. I tested the hooks only by piping JSON into them and ran no install script. The guard blocked 14 cases (for example ./bootstrap.sh, cd init && sh .osx, source init/.osx, bash -c "cd x; bash init/.npm", env bash bootstrap.sh, echo $(sudo whoami), brew install jq) and allowed 10 (shellcheck init/.osx bootstrap.sh, cat init/.osx, git diff bootstrap.sh, git commit -m "guard sudo and brew install", brew info jq, defaults read ..., the AGENTS.md check command and others). The ShellCheck hook exited 2 on an unquoted $1 and on a broken .zshrc, and exited 0 on clean files, non-shell files and missing files.

Not in this PR: saying bash instead of sh in the install steps (left for Frances), and the Project-level setup script and instructions (account settings, not repo files).

---

Generated by Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	⚠️ Failed 2026-10-24T15:16:38.701625Z We couldn’t complete this review. Comment @codex review to try again.	eb7ac49	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.