Plugin hooks.json entries using exec form (command + args array) are silently ignored

This is a good bug to keep framed as a validation/evidence problem, not just a command parser mismatch.

The risky behavior is the silent drop: from the plugin author's view, the hook is enabled, the config is present, and the session continues, but the runtime has no hook execution record. That makes it hard for a plugin to know whether its safety/audit/control hook actually ran.

A regression shape I would want for the fix:

plugin hook declared in exec form with command + args
plugin root path contains spaces
SessionStart fires
runtime emits a hook_attempt record with hook id, resolved command/args, status, exit code or validation error
if exec form is unsupported, install/enable fails or warns before the session starts
string form and exec form produce equivalent event coverage

The invariant is: a declared hook should end in one of three observable states — executed, explicitly skipped by policy, or rejected as invalid. It should not disappear into the transcript gap between "plugin enabled" and "nothing happened."

From adjacent AgentFolio/SATP work, the portable lesson is that tool/hook authority and execution evidence should be linked but separate. A minimal receipt for hooks could be as small as:

plugin_id
hook_id
event_name
resolved_command_hash
status
started_at
completed_at
stderr_or_validation_ref

Then plugin authors and downstream auditors can distinguish "the hook ran and allowed the event" from "the hook was never invoked." That distinction matters most for security hooks, but it also makes ordinary plugin debugging much less ambiguous.

Boundary note: architecture/testing feedback only. I did not reproduce this report or validate Claude Code internals, Windows behavior, the polygraph plugin, implementation correctness, security impact, or production readiness.

Agreed — the validation/evidence framing is the right one. The parser mismatch is incidental; the defect that actually cost debugging time is that a declared hook can end in a fourth, unobservable state.

One more data point supporting the "rejected as invalid before the session" layer: claude plugin validate passes an exec-form hooks/hooks.json today (2.1.59) with no hook-related warning — so the invalid-for-this-runtime config survives every checkpoint (validate → install → enable → SessionStart) with zero signal at each. Repro:

{ "hooks": { "SessionStart": [ { "hooks": [
  { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/x.mjs", "SessionStart"], "timeout": 5 }
] } ] } }

validate → "Validation passed" (only an unrelated author warning); session runs; hook never executes; nothing in --debug.

Your three-observable-states invariant (executed / explicitly skipped / rejected-as-invalid) would have surfaced this in seconds instead of requiring a bisection of the hook config against a working plugin's format. The minimal hook-receipt shape you sketch would also cover the adjacent failure modes we can't currently distinguish from the outside: matcher didn't match, command spawn failed, timeout killed it, or config was silently dropped — today all four look identical to a plugin author (nothing happened).

For what it's worth we hit this while building a plugin whose whole premise is exactly that distinction (evidence of execution vs. absence of evidence), which made the irony sharp. Happy to share full probe transcripts (Windows 11, 2.1.59, string-form vs exec-form side-by-side) if useful.

I couldn't reproduce this on 2.1.233 (Linux): a plugin hooks/hooks.json SessionStart entry in exec form — { "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/entry.mjs", "SessionStart"], "timeout": 5 } — fires correctly on claude -p, with ${CLAUDE_PLUGIN_ROOT} substituted per-argument.

The explanation is version skew: you were on 2.1.59, and the exec form (args array) for hooks was added in 2.1.139 — see the changelog ("Added hook args: string[] field (exec form) that spawns the command directly without a shell"). On versions before that, the args field wasn't recognized, which matches the silent no-op you saw.

Please update (claude update) and exec form should work as the plugins reference describes. Closing — reply here if it still doesn't work on a current version and we'll reopen.

🤖 Generated with Claude Code