[Bug]: PR #2713's EXECUTE_COMMAND directive emits correctly but is never executed in pure-Claude-Code invocations

[thlandgraf]

Follow-up to #2688

PR #2713 (shipped in v0.8.15) restructured the after_/before_ hook dispatch in core command SKILLs with a ## Mandatory Post-Execution Hooks H2 + directive language + ## Done When checklist. Empirically, the emission half works: the agent now reliably emits

EXECUTE_COMMAND: my-extension.my-hook-target

in its response stream during /speckit-plan invocations on v0.8.15+.

The execution half does not work in pure Claude Code (no specify-CLI wrapper). Nothing in Claude Code's slash-command runtime watches the agent's stdout for EXECUTE_COMMAND: lines and dispatches them. The agent emits the directive, waits ~6 seconds, and returns control without ever invoking the underlying hook script. The result is functionally identical to #2688's original failure mode (the registered hook does not run) — just with a more visible symptom (the directive shows in the agent's output, so the user can SEE that something should have happened).

Reproduction

The repro is structural and doesn't depend on any particular extension. A minimal stub is enough:

1. specify init . --integration claude on spec-kit ≥ 0.8.15.
2. Hand-create a minimal local extension at .specify/extensions/repro/:
   • extension.yml:

     schema_version: "1.0"
     extension:
       id: repro
       name: "Hook Dispatch Repro"
       version: "0.0.1"
     requires:
       speckit_version: ">=0.8.15"
     provides:
       commands:
         - name: repro.before-plan
           file: commands/before-plan.md
           description: "Hook dispatch repro target."
     hooks:
       before_plan:
         command: repro.before-plan
         optional: false
         description: "Should run before /speckit-plan."

   • commands/before-plan.md: any content; the command's body never runs in this repro so the contents don't matter beyond being present.
3. Run specify extension add --dev .specify/extensions/repro so the hook is registered in .specify/extensions.yml and a SKILL is generated under .claude/skills/repro-before-plan/.
4. From inside Claude Code (NOT via specify run or any CLI wrapper), invoke /speckit-plan against any feature directory.
5. Observe: the agent emits the H2 block with EXECUTE_COMMAND: repro.before-plan correctly, then stalls. The hook command body never runs. /speckit-plan then proceeds (or fails, depending on what the hook was supposed to do) as if no hook were registered.

Empirical log grep on a real session against a before_plan hook that's supposed to write a file:

grep -E 'EXECUTE_COMMAND|tool_dispatch_start tool=Bash.*<hook-script>' debug.log
# → emits EXECUTE_COMMAND line, zero matching Bash dispatches

Why this is distinct from #2104

#2104 asked for auto-run as a new feature and was closed because the workflow engine is the right answer for deterministic dispatch. This issue is narrower: the existing best-effort dispatch contract documented in PR #2713 doesn't actually dispatch in the most common Claude Code invocation pattern. I am not asking for auto-run; I am asking that the contract the SKILL describes actually completes in the documented happy path.

Hypothesis

The v0.8.15 SKILL implicitly assumes a platform-level stdout watcher that parses EXECUTE_COMMAND: lines. That watcher exists when specify is the orchestrator (auto_execute_hooks: true in .specify/extensions.yml is presumably the flag that activates it). It does not exist when the agent's slash command is invoked directly in Claude Code, which is the default invocation pattern for ~all extension users.

Proposed Resolution Paths (one of)

1. Strengthen the SKILL contract. Add an explicit instruction immediately after the EXECUTE_COMMAND: directive emission: "You MUST then invoke the Bash tool with the underlying hook script path to actually execute the command. Emitting the directive alone is not sufficient — the directive is a ceremony signal, not a dispatcher." This is the lowest-cost fix and makes the contract self-contained.

2. Document the prerequisite explicitly. Add a note to extensions/EXTENSION-API-REFERENCE.md that EXECUTE_COMMAND: directives require an orchestrator process (e.g. specify run) and will not be dispatched by pure Claude Code slash invocations. Extension authors can then advertise the dispatch limitation in their READMEs.

