Skip to content

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.sh
index 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 0
diff --git a/.cursor/hooks/before-mcp-github.sh b/.cursor/hooks/before-mcp-github.sh
index 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.sh
index 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.md
index 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-based
harnesses (Codex CLI, IDE extension, ChatGPT desktop app) discover the same
skills; when adding a skill, create it in `/.claude/skills/` and add a
diff --git a/scripts/agent-hooks/check-on-stop.sh b/scripts/agent-hooks/check-on-stop.sh
index 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; t
fi
# Resolve the repo root regardless of which agent invoked us.
-. "$(dirname "$0")/common.sh"
ROOT=$(resolve_repo_root)
cd "$ROOT" 2>/dev/null || exit 0
diff --git a/scripts/agent-hooks/common.sh b/scripts/agent-hooks/common.sh
index 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.sh
index 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 0
diff --git a/scripts/agent-hooks/git-guard.sh b/scripts/agent-hooks/git-guard.sh
index 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.sh
index 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 is
diff --git a/scripts/agent-hooks/no-strict-ignore-new-file.sh b/scripts/agent-hooks/no-strict-ignore-new-file.sh
index 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 0
diff --git a/scripts/agent-hooks/pr-template-blank.sh b/scripts/agent-hooks/pr-template-blank.sh
index 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.sh
index 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 0
case "$file" in
@@ -16,7 +19,6 @@ esac
dir=$(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 is
diff --git a/upcoming-release-notes/agent-hooks-missing-jq.md b/upcoming-release-notes/agent-hooks-missing-jq.md
new file mode 100644
index 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