Hooks Setup

iEvo Hooks Setup

Safe-mode caveat. Running Claude Code with --safe-mode or CLAUDE_CODE_SAFE_MODE=1 (v2.1.169) disables ALL customizations at startup, including hooks — none of the entries this skill configures fire in that mode. Completion notifications for a long /ievo:init run or a parallel security scan will silently not trigger; verify safe mode is off if you rely on these notifications.

Configure Claude Code lifecycle hooks that fire on iEvo pipeline events — so you can get notified when a long init finishes, when a security audit finds something RED, or when an evolution is captured.

Uses two Claude Code hook features (verified against v2.1.139 + v2.1.141 release notes):

• Exec-form args: string[] (v2.1.139+): spawns the command directly without a shell at the outer invocation — eliminates the shell-quoting injection surface when paths get interpolated into the matcher → args chain. (We still use sh -c "..." inside args for the date/mkdir/echo pipeline — that's intentional, and there's no user-controlled input in the inner shell string.)
• terminalSequence field on hook JSON output (v2.1.141+): emits desktop notifications, window titles, and bells without requiring a controlling terminal.

Hooks trigger on signal files that iEvo writes at well-known paths under .ievo/hooks/. Init, evo, and the security-auditor agent each write their respective signal file as a final step (added in v0.6.9 alongside this skill); this skill configures the matching PostToolUse Write(...) hooks.

Two complementary hook tiers — this skill vs. per-skill built-ins

This skill (/ievo:hooks-setup) is one of two hook tiers iEvo offers; they coexist and don't conflict:

