claude-ruby-grape-rails hooks-review.instructions.md

Shell Script and Hook Review Rules

Scope: shell hook scripts under plugins/**/hooks/scripts/*.sh, Ruby hook scripts under plugins/**/hooks/scripts/*.rb (e.g. compress-verify-output.rb, skill-discovery-observer.rb), and shipped binaries under plugins/**/bin/*. Shell-specific rules below apply to .sh scripts; Ruby hooks follow the cross-cutting hook conventions (# Policy: header, opt-in env var short-circuit before side effects, file mode 0o600 on telemetry artifacts, symlink-refusal on ${CLAUDE_PLUGIN_DATA} before mkdir_p/writes).

Audience: Agents, Not Humans

Imperative-only. Hook script source code follows normal code-comment conventions — rule applies to markdown review checklist itself.

Shell Hardening

• All executable hook scripts must use set -o nounset and set -o pipefail
• Library files (*-lib.sh) sourced by other scripts may omit these since the caller's settings apply
• Do NOT add set -e / set -o errexit unless the script must abort on any failure. Current strict-abort hooks: block-dangerous-ops.sh, block-out-of-bounds-writes.sh, active-plan-marker.sh. Most hooks intentionally handle failures gracefully — advisory hooks warn/skip, guardrails fail closed via explicit checks, not errexit
• Use command -v to check for dependencies (jq, grep, etc) before use
• Use ${var:?} in deletion commands to prevent empty-variable disasters
• Each script should have a # Policy: comment near the top documenting its failure behavior (advisory, fail-closed, or security-sensitive)
• Use read_hook_input from workspace-root-lib.sh for stdin JSON parsing
• Use resolve_workspace_root for safe repo root resolution

Deletion Safety

• rm -f only for mktemp outputs or exact fixed plugin-owned paths
• rm -rf only for validated mktemp -d outputs
• rmdir for expected-empty lock directories
• For variable-based cleanup, validate the path/prefix first

Hook Output Patterns

• PostToolUse stdout is verbose-mode only — use exit 2 + stderr to feed messages to Claude
• SessionStart stdout IS added to Claude's context
• SubagentStart uses hookSpecificOutput.additionalContext
• PostToolUseFailure uses hookSpecificOutput.additionalContext
• PreCompact uses stderr for context reminders; exit 2 blocks compaction during active work/full phases