A local-first personal finance app
[AI] Fail agent hooks with an actionable error when jq is missing (#8651)
Matiss Janis Aboltinsda8eb795391d
diff --git a/.cursor/hooks/after-file-edit.sh b/.cursor/hooks/after-file-edit.shindex d1b5304eab..ef7b55e314 100755--- a/.cursor/hooks/after-file-edit.sh+++ b/.cursor/hooks/after-file-edit.sh@@ -7,6 +7,13 @@# (no @ts-strict-ignore, one component per file) are advisory, not enforced.# Cursor input on stdin: { file_path, edits, ... }.+# jq is a hard prerequisite. afterFileEdit cannot block, so surface an advisory+# instead of silently skipping the formatting and new-file checks.+command -v jq >/dev/null 2>&1 || {+ echo "[actual] Advisory: the agent hooks require jq, which was not found on PATH — formatting and new-file checks were skipped. Install jq (https://jqlang.org)."+ exit 0+}+input=$(cat)file=$(printf '%s' "$input" | jq -r '.file_path // empty')[ -n "$file" ] && [ -f "$file" ] || exit 0diff --git a/.cursor/hooks/before-mcp-github.sh b/.cursor/hooks/before-mcp-github.shindex 25fb943ae6..d62e29a66e 100755--- a/.cursor/hooks/before-mcp-github.sh+++ b/.cursor/hooks/before-mcp-github.sh@@ -8,6 +8,13 @@# Cursor input on stdin: { tool_name, tool_input, ... }. Output on stdout:# { permission: "allow" | "deny", userMessage, agentMessage }.+# jq is a hard prerequisite — even deny() below needs it to build JSON — so+# fail closed with a static deny instead of emitting nothing at all.+command -v jq >/dev/null 2>&1 || {+ printf '%s\n' '{"permission":"deny","userMessage":"Blocked by repo policy","agentMessage":"The agent hooks require jq, which was not found on PATH. Install jq (https://jqlang.org) and retry."}'+ exit 0+}+input=$(cat)# `CDPATH= cd` is an intentional empty-env prefix (not an assignment); silence the# SC1007 false positive shellcheck raises for it.diff --git a/.cursor/hooks/guard-shell.sh b/.cursor/hooks/guard-shell.shindex 0cfe0b731b..1f220bc611 100755--- a/.cursor/hooks/guard-shell.sh+++ b/.cursor/hooks/guard-shell.sh@@ -5,6 +5,13 @@# scripts/agent-hooks/git-guard.sh. Cursor input on stdin: { command, cwd, ... }.# Output on stdout: { permission: "allow" | "deny", userMessage, agentMessage }.+# jq is a hard prerequisite — even deny() below needs it to build JSON — so+# fail closed with a static deny instead of emitting nothing at all.+command -v jq >/dev/null 2>&1 || {+ printf '%s\n' '{"permission":"deny","userMessage":"Blocked by repo policy","agentMessage":"The agent hooks require jq, which was not found on PATH. Install jq (https://jqlang.org) and retry."}'+ exit 0+}+input=$(cat)ROOT=$(CDPATH= cd "$(dirname "$0")/../.." && pwd)diff --git a/AGENTS.md b/AGENTS.mdindex 1ba953c64a..033f631880 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -348,7 +348,8 @@ describe('ComponentName', () => {- `/.oxlintrc.json` - Lint rules (oxlint); `/.oxfmtrc.json` - formatting (oxfmt)- `/.nano-staged.json` - pre-commit format/lint config (run via Husky)- `/.claude/settings.json`, `/.codex/config.toml`, `/.cursor/hooks.json` - agent- hook wiring; shared scripts live in `/scripts/agent-hooks/`+ hook wiring; shared scripts live in `/scripts/agent-hooks/` and require `jq`+ on PATH (a missing `jq` fails the hooks with an install message)- `/.agents/skills/` - symlink mirror of `/.claude/skills/` so Codex-basedharnesses (Codex CLI, IDE extension, ChatGPT desktop app) discover the sameskills; when adding a skill, create it in `/.claude/skills/` and add adiff --git a/scripts/agent-hooks/check-on-stop.sh b/scripts/agent-hooks/check-on-stop.shindex 6923661e07..0b37ec8bce 100755--- a/scripts/agent-hooks/check-on-stop.sh+++ b/scripts/agent-hooks/check-on-stop.sh@@ -7,6 +7,9 @@# Adapted from a suggestion by @StephenBrown2 on PR #8089.set -uo pipefail+. "$(dirname "$0")/common.sh"+require_jq+# Read the hook payload (Claude provides stop_hook_active to prevent loops).payload=$(cat 2>/dev/null || true)if printf '%s' "$payload" | jq -e '.stop_hook_active == true' >/dev/null 2>&1; then@@ -14,7 +17,6 @@ if printf '%s' "$payload" | jq -e '.stop_hook_active == true' >/dev/null 2>&1; tfi# Resolve the repo root regardless of which agent invoked us.-. "$(dirname "$0")/common.sh"ROOT=$(resolve_repo_root)cd "$ROOT" 2>/dev/null || exit 0diff --git a/scripts/agent-hooks/common.sh b/scripts/agent-hooks/common.shindex 7c05ba556d..1656b0b943 100644--- a/scripts/agent-hooks/common.sh+++ b/scripts/agent-hooks/common.sh@@ -1,6 +1,23 @@#!/bin/sh# Shared helpers for the agent-hook scripts. Source this file; don't execute it.+# Every hook parses its stdin payload with jq — a hard prerequisite. Call this+# before the first jq use so a missing jq fails with an actionable message,+# distinct from a malformed-payload error. PreToolUse hooks get a "Blocked:"+# message (exit 2 blocks the call); PostToolUse hooks pass "advisory" — the+# tool call already ran, so the message reports the skipped hook instead of+# claiming a block. Exit 2 stays in both modes: it is the only exit code that+# feeds stderr back to the agent rather than dropping it.+require_jq() {+ command -v jq >/dev/null 2>&1 && return 0+ if [ "${1:-}" = advisory ]; then+ echo "Agent hook skipped: 'jq' is required but was not found on PATH. Install jq (https://jqlang.org). (scripts/agent-hooks/${0##*/})" >&2+ else+ echo "Blocked: the agent hooks require 'jq', which was not found on PATH. Install jq (https://jqlang.org) and retry. (scripts/agent-hooks/${0##*/})" >&2+ fi+ exit 2+}+# Resolve the repo root regardless of which agent invoked the hook.# Optional $1: a directory hint for the `git` fallback (e.g. an edited file's dir).resolve_repo_root() {diff --git a/scripts/agent-hooks/format-edited-file.sh b/scripts/agent-hooks/format-edited-file.shindex 09fbd00de4..9dfe8bf948 100755--- a/scripts/agent-hooks/format-edited-file.sh+++ b/scripts/agent-hooks/format-edited-file.sh@@ -8,11 +8,13 @@# `--type-aware` is intentionally skipped here to keep the edit loop fast; the# type-aware pass still runs at commit time via nano-staged.+. "$(dirname "$0")/common.sh"+require_jq advisory+file=$(jq -r '.tool_input.file_path // empty')[ -n "$file" ] && [ -f "$file" ] || exit 0# Resolve the repo root regardless of which agent invoked us.-. "$(dirname "$0")/common.sh"ROOT=$(resolve_repo_root "$(dirname "$file")")BIN="$ROOT/node_modules/.bin"[ -x "$BIN/oxfmt" ] || exit 0diff --git a/scripts/agent-hooks/git-guard.sh b/scripts/agent-hooks/git-guard.shindex cfd5006c4a..199369966c 100755--- a/scripts/agent-hooks/git-guard.sh+++ b/scripts/agent-hooks/git-guard.sh@@ -18,6 +18,11 @@ block() {exit 2}+# A missing jq gets its own actionable block, distinct from the+# malformed-payload block below.+. "$(dirname "$0")/common.sh"+require_jq+# Fail closed: a malformed payload (jq parse failure) blocks rather than allows.cmd=$(jq -r '.tool_input.command // empty' 2>/dev/null) ||block "Blocked: could not parse the hook payload (.tool_input.command)."diff --git a/scripts/agent-hooks/github-comment-style.sh b/scripts/agent-hooks/github-comment-style.shindex 6a5f9019f4..01b1e5488a 100755--- a/scripts/agent-hooks/github-comment-style.sh+++ b/scripts/agent-hooks/github-comment-style.sh@@ -16,6 +16,11 @@ block() {exit 2}+# A missing jq gets its own actionable block, distinct from the+# malformed-payload block below.+. "$(dirname "$0")/common.sh"+require_jq+input=$(cat)# 🤖 = U+1F916, UTF-8 F0 9F A4 96. Build it from raw bytes so the prefix check isdiff --git a/scripts/agent-hooks/no-strict-ignore-new-file.sh b/scripts/agent-hooks/no-strict-ignore-new-file.shindex 71ef5ee7e4..1d264964b0 100755--- a/scripts/agent-hooks/no-strict-ignore-new-file.sh+++ b/scripts/agent-hooks/no-strict-ignore-new-file.sh@@ -7,6 +7,9 @@# contains `// @ts-strict-ignore`. Existing files (241 of them) are grandfathered# automatically because this only fires when the target path does not yet exist.+. "$(dirname "$0")/common.sh"+require_jq+input=$(cat)file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')[ -n "$file" ] || exit 0diff --git a/scripts/agent-hooks/pr-template-blank.sh b/scripts/agent-hooks/pr-template-blank.shindex 332ade1bfb..f7b029aba8 100755--- a/scripts/agent-hooks/pr-template-blank.sh+++ b/scripts/agent-hooks/pr-template-blank.sh@@ -20,8 +20,12 @@ block() {input=$(cat)-# Resolve the repo root regardless of which agent invoked us, then the template.. "$(dirname "$0")/common.sh"+# A missing jq fails closed here; the fail-open below is only for payloads jq+# itself can't make sense of.+require_jq++# Resolve the repo root regardless of which agent invoked us, then the template.ROOT=$(resolve_repo_root)template="$ROOT/.github/PULL_REQUEST_TEMPLATE.md"diff --git a/scripts/agent-hooks/prefer-one-component.sh b/scripts/agent-hooks/prefer-one-component.shindex 951120c144..995f91275a 100755--- a/scripts/agent-hooks/prefer-one-component.sh+++ b/scripts/agent-hooks/prefer-one-component.sh@@ -6,6 +6,9 @@# (skipped if already tracked by git), and this never touches `yarn lint`, so# react/no-multi-comp stays out of .oxlintrc.json.+. "$(dirname "$0")/common.sh"+require_jq advisory+file=$(jq -r '.tool_input.file_path // empty')[ -n "$file" ] && [ -f "$file" ] || exit 0case "$file" in@@ -16,7 +19,6 @@ esacdir=$(dirname "$file")# Resolve the repo root regardless of which agent invoked us.-. "$(dirname "$0")/common.sh"ROOT=$(resolve_repo_root "$dir")# Normalize to an absolute + repo-root-relative path so the git pathspec isdiff --git a/upcoming-release-notes/agent-hooks-missing-jq.md b/upcoming-release-notes/agent-hooks-missing-jq.mdnew file mode 100644index 0000000000..b310ea2bae--- /dev/null+++ b/upcoming-release-notes/agent-hooks-missing-jq.md@@ -0,0 +1,6 @@+---+category: Maintenance+authors: [MatissJanis]+---++Fix agent hook scripts to show a clear, actionable error when jq is missing instead of a misleading parse error or a silent skip