• Session-level, opt-in (this skill). Writes durable entries into .claude/settings.json (project or global scope) that fire across every future session, with a full menu of notification styles: terminal bell, terminalSequence desktop popups (iTerm2/WezTerm), a custom script, the background-agents-complete Stop hook (Step 5.5), claude agents Notification hooks (Step 5.6), and the version-check SessionStart nudge (Step 5.7). Requires running this skill once and persists across sessions.
• Per-skill, zero-setup (built-in, v0.48.0+), skills only — not the sub-agents they may delegate to. evo/SKILL.md, security-check/SKILL.md, and init/SKILL.md each carry their own hooks: frontmatter field (Hooks in skills and agents) that prints a plain one-line completion message with no configuration at all, scoped to that skill's own lifecycle and cleaned up when it finishes. This does NOT cover evo's delegated path to the evolution sub-agent: plugin-shipped agents ignore hooks: frontmatter entirely (see agents/evolution.md's own frontmatter comment), so that agent's hooks: block never fires, on any platform, when the capture is delegated to it. They intentionally stay terminal-only (no osascript/notify-send popups) so they degrade identically on every platform; use this skill's Step 2 for a richer, popup-style notification on the same signal files. This tier is Claude-Code-only (issue #461) even where it does work: Codex loads hook config from .codex/hooks.json, [hooks] tables in .codex/config.toml, or a Codex plugin's bundled hooks/hooks.json — never from a skill's or agent's own frontmatter — so no matcher added to a hooks: frontmatter block, apply_patch included, can fire on Codex CLI or Codex Desktop. A Codex user, or anyone on the delegated-to-agent path on either platform, gets the same evolution-captured notification only via a PostToolUse entry configured through this skill's Step 5 (fires at the session level regardless of which component performed the write — but see this section's own "Known gap" note below: Step 5's template currently writes the path pattern into matcher rather than if, which the current hooks reference documents as invalid) or the equivalent Codex hooks-config entry: see references/codex-hooks.md § "Getting the evolution-captured notification on Codex".

Practical implications of the per-skill tier's scoping (neither is a bug, both follow directly from how skill/agent-scoped hooks work):

• evo's PostToolUse hook filters with the if field (if: "Write(.ievo/hooks/evolution-captured)"), not matcher — matcher only accepts tool names ("Write", "Edit|Write", or a bare regex), never a parenthesized path pattern like "Write(...)"; the path filter belongs in if, which uses full permission-rule syntax.
• Stop hooks (security-check, init) never take a matcher or if — those fields are silently ignored / never run on non-tool events, so the hook fires unconditionally whenever its carrying skill's turn ends, and the command itself must do the deciding.
• security-check's Stop hook is converted to SubagentStop when the skill runs inside a security-auditor sub-agent (the normal /ievo:init Step 8 path) — it fires once per candidate scanned, not once for the whole parallel batch. The batch-level "all scans done" signal is this skill's own Step 5.5 Stop hook, which is genuinely session-scoped and can see background_tasks across every dispatched sub-agent.

Known gap, not addressed here (ticket-link-pending): the matcher restriction above (tool names only, never a parenthesized Tool(pattern)) applies to every hook config format — session settings.json entries included, not just skill/agent frontmatter. Step 5's own template below predates this constraint and writes the full "Write(.ievo/hooks/<event>)" string directly into matcher, which the current hooks reference documents as invalid; the per-event if field is where that path pattern belongs instead. Fixing it also touches Step 6's dedup-by-matcher logic (today's three events share the tool name "Write" once matcher is corrected, so dedup would need to key on the if value instead) — out of scope for this docs-only pass; left as a follow-up.

Step 1: Ask the user which events to hook

Use AskUserQuestion (multiSelect: true) — let the user pick any combination of the three iEvo events:

Which iEvo pipeline events should fire hooks?
Options (multi-select):
- "init-complete"       — when /ievo:init finishes installing skills
- "security-red"        — when security-auditor returns a RED verdict
- "evolution-captured"  — when /ievo:evo captures a lesson overlay

If user picks nothing, do NOT exit yet — Steps 5.5, 5.6, and 5.7 below offer independent hook flows (a Stop hook, a claude agents Notification hook, and a SessionStart version-check nudge). Only exit once Step 5.7 is done, and only if Step 1, Step 5.5, Step 5.6, and Step 5.7 all produced zero hook entries.

Step 2: Ask for notification preference

How do you want to be notified when a selected event fires?
Options (single-select):
- "terminal-bell"     — ring the terminal bell (universal; works in every terminal)
- "terminal-sequence" — desktop notification via terminalSequence (requires iTerm2 / WezTerm / similar; v2.1.141+ Claude Code)
- "custom-script"     — run a custom script (you provide the absolute path)
- "none"              — no notification; only log to .ievo/log/hooks/events.log

If "custom-script" → follow-up AskUserQuestion for the absolute path. Validate it's a regular file AND executable (test -f "$path" && test -x "$path" — test -x alone returns true for executable directories, which would pass validation but fail at hook fire time); re-prompt or fall back to "none" on failure.

If "terminal-sequence" → follow-up AskUserQuestion for the terminal family:

Which terminal emulator do you use?
- "iTerm2"   — uses `]9;<msg>` escape sequence
- "WezTerm"  — uses `]777;notify;iEvo;<msg>` escape sequence
- "other"    — falls back to terminal-bell

Step 3: Ask for settings.json scope

Where should the hooks be written?
- "project"  — .claude/settings.json (recommended; commits with the repo)
- "global"   — ~/.claude/settings.json (applies to every Claude Code session for this user)

Step 4: Read the current settings.json

Read the target path (project or global from Step 3) using the Read tool. If the file doesn't exist, treat the current state as {}.

If the file exists and contains invalid JSON, halt with: "Existing settings.json is not valid JSON — fix the file manually before configuring hooks." Do NOT write — risk of clobbering manual edits.

Step 5: Build hook entries (one per selected event)

For each event the user selected in Step 1, construct one PostToolUse hook entry that matches on Write(.ievo/hooks/<event>). The matcher is the Write tool call writing to the iEvo-specific signal-file path; this is precise and portable (no broad-Bash-matcher false positives).

Important: per Claude Code's hooks reference, the terminalSequence field belongs in the hook command's JSON output (stdout), NOT as a static field in settings.json. The hook command emits {"terminalSequence": "<escape>"} to stdout; Claude Code reads stdout, parses the JSON, and emits the sequence through its own terminal write path (hooks run without a controlling terminal, so direct /dev/tty writes fail). Restricted to OSC 0/1/2/9/99/777 and BEL — values outside the allowlist are silently ignored.

Template per event (replace <event> with init-complete / security-red / evolution-captured; <msg> with the per-event string from the table below; <seq-printf> with the per-preference printf format from the second table):

{
  "matcher": "Write(.ievo/hooks/<event>)",
  "hooks": [
    {
      "type": "command",
      "args": ["sh", "-c", "mkdir -p .ievo/log/hooks && echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) <msg>\" >> .ievo/log/hooks/events.log && printf '{\"terminalSequence\":\"<seq-printf>\"}'"]
    }
  ]
}

The args pipeline does three things on every fire:

1. mkdir -p .ievo/log/hooks — idempotent, creates parent dirs if missing
2. echo "<ISO-8601 timestamp> <msg>" >> .ievo/log/hooks/events.log — append timestamped audit entry to a single rotating log file (one per project, NOT per-fire — easier to tail -f / grep)
3. printf '{"terminalSequence":"..."}' — emit JSON to stdout so Claude Code reads it and fires the notification

Per-event message (substitute for <msg>):

Per-preference <seq-printf> content (replace <msg> with the per-event message; escape characters are JSON-encoded inside the printf format so they round-trip through sh -c → printf → JSON parser):

Step 5.5: Optional — Stop hook for "all background agents complete"

Different mechanism from Steps 1–5. The signal-file hooks above are write-side PostToolUse matchers that fire when a Write call lands on a known path. The Stop hook is a read-side hook: Claude Code pipes a JSON object to the hook's stdin every time the main session is about to stop, and the hook decides whether to fire a notification. Claude Code v2.1.145+ (release notes) added background_tasks and session_crons fields to that JSON — the hook fires its notification only when both are empty, i.e. when all parallel subagents (e.g. security-auditor / repo-indexer dispatched by /ievo:init) have actually finished.

Step 5.5.1: Ask whether to configure

Configure background-agents-complete notification (read-side Stop hook)?
- "yes"  — write .ievo/hooks/scripts/on-stop.sh + register Stop hook entry
- "no"   — skip (you can re-run /ievo:hooks-setup later)

If "no" → skip to Step 5.6 (with whatever signal-file entries Step 5 built). The graceful "No hooks configured. Re-run /ievo:hooks-setup to pick events later." exit is deferred to Step 5.7.1, the final opt-in.

Step 5.5.2: Ask for notification command

Which notification to fire when all background agents complete?
- "macos"   — osascript -e 'display notification "..." with title "iEvo"' (macOS only; fires a real desktop notification independent of TTY)
- "linux"   — notify-send "iEvo" "..." (requires libnotify; freedesktop.org notification spec)
- "bell"    — printf '\a' (terminal BEL fallback; reliability depends on the terminal's handling of hook-process stdout)
- "custom"  — user-provided shell command (validated the same way as Step 2's custom-script path: `test -f "$path" && test -x "$path"` — regular file AND executable; `test -x` alone accepts directories which would exec-fail at hook fire time)

Step 5.5.3: Write the Stop hook script

Use the Write tool to create .ievo/hooks/scripts/on-stop.sh (Write tool creates parent dirs). The body is parameterised on the Step 5.5.2 choice — substitute <notify-cmd> with one of:

Script template:

#!/bin/sh
# iEvo Stop hook — fires a notification only when all background work is done.
# stdin: JSON from Claude Code (v2.1.145+ includes background_tasks + session_crons).
# Exit 0 always — this hook is informational, never blocks the turn. A blocking
# Stop hook is force-released after CLAUDE_CODE_STOP_HOOK_BLOCK_CAP consecutive
# blocks (default 8, v2.1.143+); iEvo's hook never blocks at all.
#
# Note: NO `set -e` — that would turn any per-line failure (full disk, EACCES
# on project root, jq absent, etc.) into a non-zero exit, contradicting the
# non-blocking guarantee. Each line that can fail is individually guarded
# with `|| true` or `2>/dev/null || ...` so the final `exit 0` is reachable
# always.

mkdir -p .ievo/log/hooks 2>/dev/null || true

input=$(cat)
# jq is a hard dependency of `gh`, which iEvo already requires; fall back to 0 if jq absent.
bg=$(printf '%s' "$input" | jq '.background_tasks | length' 2>/dev/null || echo 0)
cron=$(printf '%s' "$input" | jq '.session_crons | length' 2>/dev/null || echo 0)

printf '%s stop-hook bg=%s cron=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$bg" "$cron" \
  >> .ievo/log/hooks/events.log 2>/dev/null || true

if [ "$bg" = "0" ] && [ "$cron" = "0" ]; then
  <notify-cmd> || true
fi

exit 0

Then make it executable. Use Bash: chmod +x .ievo/hooks/scripts/on-stop.sh.

Field availability: On Claude Code <v2.1.145, background_tasks and session_crons are absent from the stdin JSON. jq '.background_tasks | length' returns 0 directly in that case (jq's null | length evaluates to 0 with exit code 0 — the || echo 0 guard does NOT fire on missing fields; it only fires when jq itself is unavailable or the input is unparseable JSON). Both counts become 0, so the notification fires on every Stop. Warn the user if claude --version (run via Bash in Step 5.5.3) returns a version below 2.1.145 — they can still install the hook, but it will fire on every stop instead of "all background agents done".

Step 5.5.4: Build the Stop hook entry

For Step 6's merge stage, build this entry (to be added to hooks.Stop[]):

{
  "hooks": [
    {
      "type": "command",
      "args": ["sh", ".ievo/hooks/scripts/on-stop.sh"]
    }
  ]
}

Stop hook entries don't have a matcher field — Claude Code calls every Stop hook on every stop, the script itself decides whether to act. Dedup at merge time by checking whether an existing entry has the same args array.

Step 5.5.5: Optional — feedback via additionalContext (v2.1.163+)

Claude Code v2.1.163+ (release notes) lets Stop and SubagentStop hooks also return hookSpecificOutput.additionalContext — a string injected back into the model's conversation, "to give Claude feedback and keep the turn going without being labeled a hook error." This is separate from the notification Steps 5.5.1–5.5.4 configure (sound/banner only, nothing reaches the model); Claude Code below v2.1.163 simply ignores the field. To report a one-line status alongside (or instead of) the notification, have the Step 5.5.3 script's success branch also print, after <notify-cmd>, a single line of JSON:

{"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":"iEvo: all background agents complete."}}

The four <notify-cmd> choices (osascript, notify-send, printf '\a', and a well-behaved custom command per Step 5.5.3's table) emit nothing to stdout on success, so this JSON line stays the hook's only stdout output — verify a custom notification command does the same before combining the two, since any stray stdout ahead of it would break the JSON parse.

Applies equally to SubagentStop output ("hookEventName":"SubagentStop") — relevant because security-check's own per-skill Stop hook (see "Two complementary hook tiers" above) converts to SubagentStop when it runs inside a parallel security-auditor sub-agent dispatch. This skill does not wire that up today (that hook ships with security-check/SKILL.md itself, not /ievo:hooks-setup) — noted here as a pointer for anyone extending it.

Step 5.6: Optional — Notification hook for claude agents background sessions

Different agent-dispatch model from Step 5.5 — read this scope note first. Step 5.5's Stop hook and this Notification hook are NOT interchangeable; they cover two genuinely different dispatch models:

• Step 5.5 (Stop hook) applies to Task-tool sub-agents dispatched within one session (e.g. the security-auditor / repo-indexer that /ievo:init fans out). It is read-side polling at session-stop: Claude Code hands the hook the current session's background_tasks/session_crons queues and the hook fires only when both are empty. It sees a single point in time and cannot tell "still running" apart from "blocked waiting on input".
• Step 5.6 (Notification hook) applies to background sessions launched with claude agents — separate sessions, not Task-tool sub-agents of the current one. Claude Code v2.1.198+ (release notes) fires the Notification hook per transition for these sessions, with a matcher that separates the actionable case from the informational one — the distinction the Stop hook's single "queue empty?" check cannot draw.

Keep Step 5.5 for in-session Task sub-agents; use Step 5.6 for claude agents background sessions. They can coexist.

Matcher values (Notification hook, v2.1.198+):

Audited against v2.1.195's hyphenated-matcher fix (release notes): hook matchers with hyphenated identifiers (e.g. code-reviewer, mcp__brave-search) now exact-match instead of substring-match — use mcp__brave-search__.* to match a whole hyphenated MCP server's tool family. Neither matcher this skill writes is hyphenated (agent_needs_input/agent_completed here; startup in Step 5.7; the Step 5 signal-file event names like init-complete sit inside a Write(...) argument, not the bare matcher value this fix changes — see the existing Known-gap note above), so this is a compatibility note, not a functional fix.

Step 5.6.1: Ask whether to configure

Configure claude-agents background-session notifications (Notification hook, requires Claude Code v2.1.198+)?
- "yes"  — register Notification hook entries for agent_needs_input / agent_completed
- "no"   — skip (you can re-run /ievo:hooks-setup later)

If "no" → skip to Step 5.7 (with whatever entries Steps 5 and 5.5 built). The graceful "No hooks configured" exit is deferred to Step 5.7.1, the final opt-in.

Run claude --version via Bash: if it is below v2.1.198, warn the user that the Notification matchers agent_needs_input/agent_completed are unavailable on their version — offer to skip, since the entries would never fire.

Step 5.6.2: Build the Notification hook entries

Register one entry per matcher under hooks.Notification[] (a top-level key alongside hooks.PostToolUse and hooks.Stop). Surface agent_needs_input more prominently than agent_completed: the first needs you now and the session is blocked until you act; the second is a status update you can glance at later.

macOS example (osascript) — the actionable entry plays a sound and titles itself "action needed"; the informational entry is a plain, silent banner:

{
  "matcher": "agent_needs_input",
  "hooks": [
    {
      "type": "command",
      "args": ["sh", "-c", "mkdir -p .ievo/log/hooks && echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) agent_needs_input\" >> .ievo/log/hooks/events.log && osascript -e 'display notification \"A claude agents session is waiting on your input\" with title \"iEvo — action needed\" sound name \"Ping\"' || true"]
    }
  ]
}

{
  "matcher": "agent_completed",
  "hooks": [
    {
      "type": "command",
      "args": ["sh", "-c", "mkdir -p .ievo/log/hooks && echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) agent_completed\" >> .ievo/log/hooks/events.log && osascript -e 'display notification \"A claude agents session finished\" with title \"iEvo\"' || true"]
    }
  ]
}

The prominence difference is deliberate: agent_needs_input carries a sound + an "action needed" title so it interrupts; agent_completed is a quiet banner (log line + plain notification, no sound). Linux equivalents keep the same split via notify-send urgency: notify-send -u critical "iEvo — action needed" "A claude agents session is waiting on your input" for agent_needs_input vs notify-send -u low "iEvo" "A claude agents session finished" for agent_completed. Both entries end with || true so a missing osascript/notify-send never turns the hook into a non-zero exit (the notification is best-effort; the log line is the durable record). As in Step 5, each args line first appends a timestamped entry to the shared .ievo/log/hooks/events.log.

Step 5.6.3: Merge the Notification entries

For Step 6, ensure hooks.Notification exists as an array (create if missing), then for each of the two entries dedup by matcher: if an entry with the same matcher (agent_needs_input / agent_completed) already exists in hooks.Notification, do not duplicate — print "Notification hook for <matcher> already configured; skipping. Edit settings.json manually to overwrite it." Otherwise append. The entries then flow through Step 7's confirmation and Step 8's apply like any other.

Step 5.7: Optional — SessionStart version-check nudge (iEvo behind latest)

A different trigger from every hook above. Steps 5 / 5.5 / 5.6 all fire on iEvo pipeline events (a signal-file Write, a session Stop, a claude agents transition). This one fires on session start and answers a different question: is the installed iEvo plugin behind the marketplace's latest version? It exists for users who keep native plugin auto-update off (third-party marketplaces default to off — see README § "Keep iEvo up to date"); users who enable auto-update don't need it, because Claude Code then updates iEvo at startup natively.

Mechanism (verified against the SessionStart hook reference, 2026-07-02):

• SessionStart is context-only — it cannot block or delay startup (exit code is ignored for flow control). A command hook's job is to optionally emit hookSpecificOutput.additionalContext, which is injected into the model's context before the first prompt. So the hook must be fast and fail-silent: any error (offline, missing tool, parse failure, up-to-date) emits nothing and exits 0.
• Throttle (required). SessionStart runs every session, so the script self-throttles the network call to ≤ once per 24h via a cache file (${XDG_CACHE_HOME:-$HOME/.cache}/ievo/version-check.json holding {checked_at, latest_version}). On a cache hit within 24h it uses the cached latest and makes no network call; the compare is a cheap local read, so the cache-hit path adds no measurable startup latency.
• Source of truth for "latest" is the marketplace manifest on the default branch — plugins[0].version in https://raw.githubusercontent.com/ievo-ai/skills/main/.claude-plugin/marketplace.json (a single unauthenticated GET; the once/day cache keeps well under GitHub's unauthenticated rate limit). "Installed" is .version from the plugin's own plugin.json.
• Other SessionStart return fields exist but are unused here (v2.1.152+, release notes): reloadSkills: true (re-scans skill directories so a hook-installed skill becomes usable the same session) and hookSpecificOutput.sessionTitle (sets the session title). Neither applies to a version-check nudge — noted for anyone extending this hook to also install/update skills or brand the session.

Step 5.7.1: Ask whether to configure

Configure a SessionStart version-check nudge (reminds you at most once/day when iEvo is behind latest)?
- "yes"  — write .ievo/hooks/scripts/version-check.sh + register a SessionStart hook entry
- "no"   — skip

If "no" → proceed to Step 6 with whatever entries Steps 5, 5.5, and 5.6 built. If all of Step 5, Step 5.5, Step 5.6, and Step 5.7 produced zero entries, exit gracefully with "No hooks configured. Re-run /ievo:hooks-setup to pick events later." and stop.

Recommend enabling native auto-update instead / as well. Tell the user the higher-leverage fix is to turn on native plugin auto-update (/plugin → Marketplaces → ievo-skills → Enable auto-update); this nudge is the fallback for when they deliberately keep it off. Both can coexist — if auto-update is on, the installed version stays current and the nudge simply never fires.

Step 5.7.2: Resolve and bake the plugin.json path

The generated script reads the installed version from the plugin's plugin.json. A hook in the user's settings.json does not get CLAUDE_PLUGIN_ROOT set at fire time (that variable is only populated for hooks shipped inside a plugin), so resolve the absolute path now, at setup time, while this skill is running inside the plugin, and bake it into the script as a string literal.

Run via Bash (both allowed by this skill's allowed-tools):

test -f "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" && echo "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json"

Use the printed absolute path as <plugin-json-abs-path> in the template below. If the test fails (empty output), the plugin root couldn't be resolved — tell the user the nudge can't be configured right now and skip to Step 6 (do not write a script with an unresolved path).

Step 5.7.3: Write the version-check script

Use the Write tool to create .ievo/hooks/scripts/version-check.sh (Write creates parent dirs). Substitute <plugin-json-abs-path> with the Step 5.7.2 result — a write-time placeholder, embedded as a literal, NOT a runtime $VAR:

#!/bin/sh
# iEvo SessionStart version-check nudge — reminds you when the installed iEvo
# plugin is behind the marketplace's latest version.
#
# CONTRACT (see hooks-setup/SKILL.md Step 5.7):
#   - Fail-silent: any error or "up to date" => emit nothing, exit 0. SessionStart
#     is context-only and cannot block startup; this hook never delays a session.
#   - Network throttled to <= once / 24h via a cache file. Cache-hit path makes
#     NO network call and adds no measurable latency.
#   - NO `set -e`: every fallible step is individually guarded so `exit 0` is
#     always reachable and a partial failure never surfaces to the user.
#   - Untrusted input: `installed`/`latest` (local plugin.json, but `latest` can
#     come from a network fetch or a cache file, either tamperable) are rejected
#     unless they're a strict X.Y.Z SemVer form BEFORE being cached, compared, or
#     placed in the SessionStart additionalContext the model reads as instructions.
#     Output JSON is built with `jq -n`/`--arg`, never raw string interpolation.

MARKETPLACE_URL="https://raw.githubusercontent.com/ievo-ai/skills/main/.claude-plugin/marketplace.json"
CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/ievo"
CACHE="$CACHE_DIR/version-check.json"
TTL=86400  # 24h, in seconds

# Prefer a runtime CLAUDE_PLUGIN_ROOT if present; else the path baked at setup.
PLUGIN_JSON="${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/.claude-plugin/plugin.json}"
[ -n "$PLUGIN_JSON" ] && [ -f "$PLUGIN_JSON" ] || PLUGIN_JSON="<plugin-json-abs-path>"

# Strict X.Y.Z SemVer gate (this repo's own version convention — no
# pre-release/build metadata). Reject empty, any byte outside [0-9.], a
# leading/trailing/doubled dot, or a component count other than 3.
is_semver() {
  case "$1" in
    ""|*[!0-9.]*|.*|*.|*..*) return 1 ;;
  esac
  case "$1" in
    *.*.*.*) return 1 ;;
    *.*.*) return 0 ;;
    *) return 1 ;;
  esac
}

# jq is a hard dependency of gh, which iEvo already requires; bail silently if absent.
installed=$(jq -r '.version // empty' "$PLUGIN_JSON" 2>/dev/null) || exit 0
is_semver "$installed" || exit 0

now=$(date +%s 2>/dev/null) || exit 0
case "$now" in ""|*[!0-9]*) exit 0 ;; esac

latest=""
# Cache hit within TTL -> use cached latest, NO network call.
if [ -f "$CACHE" ]; then
  checked_at=$(jq -r '.checked_at // 0' "$CACHE" 2>/dev/null || echo 0)
  case "$checked_at" in ""|*[!0-9]*) checked_at=0 ;; esac
  age=$((now - checked_at))
  if [ "$age" -ge 0 ] && [ "$age" -lt "$TTL" ]; then
    latest=$(jq -r '.latest_version // empty' "$CACHE" 2>/dev/null || echo "")
    is_semver "$latest" || latest=""
  fi
