oprogramadorreal/optimus-claude / skills/permissions
permissions
FlaggedConfigures Claude Code permissions for low-prompt work inside a project; changes nothing under Codex. Creates or merges allow/deny rules in .claude/settings.json and installs a PreToolUse hook gating out-of-project writes and deletes, precious untracked files, and history-changing git on protected branches. Writes only under .claude/, including an ownership record. Use after /optimus:init or standalone.
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 12.2 KB |
| SKILL.md | skill md | 5.8 KB |
| agents/openai.yaml | config | 198 B |
| templates/hooks/restrict-paths.sh | script | 96.2 KB |
| templates/settings.json | config | 1.5 KB |
templates/hooks/restrict-paths.sh
View on GitHub#!/usr/bin/env bash
# ============================================================================
# restrict-paths.sh — Claude Code PreToolUse hook
# Installed by: /optimus:permissions (optimus-claude plugin)
# Source: https://github.com/oprogramadorreal/optimus-claude
# Docs: skills/permissions/README.md
# ============================================================================
# HOOK_VERSION: 13
# ^ Bump on every behavioural change. The plugin's SessionStart hook compares
# this against the copy installed in a project and recommends re-running
# /optimus:permissions when the project's copy is older — a plugin update
# never re-copies an already-installed hook on its own.
# ============================================================================
#
# PURPOSE:
# Prevents Claude Code from writing or deleting files outside your project
# directory. This is a safety guardrail, not a permissions bypass — it adds
# restrictions, not removes them.
#
# WHAT THIS SCRIPT DOES:
# - Edit/Write operations inside the project → silently allowed
# - Edit/Write operations outside the project → prompts you for approval
# - Creating a NEW file under the OS temp root → prompts you, and tells Claude
# the session scratchpad is exempt
# - Edit/Write/delete in Claude's memory store → silently allowed
# - Edit/Write/delete in Claude's scratchpad → silently allowed
# - rm/rmdir commands outside the project → hard blocked
# - Edit/Write of precious unversioned files → prompts you for approval
# - rm/rmdir of precious unversioned files → hard blocked
# - Git history changes on feature branches → silently allowed
# - Git history changes on protected branches → hard blocked
# - Everything else (reads, searches, etc.) → passes through unchanged
#
# WHAT THIS SCRIPT DOES NOT DO:
# - Does NOT send data anywhere (no network calls)
# - Does NOT log or record file paths or commands
# - Does NOT modify, read, or copy your files
# - Does NOT run in the background or persist after Claude Code exits
#
# FAIL-OPEN DESIGN:
# When the hook cannot determine whether an operation is safe (e.g.,
# CLAUDE_PROJECT_DIR is unset, JSON parsing fails, or the file_path field
# is missing), it allows the operation rather than blocking it. This avoids
# breaking legitimate tool use when input formats change.
#
# MULTI-REPO WORKSPACE SUPPORT:
# When the project root is not itself a git repo (e.g., a directory
# containing multiple independent git repos), the hook resolves the git
# context per-file and per-command. This ensures precious file protection
# and branch protection work correctly in each sub-repo.
#
# PRECIOUS FILE PROTECTION (always-on):
# Well-known sensitive files (.env, *.key, *.pem, *.sqlite, etc.) that are
# not tracked by git receive extra protection: edits prompt for approval,
# deletions are blocked. No configuration needed — the patterns live in
# is_precious_name() (delete blocked) and is_recoverable_precious_name()
# (backups/IDE scratch: edit asks, delete allowed).
#
# CLAUDE MEMORY STORE (always-allowed):
# Claude Code keeps a per-project auto-memory store under
# <home>/.claude/projects/<project>/memory/. Although that path is outside
# CLAUDE_PROJECT_DIR, it is Claude's own scratchpad (plain markdown, designed
# to be written and pruned by Claude), so writes AND deletes there are allowed
# without a prompt. The exemption is scoped to a single-segment memory/ subtree
# only — the rest of ~/.claude (settings.json, etc.) is NOT exempt and still
# prompts on out-of-project write / is blocked on out-of-project delete.
#
# CLAUDE SESSION SCRATCHPAD (always-allowed):
# The harness gives each session a scratchpad under
# <temp>/claude/<project>/<session>/scratchpad/ (temp root taken from
# TMPDIR/TEMP/TMP, or /tmp). Like the memory store it is Claude's own throwaway
# working area, so writes AND deletes there are allowed without a prompt. The
# match requires the full <temp>/claude/<project>/<session>/scratchpad shape
# (both <project> and <session> are single path segments), so it can't stretch
# to an unrelated 'scratchpad' dir elsewhere under the temp root. If the temp
# root can't be resolved, the path falls back to the normal out-of-project prompt.
#
# TEMP-WRITE NUDGE: creating a NEW file under the temp root WITHOUT this shape
# (an invented temp dir) still prompts you — the nudge never decides for you,
# so a temp path you asked for yourself still comes to you for approval.
#
# TWO AUDIENCES, TWO FIELDS. For a PreToolUse "ask", Claude Code shows
# permissionDecisionReason to the USER, while additionalContext injects
# information for CLAUDE alongside the tool decision. Only "deny" sends its
# reason to the model. So the prompt text is
# written for you, and the scratchpad reminder — the part only Claude can act
# on — rides additionalContext. Putting the reminder in the reason instead
# would deliver it to the one party who cannot act on it.
#
# The reminder deliberately does NOT name a scratchpad path: only the harness
# knows it, and it already gives it to Claude in the system prompt. A path
# built here from the project basename would name a look-alike directory the
# harness neither creates nor cleans up.
#
# Scope: a file that ALREADY EXISTS keeps the plain prompt (existence is
# tested on the NORMALIZED path, so a phantom intermediate dir cannot make an
# existing file look new), and ~/.claude keeps its own — it is Claude's
# config, not scratch, and it can sit under the temp root in CI images. The
# nudge is skipped when the path contains a ".." this platform's realpath left
# unresolved. The ~/.claude veto is deliberately NOT a whole-$HOME veto, which
# would disable the nudge wherever the temp root lives under the home dir
# (TMPDIR=$HOME/tmp, MSYS2/Cygwin default mounts) — the common case.
#
# PATH NORMALIZATION:
# normalize() lowercases on Windows, resolves "..", collapses repeated slashes
# and drops a trailing one, so every spelling of a path compares equal. The
# collapse is load-bearing: macOS TMPDIR ends in '/', a non-GNU realpath that
# rejects '-m' returns the string untouched, and the cd/pwd fallback splices
# '//tmp' when the parent is '/' — each would otherwise leave a base that stops
# matching paths written the ordinary way, silently killing an exemption.
#
# A leading '//' is preserved only when it is present BOTH in the path as the
# OS spells it (i.e. after cygpath, which is what turns '\\server\share' into
# '//server/share' — probing the raw argument would miss every natively spelled
# UNC path) AND in the post-realpath string. That is a UNC network root on
# MSYS/Cygwin, genuinely distinct from '/'. Requiring both readings matters in
# both directions: on Linux realpath collapses '//x' to '/x' (POSIX leaves
# exactly two leading slashes implementation-defined) and the platform's answer
# is respected, while the cd/pwd fallback's spliced '//tmp' is NOT mistaken for
# a UNC root. Three or more leading slashes are plain '/'.
#
# normalize() also resolves '.' and '..' ITSELF (collapse_dot_segments) when
# the steps above left them in place — a realpath that rejects '-m', or the
# cd/pwd fallback. Doing so is what lets an ordinary in-project 'a/../b' stay
# allowed on those platforms: the alternative, failing closed on any '..',
# turns it into a hard DENY that goes to the model and can never be approved.
# An absolute path cannot climb above its own root (POSIX: '/..' is '/').
#
# Exemption gates take an ALREADY normalized path (the `_n` suffix), so a
# caller normalizes once and consults all of them. Every gate that can reach an
# auto-allow keeps a has_unresolved_traversal backstop for the one case the
# resolution above cannot settle — a RELATIVE path, which has no root to anchor
# '..' against — so such a path can never pass a prefix test.
#
# COMMAND PARSING:
# A Bash tool call arrives as ONE string that may hold many commands. Both
# Bash-side guards (delete protection, git branch protection) work on it in
# four stages, each of which exists because skipping it turned the guard off
# for an ordinary spelling rather than an exotic one:
# 1. Join backslash-newline line continuations (a continuation is one
# command, not two), then split on the shell's command operators — '&&',
# '||', ';', '|', '&' and newline — then peel any leading keyword ('do ',
# 'then ', '{ ') or case pattern ('b) ') the split left at the front of a
# fragment. A subshell's parens are counted, not just stripped, so a `cd`
# inside one does not outlive it.
# 2. shell_split() each fragment into words, honouring quotes and escapes and
# expanding '~' and every SET $VAR, so a gate compares the path the shell
# will act on rather than the characters as typed. A name this hook cannot
# see (a caller's shell variable is not exported) stays literal — see
# expand_word.
# 3. cmd_word_index() locates the fragment's command word THROUGH a wrapper
# prefix (sudo, command, env VAR=val, xargs and its flags — including a
# flag's separate-word value, as in `sudo -u root` — /bin/rm, \rm), and
# stops at the first token that is a real command, so an argument that
# merely reads 'rm' is never mistaken for one.
# 4. `sh -c <string>`, `bash -c <string>` and `eval` carry a whole command
# inside a single ARGUMENT, which stage 3 can never reach. unwrap_shell_c()
# pulls the string out and feeds it back through stage 1, depth-bounded.
# Two things a fragment's words are NOT: a redirection operator or its target
# ('> /dev/null' is a stream, not a file to delete or a refspec to push), and a
# relative path meaning what it says — a target is resolved against the chain's
# own `cd` first, so `cd /etc && rm passwd` is judged as /etc/passwd.
# Not covered, by design: command substitution (`rm $(cat list)`) and
# `find -exec`, where the delete is not the fragment's own command, and the
# CONTENTS of a deleted directory (`rm -rf config/`) or a mid-word brace
# (`.env.{a,b}`): the precious test sees the named target, or each match of a
# glob, only. This is a guardrail against accidents, not a sandbox against a
# determined bypass.
#
# Known false positive, and deliberately kept: stage 1 splits on operators
# BEFORE stage 2 parses quotes, so an operator INSIDE a quoted argument
# (`echo "a; rm /etc/passwd"`) leaves a fragment that reads as a real command,
# and it is denied. Stage 4 inherits the same wart — a mangled fragment
# beginning `eval` gets unwrapped too. Quote-aware splitting would remove it,
# and would also turn today's denies into silent allows: that same mangling is
# the only reason `sh -c "cd /etc; rm passwd"` is caught, since the payload
# reaches stage 4 as `cd /etc` and the delete arrives as its own fragment.
# An over-eager prompt is recoverable; a missed delete is not.
#
# TO DISABLE OR REMOVE:
# 1. Delete this file: rm .claude/hooks/restrict-paths.sh
# 2. Remove the PreToolUse hook entry from .claude/settings.json
# Or run /optimus:reset permissions, which also removes the settings rules
# and .claude/.optimus-managed.json entries that /optimus:permissions added.
# Or simply ignore it — the hook only runs when Claude Code invokes tools.
# ============================================================================
_rp_input=$(cat)
# --- Environment snapshot for expand_word (see lookup_env_value) ---
# Taken HERE, before the hook assigns anything else, because `${!name}` reads the
# SHELL namespace: an exported name matching a hook global is captured with the
# HOOK's value. Taken later, `root=/etc` exported made `rm -rf $root/passwd` read
# as an in-project delete while the shell removed /etc/passwd — and prefixing
# globals cannot close it, since /optimus:commit parses PROTECTED_BRANCHES by
# name. Here the only names assigned are _rp_-prefixed, and top level is the one
# scope with no function locals in it.
#
# Bash calls with a '$' only: `$(compgen -e)` forks (~34 ms on Windows) on the
# synchronous path of every tool call, and with no '$' in the command no word
# reaches a lookup (expand_word loops on `*'$'*`; a leading '~' reads $HOME
# directly), so an empty snapshot changes no decision. The raw input is a
# superset of the command — JSON leaves '$' unescaped.
_rp_env_keys=()
_rp_env_vals=()
if [[ "$_rp_input" =~ \"tool_name\"[[:space:]]*:[[:space:]]*\"Bash\" && "$_rp_input" == *'$'* ]]; then
while IFS= read -r _rp_env_name; do
[[ "$_rp_env_name" =~ ^[a-zA-Z_][a-zA-Z0-9_]*$ ]] || continue
_rp_env_keys+=("$_rp_env_name")
_rp_env_vals+=("${!_rp_env_name}")
done <<< "$(compgen -e 2>/dev/null)"
# A bash built without programmable completion has no `compgen`. Fall back
# to the names the gates actually depend on rather than expanding nothing,
# which would quietly unblock `rm $HOME/.ssh/id_rsa`.
if (( ${#_rp_env_keys[@]} == 0 )); then
for _rp_env_name in HOME USERPROFILE TMPDIR TEMP TMP CLAUDE_PROJECT_DIR; do
[[ -n "${!_rp_env_name+set}" ]] || continue
_rp_env_keys+=("$_rp_env_name")
_rp_env_vals+=("${!_rp_env_name}")
done
fi
fi
_rp_root="${CLAUDE_PROJECT_DIR}"
# Fail-open: if project root is unknown, allow rather than block all tool use
[[ -z "$_rp_root" ]] && exit 0
# --- Git repo resolution (per-path) ---
# In multi-repo workspaces the project root may not be a git repo.
# We resolve the git toplevel from each file's directory instead.
find_git_root() {
# Returns the git toplevel for a given path, or empty string if not in a repo.
local target_dir="$1"
[[ -d "$target_dir" ]] || target_dir="$(dirname "$target_dir")"
[[ -d "$target_dir" ]] || { echo ""; return; }
local result
result="$(git -C "$target_dir" rev-parse --show-toplevel 2>/dev/null)" || result=""
# Normalize on Windows
if [[ -n "$result" ]] && command -v cygpath &>/dev/null; then
result="$(cygpath -u "$result" 2>/dev/null || echo "$result")"
fi
echo "$result"
}
is_git_tracked() {
# Check that every given file is tracked by git in its containing repo.
# Fail-open: if not in a git repo or git unavailable, assume tracked (allow).
# One repo lookup and one ls-files per run of files sharing a directory, not
# per file: a glob's matches share one, and forks per match let
# `rm -f fixtures/*.sqlite` outrun the hook's timeout — which fails OPEN.
local filepath dir repo_root="" last_dir="" started=""
local -a group=()
for filepath in "$@"; do
[[ "$filepath" == */* ]] && dir="${filepath%/*}" || dir=.
if [[ -z "$started" || "$dir" != "$last_dir" ]]; then
if [[ -n "$repo_root" ]]; then
git -C "$repo_root" ls-files --error-unmatch -- "${group[@]}" &>/dev/null || return 1
fi
started=1 last_dir="$dir" group=()
repo_root="$(find_git_root "$filepath")"
fi
group+=("$filepath")
done
[[ -n "$repo_root" ]] || return 0 # fail-open: no repo → assume tracked
git -C "$repo_root" ls-files --error-unmatch -- "${group[@]}" &>/dev/null
}
# basename without the fork. The precious tests below run on EVERY Edit, Write
# and NotebookEdit, so a `$(basename ...)` here is a subshell on the hook's
# hottest path — and the `basename | tr` pipeline this replaces measured ~109 ms
# per call on Windows, where nothing else on that path forks at all.
_basename=""
basename_of() {
local p="$1"
# Both separators end a segment on Windows. Claude Code spells file_path as
# 'C:\Users\me\proj\.env', which holds no '/' at all — so splitting on '/'
# alone left the WHOLE path as the basename, and no prefix or exact pattern
# ('.env*', 'credentials.*', 'local.settings.json', 'appsettings.*.json') can
# match that. Precious-file protection was silently off for every
# backslash-spelled path, on both the edit ask and the delete block; only the
# suffix-anchored patterns ('*.key', '*.pem', '*.sqlite') still matched, by
# accident. Platform-gated because a backslash is a legal FILENAME character
# elsewhere: on Linux 'a\b' is one file, and splitting it would drop the
# protection this restores.
case "${OSTYPE:-}" in msys*|cygwin*) p="${p//\\//}" ;; esac
while [[ "$p" == */ && "$p" != "/" ]]; do p="${p%/}"; done
_basename="${p##*/}"
}
# Case-fold ONCE, here, and hand the folded basename to both list tests. Folding
# separately inside each let the two disagree about the same file: this rule is
# platform-gated, and the recoverable test used to fold unconditionally, so on
# Linux 'NOTES.TXT.BAK' was recoverable to one entry point and unknown to the other.
precious_basename() {
basename_of "$1"
# Case-insensitive matching for Windows (NTFS) and macOS (APFS)
if [[ "${OSTYPE:-}" == msys* || "${OSTYPE:-}" == cygwin* || "${OSTYPE:-}" == darwin* ]]; then
if (( BASH_VERSINFO[0] >= 4 )); then
_basename="${_basename,,}"
else
# Bash 3.2 (macOS /bin/bash) has no ${,,}. Fold ASCII in-process — every
# precious pattern is ASCII — because a `printf | tr` fork per name let a
# glob delete over thousands of matches outrun the hook's timeout.
local _up=ABCDEFGHIJKLMNOPQRSTUVWXYZ _lo=abcdefghijklmnopqrstuvwxyz _i
for (( _i = 0; _i < 26; _i++ )); do
_basename="${_basename//${_up:_i:1}/${_lo:_i:1}}"
done
fi
fi
}
is_precious() {
precious_basename "$1"
local lname="$_basename"
is_precious_name "$lname" && return 0
is_recoverable_precious_name "$lname"
}
# What the DELETE gate tests: the hard list, and nothing else.
#
# Deliberately NOT `is_precious && ! is_recoverable_precious`. is_precious is
# itself (hard || recoverable), so that expression expands to
# (hard || recoverable) && !recoverable — and any name on BOTH lists
# short-circuits to unprotected. '.env.suo', '.env.<x>.user', 'credentials.suo'
# and 'secrets.user' each match a hard pattern ('.env*', 'credentials.*',
# 'secrets.*') AND a recoverable one ('*.suo', '*.user'), so every one of them
# became silently deletable — the exact opposite of the intent.
#
# A stem re-test inside is_recoverable_precious_name cannot fix it either:
# 'credentials.suo' matches 'credentials.*' as a WHOLE name, not through a stem,
# so there is nothing to strip. Hard-precious has to win at the gate.
is_hard_precious() {
precious_basename "$1"
is_precious_name "$_basename"
}
# Strip ONE trailing backup or rotation suffix from a name. Result in _stripped;
# returns 1 when the name carries none. Shared by is_precious_name so the whole
# CLASS of backup suffixes is closed rather than one instance of it.
_stripped=""
strip_backup_suffix() {
local n="$1"
case "$n" in
*'~') _stripped="${n%\~}"; return 0 ;;
*.bak|*.backup|*.old|*.orig|*.save|*.saved|*.copy|*.prev) _stripped="${n%.*}"; return 0 ;;
# Rotation: 'server.key.1', 'db.sqlite.02', 'prod.dump.003'.
*.[0-9]|*.[0-9][0-9]|*.[0-9][0-9][0-9]) _stripped="${n%.*}"; return 0 ;;
esac
return 1
}
# The hard list, matched on a basename the caller has already case-folded.
# Split out so is_recoverable_precious_name can re-test a '.bak' stem against it.
is_precious_name() {
local lname="$1"
case "$lname" in
# Secrets / credentials
.env*) return 0 ;;
local.settings.json|credentials.*|secrets.*) return 0 ;;
docker-compose.override.yml) return 0 ;;
appsettings.*.json)
# appsettings.json (no dot-suffix) is usually tracked; variants are not
[[ "$lname" != "appsettings.json" ]] && return 0 ;;
# Service account / API keys
*keyfile*.json) return 0 ;;
# Monitoring agent configs (may contain license keys)
newrelic.config) return 0 ;;
# Certificates / keys
*.key|*.pem|*.pfx|*.p12|*.cert|*.crt|*.jks) return 0 ;;
# Database files
*.sqlite|*.sqlite3|*.db|*.db-shm|*.db-wal|*.db-journal|*.mdf|*.ldf|*.ndf) return 0 ;;
# Database dumps
*.dump|*.sql.gz) return 0 ;;
esac
# A backup copy holds exactly what it copied, so re-test the stem against the
# same list. Without this, only the PREFIX patterns above ('.env*',
# 'credentials.*') survived an appended suffix — 'id_rsa.pem.bak',
# 'server.key.old' and 'app.sqlite~' matched nothing, and the suffix laundered
# them off the list. Re-testing only '.bak' closed one instance of that and
# left '.old', '.orig', '.backup', '~' and '.1' doing the same job. Each hop
# strips at least one character, so the recursion is bounded by the name.
if strip_backup_suffix "$lname"; then
is_precious_name "$_stripped"
return $?
fi
return 1
}
# Precious, but recoverable: worth an ask before overwriting, never worth an
# undeniable block on delete. A PreToolUse deny is delivered to the model, not
# the user, so there is no path to "yes, delete it" — and these are exactly the
# files a cleanup step legitimately removes (the harness writes
# .claude/<skill>-deep-progress.json.bak on every run).
#
# Matched on a basename the caller has already case-folded, like is_precious_name.
# The trigger list stays deliberately narrower than strip_backup_suffix: this one
# also decides which ORDINARY files prompt before an overwrite, so widening it to
# every rotation suffix would start prompting on 'access.log.1' and 'main.py.orig'.
# Laundering is closed in is_precious_name instead, where the wider set can only
# ever ADD protection.
is_recoverable_precious_name() {
local lname="$1"
case "$lname" in
*.suo|*.user) return 0 ;;
*.bak)
# Only a backup OF something ordinary is recoverable. Matching the '.bak'
# suffix alone made the suffix a laundering trick: '.env.bak',
# 'id_rsa.pem.bak', 'credentials.json.bak' and 'app.sqlite.bak' hold
# exactly the secrets of the file they copy, yet each dropped out of the
# hard list the moment the suffix was appended. Re-test the stem.
is_precious_name "${lname%.bak}" && return 1
return 0 ;;
esac
return 1
}
# --- Path normalization (cross-platform) ---
# Resolve '.' and '..' segments lexically, preserving a leading '/' or '//'.
# Pure bash (result in a global, no fork). `realpath -m` already does this, but a
# realpath that REJECTS '-m' (macOS/BSD) and the cd/pwd fallback both leave the
# segments in place — and a gate that cannot resolve '..' has to fail closed,
# which would turn an ordinary in-project 'a/../b' into an unapprovable deny.
_collapsed=""
collapse_dot_segments() {
local p="$1" seg lead="" n
case "$p" in
//[!/]*) lead="//"; p="${p#//}" ;;
/*) lead="/"; p="${p#/}" ;;
esac
local -a parts=()
local IFS='/'
# noglob around the split. `for seg in $p` is unquoted — it MUST be, that is
# what splits on IFS — so without this every segment is also pathname-expanded
# against the hook's CWD (the project root). A '*' segment then becomes N
# segments here but stays ONE for the OS, and the extra segments absorb the
# following '..', so '<proj>/*/../../../etc/evil' looks in-project to every
# gate while the OS resolves it outside: a silent allow on the write AND an
# escape from the rm hard-block. has_unresolved_traversal cannot backstop it,
# since the '..' are gone by then. Restored only if we set it, so an outer
# `set -f` survives.
local _noglob_set=""
[[ -o noglob ]] || { _noglob_set=1; set -f; }
for seg in $p; do
case "$seg" in
""|.) ;;
..)
n=${#parts[@]}
if [[ $n -gt 0 && "${parts[$((n-1))]}" != ".." ]]; then
unset "parts[$((n-1))]"
parts=(${parts[@]+"${parts[@]}"})
elif [[ -z "$lead" ]]; then
# A relative path may legitimately keep leading '..'; an absolute one
# cannot go above its root (POSIX: '/..' is '/').
parts+=("..")
fi
;;
*) parts+=("$seg") ;;
esac
done
[[ -n "$_noglob_set" ]] && set +f
_collapsed="$lead${parts[*]-}"
}
normalize() {
local p="$1"
# Convert Windows paths on MSYS/Cygwin. '--' so a path that looks like a flag
# ('-n', '-e') is not eaten as one, which would hand the gates an empty string.
command -v cygpath &>/dev/null && p="$(cygpath -u -- "$p" 2>/dev/null || printf '%s\n' "$p")"
# How the OS itself spells the path, before any resolution. The UNC probe below
# reads THIS, not "$1": cygpath is what turns '\\server\share' into
# '//server/share', so probing the raw argument would miss every UNC path
# spelled the native Windows way and collapse it onto an unrelated local path.
local spelled="$p"
# Resolve ../ traversal without requiring path to exist
if command -v realpath &>/dev/null; then
p="$(realpath -m -- "$p" 2>/dev/null || printf '%s\n' "$p")"
elif [[ -d "$(dirname "$p")" ]]; then
local resolved_parent
# -d does not imply traversal permission; preserve the input if cd fails.
if resolved_parent="$(cd "$(dirname "$p")" 2>/dev/null && pwd)"; then
p="$resolved_parent/$(basename "$p")"
fi
fi
# Collapse repeated slashes, drop a trailing one (see header: PATH
# NORMALIZATION). Requiring the UNC shape in BOTH the OS spelling and the
# post-realpath string keeps the cd/pwd fallback's spliced '//tmp' from being
# mistaken for a UNC root, while respecting a realpath that already collapsed a
# genuine '//' per its platform's rule.
local lead=""
[[ "$spelled" == //[!/]* && "$p" == //[!/]* ]] && { lead="/"; p="${p#/}"; }
while [[ "$p" == *//* ]]; do p="${p//\/\//\/}"; done
[[ "$p" == "/" ]] || p="${p%/}"
p="$lead$p"
# Resolve anything the steps above left behind. Skipped unless a dot-segment is
# actually present, so the common path stays pure parameter expansion.
case "$p" in
*/../*|*/..|../*|..|*/./*|*/.|./*|.) collapse_dot_segments "$p"; p="$_collapsed" ;;
esac
# Case-insensitive on Windows (NTFS)
if [[ "${OSTYPE:-}" == msys* || "${OSTYPE:-}" == cygwin* ]]; then
if (( BASH_VERSINFO[0] >= 4 )); then
p="${p,,}"
else
p="$(printf '%s' "$p" | tr '[:upper:]' '[:lower:]')"
fi
fi
# printf, not echo: a path of exactly '-n'/'-e'/'-E' is an echo FLAG and would
# come back as the empty string, silently dropping the path from every gate.
printf '%s\n' "$p"
}
# --- Shared path predicates (see header: PATH NORMALIZATION) ---
# Backstop, not the primary defence: normalize() now resolves '..' itself, so an
# absolute path reaching a gate has none left. What can still arrive is a
# RELATIVE path, which has no root to anchor '..' against. Kept on every gate
# that can auto-allow because it is free and fails in the safe direction.
has_unresolved_traversal() {
case "$1" in */../*|*/..|../*|..) return 0 ;; esac
return 1
}
# Rejects a RELATIVE temp root, which normalize() would resolve against this
# hook's working directory — turning an arbitrary sibling of the project into an
# auto-allowed subtree, exempt from the prompt AND from the rm hard-block.
# A bare leading backslash stays rejected: it is drive-RELATIVE on Windows.
is_absolute_path() {
case "$1" in
/*) return 0 ;; # POSIX absolute, incl. //server/share
'\\'?*) return 0 ;; # UNC \\server\share (cygpath maps it to //...)
[A-Za-z]:[/\\]*) return 0 ;; # drive-qualified C:\ or C:/
esac
return 1
}
# One path segment an exemption shape may match. Like has_unresolved_traversal
# this is now a backstop: normalize() drops '.' segments before any gate sees
# them. Kept because it is free and the shapes are meant to be exact.
is_single_segment() {
case "$1" in
""|.|..) return 1 ;;
*/*|*\\*) return 1 ;;
esac
return 0
}
# --- Project root ---
# Resolved lazily: this hook fires on EVERY tool call, but only the write and rm
# branches consult the root, so reads/searches skip the normalize() forks.
_norm_root=""
_norm_root_resolved=""
resolve_norm_root() {
[[ -n "$_norm_root_resolved" ]] && return
_norm_root="$(normalize "$_rp_root")"
# Trailing slash for prefix matching (avoids /project-other matching /project)
[[ "$_norm_root" != */ ]] && _norm_root="${_norm_root}/"
_norm_root_resolved=1
}
is_inside_project_n() {
has_unresolved_traversal "$1" && return 1
resolve_norm_root
[[ "$1" == "$_norm_root"* || "$1" == "${_norm_root%/}" ]]
}
# --- Claude Code auto-memory store (see header: CLAUDE MEMORY STORE) ---
_norm_home=""
_norm_home_resolved=""
resolve_norm_home() {
[[ -n "$_norm_home_resolved" ]] && return
_norm_home_resolved=1
# Fail closed on an unset home rather than normalizing "": on a realpath-less
# platform that resolves to this hook's working directory, which would anchor
# the memory-store exemption on an arbitrary cwd.
local raw="${HOME:-${USERPROFILE:-}}"
[[ -n "$raw" ]] || return
_norm_home="$(normalize "$raw")"
}
# `${_norm_home%/}` so a home of "/" yields "/.claude", not "//.claude".
is_under_claude_config() {
resolve_norm_home
[[ -n "$_norm_home" ]] || return 1
local home="${_norm_home%/}"
[[ "$1" == "$home/.claude" || "$1" == "$home/.claude/"* ]]
}
is_claude_memory_n() {
resolve_norm_home
[[ -n "$_norm_home" ]] || return 1
local norm_path="$1"
has_unresolved_traversal "$norm_path" && return 1
# Match exactly <home>/.claude/projects/<project>/memory[/...]. A bare case-glob
# '*' also spans '/', so <project> goes through is_single_segment or the
# exemption would stretch to a 'memory' dir nested arbitrarily deep.
local prefix="${_norm_home%/}/.claude/projects/"
[[ "$norm_path" == "$prefix"* ]] || return 1
local rest="${norm_path#"$prefix"}"
local seg="${rest%%/*}"
is_single_segment "$seg" || return 1
case "${rest#"$seg"}" in
/memory|/memory/*) return 0 ;;
esac
return 1
}
# --- Claude Code session scratchpad (see header: CLAUDE SESSION SCRATCHPAD) ---
# Resolved lazily like the project root. The OS temp root varies (TMPDIR on
# macOS/Linux, TEMP/TMP on Windows, /tmp as a POSIX fallback), so each candidate
# is normalized once — a Windows temp mounted at /tmp then compares equal to a
# normalized file_path, and duplicate spellings collapse onto one base.
_scratch_bases_resolved=""
_scratch_bases=()
resolve_scratch_bases() {
[[ -n "$_scratch_bases_resolved" ]] && return
_scratch_bases_resolved=1
local candidate norm_candidate entry seen
local -a raws=()
for candidate in "${TMPDIR:-}" "${TEMP:-}" "${TMP:-}" /tmp; do
[[ -n "$candidate" ]] || continue
is_absolute_path "$candidate" || continue
# Dedup the RAW spelling before paying for normalize(): on Windows TEMP and
# TMP are routinely the identical string, and each normalize() forks twice.
seen=""
for entry in ${raws[@]+"${raws[@]}"}; do [[ "$entry" == "$candidate" ]] && { seen=1; break; }; done
[[ -n "$seen" ]] && continue
raws+=("$candidate")
norm_candidate="$(normalize "$candidate")"
[[ -n "$norm_candidate" ]] || continue
# A bare root is not a usable temp root — treating "/" (or the UNC namespace
# root "//") as one would make every path "under the temp root".
[[ "$norm_candidate" == "/" || "$norm_candidate" == "//" ]] && continue
seen=""
for entry in "${_scratch_bases[@]}"; do [[ "$entry" == "$norm_candidate" ]] && { seen=1; break; }; done
[[ -n "$seen" ]] || _scratch_bases+=("$norm_candidate")
done
}
is_under_temp_root() {
resolve_scratch_bases
local base
for base in "${_scratch_bases[@]}"; do
[[ "$1" == "$base/"* ]] && return 0
done
return 1
}
is_claude_scratchpad_n() {
resolve_scratch_bases
local norm_path="$1"
has_unresolved_traversal "$norm_path" && return 1
# Match exactly <temp>/claude/<project>/<session>/scratchpad[/...]; both slots
# go through is_single_segment so the exemption can't stretch to a 'scratchpad'
# dir nested arbitrarily deep under <temp>/claude/.
local base prefix rest proj after sess
for base in "${_scratch_bases[@]}"; do
prefix="$base/claude/"
[[ "$norm_path" == "$prefix"* ]] || continue
rest="${norm_path#"$prefix"}" # <project>/<session>/scratchpad/...
proj="${rest%%/*}"
after="${rest#"$proj"}" # /<session>/scratchpad/...
is_single_segment "$proj" || continue
[[ "$after" == /* ]] || continue
after="${after#/}" # <session>/scratchpad/...
sess="${after%%/*}"
is_single_segment "$sess" || continue
case "${after#"$sess"}" in
/scratchpad|/scratchpad/*) return 0 ;;
esac
done
return 1
}
# --- Temp-write nudge (see header: TEMP-WRITE NUDGE) ---
# Either prompts (exits via ask_permission) or returns 1 — never prints otherwise.
nudge_temp_write() {
local filepath="$1" norm_path="$2" noun="$3" verb="$4"
# Only a NEW file is nudged: an Edit of an existing temp file has nothing to do
# with choosing a scratch location. Test the NORMALIZED path so a phantom
# intermediate dir ('<temp>/a/../b.md') cannot make an existing file look new.
# -L as well as -e, because -e follows symlinks and would call a dangling one new.
[[ -e "$norm_path" || -L "$norm_path" ]] && return 1
has_unresolved_traversal "$norm_path" && return 1
is_under_claude_config "$norm_path" && return 1
is_under_temp_root "$norm_path" || return 1
ask_permission \
"$noun '$filepath' is a new file outside the project, under the OS temp root. Allow this $verb?" \
"This path is outside the exempt session scratchpad. Prefer the scratchpad directory given in your system prompt for throwaway files — writes there need no approval."
}
# --- JSON response helpers ---
# A reason can carry raw environment values (a temp root or directory name may
# legally contain a tab, CR or newline — a CRLF-sourced TEMP on Windows is the
# easy way to get one), and a bare control character makes the whole decision
# unparseable JSON, which the harness reads as "no decision" — silently dropping
# the deny or the ask. Every C0 code point JSON gives a short escape gets one;
# the rest are dropped. (DEL is legal raw in JSON, so it stays.)
# Writes to a global rather than stdout so the caller pays no subshell fork.
_json_escaped=""
json_escape() {
# C locale pins the [$'\001'-$'\037'] range below to byte order: before bash
# 4.3's globasciiranges default (stock macOS ships 3.2), bracket ranges follow
# locale collation, which can let a control char through in a UTF-8 locale.
local LC_ALL=C
local s="${1//\\/\\\\}"
s="${s//\"/\\\"}"
s="${s//$'\n'/\\n}"
s="${s//$'\r'/\\r}"
s="${s//$'\t'/\\t}"
s="${s//$'\b'/\\b}"
s="${s//$'\f'/\\f}"
s="${s//[$'\001'-$'\037']/}"
_json_escaped="$s"
}
# The reverse, for a tool_input string value, so the guards judge what the tool
# will actually touch. \001 shields literal backslashes from the later passes;
# the value never reaches emitted JSON, so the sentinel cannot leak.
_json_unescaped=""
json_unescape() {
local s="${1//\\\\/$'\001'}"
s="${s//\\\"/\"}"; s="${s//\\\//\/}"
s="${s//\\n/$'\n'}"; s="${s//\\r/$'\r'}"; s="${s//\\t/$'\t'}"
_json_unescaped="${s//$'\001'/\\}"
}
# $1 = decision, $2 = reason for the USER, $3 = optional context for CLAUDE.
# The two audiences are distinct — see header: TEMP-WRITE NUDGE. printf, not a
# `cat` heredoc, so emitting a decision costs no fork.
emit_decision() {
json_escape "$2"
local reason="$_json_escaped" extra=""
if [[ -n "${3:-}" ]]; then
json_escape "$3"
extra=",\"additionalContext\":\"$_json_escaped\""
fi
printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"%s","permissionDecisionReason":"%s"%s}}\n' \
"$1" "$reason" "$extra"
exit 0
}
ask_permission() { emit_decision ask "$1" "${2:-}"; }
# A deny already sends its reason to the model, so it needs no additionalContext.
deny_operation() { emit_decision deny "$1"; }
# --- Shared exemption ladder ---
# Locations that may be written/deleted without an out-of-project prompt. The
# structured-write branch and the Bash rm branch both consult THIS function, so
# the two can never disagree about what is exempt. Cheapest gate first: the
# project test is fork-free, the memory store costs one normalize, the scratchpad
# up to four. (Callers still run their own precious-file check afterwards, so
# this is not a blanket bypass.)
is_exempt_out_of_project_n() {
is_inside_project_n "$1" && return 0
is_claude_memory_n "$1" && return 0
is_claude_scratchpad_n "$1" && return 0
return 1
}
# --- Out-of-project gate for the structured write tools ---
# Returns 0 when the write may continue to the precious-file check;
# ask_permission exits the script.
guard_out_of_project_write() {
local filepath="$1" noun="$2" verb="$3"
local norm_path
norm_path="$(normalize "$filepath")"
is_exempt_out_of_project_n "$norm_path" && return 0
# A new file under the temp root prompts with a scratchpad reminder for Claude;
# the plain prompt below covers everything else. `|| true` so the expected
# non-zero return cannot abort the script under an inherited errexit, which
# would emit no decision at all.
nudge_temp_write "$filepath" "$norm_path" "$noun" "$verb" || true
ask_permission "$noun '$filepath' is outside project root. Allow this $verb?"
}
# --- Command-line word splitting (see header: COMMAND PARSING) ---
# Split a command fragment into shell words, honouring single quotes, double
# quotes and backslash escapes, then expand '~' and $VAR. Result in _words.
#
# `read -ra` is not a substitute: it splits on whitespace and hands back the
# characters verbatim, quote marks included. `rm "<abs path>"` then arrives as
# the single word '"<abs path>"', which normalize() resolves as a RELATIVE path
# under the project root — so the out-of-project hard block never fires. Claude
# Code quotes any path containing a space, so that was the common case, not an
# exotic one. Same story for '~/x' and '$HOME/x'.
_words=()
shell_split() {
# Byte semantics for the character walk below, like json_escape pins for its
# bracket range. In a UTF-8 locale bash decodes ${s:i:1} as a CHARACTER, which
# re-scans from the front of the string on every index — the walk is
# superlinear, and past ~2 KB it costs more than the `sed` split it replaced
# (about a second slower on a 16 KB one-liner). The loop only ever compares
# against ASCII delimiters and reassembles the pieces in order, and a UTF-8
# continuation byte can never equal one of those, so byte-wise walking yields
# identical words.
local LC_ALL=C
# Two statements on purpose: bash expands a whole `local` line BEFORE binding
# any of its names, so `local s="$1" n=${#s}` reads the OUTER s and sets n=0 —
# the loop below then never runs and every fragment splits to nothing.
local s="$1"
local n=${#s} i=0 c d q="" cur="" started=""
_words=()
while (( i < n )); do
c="${s:i:1}"
if [[ "$q" == "'" ]]; then
if [[ "$c" == "'" ]]; then q=""; else cur+="$c"; fi
elif [[ "$q" == '"' ]]; then
if [[ "$c" == '"' ]]; then
q=""
elif [[ "$c" == '\' ]]; then
# Inside double quotes a backslash escapes only these four.
d="${s:i+1:1}"
case "$d" in
'"'|'\'|'$'|'`') cur+="$d"; (( ++i )) ;;
*) cur+="$c" ;;
esac
else
cur+="$c"
fi
else
case "$c" in
"'"|'"') q="$c"; started=1 ;;
'\') cur+="${s:i+1:1}"; (( ++i )); started=1 ;;
' '|$'\t'|$'\n')
if [[ -n "$started" ]]; then _words+=("$cur"); cur=""; started=""; fi
;;
*) cur+="$c"; started=1 ;;
esac
fi
# PRE-increment, throughout. `(( i++ ))` evaluates to the OLD value, so on
# the first pass it evaluates to 0 — and an arithmetic command whose result
# is 0 returns exit status 1. Under an inherited errexit that aborts the
# hook on the very first character of the very first fragment, before any
# decision is emitted: both Bash-side guards silently stop existing. `++i`
# increments identically and can never evaluate to 0 here.
(( ++i ))
done
[[ -n "$started" ]] && _words+=("$cur")
local _i=0
while (( _i < ${#_words[@]} )); do
expand_word "${_words[_i]}"
_words[_i]="$_expanded"
(( ++_i ))
done
return 0
}
# Expand a leading '~' and every $VAR / ${VAR} in a word. No eval, no forks.
# Result in _expanded.
#
# Expansion is applied to every word, including single-quoted ones the shell
# would keep literal. That over-expands in exactly one direction: a file
# literally named '$HOME' would be judged by where the variable points, which
# errs toward asking or blocking. Under-expanding is the hole this closes —
# `rm $HOME/.ssh/id_rsa` used to read as an in-project relative path and sail
# straight through the out-of-project block.
_expanded=""
expand_word() {
local w="$1" out="" rest name literal ch
case "$w" in
"~") w="${HOME:-\~}" ;;
"~/"*) w="${HOME:-\~}/${w#\~/}" ;;
esac
while [[ "$w" == *'$'* ]]; do
out+="${w%%\$*}"
rest="${w#*\$}"
name=""
if [[ "$rest" == '{'* && "$rest" == *'}'* ]]; then
name="${rest%%\}*}"; name="${name#\{}"
literal="\${$name}"
rest="${rest#*\}}"
else
while [[ -n "$rest" ]]; do
ch="${rest:0:1}"
case "$ch" in
[a-zA-Z0-9_]) name+="$ch"; rest="${rest:1}" ;;
*) break ;;
esac
done
literal="\$$name"
fi
# Only a plain identifier the CALLER's shell would also see is resolved.
# '$(...)', '$1', '${x:-y}' and the like stay literal — reading them needs an
# eval this hook will not run, and a word the hook leaves literal is still
# checked, just as written.
#
# The lookup is load-bearing in both directions. A shell variable assigned in
# the caller (`BUILD_DIR=build && rm -rf $BUILD_DIR/x`) is not exported, so
# the hook never sees it — substituting "" collapsed the word to '/x', which
# every gate read as an absolute path outside the project and HARD DENIED.
# A deny goes to the model with no prompt and no override, so ordinary
# build-dir cleanup became impossible. Leaving the word literal matches the
# file's fail-open rule (see header: FAIL-OPEN DESIGN): a name this hook
# cannot resolve is a path it cannot judge. Exported and environment
# variables — $HOME above all — are still expanded, so `rm $HOME/.ssh/id_rsa`
# stays blocked.
if lookup_env_value "$name"; then
out+="$_env_value"
else
out+="$literal"
fi
w="$rest"
done
_expanded="$out$w"
}
# The caller's view of a $VAR, from a snapshot of the environment (see the
# snapshot at the top of this file).
#
# What this replaces: `-n "${!name+set}"` followed by `${!name}`. An indirect
# expansion resolves against the WHOLE shell namespace — this hook's own globals
# and, because bash scopes `local` dynamically, the locals of every function on
# the stack. expand_word's own `out`/`rest`/`ch` and shell_split's `q`/`cur`/`n`
# were all in scope, so a user command that merely mentioned one of those names
# was judged against the HOOK's value: `out=dist && rm -rf $out/assets` denied
# '/assets', `q=queue && rm -rf $q/tmp` denied '/tmp'. Unappealable, on commands
# that never named a path outside the project. Names the hook cannot see are
# exactly the ones that must stay literal, and only the environment is genuinely
# shared with the caller's shell.
#
# Parallel indexed arrays rather than one associative array: bash 3.2 (stock
# macOS) has no `declare -A`, and this must not quietly stop expanding $HOME
# there. A linear scan of ~100 names per '$' is nothing next to the forks the
# gates below already pay.
_env_value=""
lookup_env_value() {
local i=0
while (( i < ${#_rp_env_keys[@]} )); do
if [[ "${_rp_env_keys[i]}" == "$1" ]]; then _env_value="${_rp_env_vals[i]}"; return 0; fi
(( ++i ))
done
return 1
}
# Locate the command word of an already-split fragment: sets _cmd_idx to the
# index of the first token whose basename matches one of the '|'-separated
# names in $1, and returns 1 when the fragment runs some other command.
#
# A guard anchored on the fragment's FIRST token misses every ordinary spelling
# of the same command — `sudo rm`, `command rm`, `env rm`, `/bin/rm`, `\rm`
# (which defeats an alias, not this hook), `xargs -n 1 rm`, `xargs -I {} rm`,
# `timeout 5 rm`. The walk steps over a wrapper, its flags, a flag's numeric or
# placeholder value, and VAR=val assignments, and it stops dead at the first
# token that is a real command, so `git commit -m "rm the old file"` can never
# be read as a delete.
#
# `sh -c <string>`, `bash -c <string>` and `eval <words>` are NOT wrappers in
# this sense and must not be added to the list below: their payload is a whole
# command string inside a single argument, not a token of this fragment, so no
# walk over these tokens can reach it. unwrap_shell_c() handles them instead, by
# handing the string back to the fragment splitter.
#
# Known limits, both pre-existing: a command reached through `find -exec` or a
# command substitution (`rm $(cat list)`) is not seen, because neither is a
# wrapper prefix — the fragment's command is `find` / the outer command.
_cmd_idx=-1
# The directory a wrapper option moved the command into (`sudo -D <dir>`,
# `env -C <dir>`, `--chdir=<dir>`), for the caller to resolve relative paths
# against. Set by the walk below, which already has to step over that value to
# reach the command word — it just used to throw it away, so `sudo -D /etc rm
# passwd` was judged as an in-project delete of <project>/passwd while the shell
# removed /etc/passwd.
_cmd_chdir=""
cmd_word_index() {
local names="$1"; shift
local -a t=("$@")
local i tok base flag valflags="" chdirflags="" skip="" skip_is_chdir=""
_cmd_chdir=""
for ((i=0; i<${#t[@]}; i++)); do
tok="${t[i]#\\}"
base="${tok##*/}"
# The previous token was a wrapper option that takes its value as a SEPARATE
# word, so this token is that value and not a command. Consuming it is what
# the walk was missing: it ended ON the value and reported "runs some other
# command", which turned BOTH Bash guards off. `sudo rm <outside>` was denied
# while `sudo -u root rm <outside>` was allowed — and the same one word
# unguarded `sudo -u root git push origin master`.
if [[ -n "$skip" ]]; then
[[ -n "$skip_is_chdir" ]] && _cmd_chdir="${t[i]}"
skip=""; skip_is_chdir=""; continue
fi
case "|$names|" in
*"|$base|"*) _cmd_idx=$i; return 0 ;;
esac
case "$tok" in
# Wrappers, each with the options that swallow the following word. Listing
# them per wrapper rather than skipping any bare word after a flag keeps
# `sudo -u root somecmd rm` from reading as a delete: 'somecmd' still ends
# the walk.
#
# A flag belongs here ONLY if its value is REQUIRED and can arrive as a
# separate word. A flag whose value is optional or attached-only takes no
# following word, so listing it consumes the COMMAND — the walk ends on it
# and reports "runs some other command", which turns both Bash guards off.
# That is why `i` and `replace` are absent below while `I` is present: GNU
# spells the required form `-I R` / `--replace=R` but the optional forms
# `-i[R]` and `--replace[=R]` take nothing, and `xargs -i rm -rf <outside>`
# — an entirely mainstream spelling — was allowed while a bare `xargs rm`
# was denied. Same for `--max-lines` / `--eof` (optional) against `-L` /
# `-E` (required), and for sudo's `-h`, which alone is `--help`.
# --chroot is a chdir for this purpose: a relative target under it resolves
# against the new root on the HOST filesystem, which is what the gates judge.
sudo|doas) valflags="u|user|g|group|p|prompt|r|role|t|type|C|close-from|U|other-user|D|chdir|R|chroot"; chdirflags="D|chdir|R|chroot" ;;
# -S/--split-string is deliberately NOT listed: it carries a whole command
# in its value, so consuming it as a flag value ended the walk on the
# payload and reported "runs some other command", turning both Bash guards
# off. unwrap_shell_c claims that form before this walk ever runs.
env) valflags="u|unset|C|chdir"; chdirflags="C|chdir" ;;
timeout) valflags="s|signal|k|kill-after"; chdirflags="" ;;
nice) valflags="n|adjustment"; chdirflags="" ;;
ionice) valflags="c|class|n|classdata|p|pid|P|pgid|u|uid"; chdirflags="" ;;
stdbuf) valflags="i|input|o|output|e|error"; chdirflags="" ;;
xargs) valflags="n|max-args|L|I|a|arg-file|d|delimiter|E|P|max-procs|s|max-chars"; chdirflags="" ;;
command|builtin|exec|nohup|time) valflags=""; chdirflags="" ;;
-*)
if [[ "$tok" == *=* ]]; then
# An '=' carries the value in the same word, so nothing follows it —
# but a --chdir=<dir> still moves the command, so record it.
flag="${tok%%=*}"; flag="${flag#-}"; flag="${flag#-}"
if [[ -n "$flag" && -n "$chdirflags" ]]; then
case "|$chdirflags|" in *"|$flag|"*) _cmd_chdir="${tok#*=}" ;; esac
fi
else
# A LONG option is one name, matched whole. A SHORT cluster is many
# one-letter flags, and only the LAST of them can take a separate-word
# value — so testing the whole post-dash remainder missed every bundled
# spelling: `-Hu` never matched `u`, and `sudo -Hu root rm <outside>`
# walked onto 'root', ended there, and lost both guards while the
# unbundled `sudo -u root` was correctly denied.
if [[ "$tok" == --?* ]]; then
flag="${tok#--}"
else
flag="${tok#-}"; flag="${flag: -1}"
fi
# The emptiness guards matter: '--' strips to "", which would otherwise
# match the empty valflags of a no-option wrapper and swallow the
# command word.
if [[ -n "$flag" && -n "$valflags" ]]; then
case "|$valflags|" in *"|$flag|"*) skip=1 ;; esac
fi
if [[ -n "$flag" && -n "$skip" && -n "$chdirflags" ]]; then
case "|$chdirflags|" in *"|$flag|"*) skip_is_chdir=1 ;; esac
fi
fi
;;
# A VAR=val assignment, and the placeholder / count tokens of an xargs or
# find invocation — none of them is a command word.
*=*|'{}'|'%'|[0-9]*) ;;
*) return 1 ;;
esac
done
return 1
}
# Recognize a redirection token. A redirection names a STREAM, never a path the
# command acts on or a refspec it pushes, and both spellings have to be caught:
# a lone operator ('rm x > /dev/null', 'git push > /dev/null') leaves its target
# in the NEXT word, while a glued one ('>/dev/null', '2>&1') carries it in the
# same word. Left unhandled, the first spelling made '/dev/null' look like a
# delete target — an unappealable deny on one of the most ordinary shell idioms
# there is — and made 'git push' look like it named an explicit refspec, which
# skipped the current-branch resolution and walked straight past the protected
# branch check. Sets _redir_takes_arg when the caller must also skip the next word.
_redir_takes_arg=""
is_redirection() {
_redir_takes_arg=""
local w="$1"
# Drop a leading fd number ('2>', '10>&1') before matching the operator.
w="${w#"${w%%[!0-9]*}"}"
case "$w" in
'>'|'>>'|'<'|'<<'|'<<<'|'>&'|'<&'|'<>'|'&>'|'&>>') _redir_takes_arg=1; return 0 ;;
'>'*|'<'*|'&>'*) return 0 ;;
esac
return 1
}
# Extract the command string carried inside `sh -c <string>` / `bash -c <string>`
# (through any wrapper prefix) or concatenated after `eval`. Result in _unwrapped.
#
# Without this, one wrapper turned BOTH Bash-side guards off at once:
# `sh -c "rm -rf /etc"`, `eval rm /etc/passwd` and `bash -c "git push origin
# master"` all emitted nothing at all. The inner string is a single shell WORD to
# this fragment, so the only way to check it is to split it as a command in its
# own right — which is what the caller does with the result.
_unwrapped=""
unwrap_shell_c() {
local -a t=("$@")
local i
# `env -S '<cmd>'` / `env --split-string=<cmd>` carry a whole command inside one
# argument exactly as `sh -c` does, so they need the same treatment. Checked
# BEFORE the shell names and falling through when no payload is found, so
# `env FOO=bar sh -c '<cmd>'` still reaches the shell branch below.
if cmd_word_index 'env' "${t[@]}"; then
for ((i=_cmd_idx + 1; i<${#t[@]}; i++)); do
case "${t[i]}" in
-S|--split-string) _unwrapped="${t[i+1]:-}"; [[ -n "$_unwrapped" ]] && return 0 ;;
--split-string=*) _unwrapped="${t[i]#--split-string=}"; [[ -n "$_unwrapped" ]] && return 0 ;;
-S?*) _unwrapped="${t[i]#-S}"; [[ -n "$_unwrapped" ]] && return 0 ;;
esac
done
fi
cmd_word_index 'sh|bash|dash|ksh|zsh|eval' "${t[@]}" || return 1
local base="${t[_cmd_idx]#\\}"; base="${base##*/}"
local _oldifs flags
if [[ "$base" == eval ]]; then
# `eval a b c` joins its words with a space and runs the result.
(( ${#t[@]} > _cmd_idx + 1 )) || return 1
_oldifs="$IFS"; IFS=' '; _unwrapped="${t[*]:$((_cmd_idx + 1))}"; IFS="$_oldifs"
[[ -n "$_unwrapped" ]] || return 1
return 0
fi
# A shell's command string is the argument after -c, which may be bundled with
# other short flags ('sh -ec', 'bash -lc', 'sh -cx').
#
# The bundle has to be tested for the LETTER. `-*c` — matching any flag that
# merely ends in 'c' — claimed '--norc': it handed back the following token,
# the literal '-c', as the payload and returned success, so the caller
# re-scanned the string "-c" and skipped both guards for the real command.
# `bash --norc -c "rm -rf <outside>"` was allowed while the plain `sh -c`
# spelling was denied, and 'sh -cx' was missed from the other side: its 'c' is
# in the bundle but not last.
for ((i=_cmd_idx + 1; i<${#t[@]}; i++)); do
case "${t[i]}" in
# The two long options taking a separate-word value. Left unhandled, the
# value read as a script path and ended the walk, so `bash --rcfile f -c
# "<cmd>"` unwrapped nothing at all.
--rcfile|--init-file) (( ++i )) ;;
# Every other long option is a switch, and none of them is '-c'.
--*) ;;
-?*|+?*)
flags="${t[i]#[-+]}"
if [[ "$flags" == *c* ]]; then
_unwrapped="${t[i+1]:-}"
[[ -n "$_unwrapped" ]] && return 0
return 1
fi
# '-o <shopt>' takes a separate-word value, like the long options above,
# and so do '-O <shopt>' and its '+O' off-switch. Matching only lowercase
# 'o' left the shopt name to be read as a script path, which ended the
# walk: `bash -O extglob -c "rm -rf <outside>"` unwrapped nothing and lost
# both guards, while the plain `bash -c` spelling was denied.
if [[ "$flags" == *[oO] ]]; then (( ++i )); fi
;;
# A bare '-' reads the script from stdin, and any other non-flag argument
# is a SCRIPT PATH ('bash scripts/build.sh') — neither carries a command
# string to unwrap.
*) return 1 ;;
esac
done
return 1
}
# --- Git branch protection ---
# Customize this list to match your project's protected branches.
# These branches are shielded from commits (incl. cherry-pick/revert/am),
# merges, pushes, rebases, hard resets, restores/discards, and branch rewrites
# or deletions (including update-ref). All other branches are treated as
# feature branches where git operations are allowed without prompts.
PROTECTED_BRANCHES=("master" "main" "develop" "dev" "development" "staging" "stage" "prod" "production" "release")
is_protected_branch() {
local branch="$1"
for pb in "${PROTECTED_BRANCHES[@]}"; do
[[ "$branch" == "$pb" ]] && return 0
done
return 1
}
get_current_branch() {
git -C "${1:-$_rp_root}" rev-parse --abbrev-ref HEAD 2>/dev/null
}
# Resolve which git repo a git command targets.
# Uses -C <path> if present, otherwise tries the project root.
# Returns the repo directory suitable for get_current_branch, or empty if none.
resolve_git_context() {
local dir="$1" # from -C flag, or empty
if [[ -n "$dir" ]]; then
# Normalize Windows paths (d:/foo, D:\foo) to POSIX form (/d/foo)
command -v cygpath &>/dev/null && dir="$(cygpath -u "$dir" 2>/dev/null || echo "$dir")"
# -C was specified — resolve to an absolute path relative to project root
if [[ "$dir" != /* ]]; then
dir="$_rp_root/$dir"
fi
local repo_root
repo_root="$(find_git_root "$dir")"
if [[ -n "$repo_root" ]]; then
echo "$repo_root"
return
fi
fi
# No -C or -C didn't resolve — try project root
local root_repo
root_repo="$(find_git_root "$_rp_root")"
[[ -n "$root_repo" ]] && echo "$root_repo" && return
# Multi-repo workspace: no git at root and no -C — can't determine context
echo ""
}
# Parse git push arguments and deny if targeting a protected branch.
# Called with all tokens after "git push" as arguments.
# Calls deny_operation (which exits) if blocked; returns silently if allowed.
check_git_push() {
local t
for t in "$@"; do
case "$t" in
--all|--mirror) deny_operation "BLOCKED: 'git push $t' can affect protected branches." ;;
esac
done
# Separate flags from positional args
local -a positional=()
local has_delete=false
local i=1 skip_next=""
while (( i <= $# )); do
local arg="${!i}"
if [[ -n "$skip_next" ]]; then skip_next=""; i=$(( i + 1 )); continue; fi
# A redirection is not a refspec. Counted as one, `git push > /dev/null`
# reached the branch resolution below with TWO positionals, so it took the
# 'git push <remote> <refspec>' path and checked '/dev/null' against the
# protected list instead of resolving the current branch — a push to master
# one space away from unguarded.
if is_redirection "$arg"; then
skip_next="$_redir_takes_arg"
i=$(( i + 1 )); continue
fi
case "$arg" in
-d|--delete) has_delete=true ;;
-f|--force|--force-with-lease*|--force-if-includes) ;;
-u|--set-upstream|--no-verify|--dry-run|-n|--verbose|-v|--quiet|-q) ;;
--atomic|--signed*|--no-signed|--thin|--no-thin|--tags|--prune) ;;
--progress|--no-progress|--porcelain|--no-recurse-submodules) ;;
--push-option|-o|--repo|--receive-pack|--exec) skip_next=1 ;;
--push-option=*|-o*|--repo=*) ;;
-*) ;; # unknown flag, skip (fail-open)
*) positional+=("$arg") ;;
esac
i=$(( i + 1 ))
done
# Determine target branch(es)
local -a targets=()
if (( ${#positional[@]} <= 1 )); then
# git push [remote] — pushes current branch
local current
current="$(get_current_branch "${git_repo_dir:-}")" || return 0
[[ "$current" == "HEAD" ]] && return 0
targets=("$current")
else
# git push <remote> <refspec>...
local refspec target
for refspec in "${positional[@]:1}"; do
if [[ "$has_delete" == true ]]; then
target="$refspec"
elif [[ "$refspec" == *:* ]]; then
target="${refspec#*:}"
else
target="${refspec#+}" # strip + force prefix
fi
target="${target#refs/heads/}" # strip refs/heads/ prefix
# 'git push origin HEAD' (or '@') pushes the CURRENT branch — resolve it,
# or a protected branch is reachable by naming it indirectly.
if [[ "$target" == "HEAD" || "$target" == "@" ]]; then
target="$(get_current_branch "${git_repo_dir:-}")" || continue
[[ "$target" == "HEAD" ]] && continue # detached — no branch to protect
fi
[[ -n "$target" ]] && targets+=("$target")
done
fi
# Check targets against protected branches
local tgt
for tgt in "${targets[@]}"; do
if is_protected_branch "$tgt"; then
deny_operation "BLOCKED: Cannot push to protected branch '$tgt'. Push to a feature branch instead."
fi
done
}
# Check one already-split command fragment for git branch protection violations.
# Called with an optional cd directory from a chained command, followed by the
# fragment's words as produced by shell_split.
# Calls deny_operation (exits the script) if blocked; returns 0 if allowed.
check_git_command() {
local cd_dir="${1:-}"; shift
local -a tokens=("$@")
# Detect git through any wrapper prefix (sudo, env VAR=val, command, /usr/bin/git).
cmd_word_index 'git' "${tokens[@]}" || return 0
# Re-base the array on the git word so every index below still counts from 'git'.
local -a _args=()
(( ${#tokens[@]} > _cmd_idx + 1 )) && _args=("${tokens[@]:$((_cmd_idx + 1))}")
tokens=(git ${_args[@]+"${_args[@]}"})
# Rejoin for the '--hard' whole-string check further down. IFS is restored
# immediately: the callees below run `read`.
local git_portion _oldifs="$IFS"
IFS=' '; git_portion="${tokens[*]}"; IFS="$_oldifs"
# Find git subcommand (skip global flags between 'git' and subcommand)
local git_subcmd="" git_subcmd_idx=0 git_dir=""
local i
for ((i=1; i<${#tokens[@]}; i++)); do
case "${tokens[i]}" in
-C) git_dir="${tokens[i+1]:-}"; (( ++i )) ;; # capture -C target dir
-c|--git-dir|--work-tree|--namespace) (( ++i )) ;; # skip flag + its argument
--git-dir=*|--work-tree=*|--namespace=*) ;; # skip =form (no extra arg)
-*) ;; # skip other flags
*) git_subcmd="${tokens[i]}"; git_subcmd_idx=$i; break ;;
esac
done
# Resolve which git repo this command targets
# Priority: explicit -C flag > cd directory from chain > project root
local git_repo_dir
if [[ -n "$git_dir" ]]; then
git_repo_dir="$(resolve_git_context "$git_dir")"
elif [[ -n "$cd_dir" ]]; then
git_repo_dir="$(resolve_git_context "$cd_dir")"
else
git_repo_dir="$(resolve_git_context "")"
fi
# Fail-open: if we can't determine a git repo, allow (no branches to protect)
[[ -n "$git_repo_dir" ]] || return 0
local current_branch
case "$git_subcmd" in
push)
# Delegate to check_git_push with tokens after "git push"
check_git_push "${tokens[@]:$((git_subcmd_idx+1))}"
;;
# cherry-pick/revert/am create commits on the checked-out branch exactly
# like commit, so they share its block — but not their way OUT of a
# conflicted run: --abort and --quit commit nothing, and git refuses them
# alongside a commit or another action. --continue and --skip go on to
# commit the rest, so they stay blocked.
commit|merge|cherry-pick|revert|am)
if [[ "$git_subcmd" != commit ]]; then
case "${tokens[git_subcmd_idx+1]:-}" in
--abort|--quit|--show-current-patch|--show-current-patch=*) return 0 ;;
esac
fi
current_branch="$(get_current_branch "$git_repo_dir")" || return 0
[[ "$current_branch" == "HEAD" ]] && return 0
if is_protected_branch "$current_branch"; then
deny_operation "BLOCKED: Cannot '$git_subcmd' on protected branch '$current_branch'. Switch to a feature branch first."
fi
;;
reset)
# Only block 'reset --hard' on protected branches
[[ "$git_portion" == *--hard* ]] || return 0
current_branch="$(get_current_branch "$git_repo_dir")" || return 0
[[ "$current_branch" == "HEAD" ]] && return 0
if is_protected_branch "$current_branch"; then
deny_operation "BLOCKED: 'git reset --hard' on protected branch '$current_branch' is not allowed."
fi
;;
rebase)
current_branch="$(get_current_branch "$git_repo_dir")" || return 0
[[ "$current_branch" == "HEAD" ]] && return 0
if is_protected_branch "$current_branch"; then
deny_operation "BLOCKED: 'git rebase' on protected branch '$current_branch' is not allowed."
fi
;;
checkout)
# Scan tokens after the subcommand for -b/-B flags (handles both "-b name" and "-bname")
local co_flag="" co_target="" ci
for ((ci=git_subcmd_idx+1; ci<${#tokens[@]}; ci++)); do
case "${tokens[ci]}" in
-b) co_flag="-b"; co_target="${tokens[ci+1]:-}"; break ;;
-b*) co_flag="-b"; co_target="${tokens[ci]#-b}"; break ;;
-B) co_flag="-B"; co_target="${tokens[ci+1]:-}"; break ;;
-B*) co_flag="-B"; co_target="${tokens[ci]#-B}"; break ;;
esac
done
# Allow 'git checkout -b' (create new branch, fails if exists — always safe)
[[ "$co_flag" == "-b" ]] && return 0
# 'git checkout -B <name>' force-resets a branch — block if target is protected
if [[ "$co_flag" == "-B" ]]; then
if [[ -n "$co_target" ]] && is_protected_branch "$co_target"; then
deny_operation "BLOCKED: 'git checkout -B $co_target' would reset protected branch '$co_target'."
fi
return 0
fi
# Block 'git checkout -- <paths>' and 'git checkout .' on protected branches
local has_discard=false
for ((ci=git_subcmd_idx+1; ci<${#tokens[@]}; ci++)); do
case "${tokens[ci]}" in
--|.) has_discard=true; break ;;
esac
done
[[ "$has_discard" == true ]] || return 0
current_branch="$(get_current_branch "$git_repo_dir")" || return 0
[[ "$current_branch" == "HEAD" ]] && return 0
if is_protected_branch "$current_branch"; then
deny_operation "BLOCKED: Discarding changes on protected branch '$current_branch' is not allowed."
fi
;;
restore)
current_branch="$(get_current_branch "$git_repo_dir")" || return 0
[[ "$current_branch" == "HEAD" ]] && return 0
if is_protected_branch "$current_branch"; then
deny_operation "BLOCKED: 'git restore' on protected branch '$current_branch' is not allowed."
fi
;;
switch)
# Scan tokens after the subcommand for -c/-C flags (handles both "-c name" and "-cname")
local sw_flag="" sw_target="" si
for ((si=git_subcmd_idx+1; si<${#tokens[@]}; si++)); do
case "${tokens[si]}" in
-c) sw_flag="-c"; sw_target="${tokens[si+1]:-}"; break ;;
-c*) sw_flag="-c"; sw_target="${tokens[si]#-c}"; break ;;
-C) sw_flag="-C"; sw_target="${tokens[si+1]:-}"; break ;;
-C*) sw_flag="-C"; sw_target="${tokens[si]#-C}"; break ;;
# --force-create is -C's long form; git also takes any unique prefix
# of it (--force-c, even --force-), with the name attached by = or not.
--force-*=*) sw_flag="-C"; sw_target="${tokens[si]#*=}"; break ;;
--force-*) sw_flag="-C"; sw_target="${tokens[si+1]:-}"; break ;;
esac
done
# Allow 'git switch -c' (create new branch, fails if exists — always safe)
[[ "$sw_flag" == "-c" ]] && return 0
# 'git switch -C <name>' force-resets a branch — block if target is protected
if [[ "$sw_flag" == "-C" ]]; then
if [[ -n "$sw_target" ]] && is_protected_branch "$sw_target"; then
deny_operation "BLOCKED: 'git switch -C $sw_target' would reset protected branch '$sw_target'."
fi
fi
return 0
;;
branch)
# Two destructive shapes, not one. Keying on the delete flags alone left
# `git branch -f master HEAD~3` and `git branch -M feat master` free to
# rewrite a protected branch's pointer — the same loss as a delete, and
# the one way to do it that the Bash tool never had to ask about.
# delete: -d/-D (also bundled with other short flags, e.g. -Df),
# --delete, --force-delete
# rewrite: -f/--force (force-create over an existing name), -m/-M/--move
# (rename onto one)
# Read the options from the tokens AFTER the subcommand, splitting short
# bundles from long names. Regexing the rejoined command instead made the
# three tests below near-duplicate patterns that then drifted apart: 'c'/'C'
# were simply missing from the rewrite one, so `git branch -C feature
# master` overwrote master and was allowed. It also let git's own global
# options leak in — the '-c' of `git -c user.name=x branch feature` belongs
# to git, not to branch.
local bi btok bshort="" blong="|"
local -a bnames=()
for ((bi=git_subcmd_idx+1; bi<${#tokens[@]}; bi++)); do
btok="${tokens[bi]}"
case "$btok" in
--*) btok="${btok%%=*}"; blong+="${btok#--}|" ;;
-?*) bshort+="${btok#-}" ;;
# Everything else is a branch name. `git branch -d` accepts several,
# and a rename's OLD name matters as much as its new one.
*) bnames+=("$btok") ;;
esac
done
local branch_op="" is_move="" is_copy=""
if [[ "$bshort" == *[dD]* || "$blong" == *"|delete|"* || "$blong" == *"|force-delete|"* ]]; then
branch_op=delete
elif [[ "$bshort" == *[fmMcC]* || "$blong" == *"|force|"* \
|| "$blong" == *"|move|"* || "$blong" == *"|copy|"* ]]; then
branch_op=rewrite
fi
[[ -n "$branch_op" ]] || return 0
if [[ "$bshort" == *[mM]* || "$blong" == *"|move|"* ]]; then is_move=1; fi
if [[ "$bshort" == *[cC]* || "$blong" == *"|copy|"* ]]; then is_copy=1; fi
# Which of the branch names does the command WRITE?
# -m/-M/--move rename: the old name is destroyed and the new one
# overwritten, so BOTH matter — and with a single argument
# the name it destroys is the CHECKED-OUT branch, which
# never appears on the command line at all. Every sibling
# arm resolves the current branch; this one did not, so on
# master `git branch -m archived` renamed master out of
# existence and was allowed.
# -c/-C/--copy copy: only the DESTINATION (last) is written; the source
# is read.
# -f/--force force-create: only the NAME (first) is written; the
# start-point after it is read. Without that, creating an
# ordinary feature branch off master ('git branch -f
# feature master') would be denied.
if [[ "$branch_op" == rewrite ]]; then
if [[ -n "$is_move" ]]; then
if (( ${#bnames[@]} == 1 )); then
current_branch="$(get_current_branch "$git_repo_dir")"
if [[ -n "$current_branch" && "$current_branch" != "HEAD" ]]; then
bnames+=("$current_branch")
fi
fi
elif [[ -n "$is_copy" ]]; then
(( ${#bnames[@]} > 1 )) && bnames=("${bnames[${#bnames[@]}-1]}")
else
(( ${#bnames[@]} > 1 )) && bnames=("${bnames[0]}")
fi
fi
local bname
for bname in ${bnames[@]+"${bnames[@]}"}; do
bname="${bname#refs/heads/}"
if is_protected_branch "$bname"; then
if [[ "$branch_op" == delete ]]; then
deny_operation "BLOCKED: Cannot delete protected branch '$bname'."
fi
deny_operation "BLOCKED: 'git branch' would rewrite protected branch '$bname'. Use a feature branch instead."
fi
done
;;
update-ref)
# `git update-ref refs/heads/master <sha>` moves a branch pointer with no
# branch subcommand in sight — and it works even on the CHECKED-OUT
# branch, where 'git branch -f' refuses. Same destruction, different door.
local ui uref=""
for ((ui=git_subcmd_idx+1; ui<${#tokens[@]}; ui++)); do
case "${tokens[ui]}" in
# --stdin takes the refs on stdin, which this hook cannot read: nothing
# to check, so fail open as everywhere else.
--stdin) return 0 ;;
-m) (( ++ui )) ;; # reflog message + its argument
-*) ;;
*) uref="${tokens[ui]}"; break ;;
esac
done
[[ -n "$uref" ]] || return 0
if is_protected_branch "${uref#refs/heads/}"; then
deny_operation "BLOCKED: 'git update-ref' would rewrite protected branch '${uref#refs/heads/}'."
fi
;;
esac
return 0
}
# --- Command scanning (see header: COMMAND PARSING) ---
# Walk ONE command string: split it on the shell's operators, then run both
# Bash-side guards over every fragment. Recurses, depth-bounded, into the command
# string carried by `sh -c` / `bash -c` / `eval`.
#
# 'cd <dir>' targets are tracked here because two guards need them: git context
# in multi-repo workspaces, where Claude Code writes "cd <repo> && git ...", and
# the base a RELATIVE delete target resolves against. _cd_dir is deliberately a
# global — a cd persists across the operator that follows it, and into a nested
# `sh -c`, exactly as it does for the shell.
_cd_dir=""
# Where `cd -` goes, and what `popd` pops. Tracking them is what lets the two
# spellings be resolved instead of guessed: the guess was "the project root",
# which is wrong for every chain that moved more than once.
_cd_prev=""
_cd_dirstack=()
_scan_depth=0
# Restore the `cd` that was in force before a subshell which has now CLOSED.
# Reads the paren bookkeeping declared local in scan_command_string, the way
# check_git_push reads git_repo_dir — so a nested `sh -c` scan pushes and pops
# its own parens instead of unwinding its caller's.
cd_pop_closed() {
while (( _cd_pending_close > 0 )); do
_cd_pending_close=$(( _cd_pending_close - 1 ))
(( _cd_depth > 0 )) || continue
_cd_depth=$(( _cd_depth - 1 ))
_cd_dir="${_cd_stack[_cd_depth]}"
done
}
# Count the parens in ONE fragment that close a subshell opened OUTSIDE it.
# Result in _frag_closes.
#
# Testing whether the fragment ENDS in ')' was wrong in both directions. It
# over-counted, because the ')' of a command substitution ends a fragment too:
# in `(cd /etc && echo $(date) && rm passwd)` the ` echo $(date) ` fragment
# banked a close, the deferred pop restored the pre-subshell directory, and the
# `rm passwd` still inside that subshell was judged against the project root
# while the shell deleted /etc/passwd. And it under-counted, because a real
# close need not be last: `(cd /etc && ls) 2>&1 && rm -rf build` ends in
# '2>&1', so no close was banked, /etc stayed in force, and an ordinary
# in-project cleanup was hard-DENIED with no way to override it.
#
# So: walk the fragment, skip quoted runs, and treat every '(' as opening a
# depth — which is exactly what makes '$(', '$((', '<(' and '>(' self-cancelling
# — counting only the ')' that runs out of depth.
_frag_closes=0
count_frag_closes() {
# Byte semantics, for the same reason shell_split pins them: a UTF-8
# continuation byte can never equal one of the ASCII delimiters below.
local LC_ALL=C
local s="$1"
local n=${#s} i=0 c q="" depth=0
_frag_closes=0
while (( i < n )); do
c="${s:i:1}"
if [[ "$q" == "'" ]]; then
[[ "$c" == "'" ]] && q=""
elif [[ "$q" == '"' ]]; then
if [[ "$c" == '\' ]]; then (( ++i ))
elif [[ "$c" == '"' ]]; then q=""; fi
else
case "$c" in
"'"|'"') q="$c" ;;
'\') (( ++i )) ;;
'(') depth=$(( depth + 1 )) ;;
')')
if (( depth > 0 )); then depth=$(( depth - 1 ))
else _frag_closes=$(( _frag_closes + 1 )); fi
;;
esac
fi
(( ++i ))
done
}
# Split the one shell word at the head of $1 off what follows it; the rest,
# from the first whitespace or ')' outside quotes and outside any (...) the
# word opens, lands in _word_rest. The case peel reads a subject and a pattern
# with it, so `"a b")`, `a\ b)` and `$(uname)` are each one word.
_word_rest=""
split_word() {
local LC_ALL=C
local s="$1"
local n=${#s} i=0 c q="" depth=0
while (( i < n )); do
c="${s:i:1}"
if [[ "$q" == "'" ]]; then
[[ "$c" == "'" ]] && q=""
elif [[ "$q" == '"' ]]; then
if [[ "$c" == '\' ]]; then (( ++i ))
elif [[ "$c" == '"' ]]; then q=""; fi
else
case "$c" in
"'"|'"') q="$c" ;;
'\') (( ++i )) ;;
'(') depth=$(( depth + 1 )) ;;
')') (( depth == 0 )) && break
depth=$(( depth - 1 )) ;;
[[:space:]]) (( depth == 0 )) && break ;;
esac
fi
(( ++i ))
done
_word_rest="${s:i}"
}
scan_command_string() {
local _split="$1"
local _subcmd _cd_tok _cd_target _cd_base _cd_noop word target nword skip_next _m _ifs _ng
local -a _matches _precious
local _saved_cd _saved_prev _wrap_base _wrap_cd _eff_cd _n_close
local -a _frag
local -a _saved_stack=()
local -a _cd_stack=()
local _cd_depth=0 _cd_pending_close=0 _pat _rest _peeled_pat
# The subshell depth each open `case` sits at, innermost last.
local _case_depths=""
# A backslash-newline is a LINE CONTINUATION, not a command separator: the
# shell joins the two lines and runs ONE command. Splitting on the newline
# first chopped
# rm -rf \
# <outside>
# into a flagless `rm` and a bare path — the first has no argument the gate
# looks at, the second has no command word — so neither half tripped the
# delete gate while the shell went ahead and deleted. Join before splitting.
_split="${_split//\\$'\n'/}"
# Pure bash, and '&' is one of the operators. The `sed 's/&&/\n/g; ...'` this
# replaces emitted no newline for a LONE '&', so `true & rm <outside>` stayed
# a single fragment that no anchored guard matched — both hard blocks were
# one background operator away from being no-ops. (It also relied on GNU
# sed's \n in a replacement, which inserts a literal 'n' on macOS/BSD, and
# forked a process per command.)
_split="${_split//&&/$'\n'}"
_split="${_split//||/$'\n'}"
_split="${_split//;/$'\n'}"
_split="${_split//|/$'\n'}"
_split="${_split//&/$'\n'}"
while IFS= read -r _subcmd; do
# Apply any subshell close seen on the PREVIOUS fragment. Deferred by one
# fragment on purpose: the ')' arrives glued to the subshell's own last
# command, which still has to be judged against the cd that was in force
# inside it.
cd_pop_closed
_subcmd="${_subcmd#"${_subcmd%%[![:space:]]*}"}" # trim leading whitespace
# Trailing whitespace too, and after each ')' below: the operator split
# leaves a space in front of the next fragment, so ' ./deploy.sh) ' ends in a
# SPACE and the close would go uncounted.
_subcmd="${_subcmd%"${_subcmd##*[![:space:]]}"}"
# Count the subshell parens rather than only stripping them — the count is
# what scopes a `cd` to its subshell. Without it the cd in
# `(cd /tmp && ./deploy.sh) && rm -rf build` stayed in force for the rest of
# the chain, and an ordinary in-project cleanup resolved to /tmp/build and
# was hard-DENIED.
#
# Peel leading shell keywords. `for f in *; do rm <outside>; done` splits
# into a fragment beginning 'do rm ...' and `if x; then rm <outside>; fi`
# into one beginning 'then rm ...' — neither of which the guards below saw,
# so a loop or an if was enough to walk both of them past an unwanted delete
# and past the protected-branch check.
# A case ARM and a function BODY leave the command behind punctuation rather
# than behind a keyword, so neither was peeled: `case x in y) rm <outside>;;
# esac` and `f() { rm <outside>; }` both left a first token that is not a
# command word, cmd_word_index bailed, and every guard below was skipped. A
# generated `cleanup() { rm -rf "$BUILD"; }` is an accident shape, not only
# an adversarial one. Peeling only ever exposes MORE to the guards.
# Only the first arm follows `case`: `;;`, `|` and a newline start every
# other one at its pattern, `b) rm <outside>`. A pattern is peeled only in a
# case, at that case's own subshell depth — `(cd X && ls) 2>&1` leaves
# `ls) 2>`, a close — once per fragment, and only as ONE shell word that a
# ')' ends: a quoted `"a b")` is one, while `x=$(pwd)/y rm` is an arm's body,
# because its word ends at the space. The subject is one word too, so it is
# skipped by the same reading: `case "$(uname)" in`, `case "a in b" in`.
# A subshell can open behind any of these — `do (cd /etc && rm passwd)` — so
# its '(' is taken inside the loop, not only at the head of the fragment.
# Closes are counted on what the peel leaves: a pattern's ')' closes nothing.
_peeled_pat=""
while :; do
if [[ -z "$_peeled_pat" && -n "$_case_depths" && "${_case_depths##* }" == "$_cd_depth" ]]; then
_pat="${_subcmd#\(}" # `(b)` is a pattern too, not a subshell
split_word "$_pat"
_rest="${_word_rest#"${_word_rest%%[![:space:]]*}"}" # `a ) cmd` is valid
if [[ "$_word_rest" != "$_pat" && "${_pat%"$_word_rest"}" != esac \
&& "$_rest" == ')'* ]]; then
_subcmd="${_rest#\)}"
_peeled_pat=1
_subcmd="${_subcmd#"${_subcmd%%[![:space:]]*}"}"
[[ -n "$_subcmd" ]] || break
continue
fi
fi
case "$_subcmd" in
'('*) _subcmd="${_subcmd#\(}"
_cd_stack[_cd_depth]="$_cd_dir"
_cd_depth=$(( _cd_depth + 1 )) ;;
do|then|else|elif|fi|done|in|'{'|'}'|'!') _subcmd="" ;;
# `esac)` ends the subshell around the case: keep its ')' for the count.
'esac'|'esac '*|'esac)'*) _case_depths="${_case_depths% *}"
_subcmd="${_subcmd#esac}"
_subcmd="${_subcmd#"${_subcmd%%[![:space:]]*}"}"
[[ "$_subcmd" == ')'* ]] || _subcmd="" ;;
do\ *|then\ *|else\ *|elif\ *|if\ *|while\ *|until\ *|in\ *|'{'\ *|'!'\ *)
_subcmd="${_subcmd#* }" ;;
*'()'*'{'*) _subcmd="${_subcmd#*\{}" ;;
case\ *) _case_depths="$_case_depths $_cd_depth"
_subcmd="${_subcmd#case}"
_subcmd="${_subcmd#"${_subcmd%%[![:space:]]*}"}"
split_word "$_subcmd"
_subcmd="${_word_rest#"${_word_rest%%[![:space:]]*}"}"
case "$_subcmd" in
in[[:space:]]*) _subcmd="${_subcmd#in}" ;;
*) _subcmd="" ;; # `case x` / `in` on the next line
esac ;;
*) break ;;
esac
_subcmd="${_subcmd#"${_subcmd%%[![:space:]]*}"}"
[[ -n "$_subcmd" ]] || break
done
count_frag_closes "$_subcmd"
_n_close=$_frag_closes
_cd_pending_close=$(( _cd_pending_close + _n_close ))
[[ -n "$_subcmd" ]] || continue
# Strip only as many trailing ')' as there are real closes, so the command
# word stays reachable without eating the ')' of a `$(...)` target. A close
# that is NOT last (a redirection follows it) keeps its paren glued to the
# word; that costs a stray character in the deny message, never a verdict,
# because the paren is on the far side of the path either way. It runs after
# the peel, which needs the ')' of a pattern alone on its line, `a)`.
while (( _n_close > 0 )) && [[ "$_subcmd" == *')' ]]; do
_subcmd="${_subcmd%\)}"
_subcmd="${_subcmd%"${_subcmd##*[![:space:]]}"}"
_n_close=$(( _n_close - 1 ))
done
# One quote-aware split per fragment, shared by all the gates below.
shell_split "$_subcmd"
(( ${#_words[@]} )) || continue
_frag=("${_words[@]}")
# Track 'cd <dir>' to resolve context for subsequent commands — through a
# wrapper prefix, like every other command word here. Matching a bare first
# token was the only spelling recognized, so `builtin cd /etc && rm passwd`
# judged 'passwd' as an in-project path while the shell removed /etc/passwd.
if cmd_word_index 'cd|pushd|popd' "${_frag[@]}"; then
_cd_base="${_frag[_cmd_idx]##*/}"
_cd_target=""
_cd_noop=""
for _cd_tok in "${_frag[@]:$((_cmd_idx + 1))}"; do
case "$_cd_tok" in
'') continue ;;
# `pushd -n <dir>` pushes WITHOUT changing directory — that is the
# entire purpose of the flag — and `popd -n` pops without moving.
# Reading the operand as a cd turned an ordinary in-project delete
# after `pushd -n <elsewhere>` into an unappealable DENY.
-n) _cd_noop=1; continue ;;
# A '+N' / '-N' operand ROTATES the stack to an entry this hook never
# saw. It is not a directory: composing it produced the nonsense base
# '<project>/+1'.
+[0-9]*|-[0-9]*) _cd_noop=1; continue ;;
# A lone '-' is cd's OPERAND, not a flag. Letting the '-*' arm below
# swallow it left no target at all, which reads as a bare `cd`.
-) _cd_target="-"; break ;;
-*) continue ;;
esac
_cd_target="$_cd_tok"
break
done
# Each arm below answers ONE question: where is the shell standing after
# this word? Answering "the project root" for every spelling the hook
# could not resolve was the bug — `popd` with an empty stack, a bare `cd`
# and `cd -P` do not go there, so a following relative `rm` was judged
# in-project while the shell deleted outside it.
if [[ -n "$_cd_noop" ]]; then
: # the shell did not move
elif [[ "$_cd_base" == popd ]]; then
# popd returns to what pushd saved. With an EMPTY stack popd fails and
# the shell stays exactly where it was: `cd /etc && popd && rm passwd`
# removed /etc/passwd while the hook read it as <project>/passwd.
if (( ${#_cd_dirstack[@]} > 0 )); then
_cd_prev="$_cd_dir"
_cd_dir="${_cd_dirstack[${#_cd_dirstack[@]}-1]}"
unset "_cd_dirstack[${#_cd_dirstack[@]}-1]"
fi
elif [[ "$_cd_target" == - ]]; then
# `cd -` returns to the PREVIOUS directory, which is only the project
# root when the chain moved exactly once: after `cd /etc && cd /var`
# it lands back in /etc.
_cd_tok="$_cd_dir"; _cd_dir="$_cd_prev"; _cd_prev="$_cd_tok"
elif [[ -z "$_cd_target" ]]; then
if [[ "$_cd_base" == pushd ]]; then
: # bare pushd swaps the top two — unresolvable
else
# A bare `cd`, `cd --` or `cd -P` goes HOME.
_cd_prev="$_cd_dir"
_cd_dir="${HOME:-$_cd_dir}"
fi
elif is_absolute_path "$_cd_target"; then
[[ "$_cd_base" == pushd ]] && _cd_dirstack+=("$_cd_dir")
_cd_prev="$_cd_dir"
_cd_dir="$_cd_target"
else
[[ "$_cd_base" == pushd ]] && _cd_dirstack+=("$_cd_dir")
_cd_prev="$_cd_dir"
# COMPOSE, never replace. Replacing re-based every later relative target
# on the LAST cd alone, so a chain that walked back out
# (`cd frontend && npm run build && cd .. && rm -rf frontend/dist`) left
# '..' as the base and resolved the delete outside the project — an
# unappealable deny on an ordinary cleanup. normalize() collapses the
# dot segments when the target is finally built.
_cd_dir="${_cd_dir:+$_cd_dir/}$_cd_target"
fi
continue
fi
# A wrapper option can move the command without any `cd` in sight
# (`sudo -D <dir>`, `env -C <dir>`, `--chdir=<dir>`). The walk above already
# stepped over that value to reach the command word, so take it from there —
# read BEFORE the walks below, each of which starts its own. It applies to
# THIS fragment only: the wrapper chdirs the process it spawns, not the
# shell, so nothing after the fragment inherits it.
_wrap_cd="$_cmd_chdir"
_eff_cd="$_cd_dir"
if [[ -n "$_wrap_cd" ]]; then
if is_absolute_path "$_wrap_cd"; then
_eff_cd="$_wrap_cd"
else
_eff_cd="${_cd_dir:+$_cd_dir/}$_wrap_cd"
fi
fi
# `sh -c <string>` / `bash -c <string>` / `eval <words>` carry a whole
# command inside ONE argument, which no walk over these tokens can reach —
# so a single wrapper switched BOTH guards off at once. Hand the string back
# to this function instead. Depth-bounded so a self-referential command
# (`sh -c "sh -c ..."`) cannot spin, and shallow because real commands nest
# once, if at all.
if unwrap_shell_c "${_frag[@]}"; then
_wrap_base="${_frag[_cmd_idx]#\\}"; _wrap_base="${_wrap_base##*/}"
_saved_cd="$_cd_dir"
_saved_prev="$_cd_prev"
_saved_stack=(${_cd_dirstack[@]+"${_cd_dirstack[@]}"})
_cd_dir="$_eff_cd"
if (( _scan_depth < 4 )); then
_scan_depth=$(( _scan_depth + 1 ))
scan_command_string "$_unwrapped"
_scan_depth=$(( _scan_depth - 1 ))
fi
# A `cd` inside `sh -c` runs in a CHILD shell and dies with it, so it must
# not re-base the fragments that follow — the same reason the paren stack
# restores after a subshell, and the same unappealable deny it produced:
# `bash -c "cd /var" ; rm -rf dist` blocked an in-project cleanup because
# _cd_dir is global and the recursion left the child's cd in force. The
# directory stack and the `cd -` target die with that child too. `eval` is
# the exception — it runs in the CURRENT shell, so its cd genuinely
# composes and must survive.
if [[ "$_wrap_base" != eval ]]; then
_cd_dir="$_saved_cd"
_cd_prev="$_saved_prev"
_cd_dirstack=(${_saved_stack[@]+"${_saved_stack[@]}"})
fi
continue
fi
# Git branch protection (feature branches allowed, protected branches blocked)
check_git_command "$_eff_cd" "${_frag[@]}"
# Delete protection (rm/rmdir outside project or precious unversioned).
# cmd_word_index sees through wrapper prefixes — a pipe hands the post-'|'
# fragment here on its own, so `find ... | xargs -n 1 rm <path>` and
# `sudo rm <path>` have to be recognized as deletes just like a bare `rm`.
if cmd_word_index 'rm|rmdir' "${_frag[@]}"; then
skip_next=""
for word in "${_frag[@]:$((_cmd_idx + 1))}"; do
if [[ -n "$skip_next" ]]; then skip_next=""; continue; fi
# Flags, and the placeholder/terminator tokens of an xargs or find
# invocation — none of them name a file.
case "$word" in -*|'{}'|'+'|';'|'') continue ;; esac
# Neither does a redirection: `rm <in-project> > /dev/null` was denied
# for deleting '/dev/null', with no prompt and no way to override it.
if is_redirection "$word"; then skip_next="$_redir_takes_arg"; continue; fi
# A word whose FIRST character is expansion syntax this hook does not
# perform is not a safe relative path — it is an absolute target in
# disguise. `rm $'/etc/passwd'`, `rm {,}/etc/passwd` and
# `rm ~root/.ssh/id_rsa` each kept their leading '/' inside syntax
# expand_word leaves alone, so is_absolute_path answered "relative",
# normalize() re-based the word on the project root, and BOTH the
# out-of-project block and the precious-file block were skipped — three
# characters were enough to strip protection off an untracked .env. Ask
# rather than deny: unresolvable is not the same as hostile, and an ask
# is appealable.
#
# Anchored at the START on purpose, and tested BEFORE the word is
# resolved. Only a LEADING expansion can hide the root: brace expansion
# and $-expansion both keep whatever precedes them, so `build/{a,b}` and
# `build/$(date)` yield relative words no matter what they expand to.
# Matching them anywhere in the word did two wrong things at once — it
# prompted on ordinary in-project cleanups like `rm -rf dist/{js,css}`,
# and it DOWNGRADED settled hard denies, because `rm -rf /etc/$(whoami)`
# is already absolute and already outside: asking there hands back a
# bypass the deny below had closed.
#
# A bare unresolved $VAR keeps its documented fail-open (see
# expand_word): it is the ordinary `rm -rf $BUILD_DIR/x` shape, and
# denying that made build-dir cleanup impossible. The split is on what
# FOLLOWS the '$'. shell_split strips the quotes of $'...', so the word
# arrives as `$/etc/passwd` — a '$' followed by something that cannot
# begin a variable name, which no ordinary $VAR or ${VAR} ever produces.
if ! is_absolute_path "$word"; then
case "$word" in
\$\'*|'$'[!A-Za-z_{]*|'~'[!/]*|'{'*,*'}'*)
ask_permission "Delete target '$word' carries a shell expansion this hook cannot resolve. Allow this delete?" ;;
esac
fi
# Resolve a RELATIVE target against the chain's `cd`, not against this
# hook's own working directory. `cd /etc && rm passwd` otherwise
# normalized to <project>/passwd and read as an IN-project delete, while
# the shell removed /etc/passwd — the tracked cd was right there, it
# just never reached this gate. A relative cd resolves against the
# project root, as it does in resolve_git_context.
target="$word"
if [[ -n "$_eff_cd" ]] && ! is_absolute_path "$target"; then
if is_absolute_path "$_eff_cd"; then
target="$_eff_cd/$target"
else
target="$_rp_root/$_eff_cd/$target"
fi
fi
# Claude's own auto-memory store and session scratchpad are writable AND
# prunable by design, so deletes there are allowed like writes — via the
# SAME ladder the write gate uses. Everything else outside the project
# root is hard-blocked. Normalize once and reuse: the two gates below
# would otherwise resolve the same word twice, two forks apiece.
nword="$(normalize "$target")"
if ! is_exempt_out_of_project_n "$nword"; then
deny_operation "BLOCKED: Cannot delete '$word' — outside project root."
fi
# Precious file protection: block deletion of sensitive unversioned files.
# Recoverable ones (backups, IDE scratch) are excluded by is_hard_precious
# testing the hard list alone — a deny here could never be overridden.
# A glob word names no file itself, so judge what the shell expands it
# to: `rm -f .env*` and `rm -f *.sqlite` otherwise failed the -e test and
# deleted the very files `rm .env` is denied for. The word stays a
# candidate too — quoted, or matching nothing, the shell deletes it as
# written, so `rm 'secret[1].key'` removes that very file. IFS= keeps a
# match that holds a space whole; nullglob drops a pattern that matches
# nothing. `|| _ng=1`, not `_ng=$?`: a bare failing `shopt -q` would abort
# the hook under an inherited errexit before it printed any decision.
_matches=("$target")
if [[ "$target" == *[*?[]* ]]; then
_ng=""; shopt -q nullglob || _ng=1
shopt -s nullglob
_ifs="$IFS"; IFS=
_matches+=($target)
IFS="$_ifs"
[[ -n "$_ng" ]] && shopt -u nullglob
fi
if is_inside_project_n "$nword"; then
# Names first, then ONE tracked check over the precious ones: git per
# match cost `rm -f fixtures/*.sqlite` a fork chain for each file.
_precious=()
for _m in "${_matches[@]}"; do
if [[ -e "$_m" ]] && is_hard_precious "$_m"; then _precious+=("$_m"); fi
done
if (( ${#_precious[@]} )) && ! is_git_tracked "${_precious[@]}"; then
(( ${#_precious[@]} > 1 )) \
&& deny_operation "BLOCKED: '$word' matches a precious file not tracked by git. Deletion denied."
deny_operation "BLOCKED: '$(basename "${_precious[0]}")' is a precious file not tracked by git. Deletion denied."
fi
fi
done
fi
done <<< "$_split"
# A subshell that closed on the LAST fragment has no next iteration to unwind
# it, and _cd_dir is global — it would leak past the end of this scan.
cd_pop_closed
return 0
}
# --- Extract tool_name ---
# Fail-open: if tool_name cannot be extracted, allow rather than block
[[ "$_rp_input" =~ \"tool_name\"[[:space:]]*:[[:space:]]*\"([^\"]+)\" ]] || exit 0
_rp_tool_name="${BASH_REMATCH[1]}"
case "$_rp_tool_name" in
Edit|MultiEdit|Write|NotebookEdit)
# Fail-open: if the path cannot be extracted, allow rather than block.
# The value is a JSON string: walk over escaped quotes ([^"\]|\\.) as the
# Bash branch does — stopping at the first \" judged only the path's prefix.
if [[ "$_rp_tool_name" == NotebookEdit ]]; then
_rp_path_re='"notebook_path"[[:space:]]*:[[:space:]]*"(([^"\]|\\.)*)"'
_rp_noun=Notebook _rp_verb=edit
else
_rp_path_re='"file_path"[[:space:]]*:[[:space:]]*"(([^"\]|\\.)*)"'
_rp_noun=File _rp_verb=write
fi
[[ "$_rp_input" =~ $_rp_path_re ]] || exit 0
json_unescape "${BASH_REMATCH[1]}"
_rp_path="$_json_unescaped"
guard_out_of_project_write "$_rp_path" "$_rp_noun" "$_rp_verb"
# Precious file protection: prompt before modifying sensitive unversioned files
if [[ -e "$_rp_path" ]] && is_precious "$_rp_path" && ! is_git_tracked "$_rp_path"; then
ask_permission "File '$(basename "$_rp_path")' is a precious file not tracked by git. Changes may be permanent. Allow this $_rp_verb?"
fi
exit 0
;;
Bash)
# Fail-open: if command cannot be extracted, allow rather than block.
# The value is a JSON string, so the match must walk over escaped quotes
# ([^"\]|\\.) — stopping at the first \" truncated the command and silently
# skipped every guard for anything as ordinary as `git commit -m "msg"`.
_bash_cmd_re='"command"[[:space:]]*:[[:space:]]*"(([^"\]|\\.)*)"'
[[ "$_rp_input" =~ $_bash_cmd_re ]] || exit 0
json_unescape "${BASH_REMATCH[1]}"
_rp_cmd="$_json_unescaped"
# --- Git branch protection + Delete protection ---
# Both live in scan_command_string, which splits the string on the shell's
# operators and checks each fragment — so chained commands like
# "cd /repo && git commit" and "cd /tmp && rm file" are covered, as is a
# command nested inside `sh -c`.
scan_command_string "$_rp_cmd"
exit 0
;;
*)
exit 0
;;
esac
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |