feat: first-class agent-native runtime hooks for integrations

[kanfil]

🎯 Problem & Motivation

While Spec Kit excels at scaffolding commands and prompt templates during specify init, there was previously no first-class mechanism for event-driven execution natively tied to AI coding agents in upstream.

This PR introduces an agent-native runtime events layer that bridges Spec Kit directly to agent lifecycle events (canonical snake_case names: session_start, pre_tool_use, post_tool_use, session_end, user_prompt_submit, stop).

---

✨ Key Features Added

1. The Event Dispatcher (.specify/events.py):
   A lightweight, zero-dependency Python script scaffolded in projects during specify init. It maps registered Spec Kit commands to their underlying scripts and executes them on demand, passing any payload through stdin.

2. Agent Event Adapters (registry-driven, one per integration):
   Target-aware adapters that generate/merge native event configurations seamlessly during setup() and teardown():

   • Claude Code: .claude/settings.json (nested JSON, single command string)
   • Cursor: .cursor/hooks.json (flat, camelCase structure)
   • Codex: .codex/config.toml (TOML format)
   • Copilot CLI: .github/hooks/speckit.json (dedicated file, bash/powershell variants)
   • opencode: .opencode/plugin/speckit-events.ts + opencode.json (TypeScript plugin)
   • Gemini, Qwen, Devin, Tabnine: Native settings merge

3. Layered Event Resolution:
   Events are resolved cleanly using a 4-tier priority stack:

   • Layer 1 (CLI): Passing --events false during init/upgrade disables events entirely (and strips prior hooks).
   • Layer 2 (User Override): Users can create .specify/integration-events.yml to override event behaviors.
   • Layer 3 (Extension-Declared): Extensions declare events: in their extension.yml (completely decoupling core code from extension details). Multiple extensions declaring the same event all run.
   • Layer 4 (Built-in Defaults): Native integration class defaults.

   Adapters translate canonical snake_case event names to each agent's native casing (Claude SessionStart, Copilot/Cursor sessionStart, Gemini BeforeTool, …), so extension authors never learn agent-specific names.

---

🛠️ Example Usage

An extension can declare events in extension.yml:

extension:
  id: "team-ai-directives"
  name: "Team AI Directives"
  version: "1.0.0"

events:
  session_start:
    command: "speckit.team-directives.boot"
    description: "Load team rules and constitution on session startup"

When the user runs specify init --integration claude, the Claude adapter automatically detects this, generates the Event Dispatcher, and injects the hook into .claude/settings.json. When Claude Code launches, it natively triggers the dispatcher, booting the team context seamlessly. Installing/enabling/disabling an extension refreshes each installed integration's native event config automatically.

---

🧪 Verification & Dependencies

• Dependencies: Uses pyyaml (already a spec-kit dependency) to parse extension-declared events. No new external dependencies.
• Teardown: Run specify integration uninstall to cleanly strip all native event config entries/plugins, leaving the user's files exactly as they were. The shared .specify/events.py dispatcher is reference-counted so it is only deleted when no installed event-capable integration still references it.
• Unit Tests: Includes a suite of unit tests verifying layered event resolution, override parsing/validation, extension collection (with registry enabled honoring), multi-handler-per-event accumulation, adapter configurations, idempotent merge/teardown, JSONC preservation, and safe-write containment.

[mnriem]

Thanks for this — the agent-runtime wiring is a real gap and the canonical→native event mapping, marker-based surgical teardown, and layered resolution are the right instincts. Sharing some architectural feedback before this goes further; happy to pair on any of it.

1. Call the feature "events", and use snake_case names consistent with the existing event vocabulary. hooks is already load-bearing in Spec Kit: extensions declare hooks: in extension.yml, there's a documented Hook System + HookExecutor, and those fire on SDD-workflow points (before_specify, after_tasks) as soft/in-prompt prompts. This PR fires on agent-runtime points (SessionStart, PreToolUse) wired into native agent config — genuinely different, and reusing "hooks" will confuse users and docs. Suggest:

• extension field events: (not runtime_hooks),
• CLI flag --events,
• canonical event names in the same xx_yyy style as the existing workflow events: session_start, pre_tool_use, post_tool_use, session_end, user_prompt_submit, stop,
• dispatcher events.py, marker __speckit_event__.

Adapters translate those canonical snake_case names to each agent's native casing (Claude SessionStart, Copilot/Cursor sessionStart, Gemini BeforeTool, …), so extension authors never learn agent-specific names.

2. Drive adapters from the integration registry, not a parallel _ADAPTERS dict. AGENTS.md makes the integration registry the single source of truth; the hardcoded {"claude": ..., "cursor-agent": ...} map means new agents must be registered twice and keys can drift. Fold each adapter into its integration class as CANONICAL_TO_NATIVE + events_config_file + emit_events()/remove_events() the registry drives — the same pattern Copilot already uses to own .vscode/settings.json. This also collapses the 4 duplicated insertions in base.py into one path.

3. Split sourcing from writing so integrations/ never imports extensions/. Right now _hooks.py both writes native config and sources declarations by scanning .specify/extensions/*/extension.yml (from ..extensions import ValidationError). Those are two responsibilities:

• Writing native config is legitimately integration-domain (like Copilot's settings.json) → keep it in the integration class.
• Sourcing the event→command map (built-in defaults + extension events: + user override) should move out: have the init orchestration resolve it and inject it via setup(..., events=map). The integration owns the write but doesn't reach up into the extension system.

4. The dispatcher is agent-agnostic → make it core. One bridge.py serves every agent and re-implements command→script resolution that already lives in _commands.py/the registrar. Lift it to a core .specify/events.py that reuses the existing resolver instead of duplicating it.

5. Two capabilities the PR description advertises aren't actually wired yet — make sure the reworked versions are real and covered by tests. As filed: the disable flag reads parsed_options.get("hooks"), but no integration declares that option via options() and there's no top-level flag, so it can't be set the way the description implies; and validate_runtime_hooks() documents itself as "called from ExtensionManifest._validate()", but the manifest isn't touched in this PR (only 3 files changed), so malformed declarations are never validated at load. After the rework that means: --events should be a real, declared gate, and event validation should actually be invoked from the manifest validator — both with end-to-end tests.

6. Missing Copilot CLI adapter. Copilot CLI has first-class hooks (docs): native events (sessionStart, preToolUse, postToolUse, sessionEnd, userPromptSubmitted), per-entry bash/powershell variants, and a dedicated .github/hooks/*.json location. Writing our own .github/hooks/speckit.json (rather than merging a shared settings file) makes teardown a plain file-delete with no marker scanning, and the bash/powershell split maps cleanly onto Spec Kit's existing scripts: {sh, ps} frontmatter. Note Copilot also reads cross-tool .claude/settings.json, so a project with both integrations needs a de-dupe guard in the resolver.

Smaller correctness notes: the Codex adapter embeds $(git rev-parse --show-toplevel) inside a TOML command string (relies on the agent shell-expanding it); several native event names (Cursor beforeSubmitPrompt, Gemini BeforeTool/AfterAgent, Tabnine) read as best-guesses worth verifying per-agent or marking experimental; and silent writes into .claude/settings.json etc. during init should be surfaced in output.

Net: the writing mechanism belongs in the integration layer as you have it — the main structural change is splitting the one module in two: native-config writing stays per-integration (registry-driven), while event sourcing moves to an injected core resolver, with the dispatcher lifted to core. Add the terminology change and the Copilot adapter and I think this is in great shape. Glad to help implement or review.

---

Posted on behalf of @mnriem by GitHub Copilot (model: Claude Opus 4.8).

[mnriem]

Please address my feedback above. Great proposal!

[Copilot]

Pull request overview

Adds agent-native runtime event handling, connecting extension commands to integration lifecycle hooks.

Changes:

• Adds event resolution, dispatch, validation, configuration merging, and cleanup.
• Adds native event mappings for nine integrations and wires events into setup workflows.
• Adds the specify event run command and event-focused tests.

Show a summary per file

File	Description
src/specify_cli/events.py	Implements event resolution, dispatch, adapters, and cleanup.
src/specify_cli/commands/event.py	Adds event execution CLI.
src/specify_cli/commands/init.py	Resolves events during initialization.
src/specify_cli/__init__.py	Registers event commands.
src/specify_cli/extensions/__init__.py	Validates extension event declarations.
src/specify_cli/integrations/base.py	Adds shared event setup and teardown behavior.
src/specify_cli/integrations/_install_commands.py	Installs resolved integration events.
src/specify_cli/integrations/_migrate_commands.py	Handles events during switch and upgrade.
src/specify_cli/integrations/claude/__init__.py	Defines Claude event mappings.
src/specify_cli/integrations/codex/__init__.py	Defines Codex event mappings and options.
src/specify_cli/integrations/copilot/__init__.py	Adds Copilot hook generation.
src/specify_cli/integrations/cursor_agent/__init__.py	Defines Cursor event mappings and options.
src/specify_cli/integrations/devin/__init__.py	Defines Devin event mappings.
src/specify_cli/integrations/gemini/__init__.py	Defines Gemini event mappings.
src/specify_cli/integrations/opencode/__init__.py	Configures OpenCode plugin events.
src/specify_cli/integrations/qwen/__init__.py	Defines Qwen event mappings.
src/specify_cli/integrations/tabnine/__init__.py	Defines Tabnine event mappings.
tests/integrations/test_events.py	Tests event resolution and adapter output.

Review details

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (3)

tests/integrations/test_events.py:18

• events_stale_exclusions is imported but never referenced, causing Ruff F401 in CI.

    collect_extension_events,
    events_stale_exclusions,
    install_integration_events,
    remove_integration_events,

tests/integrations/test_events.py:27

• IntegrationBase and CodexIntegration are unused imports, so the required Ruff job fails with F401.

from specify_cli.integrations.base import IntegrationBase
from specify_cli.integrations.manifest import IntegrationManifest
from specify_cli.integrations.claude import ClaudeIntegration
from specify_cli.integrations.cursor_agent import CursorAgentIntegration
from specify_cli.integrations.codex import CodexIntegration

tests/integrations/test_events.py:32

• None of these four integration classes is referenced by the tests, causing four Ruff F401 errors in CI.

from specify_cli.integrations.qwen import QwenIntegration
from specify_cli.integrations.gemini import GeminiIntegration
from specify_cli.integrations.devin import DevinIntegration
from specify_cli.integrations.tabnine import TabnineIntegration

• Files reviewed: 18/18 changed files
• Comments generated: 23
• Review effort level: Medium

[mnriem]

Please address Copilot feedback and fix test & lint errors

[kanfil]

Posted on behalf of @kanfil by opencode (model: glm-5.2, autonomous).

Addressed all 23 Copilot inline review findings plus the ruff lint errors. Pushed as four commits on top of da6c20d9 (head now 2623ddbd):

• 6ec91bb2 — lint: E402 noqa on the event-command import, removed unused console/patch/yaml/Path/integration imports, fixed F541 f-strings. uvx ruff@0.15.0 check src tests is clean.
• 61f0a45e — native-config generation: resolved events map now carries an ordered list of handlers per event (Fix release workflow to work with repository rules #2, so two extensions declaring the same event both run); each adapter renders a single complete shell command string (shell scripts in the scripts directory fail to execute #6, Claude/Gemini/etc. reject command+args) using a portably-resolved Python interpreter instead of hard-coded python3 (Suggestion on how to "frame" this concept #16); Gemini timeouts converted to ms (adding executable permission to the scripts so they execute when the … #7); the core runner resolves the project's sh/ps/py variant and splits the script command into argv instead of treating scripts: strings as bare paths (doco(spec-driven): Fix small typo in spec-driven.md #4), with the bundled-template fallback using the canonical _assets resolvers (feat: implement in Japanese #5); OpenCode TS plugin failures throw instead of process.exit(2) (Fix template path in plan command #13); user YAML override validated before returning (fix minor typo in constitution's Article I #21).
• 0d546a2e — merge/teardown safety: marker detection recurses into nested hooks (Support Cursor CLI #9); merge strips all Specify-marked entries before adding the new set so a changed override doesn't leave stale events (Sample Guidance on how to version control "context" within the repository #11); empty resolved map (--events false) now strips prior hooks instead of early-returning (Update README.md #3); Spec-Kit-created configs that become empty are deleted, not left as {} (feat: Add Codex CLI support #14); the shared .specify/events.py dispatcher is reference-counted across installed event-capable integrations (Include instructions for uvx dependency #10); Copilot's .github/hooks/speckit.json merges owned entries and teardown removes only owned entries (chore: Fix typo #8); JSONC/unparseable native configs are preserved instead of reset to {} (feat: add Codex CLI support #22, Proposal: Integrate VeriTrail for hallucination detection & provenance in SpecKit #23); write destinations are validated for symlinks/containment before any bytes are written (feat: allow custom specs directory via --specs-dir; default to specs/ #12).
• 2623ddbd — lifecycle/validation/contract: collect_extension_events honors the registry's enabled flag and a new refresh_integration_events() is wired into extension add/remove/enable/disable so native event config regenerates on extension state changes (Add John Lam as contributor and release badge #1); validate_events requires command to be a non-empty string, not just truthy (Create extensions folder for Gemini CLI #17); PR description updated to the implemented events/--events/integration-events.yml/events.py terminology (Support Amazon Q Developer IDE/CLI #15).

Tests: tests/integrations/test_events.py grew from 23 to 46 tests (added regressions for each finding). 189 adapter tests and 14 extension tests still pass. Version bumped 0.14.2.dev0 → 0.14.2.dev2 with CHANGELOG entries for the __init__.py touches (AGENTS.md convention).

One implementation note for #2: I moved it into the native-config tier (rather than the lifecycle tier in the original plan) because it is inseparable from the adapter command-string rendering — both rewrite the same formatters against the events-map shape, so doing them together avoided a throwaway intermediate rewrite.

[mnriem]

Please do not update CHANGELOG.md nor pyproject.toml as those are done by release process

[Copilot]

Review details

Comments suppressed due to low confidence (7)

src/specify_cli/events.py:853

• The reference-count branch still leaves events.py in this manifest. IntegrationBase.teardown() immediately calls manifest.uninstall(), so the matching dispatcher file is then deleted even though another integration references it. Drop the shared path from the manifest when retaining it; the current unit test only calls remove_integration_events() and misses the subsequent uninstall.

        if not _other_event_integrations_reference_dispatcher(project_root, integration.key):
            dispatcher_path = project_root / dispatcher_rel
            if dispatcher_path.exists():
                dispatcher_path.unlink(missing_ok=True)
            manifest.remove(dispatcher_rel)

src/specify_cli/events.py:264

• The Python branch never anchors scripts/... beneath .specify (or .specify/extensions/<id>), unlike the sh/ps branch below. Thus every event command in a project configured with --script py launches a nonexistent project-root scripts/... path. Resolve the first token against the same base before building argv.

    if variant == "py":
        # .py files aren't directly executable on Windows; prefix the resolved
        # interpreter. build_python_invocation returns a shell-quoted command
        # string, so split it back into argv for subprocess.
        invocation = IntegrationBase.build_python_invocation(script_cmd, project_root)
        try:
            return shlex.split(invocation, posix=(os.name != "nt"))
        except ValueError:
            return None

src/specify_cli/events.py:750

• All handlers are placed under the first handler's matcher. If two extensions register the same tool event with different matchers, both commands run for the first matcher and neither is registered for the later matcher. Emit a matcher group per handler (or group handlers by equal matcher) instead of selecting handlers[0].

        for ev, handlers in filtered.items():
            native = canonical_to_native[ev]
            matcher = handlers[0].get("matcher", "*") if handlers else "*"
            inner_hooks: list[dict[str, Any]] = []
            for cfg in handlers:

src/specify_cli/events.py:679

• Both fields receive one host-resolved command. For example, setup on Linux can write .venv/bin/python into the PowerShell hook, while setup on Windows can write .venv/Scripts/python.exe into the Bash hook, so the checked-in repository hook fails on the other OS. Generate independent Bash and PowerShell invocations rather than duplicating the current host's command.

                dispatcher_cmd = _dispatcher_command(integration, project_root, command, ev)
                entries.append(
                    {
                        "type": "command",
                        "bash": dispatcher_cmd,
                        "powershell": dispatcher_cmd,
                        "timeoutSec": _native_timeout(integration, cfg.get("timeout", 60)),

src/specify_cli/events.py:1273

• A parse failure returns None, but every installer branch still unconditionally calls manifest.record_existing() for that untouched config. On uninstall, cleanup also aborts parsing, after which manifest.uninstall() sees the original hash and deletes the user's JSONC/malformed file. The merge helpers need to report whether they actually wrote, and callers must not track a file when preservation caused the merge to be skipped.

    except (json.JSONDecodeError, ValueError) as exc:
        logger.warning(
            "Could not parse %s (may contain JSONC comments or be malformed); "
            "skipping event-config merge to preserve user content.",
            path,

src/specify_cli/events.py:270

• For the ps variant, the later return uses the .ps1 path as the executable. Windows subprocess.run(..., shell=False) cannot execute a PowerShell script directly, so event dispatch fails on the default Windows script type. Prefix the resolved script with pwsh -File (or the supported Windows PowerShell fallback) before returning argv.

    # sh / ps: the command string is "<relpath> [args...]". Resolve the
    # leading path component against the project, then rejoin with the
    # remaining tokens.
    tokens = shlex.split(script_cmd, posix=(os.name != "nt"))
    if not tokens:

src/specify_cli/events.py:912

• Refresh discards the integration's persisted parsed_options by passing None. After an install/upgrade with --events false, any later extension add/enable/disable re-resolves events as enabled and recreates hooks, violating the CLI gate. Read this integration's stored parsed_options from state and pass them here.

            _remove_native_event_hooks(integration, project_root, manifest)
            events_map = resolve_events(key, integration.config, project_root, None)
            if events_map:
                install_integration_events(integration, project_root, manifest, events_map)

• Files reviewed: 21/21 changed files
• Comments generated: 4
• Review effort level: Medium

[mnriem]

Please address Copilot feedback

[kanfil]

Posted on behalf of @kanfil by opencode (model: glm-5.2, autonomous).

Addressed all 11 actionable findings from Copilot review 4790195897 (the 4 high-confidence inline + 7 low-confidence suppressed). Pushed as five commits on top of 2623ddbd (head now be43bc4c):

• c5b9a93f — per maintainer request, reverted the CHANGELOG.md/pyproject.toml version bumps from the prior events commits. Both files now match their pre-PR (da6c20d9) state, so the PR makes no net change to them. (Bonus: this also clears the pending merge conflicts with upstream/main's 0.14.2 release — our side no longer diverges on those two files.)
• aaab4d23 — chore: Fix typo #8/Support Cursor CLI #9: DevinIntegration.options() and CopilotIntegration.options() now compose with super().options() so --events is declared alongside --skills; previously --integration-options "--events false" was rejected as unknown for both adapters.
• 524c2107 — adding executable permission to the scripts so they execute when the … #7: Cursor's .cursor/hooks.json now gets top-level version: 1 (added a version kwarg to _merge_json_fragment, preserving a user's value). S3: json-nested groups handlers by distinct matcher (one matcher-group per matcher) instead of placing all under the first handler's matcher. S4: Copilot's bash/powershell fields get independent OS-targeted interpreters (python3 / python) so a config generated on one OS works on the other.
• ceee5071 — S2: the py variant now anchors scripts/... under .specify/ (shared with sh/ps) before prepending the interpreter. S6: the ps variant prefixes argv with pwsh -File (fallback powershell -File) so subprocess.run(shell=False) can execute .ps1 on Windows.
• be43bc4c — S5: merge helpers return bool; install branches skip manifest.record_existing() when a merge is skipped on parse failure, so an untouched JSONC/malformed config isn't tracked and uninstall() can't later delete it. S1: remove_integration_events drops this integration's manifest claim on the shared dispatcher even when the file is retained, so the subsequent manifest.uninstall() in teardown() doesn't delete a file another integration references (test now exercises full teardown(), not just remove_integration_events). S7: refresh_integration_events passes each integration's stored parsed_options to resolve_events, so a persisted --events false survives extension add/enable/disable. Include instructions for uvx dependency #10: an invalid override entry abandons the whole override and keeps accumulated built-in+extension layers (instead of resetting to {} and disabling all hooks on a typo); only a fully-valid override, including explicit events: {}, replaces.

Tests: tests/integrations/test_events.py grew 56→61 tests; added regressions for each finding (options composition for all event-capable adapters, Cursor version + preservation, matcher grouping per-distinct/shared, Copilot bash≠powershell, py anchoring, ps launcher prefix, override preserve-layers, skipped-merge not tracked, full-teardown dispatcher retention, refresh honors --events false). 312 adapter tests still pass. uvx ruff@0.15.0 check src tests clean.

Note on stale inline comments: GitHub re-anchored the six comments from the original review (original_commit_id: da6c20d9) onto the new HEAD — they describe pre-fix code and correspond to findings already addressed in the prior round (#3 empty-map removal, #7 Gemini ms, #9 marker recursion, #12 safe-write, #13 opencode throw, #15 PR contract), so they're not actionable here.

[Copilot]

Review details

Comments suppressed due to low confidence (2)

src/specify_cli/events.py:171

• This lookup does not match the actual extension registry schema: .registry stores entries under extensions, and each registry entry stores registered_commands, not manifest command declarations. The filename scan only works when the file stem equals the command name, although valid manifests can map a command to another filename (for example, speckit.selftest.extension maps to commands/selftest.md). Such event commands always resolve as missing; load the installed extension manifest and use its provides.commands[].file mapping.

        for ext_id, meta in data.items():
            if not isinstance(meta, dict):
                continue
            for cmd in meta.get("commands", []):
                if cmd.get("name") == command_name:
                    ext_dir = project_root / ".specify" / "extensions" / ext_id
                    return ext_dir / cmd["file"], ext_id

src/specify_cli/events.py:869

• When cleanup successfully removes Specify entries but preserves user content, the helpers return False, so the native config remains claimed by the manifest. teardown(..., force=True) then calls manifest.uninstall() and deletes the entire user-owned settings file. Distinguish “retained after cleanup” from “cleanup skipped/failed” and drop the manifest claim for the retained file before forced uninstall.

    if deleted:
        manifest.remove(config_file)

• Files reviewed: 19/19 changed files
• Comments generated: 5
• Review effort level: Medium

[mnriem]

Please address Copilot feedback and fix test & lint errors

[kanfil]

Posted on behalf of @kanfil by opencode (model: glm-5.2, autonomous).

Fixed the CI-blocking stale test and addressed all 7 findings from Copilot review 4791088500 (5 inline + 2 suppressed). Pushed as three commits on top of be43bc4c (head now 6761c948); CHANGELOG.md/pyproject.toml remain untouched per the earlier instruction.

• c74e5a44 — CI: tests/test_extensions.py::test_no_commands_no_hooks matched the old validation string; updated the regex to the current "must provide at least one command, hook, or event" message (this was the sole failing test).
• 123e10a3 — data-loss & resolution:
  • S9: _remove_native_event_hooks now unconditionally drops this integration's manifest claim on the native config (not only when the file is deleted). Previously a config whose owned entries were cleaned but user content retained stayed tracked, so teardown(force=True) → manifest.uninstall(force=True) deleted the entire user-owned settings file. Config-file mirror of the earlier shared-dispatcher fix.
  • S8: _find_command_template resolved extension event commands via a broken registry lookup (the registry stores per-agent registered_commands name-lists, not a {name, file} map) and a file-stem scan that only matched when the .md stem equaled the command name. A manifest mapping speckit.selftest.extension → commands/selftest.md resolved as missing. It now enumerates installed extensions via ExtensionManager.get_extension() and matches provides.commands[].name → file, with the directory scan and core-template lookups kept as fallbacks.
  • R3: _remove_toml_entries now validates the destination with _ensure_safe_destination before read/write (the merge path already did), so a symlink swap of .codex/config.toml after install can't make teardown overwrite a file outside the project.
• 6761c948 — native-config hardening:
  • R1: the generated dispatcher and resolve_and_run_event_command now run their subprocesses with cwd = the project root. Previously specify event run (and the resolved script) inherited the agent's CWD while event_run resolves the project via Path.cwd(), so a hook fired from a subdirectory targeted the wrong project.
  • R2: _dispatcher_command shell-quotes each component for the target shell (POSIX shlex.quote; PowerShell single-quoted literals), so an interpreter path with spaces or an override command with shell metacharacters is passed as one argument. Claude's ${CLAUDE_PROJECT_DIR} prefix is left unquoted so the shell still expands it.
  • R4: the Codex TOML matcher is now rendered through the shared TOML escaper like command, so a matcher with a quote/backslash/newline/control char no longer produces malformed config.toml.
  • R5: Tabnine declares events_timeout_unit="ms" (its hook schema mirrors Gemini's BeforeTool/AfterTool), so the 60s default becomes 60000ms instead of timeout: 60 (60 ms).

Tests: tests/integrations/test_events.py grew 64→70 tests; added regressions for forced-teardown user-config preservation, manifest-driven command resolution (stem ≠ name), TOML teardown symlink rejection, cwd-forced execution from a subdirectory, POSIX/PowerShell quoting of space/metacharacter components, TOML matcher escaping, and Tabnine ms conversion. Full events suite + 235 adapter tests pass; uvx ruff@0.15.0 check src tests clean.

Note on R5: Tabnine's ms timeout unit is inferred from its Gemini-parity native mapping (BeforeTool/AfterTool) since the repo doesn't pin Tabnine's hook schema; happy to revert if Tabnine actually uses seconds.

[Copilot]

Review details

Comments suppressed due to low confidence (5)

src/specify_cli/events.py:666

• On Windows, _shell_quote() returns a single-quoted PowerShell string, but a quoted string is not invoked as a command without PowerShell's call operator. Generated hooks such as 'python' '.specify/events.py' ... therefore fail instead of launching the dispatcher. Prefix the quoted interpreter with & for Windows targets.

    q_interp = _shell_quote(interpreter, target_os)
    q_command = _shell_quote(command_name, target_os)
    q_event = _shell_quote(event_name, target_os)
    return f"{q_interp} {dispatcher} {q_command} {q_event}"

src/specify_cli/events.py:660

• Leaving the ${CLAUDE_PROJECT_DIR} expansion unquoted causes shell word splitting when the project path contains spaces, so Claude cannot launch the dispatcher in those projects. Quote the complete variable-based path; double quotes still allow the variable to expand.

    if integration.key == "claude":
        # Leave ${CLAUDE_PROJECT_DIR} unquoted so the shell expands it; the
        # prefix and the relative path are both fixed and metacharacter-free.
        dispatcher = "${CLAUDE_PROJECT_DIR}/" + EVENTS_DISPATCHER_REL

src/specify_cli/events.py:995

• The dispatcher is shared across integration manifests, but it is not excluded from upgrade stale cleanup. If Claude and Codex are installed and Claude is upgraded with --events false, Claude's new manifest omits events.py; Phase 2 then deletes it from the old manifest without the teardown refcount check, breaking Codex. Protect the shared dispatcher from the generic stale pass and leave its deletion to remove_integration_events().

    exclusions = set()
    config_file = getattr(integration, "events_config_file", None)
    if config_file:
        exclusions.add(config_file)
    if integration_key == "opencode":
        exclusions.add(".opencode/plugin/speckit-events.ts")

src/specify_cli/events.py:489

• A malformed override handler such as stop: [] or stop: bad-value normalizes to no handlers, but this branch merely skips it and still adopts resolved_override. If it is the only entry, a malformed override silently disables every built-in and extension hook, contrary to the stated invalid-override fallback. Mark the whole override invalid here, while retaining events: {} as the explicit disable case.

                for ev, raw in key_events.items():
                    handlers = _normalize_handlers(raw)
                    if not handlers:
                        logger.warning(
                            "Override %s: event '%s' has no valid handler; skipping entry",
                            override_file, ev,
                        )
                        continue

src/specify_cli/events.py:1489

• Cursor configs created by Spec Kit retain {"version": 1} after all owned hooks are removed: unlike the Copilot remover, this generic path only deletes a literally empty object. The manifest claim is then dropped, so uninstall permanently leaves the generated stub behind, contradicting clean teardown. Track whether the file pre-existed or otherwise handle the owned Cursor version field without deleting a user-owned version-only file.

        existing.pop("hooks", None)
    # #14: if the config is now empty (no user content), delete the file
    # rather than leaving a ``{}`` that confuses manifest.uninstall().
    if not existing:
        dst.unlink(missing_ok=True)
        return True
    _safe_write_json(dst, existing)

• Files reviewed: 20/20 changed files
• Comments generated: 10
• Review effort level: Medium

[kanfil]

Posted on behalf of @kanfil by opencode (model: glm-5.2, autonomous).

Fixed the three Windows CI failures and addressed all 15 findings from the latest Copilot review (5 inline + 2 suppressed high-confidence, plus 8 lower-confidence generated comments). Pushed as six commits on top of 6761c948 (head now 9b3f2496); CHANGELOG.md/pyproject.toml remain untouched per the standing instruction.

Windows CI (3 failures):

• ea333696 — EVENTS_DISPATCHER_REL was str(Path(".specify")/"events.py"), which yields .specify\events.py on Windows; manifest keys are POSIX-form, so the shared-dispatcher manifest-claim drop was skipped and uninstall(force=True) deleted the dispatcher another integration depended on. Now a POSIX constant (.as_posix()). Also made the py/ps argv assertions platform-agnostic (POSIX-form comparison, case-insensitive launcher stem) so they hold on Windows.

Copilot review — 15 findings:

• f7715a5c — C4: a malformed override handler (stop: []) now abandons the whole override (keeps prior layers) instead of disabling all hooks. C6: a non-mapping integration entry (claude: bad) is ignored as malformed, not treated as a valid disable. C10: matcher validated as a string in both manifest and override paths (a matcher: [] previously crashed by_matcher.setdefault). C11: event command refs are now canonicalized via rename_map in ExtensionManifest._validate, mirroring hook refs.
• a51ff920 — C3: shared dispatcher added to events_stale_exclusions so an --events false upgrade can't delete it via the generic stale pass and break other integrations. C5: a Spec-Kit-created Cursor file retaining only {"version": 1} is now deleted on teardown (not left as a stub). C12: refresh_integration_events resolves first and installs once; a mid-refresh failure no longer destroys the working config (the destructive pre-strip is gone — install_integration_events already handles cleanup).
• cb66271e — C1: target_os="host" always uses POSIX shlex.quote (safe tokens bare on every platform); the previous Windows-PS 'python' form wasn't invocable without &. PowerShell quoting is now only for the explicit windows target (Copilot's powershell field), prefixed with & . C2: Claude's ${CLAUDE_PROJECT_DIR} dispatcher is double-quoted so the variable still expands but a spaced project path doesn't word-split.
• e113956a — opencode TS plugin rewrite: C8 dispatcher+interpreter resolved from the directory OpenCode passes (not process.cwd()); C9 launched via execFileSync with an argv array (no shell, no injection); C7 both input and output forwarded to runEvent so pre/post_tool_use can inspect args/results.
• 9b3f2496 — U1: Qwen events_timeout_unit="ms" (Qwen Code command hooks use ms per its docs). U2: Devin json-root-nested format — its hooks.v1.json is a root event map with no hooks wrapper (per Devin docs); added _merge_json_root/_remove_json_root_entries. U3: Copilot "stop": "agentStop".

Verification: tests/integrations/test_events.py 70→85 tests (all pass); the previously-failing test_extensions.py::test_no_commands_no_hooks passes; 312 adapter tests pass; uvx ruff@0.15.0 check src tests clean. CHANGELOG.md/pyproject.toml net-diff vs the pre-PR base is empty.

Note on U1/U2/U3: these were verified against each agent's published hook documentation (Qwen Code command-hook timeout = ms; Devin hooks.v1.json = root event map, "the hooks object is the entire file"; Copilot agentStop native name). Happy to revert any if a maintainer confirms otherwise.

[Copilot]

Review details

Comments suppressed due to low confidence (7)

src/specify_cli/events.py:1243

• command and matcher values come from user/extension YAML but are interpolated into single-quoted TypeScript literals without escaping. A quote or backslash produces invalid generated code (and can inject code into the plugin). Serialize these values as JSON string literals when rendering the TypeScript.

                    checks = " || ".join(f"input.tool === '{t.lower()}'" for t in tools)
                    body_lines.append(
                        f"    if ({checks}) {{ runEvent('{command}', '{ev}', input, output); }}"

src/specify_cli/events.py:155

• OpenCode is supported on Windows, but this fallback always invokes python3, which is commonly unavailable there. Projects without .venv therefore fail every generated OpenCode event. Select python on Windows (and python3 on POSIX), or implement the same portable interpreter fallback as the other adapters.

  INTERPRETER = (
    (require('fs').existsSync(venvPy) && venvPy) ||
    (require('fs').existsSync(venvWin) && venvWin) ||
    'python3'
  ) as string;

src/specify_cli/events.py:775

• When events resolve to empty, prior native hooks are removed but the previously tracked shared dispatcher is deliberately left behind. During an --events false upgrade the new manifest no longer claims it and stale cleanup excludes it, so if this is the last event integration .specify/events.py becomes permanently orphaned and uninstall cannot remove it. Apply the same ownership/refcount cleanup used by teardown when no other manifest references the dispatcher.

    # #3: an empty resolved map (--events false, or override disabling events)
    # must still strip prior Specify hooks from this integration's native
    # config rather than leaving them active. The shared dispatcher is left
    # untouched — another integration may still reference it (#10).
    if not filtered:
        _remove_native_event_hooks(integration, project_root, manifest)
        return []

src/specify_cli/events.py:113

• The native configuration accepts a per-handler timeout, but the generated dispatcher always terminates the CLI after 120 seconds; the inner runner has the same fixed cap. Therefore a valid handler configured with a timeout above 120 seconds can never run for the requested duration. Pass the resolved timeout through to both subprocess layers or remove the conflicting internal cap.

        result = subprocess.run(
            specify_args,
            input=payload,
            capture_output=True,
            text=True,
            timeout=120,
            cwd=str(project_root),

src/specify_cli/events.py:332

• For a project configured with the supported sh script type on Windows, subprocess.run(shell=False) cannot execute a .sh file directly; chmod does not change that. Prefix the script with an available Bash/sh launcher on Windows, as the PowerShell branch already does for .ps1 files.

    # sh: the script is chmod'd executable during install.
    return [str(script_abs), *rest_args]

src/specify_cli/integrations/gemini/init.py:29

• Gemini exposes BeforeAgent for the lifecycle point represented by canonical user_prompt_submit (its own Claude-hook migration maps UserPromptSubmit to BeforeAgent). Omitting it here causes valid extension handlers to be skipped even though Gemini supports the event.

    CANONICAL_TO_NATIVE = {
        "session_start": "SessionStart",
        "pre_tool_use": "BeforeTool",
        "post_tool_use": "AfterTool",
        "session_end": "SessionEnd",
        "stop": "AfterAgent",
    }

src/specify_cli/integrations/tabnine/init.py:28

• Tabnine's Gemini-compatible hook schema also provides BeforeAgent and AfterAgent, but these mappings omit canonical user_prompt_submit and stop. Those extension events are therefore warned about and skipped for Tabnine despite native support.

    CANONICAL_TO_NATIVE = {
        "session_start": "SessionStart",
        "pre_tool_use": "BeforeTool",
        "post_tool_use": "AfterTool",
        "session_end": "SessionEnd",
    }

• Files reviewed: 20/20 changed files
• Comments generated: 3
• Review effort level: Medium

[mnriem]

Please address Copilot feedback

[kanfil]

Posted on behalf of @kanfil by opencode (model: glm-5.2, autonomous).

Addressed all 10 findings from the latest Copilot review (3 inline + 7 suppressed). Pushed as six commits on top of 9b3f2496 (head now dbf1fcb5); CHANGELOG.md/pyproject.toml remain untouched per the standing instruction.

• 7b12ebef — R1: collect_extension_events now reads events from a validated ExtensionManifest (whose command refs were canonicalized at install validation, C11) instead of the raw extension.yml YAML; an obsolete ref like my-ext.boot is now resolved to speckit.my-ext.boot so refresh doesn't emit a hook that silently no-ops. R3: refresh_integration_events accumulates per-integration failures and raises EventRefreshError so the extension lifecycle commands (add/remove/enable/disable) can't claim full deactivation while a stale native hook may still be active; a _refresh_events_and_warn helper surfaces the aggregated failures at each call site.
• 78ffdf94 — R2: the dispatcher's _find_specify and the opencode TS resolver now probe a project venv python for specify_cli importability before selecting it, so an unrelated project venv no longer shadows the PATH specify fallback and fails every event. S2: the opencode TS PATH fallback is now python on Windows (where python3 is commonly absent), python3 on POSIX.
• 44bebf88 — S1: _build_opencode_plugin serializes every interpolated value (command, event, native hook key, matcher tool names) as a JSON string literal, so a quote/backslash/backtick in a command or matcher can't break the generated TypeScript or inject code.
• ba3f1aed — S4: the per-handler timeout now flows through the chain (native command → dispatcher 4th arg → event run → inner runner) instead of a fixed 120s cap that killed handlers configured for longer. S5: the sh script variant prefixes a bash/sh launcher on Windows so subprocess.run(shell=False) can execute .sh files (mirroring the ps branch's pwsh -File).
• 9f721ed6 — S3: the empty-resolved-map install path (--events false upgrade) now runs the shared-dispatcher refcount cleanup, so the last event integration disabling events deletes .specify/events.py instead of orphaning it permanently (the new manifest wouldn't claim it and stale cleanup excludes it).
• dbf1fcb5 — S6: Gemini user_prompt_submit → BeforeAgent (verified against Gemini CLI's hooks docs). S7: Tabnine user_prompt_submit → BeforeAgent, stop → AfterAgent (Tabnine's Gemini-compatible schema).

Verification: tests/integrations/test_events.py 86→94 tests (all pass); 312 adapter tests pass; uvx ruff@0.15.0 check src tests clean. CHANGELOG.md/pyproject.toml net-diff vs the pre-PR base is empty.

Note on S6: Gemini's BeforeAgent mapping was verified against the Gemini CLI hooks documentation (BeforeAgent fires after the user submits a prompt, before planning). S7 (Tabnine) is inferred from Tabnine's deliberate Gemini-schema parity; happy to revert if Tabnine's docs say otherwise.

[Copilot]

Review details

Comments suppressed due to low confidence (4)

src/specify_cli/events.py:260

• Disabled extensions are still searched here because registry.keys() and get_extension() do not filter enabled: false; the raw directory fallback below can also rediscover them. If native cleanup is skipped (for example, an existing JSONC config cannot be parsed), a stale hook will therefore continue executing a disabled extension. Enforce the enabled flag again during dispatch and prevent the disk fallback from re-enabling explicitly disabled IDs.

        for ext_id in sorted(manager.registry.keys()):
            manifest = manager.get_extension(ext_id)
            if manifest is None:
                continue
            for cmd in manifest.commands:
                if not isinstance(cmd, dict):
                    continue
                if cmd.get("name") == command_name and cmd.get("file"):

src/specify_cli/events.py:1193

• During integration upgrade --integration-options "--events false", the caller supplies a fresh manifest (_migrate_commands.py:575-592), so this condition is false even though the old on-disk manifest owned the dispatcher. Stale cleanup also explicitly excludes this path, leaving .specify/events.py orphaned after the last integration disables events. Run the no-other-references deletion independently of whether the new manifest currently contains the key.

    if dispatcher_rel in manifest.files:
        manifest.remove(dispatcher_rel)
        if not _other_event_integrations_reference_dispatcher(project_root, integration.key):
            dispatcher_path = project_root / dispatcher_rel
            if dispatcher_path.exists():
                dispatcher_path.unlink(missing_ok=True)

src/specify_cli/events.py:219

• OpenCode ignores each handler's configured timeout: the generated callback always uses 60000 ms and invokes the dispatcher without its timeout argument, so handlers configured above 60 seconds are always terminated early while the inner runner defaults to 120 seconds. Thread cfg["timeout"] through the generated runEvent calls, using milliseconds only for execFileSync and seconds for the dispatcher argument.

    execFileSync(INTERPRETER, [DISPATCHER, command, event], {{
      input: JSON.stringify({{ input, output }}),
      stdio: ['pipe', 'inherit', 'inherit'],
      timeout: 60000,

src/specify_cli/extensions/_commands.py:63

• This refresh helper is wired to add/remove/enable/disable, but not to extension_update, which replaces the installed extension.yml at lines 1296-1300. If an update adds, removes, or changes event declarations, native configs remain stale until a manual integration upgrade. Refresh once after the update command has finalized its successful updates and rollbacks.

def _refresh_events_and_warn(project_root: Path) -> None:

• Files reviewed: 20/20 changed files
• Comments generated: 2
• Review effort level: Medium

[mnriem]

Please address Copilot feedback