fi

# Cache miss / stale -> one throttled network fetch, then refresh the cache.
if [ -z "$latest" ]; then
  latest=$(curl -fsS --max-time 5 "$MARKETPLACE_URL" 2>/dev/null \
    | jq -r '.plugins[0].version // empty' 2>/dev/null || echo "")
  is_semver "$latest" || exit 0
  mkdir -p "$CACHE_DIR" 2>/dev/null || true
  jq -n --argjson checked_at "$now" --arg latest_version "$latest" \
    '{checked_at: $checked_at, latest_version: $latest_version}' \
    > "$CACHE" 2>/dev/null || true
fi

[ -n "$latest" ] || exit 0

# Behind? Numeric semver compare (installed < latest) in awk — portable, no `sort -V`
# (macOS BSD sort lacked -V for years). Prints 1 iff installed is strictly older.
behind=$(awk -v a="$installed" -v b="$latest" 'BEGIN{
  na=split(a,x,"."); nb=split(b,y,".");
  n=(na>nb)?na:nb;
  for(i=1;i<=n;i++){ai=(i<=na)?x[i]+0:0; bi=(i<=nb)?y[i]+0:0;
    if(ai<bi){print 1; exit} if(ai>bi){print 0; exit}}
  print 0}' 2>/dev/null || echo 0)