3. Ship a Claude Code hook. Bundle a small settings.json hook (CLAUDE_CODE_HOOKS_DIR) that watches assistant message text for EXECUTE_COMMAND: <command> lines and dispatches them via the Bash tool — closing the gap at the platform level without depending on the agent doing two things.

(1) is the cleanest from an extension-author perspective. (3) is the most robust but adds non-trivial machinery.

Component

Specify CLI (commands, templates) / Extensions / Agent Integration

AI Agent (if applicable)

Claude Code (Claude Opus 4.7) — but pattern is structural; same failure mode is likely with Cursor / Codex / Gemini CLI when invoked directly without a spec-kit CLI orchestrator.

Use Cases

Every extension that registers an after_* or before_* hook with optional: false and expects it to fire during agent-direct slash invocations. Concrete classes:

• Spec-format adapters whose before_plan materializes a transient spec.md from a non-default spec store, so /speckit-plan has something to read; without dispatch, /speckit-plan has nothing to read and silently bails.
• Enterprise linting / AC-format validation pre-implement gates (mentioned in [Feature]: Wire 'after_specify' and 'after_plan' hook events into command templates (following PR #1702) #1788).
• Pre-implementation policy / compliance checks.

References

• [Bug]: after_specify / after_clarify / before_implement hook dispatch silently skipped in interactive slash-command path #2688 — the original bug; PR fix: promote post-execution hook dispatch to H2 with directive language #2713's fix closed the emission half
• PR fix: promote post-execution hook dispatch to H2 with directive language #2713 — the structural restructuring that landed in v0.8.15
• [Feature]: Automatically run extensions #2104 — closed feature request for auto-run; relevant context, not a duplicate
• [Feature]: Wire 'after_specify' and 'after_plan' hook events into command templates (following PR #1702) #1788 — original hook feature request

[thlandgraf]

Empirical refinement: dispatch reliability splits along an output-consumption axis

Continuing the same smoke session that surfaced the original report, I observed that not all hook directives are silently skipped — the failure mode appears to track whether the agent has to read the hook's result to decide what to do next.

Concretely, against an extension manifest that registered five optional: false hooks (before_plan → materialize-spec, after_plan → cleanup-spec, before_tasks → materialize-spec, before_implement → gate, after_implement → post-implement-transition), invoked through the full /speckit-plan → /speckit-tasks → /speckit-implement chain in pure Claude Code:

Hook	Class	Outcome
before_implement → gate	Output-consuming (returns JSON listing which entities pass + need transition)	Dispatched. Script actually ran. Status transitions of 62 entities (16 Features + 46 Requirements) from approved → in-development confirmed on disk.
before_plan → materialize-spec	Side-effect only	Not dispatched. EXECUTE_COMMAND emitted, no Bash invocation, no spec.md written.
after_plan → cleanup-spec	Side-effect only	Not dispatched.
before_tasks → materialize-spec	Side-effect only	Not dispatched (didn't matter — earlier manual materialize left spec.md in place).
after_implement → post-implement-transition	Side-effect only	Not dispatched. Entities stayed at in-development; no advance to under-test.

The pattern: hooks whose output the agent must read (to decide whether to proceed, or what to do next) get actually invoked — presumably because the agent realizes the directive-emission isn't enough when it needs an answer back. Hooks that are pure side-effect (write a file, transition state, no observable signal returned to the agent) get the emit-and-move-on treatment.

This refinement narrows the practical scope of the bug: extension authors whose hooks are pure side-effects (the majority of the use cases listed earlier in this issue, including the materialize-spec / cleanup-spec cleanup-on-side flow) hit the dispatch gap; extension authors whose hooks return information the agent needs (gates, classification queries, status reports) get reliable execution.

It also suggests an additional Resolution Path option for the issue body:

4. Make all hook commands return a small JSON envelope on stdout, and update the SKILL contract to require the agent to consume that JSON before proceeding. This converts every hook into an "output-consuming" hook from the agent's perspective and would, based on this empirical evidence, get them dispatched reliably under the current v0.8.15 SKILL structure — without requiring (1) per-author SKILL discipline, (2) prerequisite documentation, or (3) a Claude Code hook watcher.

The repro from the original report still stands; the additional finding is just that the failure rate within the issue's scope is non-uniform and corresponds to hook semantics.