[ "$behind" = "1" ] || exit 0

# Behind -> inject a nudge as SessionStart additionalContext. The message is
# read by the model, which relays it to the user. Built with `jq -n --arg` (a
# real JSON encoder), not string interpolation — installed/latest are already
# semver-validated above, but the encoder is the actual guarantee, not an
# unenforced formatting assumption.
msg="iEvo plugin update available: installed ${installed}, latest ${latest}. Tell the user they can enable native plugin auto-update (/plugin -> Marketplaces -> ievo-skills -> Enable auto-update) so Claude Code keeps iEvo current automatically, or update now by re-running /plugin install ievo@ievo-skills, then /reload-plugins."
jq -n --arg msg "$msg" '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":$msg}}' 2>/dev/null
exit 0

Then make it executable via Bash: chmod +x .ievo/hooks/scripts/version-check.sh.

Step 5.7.4: Build the SessionStart hook entry

For Step 6's merge stage, build this entry (added to hooks.SessionStart[]). Matcher startup targets brand-new sessions — the least-noisy signal; resume/clear/compact are deliberately excluded so a mid-work compaction never injects the nudge:

{
  "matcher": "startup",
  "hooks": [
    {
      "type": "command",
      "args": ["sh", ".ievo/hooks/scripts/version-check.sh"]
    }
  ]
}

Dedup at merge time by checking whether an existing hooks.SessionStart entry has both the same matcher (startup) and the same inner args.

Scope note (like the Stop hook): the check is machine-level (the plugin install and the ~/.cache/ievo throttle file are per-user, not per-project), so global scope suits it best — recommend it if the user chose project in Step 3. The generated version-check.sh lives at .ievo/hooks/scripts/version-check.sh, which /ievo:init Step 10's .ievo/hooks/scripts/* line keeps gitignored (Step 10's negations carve out only the five evo-auto-enable hook/dependency files, by name — never this file), so a project-scoped SessionStart entry would reference a script teammates don't have — Claude Code logs a cosmetic hook-launch error (SessionStart is non-blocking, so session flow is unaffected). Each teammate re-runs /ievo:hooks-setup once per clone to write their own copy.

Step 6: Merge entries into settings.json

Use the Read + Edit tools (NOT shell-based JSON edits — preserves existing comments and key order on Claude Code's tolerant JSON parser). Pseudo-procedure:

1. Read current settings.json (from Step 4, or {} if absent).
2. For signal-file entries (Step 5): ensure hooks.PostToolUse exists as an array; create if missing. For each new entry, check if matcher already exists in hooks.PostToolUse. If yes, do not duplicate — print "Hook for <event> already configured; skipping. Edit settings.json manually to overwrite it." Otherwise append.
3. For the Stop hook entry (Step 5.5, if Step 5.5.1 = "yes"): ensure hooks.Stop exists as an array; create if missing. Stop hook entries have no matcher, so dedup by comparing the inner hooks[0].args array — if an existing entry's args matches ["sh", ".ievo/hooks/scripts/on-stop.sh"], skip with "Stop hook already configured; skipping." Otherwise append.
4. For the SessionStart entry (Step 5.7, if Step 5.7.1 = "yes"): ensure hooks.SessionStart exists as an array; create if missing. Dedup on both matcher (startup) and inner hooks[0].args (["sh", ".ievo/hooks/scripts/version-check.sh"]) — if a matching entry exists, skip with "Version-check nudge already configured; skipping." Otherwise append.

Step 7: Confirm with the user

Display the final merged config (the entries being added, not the whole file) and ask:

The following hook entries will be added to <.claude/settings.json | ~/.claude/settings.json — substitute the actual path from Step 3 scope>:

[display new entries]

Existing hooks preserved. Proceed?
- "yes"  — write the file
- "no"   — abort; nothing written

Step 8: Apply the merged settings.json

If the file existed in Step 4: use the Edit tool to apply the new hook entries — preserves existing comments, key order, and unrelated entries (Claude Code's settings.json parser is tolerant of comments). Step 6's "Read + Edit" guidance applies here for consistency.

If the file did NOT exist in Step 4: use the Write tool to create it (Edit requires the file to exist first). The mkdir -p .ievo/log/hooks && prefix in the hook args handles directory creation lazily on first fire — no separate Step-8 dir-creation needed (Write tool would create parent dirs anyway, but the hook itself runs without a guaranteed cwd context).

Gitignore note: /ievo:init Step 10 already adds .ievo/log/ plus an eight-line, negation-capable .ievo/hooks/ block — everything under .ievo/hooks/ ignored, with exactly the five hook/dependency files /ievo:evo-auto-enable Step 3.5.1 commits carved back out (skills#446, widened in skills#552). If init was run before hooks-setup (the typical install path), no further gitignore action is needed: this skill's own on-stop.sh and version-check.sh are already covered by that block's .ievo/hooks/scripts/* line.

Never write a blanket .ievo/hooks/ line here either. git cannot re-include a file whose parent directory is excluded ("you cannot re-include a file if a parent directory of that file is excluded"), and a bare directory-form entry wins over any negation that follows it — so appending one would silently re-ignore the files a previous /ievo:evo-auto-enable or /ievo:init run had already carved out, reintroducing the exact clean-clone exit 127 those negations exist to prevent. The block below is byte-identical to the one /ievo:init Step 10 and evo-auto-enable/SKILL.md Step 3.5.1 write, so all th

…(truncated)