π« Toolkit to help you get started with SDD or any other process!
feat: first-class agent-native runtime hooks for integrations (#3704)
kanfilf8e474d6fd63
diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.pyindex 0454b6923..33bb8f5c2 100644--- a/src/specify_cli/__init__.py+++ b/src/specify_cli/__init__.py@@ -514,6 +514,11 @@ _register_extension_cmds(app)from .integrations._commands import register as _register_integration_cmds # noqa: E402_register_integration_cmds(app)++# ===== Event Commands =====+from .commands.event import register as _register_event_cmds # noqa: E402+_register_event_cmds(app)+# Re-export selected helpers to preserve the public import surface.from .integrations._helpers import ( # noqa: E402_clear_init_options_for_integration as _clear_init_options_for_integration,diff --git a/src/specify_cli/commands/event.py b/src/specify_cli/commands/event.pynew file mode 100644index 000000000..764fde7f6--- /dev/null+++ b/src/specify_cli/commands/event.py@@ -0,0 +1,39 @@+"""specify event * command handlers."""++from __future__ import annotations++from pathlib import Path+import sys+import typer++event_app = typer.Typer(+ name="event",+ help="Manage and execute event-driven commands",+ add_completion=False,+)+++@event_app.command("run")+def event_run(+ command_name: str = typer.Argument(..., help="Name of the command to execute"),+ event_name: str = typer.Argument(..., help="Canonical event name (e.g., session_start)"),+ timeout: int = typer.Argument(+ 120, help="Per-handler timeout in seconds (passed through from the native hook config)"+ ),+):+ """Resolve and run an event-driven command script with stdin payload."""+ from ..events import resolve_and_run_event_command++ # Read payload from stdin if available+ payload = sys.stdin.read() if not sys.stdin.isatty() else "{}"++ # Run the event command+ project_root = Path.cwd() # The agent runs events from project root+ exit_code = resolve_and_run_event_command(+ command_name, event_name, payload, project_root, timeout=timeout+ )+ raise typer.Exit(code=exit_code)+++def register(app: typer.Typer) -> None:+ app.add_typer(event_app, name="event")diff --git a/src/specify_cli/commands/init.py b/src/specify_cli/commands/init.pyindex 0d96e2b6c..20471d722 100644--- a/src/specify_cli/commands/init.py+++ b/src/specify_cli/commands/init.py@@ -443,12 +443,20 @@ def register(app: typer.Typer) -> None:if extra:integration_parsed_options.update(extra)+ from ..events import resolve_events+ events_map = resolve_events(+ resolved_integration.key,+ resolved_integration.config,+ project_path,+ integration_parsed_options or None,+ )resolved_integration.setup(project_path,manifest,parsed_options=integration_parsed_options or None,script_type=selected_script,raw_options=integration_options,+ events=events_map,)manifest.save()diff --git a/src/specify_cli/events.py b/src/specify_cli/events.pynew file mode 100644index 000000000..686ed410e--- /dev/null+++ b/src/specify_cli/events.py@@ -0,0 +1,2096 @@+"""Agent runtime events for integrations.++Provides:+- ``resolve_events`` β layered event resolution (CLI flag β YAML override β extension-declared β built-in).+- ``collect_extension_events`` β scan installed extension.yml files for ``events:``.+- ``install_integration_events`` / ``remove_integration_events`` β entry points called from ``IntegrationBase.setup()`` / ``teardown()``.+"""++from __future__ import annotations++import json+import logging+import os+import re+import shlex+import shutil+import sys+import subprocess+import platform+from pathlib import Path+from typing import TYPE_CHECKING, Any++import yaml++if TYPE_CHECKING:+ from .integrations.base import IntegrationBase+ from .integrations.manifest import IntegrationManifest++logger = logging.getLogger(__name__)++# -- Constants -------------------------------------------------------------++EVENTS_DISPATCHER_DIR = Path(".specify")+EVENTS_DISPATCHER_FILENAME = "events.py"+# POSIX-form (forward-slash) relative path so it matches manifest keys, which+# are always stored in POSIX form (record_file/record_existing normalize via+# .as_posix()). On Windows, str(Path(".specify")/"events.py") yields+# ".specify\\events.py", which never matched a manifest key, so the shared-+# dispatcher manifest-claim drop was skipped and uninstall(force=True) deleted+# the dispatcher another integration still depended on.+EVENTS_DISPATCHER_REL = (EVENTS_DISPATCHER_DIR / EVENTS_DISPATCHER_FILENAME).as_posix()++YAML_OVERRIDE_FILENAME = Path(".specify") / "integration-events.yml"++_SPECKIT_MARKER = "__speckit_event__"++# Buffer (seconds) added to the native hook timeout so the agent's outer cap+# fires after the dispatcher's inner subprocess timeout, letting the inner+# kill its child cleanly instead of being killed mid-flight (which orphans+# the grandchild script process). The dispatcher receives the raw seconds+# (no buffer); the native config field gets seconds + buffer (R2).+EVENT_TIMEOUT_BUFFER = 5++# Canonical event names (snake_case)+CANONICAL_EVENTS = frozenset({+ "session_start",+ "pre_tool_use",+ "post_tool_use",+ "session_end",+ "user_prompt_submit",+ "stop",+})++# -- Events Dispatcher template ---------------------------------------------++_EVENTS_DISPATCHER_TEMPLATE = '''#!/usr/bin/env python3+"""Specify CLI Event Dispatcher β dispatches agent runtime events.++Generated by: specify integration install/upgrade+Do not edit manually.++Self-contained: it prefers `specify_cli` when the package is importable+(durable pip/pipx/uv-tool install) and falls back to an inline stdlib-only+resolver when Spec Kit is not installed at runtime β e.g. a one-time `uvx`+init whose environment is discarded after `specify init` finishes (R1). In+both cases it resolves the event's command template and runs its script+directly, without requiring a persistent `specify` executable on PATH.+"""+import json+import os+import re+import shlex+import shutil+import subprocess+import sys+from pathlib import Path+++def _find_command_template(command_name, project_root):+ """Locate the command's .md template. Returns (path, ext_id|None)."""+ exts_dir = project_root / ".specify" / "extensions"+ disabled_ids = set()+ registry_file = exts_dir / ".registry"+ if registry_file.is_file():+ try:+ reg_data = json.loads(registry_file.read_text(encoding="utf-8"))+ for ext_id, meta in reg_data.get("extensions", {}).items():+ if isinstance(meta, dict) and meta.get("enabled") is False:+ disabled_ids.add(ext_id)+ except Exception:+ pass++ stem = command_name.replace("speckit.", "").replace("spec.", "")++ # 1. Manifest-driven resolution from extension.yml in enabled extensions (Suppressed #1)+ if exts_dir.is_dir():+ for ext_dir in sorted(exts_dir.iterdir()):+ if not ext_dir.is_dir() or ext_dir.name in disabled_ids:+ continue+ ext_yml = ext_dir / "extension.yml"+ if ext_yml.is_file():+ try:+ yml_text = ext_yml.read_text(encoding="utf-8")+ cur_name = None+ cur_file = None+ in_provides = False+ in_commands = False+ for line in yml_text.splitlines():+ stripped = line.strip()+ if stripped == "provides:":+ in_provides = True+ continue+ if in_provides and stripped == "commands:":+ in_commands = True+ continue+ if in_commands and stripped and not line[0].isspace():+ in_provides = False+ in_commands = False+ continue+ if in_commands:+ if "name:" in line:+ cur_name = line.split("name:", 1)[1].strip().strip('"').strip("'")+ if "file:" in line:+ cur_file = line.split("file:", 1)[1].strip().strip('"').strip("'")+ if cur_name and cur_file:+ if cur_name == command_name:+ candidate = ext_dir / cur_file+ if candidate.exists():+ return candidate, ext_dir.name+ cur_name = None+ cur_file = None+ except Exception:+ pass++ # 2. On-disk extension commands by file stem (non-disabled extensions)+ if exts_dir.is_dir():+ for ext_dir in sorted(exts_dir.iterdir()):+ if not ext_dir.is_dir() or ext_dir.name in disabled_ids:+ continue+ cmds_dir = ext_dir / "commands"+ if cmds_dir.is_dir():+ for f in cmds_dir.glob("*.md"):+ if f.stem == command_name or f.stem == stem:+ return f, ext_dir.name++ # 3. Core templates in the project+ core = project_root / ".specify" / "templates" / "commands"+ if core.is_dir():+ candidate = core / (stem + ".md")+ if candidate.exists():+ return candidate, None+ return None, None+++def _script_variant(project_root):+ """Return the project's persisted script type ('sh'|'ps'|'py')."""+ default = "ps" if os.name == "nt" else "sh"+ init_opts = project_root / ".specify" / "init-options.json"+ try:+ data = json.loads(init_opts.read_text(encoding="utf-8"))+ script = data.get("script")+ if script in ("sh", "ps", "py"):+ return script+ except Exception:+ pass+ return default+++def _extract_scripts(template_path):+ """Parse the scripts: block from a command template's frontmatter."""+ try:+ content = template_path.read_text(encoding="utf-8")+ except Exception:+ return {}+ m = re.match(r"^---\\n(.*?)\\n---", content, re.DOTALL)+ if not m:+ return {}+ scripts = {}+ in_scripts = False+ for line in m.group(1).splitlines():+ if line.rstrip() == "scripts:":+ in_scripts = True+ continue+ if in_scripts and line and not line[0].isspace():+ break+ if in_scripts and ":" in line:+ k, _, v = line.partition(":")+ scripts[k.strip()] = v.strip()+ return scripts+++def _resolve_argv(template_path, project_root, ext_id):+ """Resolve the command's script to a runnable argv (stdlib only)."""+ scripts = _extract_scripts(template_path)+ if not scripts:+ return None+ requested = _script_variant(project_root)+ order = (requested,) if requested in scripts else ()+ fallbacks = (requested, "ps" if requested != "ps" else "sh", "py", "sh")+ seen = set()+ for cand in order + fallbacks:+ if cand in seen:+ continue+ seen.add(cand)+ if cand in scripts:+ variant = cand+ break+ else:+ return None+ script_cmd = scripts.get(variant, "").strip()+ if not script_cmd:+ return None++ base = (project_root / ".specify" / "extensions" / ext_id) if ext_id else (project_root / ".specify")+ try:+ tokens = shlex.split(script_cmd, posix=(os.name != "nt"))+ except ValueError:+ return None+ if not tokens:+ return None+ script_abs = base / tokens[0]+ if not script_abs.exists():+ return None+ rest = tokens[1:]++ if variant == "py":+ # .py files aren't directly executable; run under the dispatcher's own+ # Python (sys.executable), which is always available here.+ return [sys.executable or "python3", str(script_abs), *rest]+ if variant == "ps":+ launcher = shutil.which("pwsh") or shutil.which("powershell")+ if not launcher:+ return None+ return [launcher, "-File", str(script_abs), *rest]+ # sh: direct on POSIX; a bash/sh launcher on Windows.+ if os.name == "nt":+ launcher = shutil.which("bash") or shutil.which("sh")+ if launcher:+ return [launcher, str(script_abs), *rest]+ return None+ return [str(script_abs), *rest]+++def _run_inline(command_name, payload, project_root, timeout):+ """Resolve and run the event command with stdlib only (no specify_cli)."""+ template_path, ext_id = _find_command_template(command_name, project_root)+ if not template_path:+ return 0 # command not found: fail open (no-op) for lifecycle events+ argv = _resolve_argv(template_path, project_root, ext_id)+ if not argv:+ return 0+ try:+ result = subprocess.run(+ argv,+ input=payload,+ capture_output=True,+ text=True,+ timeout=timeout,+ cwd=str(project_root),+ )+ if result.stdout:+ sys.stdout.write(result.stdout)+ if result.returncode != 0:+ if result.stderr:+ sys.stderr.write(result.stderr)+ return result.returncode+ return 0+ except subprocess.TimeoutExpired:+ print(f"Event {command_name} timed out", file=sys.stderr)+ return 2+ except Exception as e:+ print(f"Event {command_name} error: {e}", file=sys.stderr)+ return 2+++def main():+ if len(sys.argv) < 3:+ sys.exit(0)+ command_name = sys.argv[1]+ # event_name is accepted for argv-compat with the native hook command but+ # is not needed for resolution (the command template drives everything).+ _event_name = sys.argv[2]+ # Optional 4th arg: per-handler timeout in seconds (S4).+ timeout = 120+ if len(sys.argv) >= 4:+ try:+ timeout = int(sys.argv[3])+ except (TypeError, ValueError):+ timeout = 120+ payload = sys.stdin.read() if not sys.stdin.isatty() else "{}"+ project_root = Path(__file__).parent.parent.resolve()++ # Preferred path: specify_cli is importable (durable install) β delegate to+ # the full resolver, which also handles extension manifests whose file stem+ # differs from the command name and the project's custom script selection.+ try:+ from specify_cli.events import resolve_and_run_event_command+ sys.exit(+ resolve_and_run_event_command(+ command_name, _event_name, payload, project_root, timeout=timeout+ )+ )+ except ImportError:+ pass++ # Fallback: self-contained stdlib resolver (one-time/temporary installs).+ sys.exit(_run_inline(command_name, payload, project_root, timeout))+++if __name__ == "__main__":+ main()+'''++# -- TS plugin template (opencode) ----------------------------------------++_TS_PLUGIN_TEMPLATE = '''import {{ execFileSync }} from 'child_process';+import * as path from 'path';++// The dispatcher + interpreter are resolved per-project at plugin load from+// the `directory` OpenCode passes to the plugin factory (C8), not+// process.cwd() β OpenCode may be launched from a parent directory or host+// another workspace, in which case process.cwd() points at the wrong project.+let DISPATCHER = '';+let INTERPRETER = '';++function canImportSpecifyCli(py: string): boolean {{+ // R2: a project-local venv commonly lacks Spec Kit (installed globally or+ // via uv tool). Probe the interpreter can import specify_cli before+ // selecting it, so an unrelated venv doesn't shadow the PATH fallback.+ try {{+ execFileSync(py, ['-c', 'import specify_cli'], {{+ stdio: ['ignore', 'ignore', 'ignore'],+ timeout: 10000,+ }});+ return true;+ }} catch (e) {{+ return false;+ }}+}}++function resolveDispatcher(directory: string): void {{+ DISPATCHER = path.join(directory, '.specify', 'events.py');+ // Prefer a project-local venv interpreter that can import specify_cli (R2),+ // then fall back to a platform-appropriate PATH interpreter (S2: python on+ // Windows, where python3 is commonly absent; python3 on POSIX).+ const venvPy = path.join(directory, '.venv', 'bin', 'python');+ const venvWin = path.join(directory, '.venv', 'Scripts', 'python.exe');+ INTERPRETER = (+ (require('fs').existsSync(venvPy) && canImportSpecifyCli(venvPy) && venvPy) ||+ (require('fs').existsSync(venvWin) && canImportSpecifyCli(venvWin) && venvWin) ||+ (process.platform === 'win32' ? 'python' : 'python3')+ ) as string;+}}++function runEvent(command: string, event: string, input: any, output: any, timeoutSec: number): void {{+ if (!DISPATCHER) return;+ try {{+ // execFileSync with an argv array invokes the interpreter directly β no+ // shell β so command/event strings with metacharacters can't break out+ // of the dispatcher argument (C9). The dispatcher arg is seconds; the+ // execFileSync timeout is ms with a buffer so the outer cap fires after+ // the dispatcher's inner subprocess (S3).+ execFileSync(INTERPRETER, [DISPATCHER, command, event, String(timeoutSec)], {{+ input: JSON.stringify({{ input, output }}),+ stdio: ['pipe', 'inherit', 'inherit'],+ timeout: (timeoutSec + {buffer}) * 1000,+ }});+ }} catch (e) {{+ // Propagate to OpenCode's hook machinery so only this hook is rejected,+ // not the entire host process. process.exit() would kill the agent.+ throw new Error(`specify event ${{command}} (${{event}}) failed: ${{(e as Error).message}}`);+ }}+}}++{event_entries}++export default (async ({{ client, project, directory, $ }}) => {{+ resolveDispatcher(directory);+ return {{+{plugin_returns}+ }};+}});+'''+++# -- Command runner logic (core) --------------------------------------------++def _find_command_template(command_name: str, project_root: Path) -> tuple[Path | None, str | None]:+ # 1. Resolve via installed extension manifests (authoritative). The+ # registry stores per-agent ``registered_commands`` name-lists, not a+ # ``{name, file}`` map, so the commandβfile mapping lives only in each+ # extension's ``extension.yml`` ``provides.commands`` (S8). Match the+ # command name to its declared ``file`` so commands whose file stem+ # differs from the command name (e.g. ``speckit.selftest.extension`` β+ # ``commands/selftest.md``) resolve correctly.+ exts_dir = project_root / ".specify" / "extensions"+ # S1: build the set of explicitly-disabled extension IDs so dispatch skips+ # disabled extensions (a stale hook would otherwise keep executing a+ # disabled extension's command). Applied to both the manifest loop and the+ # on-disk fallback below.+ disabled_ids = _disabled_extension_ids(project_root)+ try:+ from .extensions import ExtensionManager+ manager = ExtensionManager(project_root)+ for ext_id in sorted(manager.registry.keys()):+ if ext_id in disabled_ids:+ continue+ 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"):+ candidate = exts_dir / ext_id / cmd["file"]+ if candidate.exists():+ return candidate, ext_id+ except Exception:+ # Fall through to the on-disk scan if the registry/manifests can't be+ # read; event dispatch should degrade gracefully, not crash.+ pass++ # 2. Scan extension directories by file stem (covers extensions present on+ # disk but not resolvable via the manifest above). S1: skip disabled+ # extensions here too so the disk fallback can't re-enable them.+ if exts_dir.is_dir():+ for ext_dir in sorted(exts_dir.iterdir()):+ if ext_dir.name in disabled_ids:+ continue+ cmds_dir = ext_dir / "commands"+ if cmds_dir.is_dir():+ for f in cmds_dir.glob("*.md"):+ if f.stem == command_name:+ return f, ext_dir.name++ # 3. Check core templates in the project+ core = project_root / ".specify" / "templates" / "commands"+ if core.is_dir():+ stem = command_name.replace("speckit.", "").replace("spec.", "")+ candidate = core / f"{stem}.md"+ if candidate.exists():+ return candidate, None++ # 4. Fallback to package-bundled templates via the canonical asset+ # resolvers (wheel: core_pack/commands; source: repo-root+ # templates/commands). The previous bespoke inspect.getfile() math+ # pointed at core_pack/templates/commands, which never exists in a+ # wheel build (force-include maps templates/commands -> core_pack/commands).+ from ._assets import _locate_core_pack, _repo_root+ core_pack = _locate_core_pack()+ candidate_dirs = [+ core_pack / "commands" if core_pack is not None else None,+ _repo_root() / "templates" / "commands",+ ]+ stem = command_name.replace("speckit.", "").replace("spec.", "")+ for candidate_dir in candidate_dirs:+ if candidate_dir is None or not candidate_dir.is_dir():+ continue+ candidate = candidate_dir / f"{stem}.md"+ if candidate.exists():+ return candidate, None++ return None, None+++def _resolve_event_command_argv(+ template_path: Path, project_root: Path, ext_id: str | None+) -> list[str] | None:+ """Resolve a command template's ``scripts:`` entry to a runnable argv.++ ``scripts:`` values are command strings (e.g. ``scripts/bash/setup-plan.sh --json``),+ not bare paths, so joining the whole value into a ``Path`` made ``exists()``+ false and real commands silently no-op'd. This resolves the stored variant+ (honoring the project's sh/ps/py selection), splits the command string+ safely into argv, and prepends the appropriate interpreter (Python for+ ``.py``, the platform shell otherwise). Returns ``None`` if no runnable+ script is declared.+ """+ from .integrations.base import IntegrationBase++ content = template_path.read_text(encoding="utf-8")+ m = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)+ if not m:+ return None+ fm = m.group(1)+ try:+ fm_data = yaml.safe_load(fm) or {}+ except Exception:+ return None+ if not isinstance(fm_data, dict):+ return None+ scripts = fm_data.get("scripts", {})+ if not isinstance(scripts, dict):+ return None+ # Determine the requested variant from the project's persisted selection,+ # falling back to the platform default β same logic MarkdownIntegration+ # uses for command scaffolding.+ requested = _load_project_script_type(project_root)+ try:+ variant = IntegrationBase.select_script_variant(requested, scripts)+ except ValueError:+ return None+ script_cmd = scripts.get(variant)+ if not isinstance(script_cmd, str) or not script_cmd.strip():+ return None++ # Base under which the script's leading path component is anchored β+ # .specify/ (core) or .specify/extensions/<id>/ (extension). All variants+ # share this anchoring so a `scripts/...` token resolves correctly (S2:+ # the py branch previously invoked build_python_invocation() on the raw+ # command string, leaving `scripts/...` anchored at the project root).+ if ext_id:+ base = project_root / ".specify" / "extensions" / ext_id+ else:+ base = project_root / ".specify"++ tokens = shlex.split(script_cmd, posix=(os.name != "nt"))+ if not tokens:+ return None+ script_abs = base / tokens[0]+ if not script_abs.exists():+ return None+ rest_args = tokens[1:]++ if variant == "py":+ # .py files aren't directly executable on Windows; prefix the resolved+ # interpreter. argv is passed to subprocess.run(shell=False), so no+ # shell quoting is needed.+ interpreter = IntegrationBase.resolve_python_interpreter(project_root)+ return [interpreter, str(script_abs), *rest_args]++ if variant == "ps":+ # PowerShell scripts cannot be executed directly by+ # subprocess.run(shell=False); invoke via `pwsh -File` (PowerShell 7+),+ # falling back to `powershell -File` (Windows PowerShell) when pwsh is+ # absent (S6). The default Windows script type would otherwise fail.+ launcher = shutil.which("pwsh") or shutil.which("powershell") or "pwsh"+ return [launcher, "-File", str(script_abs), *rest_args]++ # sh: the script is chmod'd executable during install on POSIX. On Windows+ # subprocess.run(shell=False) can't execute a .sh directly, so prefix a+ # bash/sh launcher when one is available (mirroring the ps branch's+ # pwsh -File handling, S5).+ if os.name == "nt":+ launcher = shutil.which("bash") or shutil.which("sh")+ if launcher:+ return [launcher, str(script_abs), *rest_args]+ return [str(script_abs), *rest_args]+++def _load_project_script_type(project_root: Path) -> str:+ """Return the project's persisted script type ('sh'|'ps'|'py').++ Falls back to the platform default when init-options are absent or+ unreadable so event dispatch still works in a partially-initialized+ project.+ """+ default = "ps" if platform.system().lower().startswith("win") else "sh"+ try:+ from ._init_options import load_init_options+ opts = load_init_options(project_root)+ if isinstance(opts, dict):+ script = opts.get("script")+ if isinstance(script, str) and script in ("sh", "ps", "py"):+ return script+ except Exception:+ pass+ return default+++def resolve_and_run_event_command(+ command_name: str,+ event_name: str,+ payload: str,+ project_root: Path,+ *,+ timeout: int = 120,+) -> int:+ """Core entry point to resolve and execute an event-driven command.++ *timeout* is the per-handler timeout in seconds, passed through from the+ native hook config via the dispatcher (S4) so a handler configured above+ the previous fixed 120s cap can run for its full duration.+ """+ template_path, ext_id = _find_command_template(command_name, project_root)+ if not template_path:+ logger.warning("Event command '%s' not found", command_name)+ return 0+ argv = _resolve_event_command_argv(template_path, project_root, ext_id)+ if not argv:+ logger.warning("No script found for event command '%s'", command_name)+ return 0+ try:+ result = subprocess.run(+ argv,+ input=payload,+ capture_output=True,+ text=True,+ timeout=timeout,+ cwd=str(project_root),+ )+ if result.stdout:+ sys.stdout.write(result.stdout)+ if result.returncode != 0:+ if result.stderr:+ sys.stderr.write(result.stderr)+ return result.returncode+ return 0+ except subprocess.TimeoutExpired:+ sys.stderr.write(f"Event command {command_name} timed out\n")+ return 2+ except Exception as e:+ sys.stderr.write(f"Event command {command_name} error: {e}\n")+ return 2+++# -- Sourcing events map (CLI/Orchestration domain) -------------------------++# Resolved events map: each canonical event name maps to an *ordered list* of+# handler configs. Built-in defaults and per-extension declarations both+# contribute, so two extensions declaring ``session_start`` both run (finding+# #2) instead of the last one silently winning.+ResolvedEvents = dict[str, list[dict[str, Any]]]+++def _normalize_handlers(value: Any) -> list[dict[str, Any]]:+ """Coerce a single handler config or a list of them into a validated list.++ Accepts both the legacy single-mapping shape (``{command: ...}``) and the+ explicit list shape (``[{command: ...}, ...]``). Drops any entry that is+ not a mapping or lacks a ``command`` with a warning, so a malformed user+ override never reaches installation and crashes on ``cfg.get(...)`` (#21).+ """+ if isinstance(value, dict):+ value = [value]+ if not isinstance(value, list):+ return []+ handlers: list[dict[str, Any]] = []+ for entry in value:+ if not isinstance(entry, dict):+ logger.warning("Skipping malformed event handler (expected a mapping): %r", entry)+ continue+ handlers.append(entry)+ return handlers+++def _validate_resolved_event(event_name: str, handlers: list[dict[str, Any]]) -> None:+ """Validate a resolved event's handlers, raising a user-facing error.++ Raised for structural problems the user must fix (unknown event name,+ handler missing a ``command``, or ``command`` not a non-empty string per+ #17). Malformed-but-skipable entries are already dropped by+ ``_normalize_handlers``.+ """+ from .extensions import ValidationError++ if event_name not in CANONICAL_EVENTS:+ raise ValidationError(+ f"Unknown event '{event_name}': must be one of {sorted(CANONICAL_EVENTS)}"+ )+ for handler in handlers:+ command = handler.get("command")+ if not isinstance(command, str) or not command.strip():+ raise ValidationError(+ f"Event '{event_name}' handler missing required non-empty 'command' string"+ )+ # C10: matcher must be a string (or absent). A non-string matcher such+ # as `matcher: []` passes extension validation but later crashes+ # by_matcher.setdefault(matcher, ...) with TypeError: unhashable type.+ matcher = handler.get("matcher")+ if matcher is not None and not isinstance(matcher, str):+ raise ValidationError(+ f"Event '{event_name}' handler has invalid 'matcher': "+ "must be a string"+ )+ timeout = handler.get("timeout")+ if timeout is not None:+ if not isinstance(timeout, int) or isinstance(timeout, bool) or timeout <= 0:+ raise ValidationError(+ f"Event '{event_name}' handler has invalid 'timeout': must be a positive integer"+ )+++def resolve_events(+ integration_key: str,+ integration_config: dict[str, Any] | None,+ project_root: Path,+ parsed_options: dict[str, Any] | None,+) -> ResolvedEvents:+ """Resolve the final event set for an integration.++ Returns a mapping of canonical event name β ordered list of handler+ configs. Layers (lowest β highest precedence):++ 1. CLI gate ``--events false`` β empty map (caller still removes prior+ native hooks; see ``install_integration_events``).+ 2. Built-in defaults from ``integration_config["events"]`` (single-config+ per event, wrapped as one-element lists).+ 3. Extension-declared ``events:`` β appended per extension so multiple+ extensions can declare the same event (#2).+ 4. User YAML override (``.specify/integration-events.yml``) β replaces the+ accumulated set entirely when the integration key is present. Validated+ (#21) before returning; a malformed override is warned about and+ ignored rather than crashing downstream.+ """+ # Layer 1: CLI flag gate+ if parsed_options:+ events_flag = str(parsed_options.get("events", "true")).lower()+ if events_flag in ("false", "0", "no", "off"):+ return {}++ events: ResolvedEvents = {}++ # Layer 2: built-in defaults from integration config+ if integration_config and isinstance(integration_config.get("events"), dict):+ for ev, cfg in integration_config["events"].items():+ handlers = _normalize_handlers(cfg)+ if handlers:+ events.setdefault(ev, []).extend(handlers)++ # Layer 3: extension-declared events (accumulated, not overwriting)+ for ev, handlers in collect_extension_events(project_root).items():+ events.setdefault(ev, []).extend(handlers)++ # Layer 4: user YAML override (replaces entirely if key present)+ override_file = project_root / YAML_OVERRIDE_FILENAME+ if override_file.exists():+ try:+ override = yaml.safe_load(override_file.read_text(encoding="utf-8")) or {}+ except yaml.YAMLError:+ logger.warning("Could not parse %s; ignoring override", override_file)+ override = {}+ integrations = override.get("integrations", {}) if isinstance(override, dict) else {}+ if isinstance(integrations, dict) and integration_key in integrations:+ key_data = integrations[integration_key]+ if not isinstance(key_data, dict):+ # C6: a non-mapping integration entry (e.g. `claude: bad`) must+ # not be treated as a valid explicit disable. Warn and abandon+ # the override, keeping the accumulated built-in + extension+ # layers. Only an explicitly present, mapping-valued `events`+ # field replaces the prior layers.+ logger.warning(+ "Override %s: entry for '%s' is not a mapping; ignoring override",+ override_file, integration_key,+ )+ else:+ key_events = key_data.get("events", {})+ if not isinstance(key_events, dict):+ logger.warning(+ "Override %s: 'events' for '%s' is not a mapping; ignoring override",+ override_file, integration_key,+ )+ else:+ # Validate every entry before adopting the override. A single+ # invalid entry abandons the whole override and keeps the+ # accumulated built-in + extension layers (#10): previously a+ # typo reset resolved_override to {} and then assigned that+ # empty map to events, silently disabling all hooks despite+ # the "ignored" warning. Only a fully-valid override (including+ # an explicit `events: {}`) replaces the prior layers.+ resolved_override: ResolvedEvents = {}+ override_valid = True+ for ev, raw in key_events.items():+ handlers = _normalize_handlers(raw)+ if not handlers:+ # C4: a malformed handler (e.g. `stop: []` or+ # `stop: bad-value`) normalizes to no handlers.+ # Abandon the whole override (keep prior layers)+ # rather than skipping the entry β otherwise an+ # override whose only entry is malformed silently+ # disabled every built-in and extension hook. An+ # explicit `events: {}` (no entries) remains a+ # valid disable.+ logger.warning(+ "Override %s: event '%s' has no valid handler; ignoring entire override",+ override_file, ev,+ )+ override_valid = False+ break+ try:+ _validate_resolved_event(ev, handlers)+ except Exception as exc:+ logger.warning(+ "Override %s: invalid event '%s': %s; ignoring entire override",+ override_file, ev, exc,+ )+ override_valid = False+ break+ resolved_override[ev] = handlers+ if override_valid:+ events = resolved_override+ # else: keep the accumulated built-in + extension layers.++ return events+++def _disabled_extension_ids(project_root: Path) -> set[str]:+ """Return the set of explicitly-disabled extension IDs.++ Extensions not tracked in the registry are treated as enabled (backward+ compat). Used by ``collect_extension_events`` and ``_find_command_template``+ so a disabled extension's events and commands are never emitted or+ executed (S1) β otherwise a stale native hook would keep running a+ disabled extension after its config file was preserved (e.g. a JSONC+ parse failure that skipped native cleanup).+ """+ from .extensions import ExtensionRegistry++ exts_dir = project_root / ".specify" / "extensions"+ disabled_ids: set[str] = set()+ if not exts_dir.is_dir():+ return disabled_ids+ try:+ registry = ExtensionRegistry(exts_dir)+ for ext_id, meta in registry.list_by_priority(include_disabled=True):+ if not isinstance(meta, dict) or not meta.get("enabled", True):+ disabled_ids.add(ext_id)+ except Exception:+ pass+ return disabled_ids+++def collect_extension_events(project_root: Path) -> ResolvedEvents:+ """Scan all installed extensions for ``events:`` declarations.++ Returns a mapping of event name β list of handler configs. Multiple+ extensions declaring the same event each contribute a handler (in+ extension-directory sort order), so callers can emit all of them (#2).++ Honors the extension registry's ``enabled`` flag (#1): an explicitly+ disabled extension's events are skipped so disabling an extension actually+ deactivates its runtime hooks. Extensions absent from the registry (e.g.+ a partially-staged install) are still included to preserve the on-disk+ scan behavior.++ Events are read from a validated ``ExtensionManifest`` (R1) rather than+ the raw ``extension.yml`` YAML, so the command-reference canonicalization+ applied during install validation (C11, e.g. ``my-ext.boot`` β+ ``speckit.my-ext.boot``) is reflected β otherwise refresh would emit the+ obsolete name and ``_find_command_template`` could not match it, leaving+ the hook silently inert.+ """+ from .extensions import ExtensionManager++ events: ResolvedEvents = {}+ exts_dir = project_root / ".specify" / "extensions"+ if not exts_dir.is_dir():+ return events++ manager = ExtensionManager(project_root)++ # Build the set of explicitly-disabled extension IDs. Extensions not+ # tracked in the registry are treated as enabled (backward compat).+ disabled_ids = _disabled_extension_ids(project_root)++ # Union of extension IDs to consider: registry-tracked IDs (validated+ # manifests, canonicalized refs) plus on-disk dirs not yet in the registry+ # (partially-staged installs). The latter fall back to the raw YAML since+ # no validated manifest is available, preserving the on-disk scan behavior.+ registry_ids = set()+ try:+ registry_ids = set(manager.registry.keys())+ except Exception:+ pass+ on_disk_ids = {+ d.name for d in exts_dir.iterdir() if d.is_dir() and (d / "extension.yml").exists()+ }+ for ext_id in sorted(registry_ids | on_disk_ids):+ if ext_id in disabled_ids:+ continue+ # Prefer the validated manifest (canonicalized command refs, R1);+ # fall back to the raw YAML for an on-disk extension not yet+ # registered (a malformed extension shouldn't abort collection).+ runtime: dict[str, Any] = {}+ if ext_id in registry_ids:+ try:+ manifest = manager.get_extension(ext_id)+ except Exception:+ manifest = None+ if manifest is not None:+ runtime = manifest.data.get("events", {}) or {}+ if not runtime:+ ext_yml = exts_dir / ext_id / "extension.yml"+ if not ext_yml.exists():+ continue+ try:+ data = yaml.safe_load(ext_yml.read_text(encoding="utf-8")) or {}+ except yaml.YAMLError:+ continue+ if not isinstance(data, dict):+ continue+ runtime = data.get("events", {}) or {}+ if not isinstance(runtime, dict):+ continue+ for event, config in runtime.items():+ handlers = _normalize_handlers(config)+ if handlers:+ events.setdefault(event, []).extend(handlers)+ return events+++# -- Writing/Merging Config (Integration domain) ---------------------------++def _resolve_interpreter(project_root: Path) -> str:+ """Resolve a portable Python interpreter for native hook commands (#16).++ Delegates to ``IntegrationBase.resolve_python_interpreter`` so generated+ commands honor the project venv and never hard-code ``python3`` (which is+ commonly absent on Windows even when ``py.exe``/``python.exe`` exist).+ """+ from .integrations.base import IntegrationBase+ return IntegrationBase.resolve_python_interpreter(project_root)+++def _resolve_interpreter_for_target(target_os: str) -> str:+ """Resolve a Python interpreter for a target OS, independent of the host (#S4).++ Copilot's native config carries both a ``bash`` (POSIX) and a+ ``powershell`` (Windows) variant in the same checked-in file. Resolving+ both with the *host* interpreter writes a Linux venv path into the+ PowerShell hook (or vice-versa), so the config fails on the other OS.+ Each variant instead gets a portable interpreter for its target shell;+ the dispatcher script's own ``_find_specify()`` does per-OS venv+ resolution at runtime.+ """+ if target_os == "windows":+ # Windows: ``python`` is the most portable on PATH; the py launcher+ # (``py -3``) is the recommended fallback when ``python`` is absent.+ return "python"+ # POSIX (bash): ``python3`` is universally available.+ return "python3"+++def _native_timeout(integration: IntegrationBase, timeout_seconds: Any) -> int:+ """Return the timeout in the unit the integration's native config expects.++ Claude/Cursor/Codex/Copilot measure timeouts in seconds; Gemini measures+ in milliseconds (#7). An integration declares its unit via+ ``events_timeout_unit`` (``"s"`` default, ``"ms"`` for Gemini).+ """+ try:+ seconds = int(timeout_seconds)+ except (TypeError, ValueError):+ seconds = 60+ if getattr(integration, "events_timeout_unit", "s") == "ms":+ return seconds * 1000+ return seconds+++def _shell_quote(value: str, target_os: str) -> str:+ """Quote *value* as one argument for the target shell (R2).++ ``host`` and ``posix`` targets use ``shlex.quote`` (POSIX shells). Safe+ tokens β ``python3``, ``speckit.ext.cmd`` β pass through bare, so a+ single-``command``-string hook (Claude/Gemini/etc.) stays invocable on+ every platform. ``windows`` targets use a PowerShell single-quoted literal+ with embedded quotes doubled, for Copilot's dedicated ``powershell`` field.++ Prevents a component containing spaces (e.g. a venv interpreter path under+ a directory with spaces) or shell metacharacters (a malformed+ extension/override ``command``) from breaking the hook or being+ interpreted by the native shell instead of passed as one dispatcher+ argument.+ """+ if target_os == "windows":+ return "'" + value.replace("'", "''") + "'"+ # "host" and "posix" both use POSIX quoting. On Windows the single-+ # command-string formats (Claude/Gemini/Qwen/Devin/Tabnine) are run via+ # Git Bash or the agent's POSIX-ish shell, so POSIX quoting is correct and+ # avoids emitting 'python' (which PowerShell wouldn't invoke without &).+ return shlex.quote(value)+++def _dispatcher_command(+ integration: IntegrationBase,+ project_root: Path,+ command_name: str,+ event_name: str,+ *,+ target_os: str = "host",+ timeout_seconds: Any = None,+) -> str:+ """Build the single shell command string that invokes the dispatcher (#6).++ Claude/Gemini/Qwen/Devin/Tabnine accept one ``command`` string (not a+ ``command``+``args`` split), so each adapter renders a complete invocation:+ ``<interpreter> <dispatcher> <command> <event> [<timeout>]``. The+ interpreter is resolved portably (#16); Claude's dispatcher path is+ prefixed with ``${CLAUDE_PROJECT_DIR}/`` (Claude expands it before shell+ execution).++ ``target_os`` selects an OS-appropriate interpreter for adapters that emit+ both POSIX and Windows variants into one checked-in file (Copilot): ``host``+ uses the host-resolved interpreter (venv-aware), while ``posix``/``windows``+ emit portable interpreters so the config works on either OS (#S4).++ Each component is shell-quoted for the target shell (R2) so an interpreter+ path with spaces or a command/event containing shell metacharacters is+ passed as a single argument rather than reinterpreted by the native shell.+ The Claude dispatcher is double-quoted (``"${CLAUDE_PROJECT_DIR}/..."``) so+ the variable still expands but a project path with spaces doesn't+ word-split (C2). For the explicit ``windows`` target (Copilot's+ powershell field) the quoted interpreter is prefixed with PowerShell's+ call operator ``&`` so the quoted command is actually invoked (C1).++ When *timeout_seconds* is given, the resolved timeout (in the+ integration's native unit) is appended as a 4th argument so the dispatcher+ and inner runner honor the per-handler timeout instead of a fixed 120s cap+ that would kill a handler configured for longer (S4).+ """+ if target_os == "host":+ interpreter = _resolve_interpreter(project_root)+ else:+ interpreter = _resolve_interpreter_for_target(target_os)+ q_interp = _shell_quote(interpreter, target_os)+ q_command = _shell_quote(command_name, target_os)+ q_event = _shell_quote(event_name, target_os)+ if integration.key == "claude":+ # C2: double-quote so ${CLAUDE_PROJECT_DIR} still expands (double+ # quotes allow variable expansion in POSIX shells) but a project path+ # containing spaces doesn't word-split.+ dispatcher = '"${CLAUDE_PROJECT_DIR}/' + EVENTS_DISPATCHER_REL + '"'+ else:+ dispatcher = _shell_quote(EVENTS_DISPATCHER_REL, target_os)+ # C1: PowerShell won't invoke a single-quoted command without the call+ # operator. Prefix & for the explicit windows target only.+ prefix = "& " if target_os == "windows" else ""+ base = f"{prefix}{q_interp} {dispatcher} {q_command} {q_event}"+ if timeout_seconds is not None:+ # R2: the dispatcher interprets this argument as seconds, so pass the+ # raw seconds β NOT _native_timeout(...) (which converts to ms for+ # Gemini/Qwen/Tabnine and would yield 60000 seconds). The buffer is+ # applied to the native hook timeout field (in the adapter formatters)+ # so the agent's outer cap fires after the inner subprocess timeout.+ base += f" {_shell_quote(str(int(timeout_seconds)), target_os)}"+ return base+++def install_integration_events(+ integration: IntegrationBase,+ project_root: Path,+ manifest: IntegrationManifest,+ events: ResolvedEvents,+) -> list[Path]:+ """Generate dispatcher, merge native config, return created files.++ ``events`` maps each canonical event to an ordered list of handler configs+ (#2); every handler is emitted as a separate native hook entry so two+ extensions declaring ``session_start`` both run.+ """+ canonical_to_native = getattr(integration, "CANONICAL_TO_NATIVE", {})+ if not canonical_to_native:+ return []++ # Filter to only supported events, preserving all handlers per event.+ filtered: ResolvedEvents = {}+ for ev, handlers in events.items():+ if not isinstance(handlers, list):+ continue+ if ev in canonical_to_native:+ filtered[ev] = handlers+ else:+ print(+ f"\u26a0\ufe0f {integration.key} does not support '{ev}' events; skipping",+ file=sys.stderr,+ )++ # #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. S3: also run the shared-+ # dispatcher refcount cleanup so an --events false upgrade of the last+ # event integration doesn't orphan .specify/events.py permanently (the+ # new manifest no longer claims it and stale cleanup excludes it).+ if not filtered:+ _remove_native_event_hooks(integration, project_root, manifest)+ _cleanup_shared_dispatcher(integration, project_root, manifest)+ return []++ created: list[Path] = []++ # 1. Generate events.py dispatcher script (#12: validate destination first)+ dispatcher_dir = project_root / EVENTS_DISPATCHER_DIR+ dispatcher_path = dispatcher_dir / EVENTS_DISPATCHER_FILENAME+ _ensure_safe_destination(dispatcher_path)+ dispatcher_dir.mkdir(parents=True, exist_ok=True)+ dispatcher_path.write_text(_EVENTS_DISPATCHER_TEMPLATE, encoding="utf-8")+ dispatcher_path.chmod(0o755)+ manifest.record_file(+ str(dispatcher_path.relative_to(project_root)),+ dispatcher_path.read_bytes(),+ )+ created.append(dispatcher_path)++ # 2. Format-specific merge/write+ fmt = getattr(integration, "events_format", "json-nested")+ config_file = getattr(integration, "events_config_file", None)+ if not config_file:+ return created++ config_path = project_root / config_file++ if fmt == "ts-plugin":+ # Opencode TS plugin custom merge+ plugin_rel = ".opencode/plugin/speckit-events.ts"+ plugin_path = project_root / plugin_rel+ _ensure_safe_destination(plugin_path)+ plugin_path.parent.mkdir(parents=True, exist_ok=True)+ plugin_path.write_text(+ _build_opencode_plugin(filtered, canonical_to_native),+ encoding="utf-8",+ )+ manifest.record_file(+ plugin_rel,+ plugin_path.read_bytes(),+ )+ created.append(plugin_path)++ # Merge plugin path into opencode.json. S5: only track the config+ # file when the merge actually wrote; a skipped merge (JSONC/malformed)+ # must not be tracked or manifest.uninstall() would later delete the+ # user's untouched file.+ if _merge_opencode_plugin_ref(config_path, f"./{plugin_rel}"):+ rel = str(config_path.relative_to(project_root))+ if rel not in manifest.files:+ manifest.record_existing(rel)+ created.append(config_path)++ elif fmt == "copilot-json":+ # Copilot dedicated .github/hooks/speckit.json. Each handler becomes+ # its own entry in the native event's list (#2). The bash and+ # powershell variants get independent OS-targeted interpreters (#S4)+ # so a config generated on Linux doesn't write a POSIX venv path into+ # the PowerShell hook (and vice-versa). Entries carry the ownership+ # marker so a pre-existing user-authored file is merged (owned entries+ # replaced) rather than overwritten (#8), and teardown removes only+ # owned entries.+ copilot_hooks: dict[str, list[dict[str, Any]]] = {}+ for ev, handlers in filtered.items():+ native = canonical_to_native[ev]+ entries: list[dict[str, Any]] = []+ for cfg in handlers:+ command = cfg.get("command", "")+ bash_cmd = _dispatcher_command(+ integration, project_root, command, ev, target_os="posix",+ timeout_seconds=cfg.get("timeout", 60),+ )+ ps_cmd = _dispatcher_command(+ integration, project_root, command, ev, target_os="windows",+ timeout_seconds=cfg.get("timeout", 60),+ )+ entries.append(+ {+ "type": "command",+ "bash": bash_cmd,+ "powershell": ps_cmd,+ "timeoutSec": _native_timeout(integration, cfg.get("timeout", 60) + EVENT_TIMEOUT_BUFFER),+ _SPECKIT_MARKER: True,+ }+ )+ copilot_hooks[native] = entries+ # S5: only track when the merge wrote (skips on JSONC/malformed).+ if _merge_copilot_json(config_path, copilot_hooks):+ rel = str(config_path.relative_to(project_root))+ if rel not in manifest.files:+ manifest.record_existing(rel)+ created.append(config_path)++ elif fmt == "toml":+ # Codex config.toml custom merge. One [[hooks.<native>.hooks]] block+ # per handler so multiple handlers per event all emit (#2).+ lines: list[str] = []+ for ev, handlers in filtered.items():+ native = canonical_to_native[ev]+ for cfg in handlers:+ command = cfg.get("command", "")+ dispatcher_cmd = _dispatcher_command(integration, project_root, command, ev, timeout_seconds=cfg.get("timeout", 60))+ lines.append(f'[[hooks.{native}]]')+ lines.append(f'matcher = {_toml_quote(str(cfg.get("matcher", "*")))}')+ lines.append('')+ lines.append(f'[[hooks.{native}.hooks]]')+ lines.append('type = "command"')+ lines.append(f'command = {_toml_quote(dispatcher_cmd)}')+ lines.append(f'timeout = {_native_timeout(integration, cfg.get("timeout", 60) + EVENT_TIMEOUT_BUFFER)}')+ lines.append('speckit_marker = true')+ lines.append('')+ _merge_toml_fragment(config_path, "\n".join(lines))+ rel = str(config_path.relative_to(project_root))+ if rel not in manifest.files:+ manifest.record_existing(rel)+ created.append(config_path)++ elif fmt == "json-flat":+ # Cursor hooks.json custom merge. Flat command-string entries, one+ # per handler (#2), single resolved command string (#6/#16).+ cursor_hooks: dict[str, list[dict[str, Any]]] = {}+ for ev, handlers in filtered.items():+ native = canonical_to_native[ev]+ entries: list[dict[str, Any]] = []+ for cfg in handlers:+ command = cfg.get("command", "")+ dispatcher_cmd = _dispatcher_command(integration, project_root, command, ev, timeout_seconds=cfg.get("timeout", 60))+ entries.append(+ {+ "command": dispatcher_cmd,+ "type": "command",+ "timeout": _native_timeout(integration, cfg.get("timeout", 60) + EVENT_TIMEOUT_BUFFER),+ "matcher": cfg.get("matcher", "*"),+ _SPECKIT_MARKER: True,+ }+ )+ cursor_hooks[native] = entries+ # #7: Cursor's .cursor/hooks.json schema requires top-level+ # "version": 1; ensure it (preserving a user's value if present).+ # S5: only track when the merge wrote (skips on JSONC/malformed).+ if _merge_json_fragment(config_path, cursor_hooks, version=1):+ rel = str(config_path.relative_to(project_root))+ if rel not in manifest.files:+ manifest.record_existing(rel)+ created.append(config_path)++ elif fmt == "json-nested":+ # Claude/Qwen/Gemini/Devin/Tabnine nested config JSON merge.+ # Native schema is a single ``command`` string per hook (not+ # command+args), so each handler renders one complete dispatcher+ # invocation (#6). Gemini timeouts are converted to ms (#7).+ # Handlers are grouped by distinct matcher so each matcher gets its+ # own matcher-group (S3); previously all handlers were placed under+ # the first handler's matcher, so two extensions registering the same+ # event with different matchers both ran for the first matcher and+ # neither for the later.+ nested_hooks: dict[str, list[dict[str, Any]]] = {}+ for ev, handlers in filtered.items():+ native = canonical_to_native[ev]+ by_matcher: dict[str, list[dict[str, Any]]] = {}+ for cfg in handlers:+ matcher = cfg.get("matcher", "*")+ command = cfg.get("command", "")+ dispatcher_cmd = _dispatcher_command(integration, project_root, command, ev, timeout_seconds=cfg.get("timeout", 60))+ by_matcher.setdefault(matcher, []).append(+ {+ "type": "command",+ "command": dispatcher_cmd,+ "timeout": _native_timeout(integration, cfg.get("timeout", 60) + EVENT_TIMEOUT_BUFFER),+ _SPECKIT_MARKER: True,+ }+ )+ nested_hooks[native] = [+ {"matcher": matcher, "hooks": inner}+ for matcher, inner in by_matcher.items()+ ]+ # S5: only track when the merge wrote (skips on JSONC/malformed).+ if _merge_json_fragment(config_path, nested_hooks):+ rel = str(config_path.relative_to(project_root))+ if rel not in manifest.files:+ manifest.record_existing(rel)+ created.append(config_path)++ elif fmt == "json-root-nested":+ # Devin hooks.v1.json: a root event map ({"PreToolUse": [...]}) with+ # no top-level "hooks" wrapper (U2). Same matcher-grouping and single+ # command string as json-nested, but written to the root.+ root_hooks: dict[str, list[dict[str, Any]]] = {}+ for ev, handlers in filtered.items():+ native = canonical_to_native[ev]+ by_matcher: dict[str, list[dict[str, Any]]] = {}+ for cfg in handlers:+ matcher = cfg.get("matcher", "*")+ command = cfg.get("command", "")+ dispatcher_cmd = _dispatcher_command(integration, project_root, command, ev, timeout_seconds=cfg.get("timeout", 60))+ by_matcher.setdefault(matcher, []).append(+ {+ "type": "command",+ "command": dispatcher_cmd,+ "timeout": _native_timeout(integration, cfg.get("timeout", 60) + EVENT_TIMEOUT_BUFFER),+ _SPECKIT_MARKER: True,+ }+ )+ root_hooks[native] = [+ {"matcher": matcher, "hooks": inner}+ for matcher, inner in by_matcher.items()+ ]+ if _merge_json_root(config_path, root_hooks):+ rel = str(config_path.relative_to(project_root))+ if rel not in manifest.files:+ manifest.record_existing(rel)+ created.append(config_path)++ return created+++def _remove_native_event_hooks(+ integration: IntegrationBase,+ project_root: Path,+ manifest: IntegrationManifest,+) -> None:+ """Remove Specify-authored hooks from *this* integration's native config.++ Used both by full teardown and by the empty-resolved-map install path (#3).+ Does NOT touch the shared dispatcher (another integration may still+ reference it β #10).+ """+ fmt = getattr(integration, "events_format", None)+ config_file = getattr(integration, "events_config_file", None)+ if not config_file:+ return+ config_path = project_root / config_file+ if not config_path.exists():+ return+ _ensure_safe_destination(config_path)+ if fmt == "copilot-json":+ _remove_copilot_entries(config_path)+ elif fmt == "toml":+ _remove_toml_entries(config_path)+ elif fmt in ("json-nested", "json-flat"):+ _remove_json_entries(config_path)+ elif fmt == "json-root-nested":+ _remove_json_root_entries(config_path)+ elif fmt == "ts-plugin":+ _remove_opencode_entries(config_path)+ # Always drop this integration's manifest claim on the native config,+ # whether the file was deleted or retained with user content (S9). If we+ # kept a retained file tracked, teardown()'s manifest.uninstall(force=True)+ # would delete the entire user-owned settings file. After cleanup the file+ # is either gone or contains only user content, so this integration must+ # no longer claim it for teardown purposes.+ manifest.remove(config_file)+++def _other_event_integrations_reference_dispatcher(+ project_root: Path, excluding_key: str+) -> bool:+ """Return True if another installed event-capable integration still+ references the shared ``.specify/events.py`` dispatcher (#10).++ Inspects each installed integration's manifest (excluding *excluding_key*)+ for the dispatcher path so uninstalling one multi-install event-capable+ integration doesn't delete the dispatcher the others still rely on.+ """+ from .integrations._helpers import _read_integration_json+ from .integrations.manifest import IntegrationManifest+ from .integration_state import installed_integration_keys++ state = _read_integration_json(project_root)+ for key in installed_integration_keys(state):+ if key == excluding_key:+ continue+ try:+ manifest = IntegrationManifest.load(key, project_root)+ except Exception:+ continue+ if EVENTS_DISPATCHER_REL in manifest.files:+ return True+ return False+++def _cleanup_shared_dispatcher(+ integration: IntegrationBase, project_root: Path, manifest: IntegrationManifest+) -> None:+ """Drop this integration's manifest claim on the shared dispatcher and+ delete the file only when no other installed event-capable integration+ still references it (#10, S3).++ The manifest.remove() runs in both branches (S1): if we retain the file+ but leave it tracked, the subsequent manifest.uninstall() in teardown()+ sees the matching hash and deletes the file another integration still+ depends on. Used by full teardown and by the empty-resolved-map install+ path so an ``--events false`` upgrade of the last event integration+ doesn't orphan ``.specify/events.py`` permanently (S3).+ """+ dispatcher_rel = EVENTS_DISPATCHER_REL+ # Drop this integration's manifest claim if present. The remove() is+ # conditional (S1): an upgrade passes a *fresh* manifest that may never+ # have claimed the dispatcher, so the key may be absent β that's a no-op.+ if dispatcher_rel in manifest.files:+ manifest.remove(dispatcher_rel)+ # S2: run the no-other-references deletion independently of whether the+ # new manifest currently contains the key. An ``integration upgrade+ # --events false`` passes a fresh manifest that never recorded the+ # dispatcher, so gating the deletion on its presence orphans the file the+ # old on-disk manifest owned β and stale cleanup excludes it (C3). If no+ # other installed event-capable integration references the dispatcher,+ # delete it; otherwise leave it for them.+ if not _other_event_integrations_reference_dispatcher(project_root, integration.key):+ dispatcher_path = project_root / dispatcher_rel+ if dispatcher_path.exists():+ _ensure_safe_destination(dispatcher_path)+ dispatcher_path.unlink(missing_ok=True)+++def remove_integration_events(+ integration: IntegrationBase, project_root: Path, manifest: IntegrationManifest+) -> None:+ """Remove Specify-authored event entries from native config.++ The shared ``.specify/events.py`` dispatcher is deleted only when no other+ installed event-capable integration still references it (#10); otherwise+ it is left in place so multi-install setups don't lose the dispatcher+ mid-stream.+ """+ _remove_native_event_hooks(integration, project_root, manifest)+ _cleanup_shared_dispatcher(integration, project_root, manifest)++ # Clean up opencode TS plugin (owned solely by the opencode integration).+ if integration.key == "opencode":+ plugin_rel = ".opencode/plugin/speckit-events.ts"+ if plugin_rel in manifest.files:+ plugin_path = project_root / plugin_rel+ if plugin_path.exists():+ _ensure_safe_destination(plugin_path)+ plugin_path.unlink(missing_ok=True)+ manifest.remove(plugin_rel)+++def events_stale_exclusions(integration_key: str) -> set[str]:+ """Return project-relative paths to protect from stale cleanup."""+ from .integrations import get_integration+ integration = get_integration(integration_key)+ if not integration:+ return set()+ 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")+ # C3: the shared dispatcher is written into every event-capable+ # integration's manifest but is reference-counted across them. An upgrade+ # with --events false omits events.py from the new manifest, so the generic+ # stale pass would delete it without the refcount check, breaking any other+ # installed event-capable integration. Protect it here; its deletion is+ # left to remove_integration_events(), which checks the refcount.+ exclusions.add(EVENTS_DISPATCHER_REL)+ return exclusions+++class EventRefreshError(RuntimeError):+ """Raised when refreshing one or more integrations' event config failed.++ Aggregates per-integration failures so a lifecycle command+ (extension add/remove/enable/disable) can surface that an extension was+ not fully deactivated β a stale native hook may still be active (R3).+ """++ def __init__(self, failures: list[tuple[str, str]]) -> None:+ self.failures = failures+ details = "; ".join(f"{key}: {detail}" for key, detail in failures)+ super().__init__(+ f"event refresh failed for {len(failures)} integration(s): {details}"+ )+++def refresh_integration_events(project_root: Path) -> None:+ """Re-resolve and re-emit native event config for every installed+ event-capable integration (#1).++ Called after extension state changes (install/uninstall/enable/disable)+ so that extension-declared events are regenerated in each installed+ integration's native config β otherwise the documented install-after-+ ``specify init`` flow is inert and disabled/removed extension events stay+ active. Each integration is refreshed independently; a failure for one+ is logged and accumulated but does not abort the others. If any+ integration failed, :class:`EventRefreshError` is raised at the end so+ the lifecycle command can't claim the extension was fully deactivated+ while a stale native hook may still be active (R3).+ """+ from .integrations import get_integration+ from .integrations._helpers import _read_integration_json, _resolve_integration_options+ from .integrations.manifest import IntegrationManifest+ from .integration_state import installed_integration_keys++ state = _read_integration_json(project_root)+ failures: list[tuple[str, str]] = []+ for key in installed_integration_keys(state):+ integration = get_integration(key)+ if integration is None or not integration.supports_events():+ continue+ try:+ manifest = IntegrationManifest.load(key, project_root)+ except Exception as exc:+ logger.warning("Could not load manifest for '%s'; skipping event refresh: %s", key, exc)+ failures.append((key, f"manifest load: {exc}"))+ continue+ try:+ # C12: resolve first, then call install_integration_events once.+ # The previous flow ran _remove_native_event_hooks *before*+ # resolution, so any later failure (invalid destination, write+ # error, formatter error) destroyed the working native config+ # before the new one was written. install_integration_events+ # already removes stale Specify-marked entries and handles an+ # empty map (stripping prior hooks), so the destructive pre-step+ # is both unsafe and redundant.+ # S7: resolve this integration's persisted parsed_options so a+ # stored --events false is honored across extension lifecycle+ # changes; passing None would re-enable events the user disabled.+ _, parsed_options = _resolve_integration_options(integration, state, key, None)+ events_map = resolve_events(+ key, integration.config, project_root, parsed_options+ )+ # install_integration_events handles both the populated case+ # (writes new config, stripping stale owned entries) and the empty+ # case (strips prior hooks for --events false / disabled override).+ install_integration_events(integration, project_root, manifest, events_map)+ manifest.save()+ except Exception as exc:+ logger.warning("Failed to refresh events for '%s': %s", key, exc)+ failures.append((key, str(exc)))++ if failures:+ raise EventRefreshError(failures)+++# -- Manifest validation ---------------------------------------------------++def validate_events(data: dict[str, Any]) -> None:+ """Validate ``events`` field in extension manifest data."""+ from .extensions import ValidationError++ events = data.get("events")+ if "events" in data and not isinstance(events, dict):+ raise ValidationError("Invalid events: expected a mapping")+ if events:+ for event_name, event_config in events.items():+ if not isinstance(event_config, dict):+ raise ValidationError(+ f"Invalid event '{event_name}': expected a mapping"+ )+ command = event_config.get("command")+ # #17: command must be a non-empty string. A truthy non-string+ # (e.g. command: [foo]) would pass a bare truthiness check and+ # later render into invalid native configuration.+ if not isinstance(command, str) or not command.strip():+ raise ValidationError(+ f"Event '{event_name}' missing required 'command' string"+ )+ if event_name not in CANONICAL_EVENTS:+ raise ValidationError(+ f"Unknown event '{event_name}': "+ f"must be one of {sorted(CANONICAL_EVENTS)}"+ )+ # C10: matcher must be a string (or absent). A non-string matcher+ # such as `matcher: []` would later crash by_matcher.setdefault.+ matcher = event_config.get("matcher")+ if matcher is not None and not isinstance(matcher, str):+ raise ValidationError(+ f"Event '{event_name}' has invalid 'matcher': must be a string"+ )+ timeout = event_config.get("timeout")+ if timeout is not None:+ if not isinstance(timeout, int) or isinstance(timeout, bool) or timeout <= 0:+ raise ValidationError(+ f"Event '{event_name}' has invalid 'timeout': must be a positive integer"+ )+++def has_events(data: dict[str, Any]) -> bool:+ """Return True if ``events`` is present and non-empty."""+ return bool(data.get("events"))+++# -- Helper merging functions ----------------------------------------------++def _toml_quote(value: str) -> str:+ """Render *value* as a TOML basic string via the shared escaper."""+ from ._toml_string import escape_toml_basic+ return escape_toml_basic(value)+++def _build_opencode_plugin(+ filtered_events: ResolvedEvents,+ canonical_to_native: dict[str, str],+) -> str:+ """Render the opencode TS plugin for the resolved event set.++ Each canonical event may carry multiple handlers (#2); all handlers for a+ native event are invoked from one generated function. The dispatcher and+ interpreter are resolved per-project at plugin load from the ``directory``+ OpenCode passes (C8); the dispatcher is launched with ``execFileSync`` and+ an argv array (C9). Both the ``input`` and ``output`` callback arguments+ are forwarded to ``runEvent`` (C7) so pre_tool_use can inspect tool+ arguments and post_tool_use can inspect the result.+ """+ event_entries: list[str] = []+ plugin_returns: list[str] = []+ event_handlers: list[str] = []++ for ev, handlers in filtered_events.items():+ native = canonical_to_native[ev]+ # S1: serialize every interpolated value as a JSON string literal so a+ # quote/backslash/backtick in a command or matcher can't break the+ # generated TypeScript or inject code. json.dumps produces a valid+ # TS/JS string literal (double-quoted, fully escaped).+ ev_lit = json.dumps(ev)+ native_lit = json.dumps(native)++ # Build the body: one runEvent() call per handler wrapped in try/catch,+ # forwarding both input and output (C7). An optional tool-name matcher+ # guard applies to tool.execute.* hooks. All handlers execute before+ # any aggregate error is thrown.+ body_lines: list[str] = [" const errors: string[] = [];"]+ for cfg in handlers:+ command = str(cfg.get("command", ""))+ command_lit = json.dumps(command)+ matcher = cfg.get("matcher", "*")+ # S3: thread the per-handler timeout (seconds) to runEvent so the+ # execFileSync cap and dispatcher arg match the configuration+ # instead of a fixed 60000ms / 120s.+ timeout_sec = int(cfg.get("timeout", 60))+ if native.startswith("tool.execute."):+ if matcher and matcher != "*":+ tools = [t.strip().strip('"') for t in matcher.split("|")]+ checks = " || ".join(+ f"input.tool === {json.dumps(t.lower())}" for t in tools+ )+ body_lines.append(+ f" try {{ if ({checks}) {{ runEvent({command_lit}, {ev_lit}, input, output, {timeout_sec}); }} }} catch (e) {{ errors.push((e as Error).message); }}"+ )+ else:+ body_lines.append(+ f" try {{ runEvent({command_lit}, {ev_lit}, input, output, {timeout_sec}); }} catch (e) {{ errors.push((e as Error).message); }}"+ )+ else:+ body_lines.append(+ f" try {{ runEvent({command_lit}, {ev_lit}, input, output, {timeout_sec}); }} catch (e) {{ errors.push((e as Error).message); }}"+ )+ body_lines.append(" if (errors.length > 0) { throw new Error(errors.join('; ')); }")++ if native.startswith("tool.execute."):+ ts_hook = native+ event_entries.append(+ f"function _{ev}(input: any, output: any) {{\n"+ + "\n".join(body_lines) + "\n"+ " }"+ )+ plugin_returns.append(+ f" {json.dumps(ts_hook)}: async (input: any, output: any) => {{\n"+ f" _{ev}(input, output);\n"+ f" }},"+ )+ else:+ event_entries.append(+ f"function _{ev}(input: any, output: any) {{\n"+ + "\n".join(body_lines) + "\n"+ " }"+ )+ event_handlers.append(+ f" if (event.type === {native_lit}) {{ _{ev}(event, event); }}"+ )++ if event_handlers:+ plugin_returns.append(+ " event: async ({ event }) => {\n"+ + "\n".join(event_handlers) + "\n"+ " },"+ )++ return _TS_PLUGIN_TEMPLATE.format(+ buffer=EVENT_TIMEOUT_BUFFER,+ event_entries="\n\n".join(event_entries),+ plugin_returns="\n".join(plugin_returns),+ )+++def _merge_opencode_plugin_ref(config_path: Path, ref: str) -> bool:+ """Merge the speckit-events plugin ref into opencode.json.++ Aborts with a warning (#23) when the file cannot be parsed (e.g. JSONC or+ malformed JSON) instead of resetting user configuration to ``{}``. Returns+ False when skipped so callers avoid tracking the untouched file (S5).+ """+ existing = _load_user_json(config_path)+ if existing is None:+ return False+ plugins = existing.get("plugin", [])+ if not isinstance(plugins, list):+ plugins = []+ if ref not in plugins:+ plugins.append(ref)+ existing["plugin"] = plugins+ _safe_write_json(config_path, existing)+ return True+++def _remove_opencode_entries(config_path: Path) -> bool:+ """Remove the speckit-events plugin ref from opencode.json (#23).++ Returns True if the file was deleted (now empty of user content), False+ otherwise. Aborts without writing when the file cannot be parsed.+ """+ _ensure_safe_destination(config_path)+ existing = _load_user_json(config_path)+ if existing is None:+ return False+ plugins = existing.get("plugin", [])+ if isinstance(plugins, list):+ ref = "./.opencode/plugin/speckit-events.ts"+ plugins = [p for p in plugins if p != ref]+ if plugins:+ existing["plugin"] = plugins+ else:+ existing.pop("plugin", None)+ if not existing:+ config_path.unlink(missing_ok=True)+ return True+ _safe_write_json(config_path, existing)+ return False+++def _merge_toml_fragment(dst: Path, fragment: str) -> None:+ _ensure_safe_destination(dst)+ existing = ""+ if dst.exists():+ existing = dst.read_text(encoding="utf-8")+ existing = re.sub(+ r'\[\[hooks\.\w+\]\]\n(?:(?!\[\[hooks\.\w+\]\]).)*?speckit_marker = true\n*',+ "",+ existing,+ flags=re.DOTALL,+ )+ dst.parent.mkdir(parents=True, exist_ok=True)+ dst.write_text(existing.rstrip() + "\n\n" + fragment + "\n", encoding="utf-8")+++def _remove_toml_entries(dst: Path) -> bool:+ """Remove Specify-marked TOML entries; delete the file if now empty (#14).++ Returns True if the file was deleted (no user content remained).+ """+ if not dst.exists():+ return False+ # R3: validate the destination before reading/writing so a symlink swap of+ # the config after install can't make teardown overwrite a file outside+ # the project (the merge/write path already validates; teardown must too).+ _ensure_safe_destination(dst)+ existing = dst.read_text(encoding="utf-8")+ cleaned = re.sub(+ r'\[\[hooks\.\w+\]\]\n(?:(?!\[\[hooks\.\w+\]\]).)*?speckit_marker = true\n*',+ "",+ existing,+ flags=re.DOTALL,+ )+ # If only whitespace/comments remain, the file had no user content β+ # delete it rather than leaving an empty stub that confuses uninstall.+ stripped = "\n".join(+ line for line in cleaned.splitlines()+ if line.strip() and not line.strip().startswith("#")+ )+ if not stripped:+ dst.unlink(missing_ok=True)+ return True+ dst.write_text(cleaned, encoding="utf-8")+ return False+++def _merge_copilot_json(dst: Path, new_hooks: dict[str, list]) -> bool:+ """Merge Specify-owned hooks into Copilot's dedicated hooks JSON (#8).++ A pre-existing user-authored ``.github/hooks/speckit.json`` is merged+ (owned entries replaced via markers) rather than overwritten, and a+ parse failure aborts instead of resetting user content (#22). Returns+ False when skipped so callers avoid tracking the untouched file (S5).+ """+ existing = _load_user_json(dst)+ if existing is None:+ return False+ if not isinstance(existing, dict):+ existing = {}+ existing.setdefault("version", 1)+ existing_hooks = existing.get("hooks", {})+ if not isinstance(existing_hooks, dict):+ existing_hooks = {}+ # #11: strip ALL Specify-marked entries from every event first.+ cleaned_hooks: dict[str, list] = {}+ for event, entries in existing_hooks.items():+ if not isinstance(entries, list):+ continue+ kept_entries = _drop_marked_entries(entries)+ if kept_entries:+ cleaned_hooks[event] = kept_entries+ for event, entries in new_hooks.items():+ cleaned_hooks.setdefault(event, []).extend(entries)+ if cleaned_hooks:+ existing["hooks"] = cleaned_hooks+ else:+ existing.pop("hooks", None)+ _safe_write_json(dst, existing)+ return True+++def _remove_copilot_entries(dst: Path) -> bool:+ """Remove Specify-owned hooks from Copilot's hooks JSON (#8, #14).++ Deletes the file when no user-authored hooks remain; otherwise keeps the+ file with user content. Aborts (no write) on parse failure (#22).+ """+ _ensure_safe_destination(dst)+ existing = _load_user_json(dst)+ if existing is None:+ return False+ if not isinstance(existing, dict):+ return False+ hooks = existing.get("hooks", {})+ if not isinstance(hooks, dict):+ hooks = {}+ cleaned: dict[str, list] = {}+ for event, entries in hooks.items():+ if not isinstance(entries, list):+ continue+ kept_entries = _drop_marked_entries(entries)+ if kept_entries:+ cleaned[event] = kept_entries+ if cleaned:+ existing["hooks"] = cleaned+ else:+ existing.pop("hooks", None)+ # Dedicated Spec-Kit file: delete when only the (Spec-Kit-invented)+ # ``version`` key would remain β no user content to preserve.+ user_keys = {k for k in existing if k != "version"}+ if not user_keys:+ dst.unlink(missing_ok=True)+ return True+ _safe_write_json(dst, existing)+ return False+++def _merge_json_fragment(dst: Path, new_hooks: dict, *, version: int | None = None) -> bool:+ """Merge Specify-authored hook entries into a native JSON config.++ Idempotent: removes ALL prior Specify-marked entries from every event in+ the existing config first (#11), so an override that drops an event (e.g.+ ``pre_tool_use`` β ``stop``) doesn't leave stale marked entries behind.+ Marker detection recurses into nested ``hooks`` arrays (#9) so a+ matcher-group containing Specify-owned inner hooks is recognized and+ replaced rather than duplicated on every upgrade.++ Aborts with a warning (no write) when the existing file cannot be parsed+ (#22) β e.g. JSONC with comments β instead of resetting user content to+ ``{}``. Returns False when the merge was skipped so callers avoid tracking+ the untouched file (S5: otherwise manifest.uninstall() later deletes the+ user's JSONC/malformed file).++ When *version* is given, the top-level ``version`` field is ensured+ (preserving a user's value if present) so formats that require it β e.g.+ Cursor's ``.cursor/hooks.json`` schema (``version: 1``) β stay valid on a+ freshly generated file (#7).+ """+ existing = _load_user_json(dst)+ if existing is None:+ return False+ if not isinstance(existing, dict):+ existing = {}++ if version is not None:+ existing.setdefault("version", version)++ hooks_key = "hooks"+ existing_hooks = existing.get(hooks_key, {})+ if not isinstance(existing_hooks, dict):+ existing_hooks = {}++ # #11: strip ALL Specify-marked entries from every event first.+ cleaned_hooks: dict[str, list] = {}+ for event, entries in existing_hooks.items():+ if not isinstance(entries, list):+ continue+ kept_entries = _drop_marked_entries(entries)+ if kept_entries:+ cleaned_hooks[event] = kept_entries++ # Then add the newly resolved set.+ for event, entries in new_hooks.items():+ cleaned_hooks.setdefault(event, []).extend(entries)++ if cleaned_hooks:+ existing[hooks_key] = cleaned_hooks+ else:+ existing.pop(hooks_key, None)+ _safe_write_json(dst, existing)+ return True+++def _merge_json_root(dst: Path, new_hooks: dict) -> bool:+ """Merge Specify-authored hooks into a root-nested JSON config (Devin U2).++ Devin's ``.devin/hooks.v1.json`` is a root event map+ (``{"PreToolUse": [...]}``) with no ``hooks`` wrapper, so the event keys+ are top-level. Same idempotent strip-all-marked-then-add semantics and+ JSONC-abort behavior as ``_merge_json_fragment``.+ """+ existing = _load_user_json(dst)+ if existing is None:+ return False+ if not isinstance(existing, dict):+ existing = {}++ # #11: strip ALL Specify-marked entries from every root event first.+ cleaned: dict[str, list] = {}+ for event, entries in existing.items():+ if not isinstance(entries, list):+ # Preserve non-list user fields at the root (Devin has none, but+ # be defensive against a mixed user file).+ cleaned[event] = entries # type: ignore[assignment]+ continue+ kept_entries = _drop_marked_entries(entries)+ if kept_entries:+ cleaned[event] = kept_entries++ # Then add the newly resolved set (list values only).+ for event, entries in new_hooks.items():+ cleaned.setdefault(event, []).extend(entries)++ if cleaned:+ existing = cleaned+ else:+ existing = {}+ if not existing:+ dst.unlink(missing_ok=True)+ return True+ _safe_write_json(dst, existing)+ return True+++def _remove_json_root_entries(dst: Path) -> bool:+ """Remove Specify-authored entries from a root-nested JSON config (Devin U2).++ Deletes the file when no user content remains (C5/#14 mirror).+ """+ _ensure_safe_destination(dst)+ existing = _load_user_json(dst)+ if existing is None:+ return False+ if not isinstance(existing, dict):+ return False+ cleaned: dict[str, Any] = {}+ for event, entries in existing.items():+ if not isinstance(entries, list):+ cleaned[event] = entries+ continue+ kept_entries = _drop_marked_entries(entries)+ if kept_entries:+ cleaned[event] = kept_entries+ if not cleaned:+ dst.unlink(missing_ok=True)+ return True+ _safe_write_json(dst, cleaned)+ return False+++def _drop_marked_entries(entries: list) -> list:+ """Return *entries* with Specify-marked hooks removed, preserving user hooks.++ Handles both flat entries (marker on the entry itself) and nested entries+ (marker on inner ``hooks`` elements). A nested matcher-group whose inner+ hooks are all Specify-owned is dropped; one with surviving user inner+ hooks is kept with only the user hooks retained (#9).+ """+ kept: list = []+ for entry in entries:+ if not isinstance(entry, dict):+ kept.append(entry)+ continue+ inner = entry.get("hooks")+ if isinstance(inner, list):+ kept_inner = [h for h in inner if not _has_marker(h)]+ if kept_inner:+ entry["hooks"] = kept_inner+ kept.append(entry)+ # else: outer group was entirely Specify-owned β drop+ elif _has_marker(entry):+ pass # flat Specify-owned entry β drop+ else:+ kept.append(entry)+ return kept+++def _load_user_json(path: Path) -> dict | None:+ """Load a user-owned JSON file, aborting (None) on parse failure (#22/#23).++ Returns the parsed dict, or ``None`` when the file is missing or cannot be+ parsed (e.g. JSONC with comments, or temporarily malformed JSON). Callers+ must skip the merge rather than resetting user content to ``{}``.+ """+ if not path.exists():+ return {}+ try:+ data = json.loads(path.read_text(encoding="utf-8"))+ 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,+ )+ logger.debug("Parse error detail: %s", exc)+ return None+ if not isinstance(data, dict):+ logger.warning("%s is not a JSON object; skipping event-config merge.", path)+ return None+ return data+++def _safe_write_json(dst: Path, data: dict) -> None:+ """Write *data* as JSON to *dst* after validating the destination (#12)."""+ _ensure_safe_destination(dst)+ dst.parent.mkdir(parents=True, exist_ok=True)+ dst.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")+++def _ensure_safe_destination(dst: Path) -> None:+ """Validate a write target is a regular path inside the project (#12).++ Walks each path component and rejects symlinks (which could escape the+ project β e.g. a symlinked ``.claude`` or ``.specify`` directory pointing+ outside the repo would redirect writes to external files). Then validates+ lexical containment so ``..`` traversal is also rejected.+ """+ from .agents import CommandRegistrar++ # Walk each component so a symlinked ancestor (e.g. ``.claude`` β outside)+ # cannot be silently followed. Mirrors IntegrationManifest.record_existing.+ walked = dst.anchor and Path(dst.anchor) or Path("/")+ for part in dst.relative_to(dst.anchor).parts if dst.anchor else dst.parts:+ walked = walked / part+ if walked.is_symlink():+ raise ValueError(+ f"Refusing to write event config through a symlink: {walked}"+ )++ # Containment check against the nearest existing ancestor directory.+ base = dst.parent+ while not base.exists() and base != base.parent:+ base = base.parent+ CommandRegistrar._ensure_inside(dst, base)+++def _remove_json_entries(dst: Path) -> bool:+ """Remove Specify-authored entries; delete the file if now empty (#14).++ Returns True if the file was deleted (Spec Kit created it and no user+ content remains), False otherwise.+ """+ _ensure_safe_destination(dst)+ existing = _load_user_json(dst)+ if existing is None:+ return False+ hooks = existing.get("hooks", {})+ if not isinstance(hooks, dict):+ return False+ cleaned: dict[str, list] = {}+ for event, entries in hooks.items():+ if not isinstance(entries, list):+ continue+ kept_entries = _drop_marked_entries(entries)+ if kept_entries:+ cleaned[event] = kept_entries+ if cleaned:+ existing["hooks"] = cleaned+ else:+ existing.pop("hooks", None)+ # #14/C5: if the config is now empty of user content, delete the file+ # rather than leaving a stub that confuses manifest.uninstall(). A+ # Spec-Kit-created Cursor file retains {"version": 1} after all owned+ # hooks are removed (we added the version field); treat the version-only+ # case as empty too, mirroring _remove_copilot_entries, so clean teardown+ # doesn't leave a generated stub behind.+ user_keys = {k for k in existing if k != "version"}+ if not user_keys:+ dst.unlink(missing_ok=True)+ return True+ _safe_write_json(dst, existing)+ return False+++def _has_marker(entry: Any) -> bool:+ """Return True if *entry* (or any nested inner hook) is Specify-marked (#9).++ Flat entries carry the marker directly; nested matcher-groups carry it on+ their inner ``hooks`` elements, so detection recurses one level to+ recognize groups that are (wholly or partly) Specify-owned.+ """+ if not isinstance(entry, dict):+ return False+ if entry.get(_SPECKIT_MARKER, False) is True:+ return True+ inner = entry.get("hooks")+ if isinstance(inner, list):+ return any(_has_marker(h) for h in inner)+ return Falsediff --git a/src/specify_cli/extensions/__init__.py b/src/specify_cli/extensions/__init__.pyindex 94fc02177..c43a3a7bd 100644--- a/src/specify_cli/extensions/__init__.py+++ b/src/specify_cli/extensions/__init__.py@@ -331,17 +331,22 @@ class ExtensionManifest:)commands = provides.get("commands", [])hooks = self.data.get("hooks")+ events = self.data.get("events")if "commands" in provides and not isinstance(commands, list):raise ValidationError("Invalid provides.commands: expected a list")if "hooks" in self.data and not isinstance(hooks, dict):raise ValidationError("Invalid hooks: expected a mapping")+ if "events" in self.data:+ from ..events import validate_events+ validate_events(self.data)has_commands = bool(commands)has_hooks = bool(hooks)+ has_events = bool(events)- if not has_commands and not has_hooks:- raise ValidationError("Extension must provide at least one command or hook")+ if not has_commands and not has_hooks and not has_events:+ raise ValidationError("Extension must provide at least one command, hook, or event")# Validate hook values (if present).# Each event is a single mapping or a list of mappings.@@ -465,6 +470,33 @@ class ExtensionManifest:f"The extension author should update the manifest.")+ # C11: apply the same rename + alias-lift canonicalization to event+ # command references. Without this, an event referencing a command+ # that was auto-corrected (e.g. speckit.boot -> speckit.<id>.boot)+ # keeps the obsolete name, dispatch reports no command, and the event+ # silently no-ops.+ events_data = self.data.get("events", {})+ if isinstance(events_data, dict):+ for event_name, event_config in events_data.items():+ if not isinstance(event_config, dict):+ continue+ command_ref = event_config.get("command")+ if not isinstance(command_ref, str):+ continue+ after_rename = rename_map.get(command_ref, command_ref)+ parts = after_rename.split(".")+ if len(parts) == 2 and parts[0] == ext["id"]:+ final_ref = f"speckit.{ext['id']}.{parts[1]}"+ else:+ final_ref = after_rename+ if final_ref != command_ref:+ event_config["command"] = final_ref+ self.warnings.append(+ f"Event '{event_name}' referenced command '{command_ref}'; "+ f"updated to canonical form '{final_ref}'. "+ f"The extension author should update the manifest."+ )+@staticmethoddef _try_correct_command_name(name: str, ext_id: str) -> Optional[str]:"""Try to auto-correct a non-conforming command name to the required pattern.diff --git a/src/specify_cli/extensions/_commands.py b/src/specify_cli/extensions/_commands.pyindex f67a7fb4f..166364920 100644--- a/src/specify_cli/extensions/_commands.py+++ b/src/specify_cli/extensions/_commands.py@@ -71,6 +71,30 @@ def _display_project_path(*args, **kwargs):return _f(*args, **kwargs)+def _refresh_events_and_warn(project_root: Path) -> None:+ """Refresh native event config and surface failures (R3).++ The extension has already been added/removed/enabled/disabled by the time+ this runs, so a refresh failure must not abort the command β but it must+ be surfaced, because a stale native hook may still be active (e.g. a+ disabled extension's hook still resolves and runs). Prints a warning with+ the per-integration failures so the user knows deactivation was incomplete.+ """+ from ..events import EventRefreshError, refresh_integration_events++ try:+ refresh_integration_events(project_root)+ except EventRefreshError as exc:+ console.print(+ f"\n[yellow]β [/yellow] Extension updated, but event refresh failed "+ f"for {len(exc.failures)} integration(s); a stale native hook may "+ f"still be active. Re-run [cyan]specify integration upgrade "+ f"<key>[cyan][/cyan][/cyan] to retry."+ )+ for key, detail in exc.failures:+ console.print(f" {key}: {_escape_markup(detail)}")++def _load_catalog_command_config(project_root: Path, config_path: Path) -> dict:"""Load extension catalog CLI config with user-facing shape errors."""try:@@ -653,6 +677,10 @@ def extension_add(console.print(f"\n[bold]{_escape_markup(str(manifest.name))}[/bold] (v{_escape_markup(str(manifest.version))})")console.print(f" {_escape_markup(str(manifest.description))}")+ # #1: regenerate native event config for installed event-capable+ # integrations so the new extension's events take effect immediately.+ _refresh_events_and_warn(project_root)+for warning in manifest.warnings:console.print(f"\n[yellow]β Compatibility warning:[/yellow] {_escape_markup(str(warning))}")@@ -759,6 +787,10 @@ def extension_remove(console.print(f"\nConfig files preserved in .specify/extensions/{safe_extension_id}/")else:console.print(f"\nConfig files backed up to .specify/extensions/.backup/{safe_extension_id}/")++ # #1: regenerate native event config so the removed extension's events+ # are stripped from installed integrations.+ _refresh_events_and_warn(project_root)console.print(f"\nTo reinstall: specify extension add {safe_extension_id}")else:console.print("[red]Error:[/red] Failed to remove extension")@@ -2126,6 +2158,13 @@ def extension_update(console.print(f" β’ {_escape_markup(str(ext_name))}: {_escape_markup(str(error))}")raise typer.Exit(1)+ # S4: regenerate native event config after a successful update. An+ # update replaces the installed extension.yml, so any added/removed/+ # changed event declarations would otherwise leave native configs+ # stale until a manual integration upgrade.+ if updated_extensions:+ _refresh_events_and_warn(project_root)+except ValidationError as e:console.print(f"\n[red]Validation Error:[/red] {_escape_markup(str(e))}")raise typer.Exit(1)@@ -2175,6 +2214,10 @@ def extension_enable(console.print(f"[green]β[/green] Extension '{_escape_markup(str(display_name))}' enabled")+ # #1: regenerate native event config so the enabled extension's events+ # are re-emitted in installed integrations.+ _refresh_events_and_warn(project_root)+@extension_app.command("disable")def extension_disable(@@ -2219,6 +2262,10 @@ def extension_disable(console.print("\nCommands will no longer be available. Hooks will not execute.")console.print(f"To re-enable: specify extension enable {_escape_markup(str(extension_id))}")+ # #1: regenerate native event config so the disabled extension's events+ # are stripped from installed integrations.+ _refresh_events_and_warn(project_root)+@extension_app.command("set-priority")def extension_set_priority(diff --git a/src/specify_cli/integrations/_install_commands.py b/src/specify_cli/integrations/_install_commands.pyindex 372a335fd..fc39dc886 100644--- a/src/specify_cli/integrations/_install_commands.py+++ b/src/specify_cli/integrations/_install_commands.py@@ -143,12 +143,21 @@ def integration_install(integration.key, project_root, version=_get_speckit_version())+ from ..events import resolve_events+ events_map = resolve_events(+ integration.key,+ integration.config,+ project_root,+ parsed_options,+ )+try:integration.setup(project_root, manifest,parsed_options=parsed_options,script_type=selected_script,raw_options=raw_options,+ events=events_map,)manifest.save()new_installed = _dedupe_integration_keys([*installed_keys, integration.key])diff --git a/src/specify_cli/integrations/_migrate_commands.py b/src/specify_cli/integrations/_migrate_commands.pyindex 0ff617ad2..187e5a526 100644--- a/src/specify_cli/integrations/_migrate_commands.py+++ b/src/specify_cli/integrations/_migrate_commands.py@@ -466,12 +466,20 @@ def integration_switch(target_integration.key, project_root, version=_get_speckit_version())+ from ..events import resolve_events+ events_map = resolve_events(+ target_integration.key,+ target_integration.config,+ project_root,+ parsed_options,+ )try:target_integration.setup(project_root, manifest,parsed_options=parsed_options,script_type=selected_script,raw_options=raw_options,+ events=events_map,)manifest.save()_set_default_integration(@@ -763,6 +771,13 @@ def integration_upgrade(console.print(f"Upgrading integration: [cyan]{key}[/cyan]")new_manifest = IntegrationManifest(key, project_root, version=_get_speckit_version())+ from ..events import resolve_events+ events_map = resolve_events(+ key,+ integration.config,+ project_root,+ parsed_options,+ )try:integration.setup(project_root,@@ -770,6 +785,7 @@ def integration_upgrade(parsed_options=parsed_options,script_type=selected_script,raw_options=raw_options,+ events=events_map,)settings = _with_integration_setting(current,diff --git a/src/specify_cli/integrations/base.py b/src/specify_cli/integrations/base.pyindex ef776b18f..cca4f1397 100644--- a/src/specify_cli/integrations/base.py+++ b/src/specify_cli/integrations/base.py@@ -30,6 +30,7 @@ import yamlfrom .._invocation_style import get_invocation_prefix, is_dollar_skills_agentfrom .._toml_string import escape_toml_basic as _escape_toml_basicfrom .._toml_string import has_illegal_toml_control as _has_illegal_toml_control+from ..events import install_integration_events, remove_integration_eventsif TYPE_CHECKING:from .manifest import IntegrationManifest@@ -159,7 +160,17 @@ class IntegrationBase(ABC):@classmethoddef options(cls) -> list[IntegrationOption]:"""Return options this integration accepts. Default: none."""- return []+ opts = []+ if bool(getattr(cls, "CANONICAL_TO_NATIVE", None) and getattr(cls, "events_config_file", None)):+ opts.append(+ IntegrationOption(+ "--events",+ is_flag=False,+ default="true",+ help="Enable/disable runtime events (true|false, default: true)",+ )+ )+ return optsdef effective_invoke_separator(self,@@ -480,7 +491,11 @@ class IntegrationBase(ABC):tracking) would otherwise be deleted even though they are stillmanaged. Subclasses list such paths here to protect them."""- return set()+ exclusions = set()+ if self.supports_events():+ from ..events import events_stale_exclusions+ exclusions.update(events_stale_exclusions(self.key))+ return exclusionsdef commands_dest(self, project_root: Path) -> Path:"""Return the absolute path to the commands output directory.@@ -916,8 +931,32 @@ class IntegrationBase(ABC):Returns ``(removed, skipped)`` file lists."""+ self.remove_events(project_root, manifest)return manifest.uninstall(project_root, force=force)+ def emit_events(+ self,+ project_root: Path,+ manifest: IntegrationManifest,+ events: dict[str, dict[str, Any]] | None = None,+ parsed_options: dict[str, Any] | None = None,+ **opts: Any,+ ) -> list[Path]:+ """Emit native event configuration for this integration."""+ return install_integration_events(self, project_root, manifest, events or {})++ def remove_events(+ self,+ project_root: Path,+ manifest: IntegrationManifest,+ ) -> None:+ """Remove Specify-authored event entries from native config."""+ remove_integration_events(self, project_root, manifest)++ def supports_events(self) -> bool:+ """Return True if this integration supports agent-native events."""+ return bool(getattr(self, "CANONICAL_TO_NATIVE", None) and getattr(self, "events_config_file", None))+# -- Convenience helpers for subclasses -------------------------------def install(@@ -1022,6 +1061,12 @@ class MarkdownIntegration(IntegrationBase):created.append(dst_file)+ # Install agent runtime events+ event_files = self.emit_events(+ project_root, manifest, events=opts.get("events"), parsed_options=parsed_options+ )+ created.extend(event_files)+return created@@ -1229,6 +1274,12 @@ class TomlIntegration(IntegrationBase):created.append(dst_file)+ # Install agent runtime events+ event_files = self.emit_events(+ project_root, manifest, events=opts.get("events"), parsed_options=parsed_options+ )+ created.extend(event_files)+return created@@ -1465,6 +1516,12 @@ class YamlIntegration(IntegrationBase):created.append(dst_file)+ # Install agent runtime events+ event_files = self.emit_events(+ project_root, manifest, events=opts.get("events"), parsed_options=parsed_options+ )+ created.extend(event_files)+return created@@ -1741,4 +1798,10 @@ class SkillsIntegration(IntegrationBase):created.append(dst)+ # Install agent runtime events+ event_files = self.emit_events(+ project_root, manifest, events=opts.get("events"), parsed_options=parsed_options+ )+ created.extend(event_files)+return createddiff --git a/src/specify_cli/integrations/claude/__init__.py b/src/specify_cli/integrations/claude/__init__.pyindex 923a77607..39732794a 100644--- a/src/specify_cli/integrations/claude/__init__.py+++ b/src/specify_cli/integrations/claude/__init__.py@@ -54,6 +54,17 @@ class ClaudeIntegration(SkillsIntegration):}multi_install_safe = True+ CANONICAL_TO_NATIVE = {+ "session_start": "SessionStart",+ "pre_tool_use": "PreToolUse",+ "post_tool_use": "PostToolUse",+ "session_end": "SessionEnd",+ "user_prompt_submit": "UserPromptSubmit",+ "stop": "Stop",+ }+ events_config_file = ".claude/settings.json"+ events_format = "json-nested"+@staticmethoddef inject_argument_hint(content: str, hint: str) -> str:"""Insert ``argument-hint`` after the first ``description:`` in YAML frontmatter.diff --git a/src/specify_cli/integrations/codex/__init__.py b/src/specify_cli/integrations/codex/__init__.pyindex 7d1ff86e2..2ffa59ca4 100644--- a/src/specify_cli/integrations/codex/__init__.py+++ b/src/specify_cli/integrations/codex/__init__.py@@ -29,6 +29,17 @@ class CodexIntegration(SkillsIntegration):dev_no_symlink = Truemulti_install_safe = True+ CANONICAL_TO_NATIVE = {+ "session_start": "SessionStart",+ "pre_tool_use": "PreToolUse",+ "post_tool_use": "PostToolUse",+ "session_end": "SessionEnd",+ "user_prompt_submit": "UserPromptSubmit",+ "stop": "Stop",+ }+ events_config_file = ".codex/config.toml"+ events_format = "toml"+def build_exec_args(self,prompt: str,@@ -49,11 +60,13 @@ class CodexIntegration(SkillsIntegration):@classmethoddef options(cls) -> list[IntegrationOption]:- return [+ opts = super().options()+ opts.append(IntegrationOption("--skills",is_flag=True,default=True,help="Install as agent skills (default for Codex)",- ),- ]+ )+ )+ return optsdiff --git a/src/specify_cli/integrations/copilot/__init__.py b/src/specify_cli/integrations/copilot/__init__.pyindex ef4470b5f..17563dcb6 100644--- a/src/specify_cli/integrations/copilot/__init__.py+++ b/src/specify_cli/integrations/copilot/__init__.py@@ -118,6 +118,19 @@ class CopilotIntegration(IntegrationBase):"extension": ".agent.md",}+ CANONICAL_TO_NATIVE = {+ "session_start": "sessionStart",+ "pre_tool_use": "preToolUse",+ "post_tool_use": "postToolUse",+ "session_end": "sessionEnd",+ "user_prompt_submit": "userPromptSubmitted",+ # Copilot CLI supports the canonical per-turn stop lifecycle as native+ # agentStop (U3); mapping it so an extension's stop handler fires.+ "stop": "agentStop",+ }+ events_config_file = ".github/hooks/speckit.json"+ events_format = "copilot-json"+# Mutable flag set by setup() β indicates the active scaffolding mode._skills_mode: bool = False@@ -162,14 +175,19 @@ class CopilotIntegration(IntegrationBase):@classmethoddef options(cls) -> list[IntegrationOption]:- return [+ # Compose with super() so the base class declares --events for this+ # event-capable integration; otherwise --integration-options+ # "--events false" is rejected as unknown (#9).+ opts = super().options()+ opts.append(IntegrationOption("--skills",is_flag=True,default=False,help="Scaffold commands as agent skills (speckit-<name>/SKILL.md) instead of .agent.md files",),- ]+ )+ return optsdef _resolve_executable(self) -> str:"""Return the Copilot CLI executable, respecting the env-var override.@@ -328,7 +346,9 @@ class CopilotIntegration(IntegrationBase):be flagged stale and deleted, destroying user settings (and the filethe integration still manages)."""- return {".vscode/settings.json"}+ exclusions = super().stale_cleanup_exclusions()+ exclusions.add(".vscode/settings.json")+ return exclusionsdef post_process_skill_content(self, content: str) -> str:"""Inject shared hook guidance into Copilot skill content.@@ -355,10 +375,18 @@ class CopilotIntegration(IntegrationBase):parsed_options = parsed_options or {}self._skills_mode = bool(parsed_options.get("skills"))if self._skills_mode:- return self._setup_skills(project_root, manifest, parsed_options, **opts)- if "skills" not in parsed_options:- _warn_legacy_markdown_default()- return self._setup_default(project_root, manifest, parsed_options, **opts)+ created = self._setup_skills(project_root, manifest, parsed_options, **opts)+ else:+ if "skills" not in parsed_options:+ _warn_legacy_markdown_default()+ created = self._setup_default(project_root, manifest, parsed_options, **opts)++ # Install agent runtime events+ event_files = self.emit_events(+ project_root, manifest, events=opts.get("events"), parsed_options=parsed_options+ )+ created.extend(event_files)+ return createddef _setup_default(self,diff --git a/src/specify_cli/integrations/cursor_agent/__init__.py b/src/specify_cli/integrations/cursor_agent/__init__.pyindex 07f2a6318..58bd89b21 100644--- a/src/specify_cli/integrations/cursor_agent/__init__.py+++ b/src/specify_cli/integrations/cursor_agent/__init__.py@@ -38,6 +38,17 @@ class CursorAgentIntegration(SkillsIntegration):multi_install_safe = True+ CANONICAL_TO_NATIVE = {+ "session_start": "sessionStart",+ "pre_tool_use": "preToolUse",+ "post_tool_use": "postToolUse",+ "session_end": "sessionEnd",+ "user_prompt_submit": "beforeSubmitPrompt",+ "stop": "stop",+ }+ events_config_file = ".cursor/hooks.json"+ events_format = "json-flat"+def build_exec_args(self,prompt: str,@@ -92,11 +103,13 @@ class CursorAgentIntegration(SkillsIntegration):@classmethoddef options(cls) -> list[IntegrationOption]:- return [+ opts = super().options()+ opts.append(IntegrationOption("--skills",is_flag=True,default=True,help="Install as agent skills (recommended for Cursor)",- ),- ]+ )+ )+ return optsdiff --git a/src/specify_cli/integrations/devin/__init__.py b/src/specify_cli/integrations/devin/__init__.pyindex 0d60bc954..dea6b5d22 100644--- a/src/specify_cli/integrations/devin/__init__.py+++ b/src/specify_cli/integrations/devin/__init__.py@@ -31,6 +31,20 @@ class DevinIntegration(SkillsIntegration):"extension": "/SKILL.md",}+ CANONICAL_TO_NATIVE = {+ "session_start": "SessionStart",+ "pre_tool_use": "PreToolUse",+ "post_tool_use": "PostToolUse",+ "session_end": "SessionEnd",+ "user_prompt_submit": "UserPromptSubmit",+ "stop": "Stop",+ }+ events_config_file = ".devin/hooks.v1.json"+ # Devin's hooks.v1.json is a root event map ({"PreToolUse": [...]}) with no+ # top-level "hooks" wrapper (U2), unlike the settings.json formats. The+ # json-root-nested writer/remover operate directly on the root event keys.+ events_format = "json-root-nested"+def build_exec_args(self,prompt: str,@@ -55,11 +69,16 @@ class DevinIntegration(SkillsIntegration):@classmethoddef options(cls) -> list[IntegrationOption]:- return [+ # Compose with super() so the base class declares --events for this+ # event-capable integration; otherwise --integration-options+ # "--events false" is rejected as unknown (#8).+ opts = super().options()+ opts.append(IntegrationOption("--skills",is_flag=True,default=True,help="Install as agent skills (default for Devin)",),- ]+ )+ return optsdiff --git a/src/specify_cli/integrations/gemini/__init__.py b/src/specify_cli/integrations/gemini/__init__.pyindex 9a459862a..2200e707c 100644--- a/src/specify_cli/integrations/gemini/__init__.py+++ b/src/specify_cli/integrations/gemini/__init__.py@@ -19,3 +19,22 @@ class GeminiIntegration(TomlIntegration):"extension": ".toml",}multi_install_safe = True++ CANONICAL_TO_NATIVE = {+ "session_start": "SessionStart",+ "pre_tool_use": "BeforeTool",+ "post_tool_use": "AfterTool",+ "session_end": "SessionEnd",+ # Gemini exposes BeforeAgent for the per-turn prompt-submit lifecycle+ # point (S6); its own Claude-hook migration maps UserPromptSubmit to+ # BeforeAgent. Mapping it so extension handlers fire.+ "user_prompt_submit": "BeforeAgent",+ "stop": "AfterAgent",+ }+ events_config_file = ".gemini/settings.json"+ events_format = "json-nested"+ # Gemini measures hook timeouts in milliseconds, unlike Claude/Cursor/Codex+ # which use seconds. The shared formatter converts via _native_timeout (#7)+ # so the default 60s becomes 60000ms instead of terminating the dispatcher+ # after 60ms.+ events_timeout_unit = "ms"diff --git a/src/specify_cli/integrations/opencode/__init__.py b/src/specify_cli/integrations/opencode/__init__.pyindex 0f734b7f4..660fd0b5f 100644--- a/src/specify_cli/integrations/opencode/__init__.py+++ b/src/specify_cli/integrations/opencode/__init__.py@@ -20,6 +20,15 @@ class OpencodeIntegration(MarkdownIntegration):"extension": ".md",}+ CANONICAL_TO_NATIVE = {+ "pre_tool_use": "tool.execute.before",+ "post_tool_use": "tool.execute.after",+ "session_start": "session.created",+ "session_end": "session.deleted",+ }+ events_config_file = "opencode.json"+ events_format = "ts-plugin"+def build_exec_args(self,prompt: str,diff --git a/src/specify_cli/integrations/qwen/__init__.py b/src/specify_cli/integrations/qwen/__init__.pyindex 1e8c15bf9..7ab55d978 100644--- a/src/specify_cli/integrations/qwen/__init__.py+++ b/src/specify_cli/integrations/qwen/__init__.py@@ -19,3 +19,20 @@ class QwenIntegration(MarkdownIntegration):"extension": ".md",}multi_install_safe = True++ CANONICAL_TO_NATIVE = {+ "session_start": "SessionStart",+ "pre_tool_use": "PreToolUse",+ "post_tool_use": "PostToolUse",+ "session_end": "SessionEnd",+ "user_prompt_submit": "UserPromptSubmit",+ "stop": "Stop",+ }+ events_config_file = ".qwen/settings.json"+ events_format = "json-nested"+ # Qwen Code's command hooks measure timeout in milliseconds (default+ # 60000), per the Qwen Code hooks documentation. Declaring the unit makes+ # the shared formatter convert the 60s default to 60000ms instead of+ # emitting timeout: 60 (60 ms), which would terminate the dispatcher+ # before it starts (U1).+ events_timeout_unit = "ms"diff --git a/src/specify_cli/integrations/tabnine/__init__.py b/src/specify_cli/integrations/tabnine/__init__.pyindex 9edf1e160..5e8a803e6 100644--- a/src/specify_cli/integrations/tabnine/__init__.py+++ b/src/specify_cli/integrations/tabnine/__init__.py@@ -19,3 +19,23 @@ class TabnineIntegration(TomlIntegration):"extension": ".toml",}multi_install_safe = True++ CANONICAL_TO_NATIVE = {+ "session_start": "SessionStart",+ "pre_tool_use": "BeforeTool",+ "post_tool_use": "AfterTool",+ "session_end": "SessionEnd",+ # Tabnine's Gemini-compatible schema also provides BeforeAgent and+ # AfterAgent (S7); mapping them so user_prompt_submit and stop+ # extension handlers fire instead of being skipped.+ "user_prompt_submit": "BeforeAgent",+ "stop": "AfterAgent",+ }+ events_config_file = ".tabnine/agent/settings.json"+ events_format = "json-nested"+ # Tabnine mirrors Gemini's hook schema (BeforeTool/AfterTool) and, like+ # Gemini, measures hook timeouts in milliseconds. Declaring the unit makes+ # the shared formatter convert the 60s default to 60000ms instead of+ # emitting timeout: 60 (60 ms), which would terminate the dispatcher+ # before it starts (R5).+ events_timeout_unit = "ms"diff --git a/tests/integrations/test_events.py b/tests/integrations/test_events.pynew file mode 100644index 000000000..362a4aed9--- /dev/null+++ b/tests/integrations/test_events.py@@ -0,0 +1,2226 @@+"""Tests for events module: integration runtime events."""++from __future__ import annotations++import json+import os+import platform+import shlex+from pathlib import Path, PurePath+from unittest.mock import MagicMock, patch++import pytest++from specify_cli.events import (+ CANONICAL_EVENTS,+ EVENTS_DISPATCHER_REL,+ collect_extension_events,+ install_integration_events,+ remove_integration_events,+ resolve_events,+ validate_events,+ resolve_and_run_event_command,+)+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.opencode import OpencodeIntegration+from specify_cli.integrations.copilot import CopilotIntegration+++# -- resolve_events --------------------------------------------------------++class TestResolveEvents:+ """Test the 4-layer event resolution chain."""++ def test_layer1_disabled_returns_empty(self, tmp_path):+ """--events false returns empty dict."""+ result = resolve_events(+ "claude",+ {"events": {"post_tool_use": {"command": "speckit.tdd.validate"}}},+ tmp_path,+ {"events": "false"},+ )+ assert result == {}++ def test_layer4_built_in_defaults(self, tmp_path):+ """Returns baseline defaults when no overrides exist."""+ result = resolve_events(+ "claude",+ {"events": {"post_tool_use": {"command": "speckit.tdd.validate"}}},+ tmp_path,+ None,+ )+ assert result == {"post_tool_use": [{"command": "speckit.tdd.validate"}]}++ def test_layer3_extension_events_appended(self, tmp_path):+ """Extension-declared events are resolved and appended."""+ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ ext_dir.mkdir(parents=True)+ ext_yml = ext_dir / "extension.yml"+ ext_yml.write_text(+ "events:\n session_start:\n command: speckit.my-ext.boot\n",+ encoding="utf-8",+ )++ result = resolve_events(+ "claude",+ {"events": {"post_tool_use": {"command": "speckit.tdd.validate"}}},+ tmp_path,+ None,+ )+ assert "post_tool_use" in result+ assert "session_start" in result+ assert result["session_start"] == [{"command": "speckit.my-ext.boot"}]++ def test_layer3_multiple_extensions_same_event_accumulate(self, tmp_path):+ """Two extensions declaring the same event both run (#2)."""+ for ext_id, cmd in (("my-ext", "speckit.my-ext.boot"), ("other-ext", "speckit.other.boot")):+ ext_dir = tmp_path / ".specify" / "extensions" / ext_id+ ext_dir.mkdir(parents=True)+ (ext_dir / "extension.yml").write_text(+ f"events:\n session_start:\n command: {cmd}\n",+ encoding="utf-8",+ )+ result = resolve_events("claude", None, tmp_path, None)+ assert result["session_start"] == [+ {"command": "speckit.my-ext.boot"},+ {"command": "speckit.other.boot"},+ ]++ def test_layer2_yaml_override_replaces(self, tmp_path):+ """integration-events.yml override replaces baseline entirely."""+ override_file = tmp_path / ".specify" / "integration-events.yml"+ override_file.parent.mkdir(parents=True, exist_ok=True)+ override_file.write_text(+ "integrations:\n"+ " claude:\n"+ " events:\n"+ " stop:\n"+ " command: speckit.override.stop\n",+ encoding="utf-8",+ )++ result = resolve_events(+ "claude",+ {"events": {"post_tool_use": {"command": "speckit.tdd.validate"}}},+ tmp_path,+ None,+ )+ assert result == {"stop": [{"command": "speckit.override.stop"}]}++ def test_layer2_empty_events_disables(self, tmp_path):+ """Empty events override disables events."""+ override_file = tmp_path / ".specify" / "integration-events.yml"+ override_file.parent.mkdir(parents=True, exist_ok=True)+ override_file.write_text(+ "integrations:\n"+ " claude:\n"+ " events: {}\n",+ encoding="utf-8",+ )++ result = resolve_events(+ "claude",+ {"events": {"post_tool_use": {"command": "speckit.tdd.validate"}}},+ tmp_path,+ None,+ )+ assert result == {}++ def test_no_config_no_events(self, tmp_path):+ """Safe fallback with empty config/options."""+ result = resolve_events("claude", None, tmp_path, None)+ assert result == {}+++# -- collect_extension_events -----------------------------------------------++class TestCollectExtensionEvents:+ """Test scanning extension.yml files for events: declarations."""++ def test_no_extensions_dir(self, tmp_path):+ assert collect_extension_events(tmp_path) == {}++ def test_no_events_in_extension(self, tmp_path):+ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ ext_dir.mkdir(parents=True)+ (ext_dir / "extension.yml").write_text("extension:\n id: my-ext\n", encoding="utf-8")+ assert collect_extension_events(tmp_path) == {}++ def test_events_collected(self, tmp_path):+ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ ext_dir.mkdir(parents=True)+ (ext_dir / "extension.yml").write_text(+ "events:\n pre_tool_use:\n command: speckit.my-ext.check\n",+ encoding="utf-8",+ )+ result = collect_extension_events(tmp_path)+ assert result == {"pre_tool_use": [{"command": "speckit.my-ext.check"}]}++ def test_invalid_yaml_skipped(self, tmp_path):+ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ ext_dir.mkdir(parents=True)+ (ext_dir / "extension.yml").write_text("invalid: - - -", encoding="utf-8")+ assert collect_extension_events(tmp_path) == {}++ def test_event_command_ref_canonicalized_via_manifest(self, tmp_path):+ """R1: events are read from a validated ExtensionManifest, so an+ obsolete command ref (e.g. my-ext.boot) is canonicalized+ (speckit.my-ext.boot) the same way hook refs are at install."""+ from specify_cli.extensions import ExtensionRegistry+ import yaml as _yaml++ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ ext_dir.mkdir(parents=True)+ # Manifest declares an alias-form event command ref (my-ext.boot)+ # alongside the command it resolves to; the validated manifest lifts+ # the ref to speckit.my-ext.boot (C11).+ (ext_dir / "extension.yml").write_text(+ _yaml.dump({+ "schema_version": "1.0",+ "extension": {+ "id": "my-ext",+ "name": "My Ext",+ "version": "1.0.0",+ "description": "test",+ },+ "requires": {"speckit_version": ">=0.1"},+ "provides": {+ "commands": [+ {"name": "speckit.my-ext.boot", "file": "commands/boot.md"}+ ]+ },+ "events": {"session_start": {"command": "my-ext.boot"}},+ }),+ encoding="utf-8",+ )+ ExtensionRegistry(tmp_path / ".specify" / "extensions").add(+ "my-ext", {"enabled": True}+ )++ result = collect_extension_events(tmp_path)+ # The ref was canonicalized to speckit.my-ext.boot by the validated+ # manifest, so dispatch can match it (raw-YAML reading would have+ # emitted the obsolete my-ext.boot and the hook would no-op).+ assert result == {"session_start": [{"command": "speckit.my-ext.boot"}]}+++# -- Class-driven mappings --------------------------------------------------++class TestCanonicalEventMapping:+ """Verify registry-driven mapping is correct on integration classes."""++ def test_claude_identity(self):+ integration = ClaudeIntegration()+ assert integration.supports_events() is True+ assert integration.CANONICAL_TO_NATIVE["pre_tool_use"] == "PreToolUse"+ assert integration.CANONICAL_TO_NATIVE["session_start"] == "SessionStart"++ def test_cursor_camelcase(self):+ integration = CursorAgentIntegration()+ assert integration.supports_events() is True+ assert integration.CANONICAL_TO_NATIVE["pre_tool_use"] == "preToolUse"+ assert integration.CANONICAL_TO_NATIVE["user_prompt_submit"] == "beforeSubmitPrompt"++ def test_opencode_limited(self):+ integration = OpencodeIntegration()+ assert integration.supports_events() is True+ assert integration.CANONICAL_TO_NATIVE["pre_tool_use"] == "tool.execute.before"+ assert "stop" not in integration.CANONICAL_TO_NATIVE++ def test_copilot_mapping(self):+ integration = CopilotIntegration()+ assert integration.supports_events() is True+ assert integration.CANONICAL_TO_NATIVE["session_start"] == "sessionStart"+ assert integration.CANONICAL_TO_NATIVE["user_prompt_submit"] == "userPromptSubmitted"++ def test_gemini_mapping_includes_before_agent(self):+ # S6: Gemini exposes BeforeAgent for user_prompt_submit and AfterAgent+ # for stop (verified against Gemini CLI's hooks docs).+ from specify_cli.integrations.gemini import GeminiIntegration+ integration = GeminiIntegration()+ assert integration.CANONICAL_TO_NATIVE["pre_tool_use"] == "BeforeTool"+ assert integration.CANONICAL_TO_NATIVE["user_prompt_submit"] == "BeforeAgent"+ assert integration.CANONICAL_TO_NATIVE["stop"] == "AfterAgent"++ def test_tabnine_mapping_includes_before_agent(self):+ # S7: Tabnine's Gemini-compatible schema provides BeforeAgent/AfterAgent.+ from specify_cli.integrations.tabnine import TabnineIntegration+ integration = TabnineIntegration()+ assert integration.CANONICAL_TO_NATIVE["user_prompt_submit"] == "BeforeAgent"+ assert integration.CANONICAL_TO_NATIVE["stop"] == "AfterAgent"+++# -- Event-capable adapters declare --events (#8, #9) ------------------------++class TestEventCapableOptionsComposition:+ """Event-capable integrations must declare --events so the documented+ --events false opt-out is accepted."""++ def _has_option(self, opts, name):+ return any(o.name == name for o in opts)++ def test_copilot_declares_events(self):+ # #9: CopilotIntegration.options() composed with super() so --events+ # is declared alongside --skills.+ opts = CopilotIntegration().options()+ assert self._has_option(opts, "--skills")+ assert self._has_option(opts, "--events"), (+ "Copilot is event-capable but --events is not declared; "+ "--integration-options \"--events false\" would be rejected."+ )++ def test_devin_declares_events(self):+ # #8: DevinIntegration.options() composed with super() so --events+ # is declared alongside --skills.+ from specify_cli.integrations.devin import DevinIntegration+ opts = DevinIntegration().options()+ assert self._has_option(opts, "--skills")+ assert self._has_option(opts, "--events"), (+ "Devin is event-capable but --events is not declared; "+ "--integration-options \"--events false\" would be rejected."+ )++ def test_cursor_declares_events(self):+ # Cursor already composed correctly; assert it stays that way.+ opts = CursorAgentIntegration().options()+ assert self._has_option(opts, "--skills")+ assert self._has_option(opts, "--events")++ def test_codex_declares_events(self):+ # Codex already composed correctly; assert it stays that way.+ from specify_cli.integrations.codex import CodexIntegration+ opts = CodexIntegration().options()+ assert self._has_option(opts, "--skills")+ assert self._has_option(opts, "--events")+++# -- validate_events --------------------------------------------------------++class TestValidateEvents:+ """Test manifest validation."""++ def test_unknown_event_rejected(self):+ from specify_cli.extensions import ValidationError+ data = {"events": {"unknown_event": {"command": "speckit.tdd.validate"}}}+ with pytest.raises(ValidationError) as exc:+ validate_events(data)+ assert "Unknown event" in str(exc.value)++ def test_known_event_accepted(self):+ data = {"events": {"pre_tool_use": {"command": "speckit.tdd.validate"}}}+ validate_events(data) # no raise++ def test_all_canonical_events_accepted(self):+ data = {+ "events": {+ name: {"command": "speckit.test"}+ for name in CANONICAL_EVENTS+ }+ }+ validate_events(data) # no raise+++# -- Claude settings JSON merging -------------------------------------------++class TestClaudeJsonMerging:+ """Test Claude settings JSON merging and cleanup."""++ def test_merge_into_empty_file(self, tmp_path):+ integration = ClaudeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ events = {+ "pre_tool_use": [{"command": "speckit.tdd.validate", "matcher": "Edit|Write"}],+ }+ install_integration_events(integration, tmp_path, manifest, events)++ config_path = tmp_path / ".claude/settings.json"+ assert config_path.is_file()+ data = json.loads(config_path.read_text())+ assert "hooks" in data+ assert "PreToolUse" in data["hooks"]+ assert data["hooks"]["PreToolUse"][0]["matcher"] == "Edit|Write"+ # #6: native schema is a single `command` string, not command+args.+ inner = data["hooks"]["PreToolUse"][0]["hooks"][0]+ assert isinstance(inner["command"], str)+ assert "args" not in inner+ assert "speckit.tdd.validate" in inner["command"]+ assert "pre_tool_use" in inner["command"]+ # The dispatcher path must be prefixed with ${CLAUDE_PROJECT_DIR}/ for+ # Claude, and double-quoted so a project path with spaces doesn't+ # word-split (C2) while the variable still expands.+ assert "${CLAUDE_PROJECT_DIR}/" in inner["command"]+ assert '"${CLAUDE_PROJECT_DIR}/.specify/events.py"' in inner["command"]++ def test_claude_emits_all_handlers_for_same_event(self, tmp_path):+ """#2: two handlers on the same event both appear in the native config."""+ integration = ClaudeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ events = {+ "pre_tool_use": [+ {"command": "speckit.tdd.validate"},+ {"command": "speckit.other.check"},+ ],+ }+ install_integration_events(integration, tmp_path, manifest, events)++ data = json.loads((tmp_path / ".claude/settings.json").read_text())+ inner_hooks = data["hooks"]["PreToolUse"][0]["hooks"]+ commands = [h["command"] for h in inner_hooks]+ assert any("speckit.tdd.validate" in c for c in commands)+ assert any("speckit.other.check" in c for c in commands)++ def test_remove_preserves_user_hooks(self, tmp_path):+ integration = ClaudeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ # Pre-seed user setting+ config_path = tmp_path / ".claude/settings.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ config_path.write_text(+ json.dumps(+ {+ "hooks": {+ "PreToolUse": [+ {+ "matcher": "Bash",+ "hooks": [+ {+ "type": "command",+ "command": "user-check",+ }+ ],+ }+ ]+ }+ }+ )+ )++ events = {+ "pre_tool_use": [{"command": "speckit.tdd.validate"}],+ }+ install_integration_events(integration, tmp_path, manifest, events)+ remove_integration_events(integration, tmp_path, manifest)++ data = json.loads(config_path.read_text())+ assert "hooks" in data+ assert "PreToolUse" in data["hooks"]+ assert len(data["hooks"]["PreToolUse"]) == 1+ assert data["hooks"]["PreToolUse"][0]["matcher"] == "Bash"+++# -- Copilot events JSON writing --------------------------------------------++class TestCopilotJsonWriting:+ """Test Copilot dedicated .github/hooks/speckit.json generation."""++ def test_copilot_json_generation(self, tmp_path):+ integration = CopilotIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ events = {+ "session_start": [{"command": "speckit.agent-context.update", "timeout": 60}],+ }+ install_integration_events(integration, tmp_path, manifest, events)++ config_path = tmp_path / ".github/hooks/speckit.json"+ assert config_path.is_file()+ data = json.loads(config_path.read_text())+ assert data["version"] == 1+ assert "hooks" in data+ assert "sessionStart" in data["hooks"]+ entry = data["hooks"]["sessionStart"][0]+ assert entry["type"] == "command"+ # #6: a complete shell command string (not command+args).+ assert "speckit.agent-context.update" in entry["bash"]+ assert "session_start" in entry["bash"]+ # S4: bash and powershell get independent OS-targeted interpreters so+ # a config generated on one OS works on the other. R2: command/event+ # args are shell-quoted for each target shell.+ assert "speckit.agent-context.update" in entry["powershell"]+ assert entry["bash"] != entry["powershell"]+ # bash uses POSIX interpreter python3 (shlex.quote leaves safe tokens+ # bare); powershell uses python single-quoted with the & call operator+ # so the quoted command is actually invoked (C1).+ assert entry["bash"].startswith("python3 ")+ assert entry["powershell"].startswith("& 'python' ")+ # PowerShell always single-quotes; POSIX leaves metacharacter-free+ # identifiers bare (shlex.quote only quotes when needed).+ assert "'speckit.agent-context.update'" in entry["powershell"]+ assert "speckit.agent-context.update" in entry["bash"]+ # R2: native timeout gets the buffer (60 + 5 = 65) so the agent's+ # outer cap fires after the dispatcher's inner subprocess timeout.+ assert entry["timeoutSec"] == 65+++# -- Cursor hooks.json version + matcher grouping (#7, S3) -------------------++class TestCursorJsonWriting:+ """#7: .cursor/hooks.json requires top-level version:1; S3: matcher grouping."""++ def test_cursor_json_includes_version(self, tmp_path):+ integration = CursorAgentIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ install_integration_events(+ integration, tmp_path, manifest,+ {"session_start": [{"command": "speckit.boot"}]},+ )+ data = json.loads((tmp_path / ".cursor/hooks.json").read_text())+ assert data["version"] == 1+ assert "sessionStart" in data["hooks"]++ def test_cursor_json_preserves_user_version(self, tmp_path):+ integration = CursorAgentIntegration()+ config_path = tmp_path / ".cursor/hooks.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ config_path.write_text(json.dumps({"version": 1, "hooks": {}}))++ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ install_integration_events(+ integration, tmp_path, manifest,+ {"session_start": [{"command": "speckit.boot"}]},+ )+ data = json.loads(config_path.read_text())+ assert data["version"] == 1++ def test_nested_matcher_grouping_per_distinct_matcher(self, tmp_path):+ """S3: two handlers with different matchers produce two matcher-groups."""+ integration = ClaudeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ events = {+ "pre_tool_use": [+ {"command": "speckit.first", "matcher": "Edit"},+ {"command": "speckit.second", "matcher": "Bash"},+ ],+ }+ install_integration_events(integration, tmp_path, manifest, events)+ data = json.loads((tmp_path / ".claude/settings.json").read_text())+ groups = data["hooks"]["PreToolUse"]+ matchers = sorted(g["matcher"] for g in groups)+ assert matchers == ["Bash", "Edit"]+ # Each group holds exactly its own handler.+ by_matcher = {g["matcher"]: g["hooks"] for g in groups}+ assert len(by_matcher["Edit"]) == 1+ assert "speckit.first" in by_matcher["Edit"][0]["command"]+ assert len(by_matcher["Bash"]) == 1+ assert "speckit.second" in by_matcher["Bash"][0]["command"]++ def test_nested_shared_matcher_stays_one_group(self, tmp_path):+ """S3: handlers sharing a matcher stay in a single matcher-group."""+ integration = ClaudeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ events = {+ "pre_tool_use": [+ {"command": "speckit.first", "matcher": "Edit"},+ {"command": "speckit.second", "matcher": "Edit"},+ ],+ }+ install_integration_events(integration, tmp_path, manifest, events)+ data = json.loads((tmp_path / ".claude/settings.json").read_text())+ groups = data["hooks"]["PreToolUse"]+ assert len(groups) == 1+ assert groups[0]["matcher"] == "Edit"+ assert len(groups[0]["hooks"]) == 2+++# -- Gemini timeout unit (#7) ------------------------------------------------++class TestGeminiTimeoutUnit:+ """Gemini measures hook timeouts in milliseconds, not seconds."""++ def test_gemini_timeout_converted_to_ms(self, tmp_path):+ from specify_cli.integrations.gemini import GeminiIntegration+ from specify_cli.events import _native_timeout++ integration = GeminiIntegration()+ # 60 (seconds) -> 60000 (ms) for Gemini; unchanged for seconds-based agents.+ assert _native_timeout(integration, 60) == 60000+ assert _native_timeout(ClaudeIntegration(), 60) == 60++ def test_tabnine_timeout_converted_to_ms(self):+ """R5: Tabnine mirrors Gemini's ms-based hook schema."""+ from specify_cli.integrations.tabnine import TabnineIntegration+ from specify_cli.events import _native_timeout++ assert _native_timeout(TabnineIntegration(), 60) == 60000++ def test_qwen_timeout_converted_to_ms(self):+ """U1: Qwen Code command hooks use milliseconds (default 60000)."""+ from specify_cli.integrations.qwen import QwenIntegration+ from specify_cli.events import _native_timeout++ assert _native_timeout(QwenIntegration(), 60) == 60000+++# -- Devin root-nested format (U2) + Copilot agentStop (U3) ------------------++class TestDevinRootNestedFormat:+ """U2: Devin's hooks.v1.json is a root event map with no 'hooks' wrapper."""++ def test_devin_events_written_at_root(self, tmp_path):+ from specify_cli.integrations.devin import DevinIntegration+ integration = DevinIntegration()+ assert integration.events_format == "json-root-nested"++ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ manifest.remove = MagicMock()++ install_integration_events(+ integration, tmp_path, manifest,+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ data = json.loads((tmp_path / ".devin/hooks.v1.json").read_text())+ # Event keys are top-level (no "hooks" wrapper).+ assert "PreToolUse" in data+ assert "hooks" not in data++ def test_devin_teardown_removes_owned_and_preserves_user(self, tmp_path):+ from specify_cli.integrations.devin import DevinIntegration+ integration = DevinIntegration()+ config_path = tmp_path / ".devin/hooks.v1.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ config_path.write_text(json.dumps({+ "PreToolUse": [{+ "matcher": "exec",+ "hooks": [{"type": "command", "command": "user-check"}],+ }]+ }))++ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ manifest.remove = MagicMock()+ install_integration_events(+ integration, tmp_path, manifest,+ {"stop": [{"command": "speckit.end"}]},+ )+ remove_integration_events(integration, tmp_path, manifest)++ data = json.loads(config_path.read_text())+ # User hook preserved at the root; Specify's Stop gone.+ assert "Stop" not in data+ assert data["PreToolUse"][0]["matcher"] == "exec"+++class TestCopilotAgentStop:+ """U3: Copilot maps the canonical stop lifecycle to native agentStop."""++ def test_copilot_stop_mapping(self):+ integration = CopilotIntegration()+ assert integration.CANONICAL_TO_NATIVE.get("stop") == "agentStop"+++# -- Shell quoting & matcher escaping (R2, R4) -------------------------------++class TestDispatcherCommandQuoting:+ """R2: dispatcher command components are shell-quoted so spaces and shell+ metacharacters are passed as single arguments, not reinterpreted."""++ def test_command_metacharacters_are_quoted_posix(self, tmp_path):+ from specify_cli.events import _dispatcher_command++ cmd = _dispatcher_command(+ ClaudeIntegration(), tmp_path, "speckit.x; rm -rf /", "pre_tool_use",+ target_os="posix",+ )+ # The metacharacter-bearing command is single-quoted as one argument.+ assert "'speckit.x; rm -rf /'" in cmd++ def test_interpreter_with_space_is_quoted_posix(self, tmp_path):+ import shlex+ from specify_cli.events import _dispatcher_command+ # Simulate a venv interpreter under a path with spaces.+ venv = tmp_path / ".venv" / "bin" / "python"+ venv.parent.mkdir(parents=True)+ venv.write_text("#!/bin/sh\n")+ proj = tmp_path+ cmd = _dispatcher_command(+ ClaudeIntegration(), proj, "speckit.x.y", "stop", target_os="host",+ )+ # The command must tokenize back into interpreter + dispatcher + 2 args.+ tokens = shlex.split(cmd)+ # dispatcher token carries the ${CLAUDE_PROJECT_DIR} prefix (double-+ # quoted in the raw string, but shlex.split strips the quotes).+ assert any("events.py" in t for t in tokens)+ assert "speckit.x.y" in tokens+ assert "stop" in tokens++ def test_windows_target_uses_powershell_quoting(self, tmp_path):+ from specify_cli.events import _dispatcher_command++ cmd = _dispatcher_command(+ CopilotIntegration(), tmp_path, "speckit.x.y", "session_start",+ target_os="windows",+ )+ # PowerShell single-quoted literals, and the & call operator so the+ # quoted interpreter is actually invoked (C1).+ assert cmd.startswith("& ")+ assert "'speckit.x.y'" in cmd+ assert "'session_start'" in cmd++ def test_host_target_never_emits_powershell_quotes(self, tmp_path):+ """C1: the host target uses POSIX quoting on every platform so a+ single-command-string hook (Claude/Gemini/etc.) stays invocable β+ never 'python' (which PowerShell wouldn't invoke without &)."""+ from specify_cli.events import _shell_quote+ # Safe tokens pass through bare under host (POSIX), not PS-quoted.+ assert _shell_quote("python3", "host") == "python3"+ assert _shell_quote("speckit.x.y", "host") == "speckit.x.y"++ def test_claude_dispatcher_double_quoted_for_spaces(self, tmp_path):+ """C2: Claude's ${CLAUDE_PROJECT_DIR} dispatcher path is double-quoted+ so a project path containing spaces doesn't word-split."""+ from specify_cli.events import _dispatcher_command+ cmd = _dispatcher_command(+ ClaudeIntegration(), tmp_path, "speckit.x.y", "stop", target_os="host",+ )+ assert '"${CLAUDE_PROJECT_DIR}/.specify/events.py"' in cmd+++class TestTomlMatcherEscaping:+ """R4: the TOML matcher is escaped like command, not raw-interpolated."""++ def test_matcher_with_quote_stays_valid_toml(self, tmp_path):+ from specify_cli.integrations.codex import CodexIntegration++ integration = CodexIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ manifest.remove = MagicMock()++ # A matcher containing a double quote would break a raw TOML basic+ # string; it must be escaped.+ install_integration_events(+ integration, tmp_path, manifest,+ {"pre_tool_use": [{"command": "speckit.x.y", "matcher": 'Ba"sh'}]},+ )+ content = (tmp_path / ".codex" / "config.toml").read_text()+ # Round-trips through a TOML parser without error.+ try:+ import tomllib+ parsed = tomllib.loads(content)+ except ModuleNotFoundError:+ import tomli as tomllib # type: ignore+ parsed = tomllib.loads(content)+ # The matcher value survived intact.+ group = parsed["hooks"]["PreToolUse"][0]+ assert group["matcher"] == 'Ba"sh'+++# -- Opencode TS Plugin merging ---------------------------------------------++class TestOpencodePluginMerging:+ """Test Opencode typescript plugin generation."""++ def test_opencode_ts_plugin_generation(self, tmp_path):+ integration = OpencodeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ events = {+ "pre_tool_use": [{"command": "speckit.tdd.validate", "matcher": "Edit"}],+ "session_start": [{"command": "speckit.agent-context.update"}],+ }+ install_integration_events(integration, tmp_path, manifest, events)++ plugin_path = tmp_path / ".opencode/plugin/speckit-events.ts"+ assert plugin_path.is_file()+ content = plugin_path.read_text()+ assert "runEvent" in content+ assert "tool.execute.before" in content+ assert "session.created" in content+ assert "speckit.tdd.validate" in content+ assert "speckit.agent-context.update" in content+ # #13: failures must propagate via throw, not process.exit(2) which+ # would kill the OpenCode host process.+ assert "process.exit(2)" not in content+ assert "throw new Error" in content++ def test_opencode_ts_plugin_resolves_interpreter_and_directory_at_load(self, tmp_path):+ """C8/C9: the dispatcher + interpreter are resolved per-project at+ plugin load from the `directory` OpenCode passes (not process.cwd()),+ preferring a project venv, and the dispatcher is launched via+ execFileSync (argv, no shell)."""+ integration = OpencodeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ # Create a project venv so the plugin's runtime resolver prefers it.+ venv_bin = tmp_path / ".venv" / "bin" / "python"+ venv_bin.parent.mkdir(parents=True)+ venv_bin.write_text("#!/bin/sh\n")++ events = {"session_start": [{"command": "speckit.boot"}]}+ install_integration_events(integration, tmp_path, manifest, events)+ content = (tmp_path / ".opencode/plugin/speckit-events.ts").read_text()+ # Runtime venv-interpreter preference is baked into the resolver.+ assert ".venv" in content and "python" in content+ # Dispatcher is resolved from `directory`, not process.cwd() (C8).+ assert "path.join(process.cwd()" not in content+ assert "directory" in content+ # execFileSync (argv, no shell) instead of a shell command string (C9).+ assert "execFileSync" in content+ assert "execSync(`" not in content+ # R2: venv interpreter is probed for specify_cli importability before+ # selection (an unrelated project venv shouldn't shadow the fallback).+ assert "canImportSpecifyCli" in content+ # S2: the PATH fallback is python on Windows (python3 is commonly+ # absent there), python3 on POSIX.+ assert "process.platform === 'win32'" in content+ assert "'python'" in content+ assert "'python3'" in content++ def test_opencode_ts_plugin_emits_all_handlers(self, tmp_path):+ """#2: multiple handlers on the same native event all invoke runEvent."""+ integration = OpencodeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ events = {+ "session_start": [+ {"command": "speckit.first.boot"},+ {"command": "speckit.second.boot"},+ ],+ }+ install_integration_events(integration, tmp_path, manifest, events)+ content = (tmp_path / ".opencode/plugin/speckit-events.ts").read_text()+ assert "speckit.first.boot" in content+ assert "speckit.second.boot" in content+ # Suppressed #6: each handler call is wrapped in try/catch and errors aggregated.+ assert "try {" in content+ assert "errors.push(" in content+ assert "throw new Error(errors.join" in content++ def test_opencode_ts_plugin_forwards_output(self, tmp_path):+ """C7: tool callbacks forward both input and output to runEvent so+ pre_tool_use can inspect tool args and post_tool_use the result."""+ integration = OpencodeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ events = {+ "pre_tool_use": [{"command": "speckit.tdd.validate", "matcher": "Edit"}],+ "post_tool_use": [{"command": "speckit.tdd.after"}],+ }+ install_integration_events(integration, tmp_path, manifest, events)+ content = (tmp_path / ".opencode/plugin/speckit-events.ts").read_text()+ # runEvent signature carries both input and output. S1: command/event+ # are JSON string literals (double-quoted, escaped). S3: the per-+ # handler timeout (seconds) is threaded as the 5th arg.+ assert 'runEvent("speckit.tdd.validate", "pre_tool_use", input, output, 60)' in content+ assert 'runEvent("speckit.tdd.after", "post_tool_use", input, output, 60)' in content+ # Tool callbacks pass both arguments through.+ assert "_pre_tool_use(input, output)" in content+ assert "_post_tool_use(input, output)" in content++ def test_opencode_ts_plugin_escapes_metacharacters(self, tmp_path):+ """S1: command/matcher values with quotes/backticks are serialized as+ JSON string literals so they can't break the generated TypeScript or+ inject code."""+ integration = OpencodeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()++ # A command and matcher containing characters that would break a+ # single-quoted TS literal.+ events = {+ "pre_tool_use": [{"command": "speckit.x'y`code", "matcher": "Ed'it"}],+ }+ install_integration_events(integration, tmp_path, manifest, events)+ content = (tmp_path / ".opencode/plugin/speckit-events.ts").read_text()+ # The value must appear inside a JSON double-quoted literal, not a+ # single-quoted TS literal (which a quote/backtick would break).+ assert json.dumps("speckit.x'y`code") in content+ # The dangerous single-quoted form (runEvent('speckit.x'y...')) β+ # where the embedded quote would terminate the literal β is absent.+ assert "runEvent('speckit.x" not in content+ assert json.dumps("ed'it") in content+++# -- Command runner test (core execution) -----------------------------------++class TestCommandRunner:+ """Test the core command/script resolution and runner."""++ def test_run_command_not_found(self, tmp_path):+ code = resolve_and_run_event_command("nonexistent.command", "session_start", "{}", tmp_path)+ assert code == 0 # no-ops gracefully++ def test_extension_command_resolves_when_file_stem_differs(self, tmp_path):+ """S8: an extension command whose declared file differs from its+ command name resolves via the manifest, not a file-stem scan."""+ from specify_cli.events import _find_command_template+ from specify_cli.extensions import ExtensionRegistry++ ext_id = "selftest"+ ext_dir = tmp_path / ".specify" / "extensions" / ext_id+ cmds_dir = ext_dir / "commands"+ cmds_dir.mkdir(parents=True)+ # Command name is speckit.selftest.extension but the file is selftest.md.+ (ext_dir / "extension.yml").write_text(+ "schema_version: '1.0'\n"+ "extension:\n"+ " id: selftest\n"+ " name: Selftest\n"+ " version: 1.0.0\n"+ " description: test\n"+ "requires:\n"+ " speckit_version: '>=0.1'\n"+ "provides:\n"+ " commands:\n"+ " - name: speckit.selftest.extension\n"+ " file: commands/selftest.md\n",+ encoding="utf-8",+ )+ (cmds_dir / "selftest.md").write_text(+ "---\ndescription: \"x\"\n---\nBody\n", encoding="utf-8"+ )+ ExtensionRegistry(tmp_path / ".specify" / "extensions").add(+ ext_id, {"enabled": True}+ )++ template, resolved_ext = _find_command_template(+ "speckit.selftest.extension", tmp_path+ )+ assert template is not None+ assert template.name == "selftest.md"+ assert resolved_ext == ext_id++ def test_disabled_extension_command_not_resolved(self, tmp_path):+ """S1: a disabled extension's command is skipped by+ _find_command_template (both the manifest loop and the disk-fallback+ scan), so a stale hook can't execute a disabled extension."""+ from specify_cli.events import _find_command_template+ from specify_cli.extensions import ExtensionRegistry+ import yaml as _yaml++ # Manifest-resolvable path (step 1).+ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ cmds_dir = ext_dir / "commands"+ cmds_dir.mkdir(parents=True)+ (ext_dir / "extension.yml").write_text(+ _yaml.dump({+ "schema_version": "1.0",+ "extension": {"id": "my-ext", "name": "My Ext", "version": "1.0.0",+ "description": "test"},+ "requires": {"speckit_version": ">=0.1"},+ "provides": {"commands": [{"name": "speckit.my-ext.boot",+ "file": "commands/boot.md"}]},+ "events": {"session_start": {"command": "speckit.my-ext.boot"}},+ }),+ encoding="utf-8",+ )+ (cmds_dir / "boot.md").write_text("---\ndescription: \"x\"\n---\nBody\n", encoding="utf-8")+ ExtensionRegistry(tmp_path / ".specify" / "extensions").add(+ "my-ext", {"enabled": False}+ )+ template, _ = _find_command_template("speckit.my-ext.boot", tmp_path)+ assert template is None, "Disabled extension's command was resolved (manifest loop)."++ # Disk-fallback path (step 2): stem == command name.+ (cmds_dir / "speckit.my-ext.boot.md").write_text("---\ndescription: \"x\"\n---\nBody\n", encoding="utf-8")+ template, _ = _find_command_template("speckit.my-ext.boot", tmp_path)+ assert template is None, "Disabled extension's command was resolved (disk fallback)."++ def test_run_command_resolves_and_executes(self, tmp_path):+ # Create a mock core command md file+ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ cmd_file = cmd_dir / "test.md"+ cmd_file.write_text(+ "---\n"+ "description: \"Test\"\n"+ "scripts:\n"+ " sh: scripts/test.sh\n"+ "---\n"+ "Body\n",+ encoding="utf-8",+ )++ script_dir = tmp_path / ".specify" / "scripts"+ script_dir.mkdir(parents=True)+ script_file = script_dir / "test.sh"+ script_file.write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")+ script_file.chmod(0o755)++ # Skip on Windows because sh is POSIX+ if platform.system().lower().startswith("win"):+ return++ code = resolve_and_run_event_command("speckit.test", "session_start", "{}", tmp_path)+ assert code == 0++ def test_py_variant_anchored_under_specify(self, tmp_path):+ """S2: the py variant resolves scripts/... under .specify/, not the+ project root, and prepends the resolved interpreter."""+ from specify_cli.events import _resolve_event_command_argv++ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "boot.md").write_text(+ "---\n"+ "description: \"Boot\"\n"+ "scripts:\n"+ " py: scripts/python/boot.py\n"+ "---\nBody\n",+ encoding="utf-8",+ )+ py_dir = tmp_path / ".specify" / "scripts" / "python"+ py_dir.mkdir(parents=True)+ (py_dir / "boot.py").write_text("import sys; sys.exit(0)\n", encoding="utf-8")++ argv = _resolve_event_command_argv(cmd_dir / "boot.md", tmp_path, None)+ assert argv is not None+ # Interpreter first, then the .specify-anchored script path. Compare in+ # POSIX form so the assertion holds on Windows (backslash paths) too.+ assert len(argv) >= 2+ assert PurePath(argv[1]).as_posix().endswith(".specify/scripts/python/boot.py")+ assert ".specify" in argv[1]++ def test_ps_variant_prefixed_with_powershell_launcher(self, tmp_path):+ """S6: the ps variant prefixes argv with pwsh/powershell -File so+ subprocess.run(shell=False) can execute the .ps1 script."""+ from specify_cli.events import _resolve_event_command_argv++ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "boot.md").write_text(+ "---\n"+ "description: \"Boot\"\n"+ "scripts:\n"+ " ps: scripts/powershell/boot.ps1\n"+ "---\nBody\n",+ encoding="utf-8",+ )+ ps_dir = tmp_path / ".specify" / "scripts" / "powershell"+ ps_dir.mkdir(parents=True)+ (ps_dir / "boot.ps1").write_text("exit 0\n", encoding="utf-8")++ argv = _resolve_event_command_argv(cmd_dir / "boot.md", tmp_path, None)+ assert argv is not None+ # Launcher (pwsh or powershell), -File, then the .specify-anchored+ # script. shutil.which may return a full path with an .EXE suffix on+ # Windows, so match by stem (case-insensitive).+ assert PurePath(argv[0]).stem.lower() in ("pwsh", "powershell")+ assert argv[1] == "-File"+ assert PurePath(argv[2]).as_posix().endswith(".specify/scripts/powershell/boot.ps1")++ def test_run_command_executes_with_project_root_cwd(self, tmp_path):+ """R1: the event command runs with cwd set to the project root, not the+ caller's arbitrary working directory, so project-relative script logic+ resolves correctly even when the agent fires the hook elsewhere."""+ if platform.system().lower().startswith("win"):+ return+ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "cwd.md").write_text(+ "---\ndescription: \"cwd\"\nscripts:\n sh: scripts/cwd.sh\n---\nBody\n",+ encoding="utf-8",+ )+ script_dir = tmp_path / ".specify" / "scripts"+ script_dir.mkdir(parents=True)+ out_file = tmp_path / "cwd.out"+ script = script_dir / "cwd.sh"+ # The script records its working directory.+ script.write_text(f"#!/bin/sh\npwd > {shlex.quote(str(out_file))}\nexit 0\n", encoding="utf-8")+ script.chmod(0o755)++ # Invoke from a different working directory to prove cwd is forced.+ import os as _os+ prev = _os.getcwd()+ subdir = tmp_path / "sub"+ subdir.mkdir()+ try:+ _os.chdir(subdir)+ code = resolve_and_run_event_command("speckit.cwd", "session_start", "{}", tmp_path)+ finally:+ _os.chdir(prev)+ assert code == 0+ recorded = out_file.read_text().strip()+ assert Path(recorded).resolve() == tmp_path.resolve()++ def test_dispatcher_is_self_contained(self, tmp_path):+ """R1: the generated dispatcher prefers `import specify_cli` (durable+ install) and falls back to an inline stdlib resolver so it works+ without a persistent `specify` executable (e.g. one-time uvx)."""+ integration = ClaudeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ install_integration_events(+ integration, tmp_path, manifest,+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ content = (tmp_path / EVENTS_DISPATCHER_REL).read_text()+ # Delegates to specify_cli when importable.+ assert "from specify_cli.events import resolve_and_run_event_command" in content+ assert "except ImportError" in content+ # Inline stdlib fallback resolver for one-time/temporary installs.+ assert "_run_inline" in content+ assert "_find_command_template" in content+ # No dependency on a persistent `specify` executable.+ assert '["specify"]' not in content++ def test_dispatcher_inline_fallback_runs_script(self, tmp_path):+ """R1: with specify_cli.events NOT importable, the inline resolver+ finds the command template and runs its script (stdlib only)."""+ import subprocess as _sp+ import sys as _sys++ # Install events (generates the dispatcher + native config).+ integration = ClaudeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ install_integration_events(+ integration, tmp_path, manifest,+ {"session_start": [{"command": "speckit.boot"}]},+ )+ dispatcher = tmp_path / EVENTS_DISPATCHER_REL+ assert dispatcher.is_file()++ # Create a core command template whose script writes its payload.+ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ out_file = tmp_path / "payload.out"+ (cmd_dir / "boot.md").write_text(+ "---\ndescription: \"Boot\"\nscripts:\n sh: scripts/boot.sh\n---\nBody\n",+ encoding="utf-8",+ )+ script_dir = tmp_path / ".specify" / "scripts"+ script_dir.mkdir(parents=True)+ script = script_dir / "boot.sh"+ script.write_text(f"#!/bin/sh\ncat > {shlex.quote(str(out_file))}\nexit 0\n", encoding="utf-8")+ script.chmod(0o755)++ if platform.system().lower().startswith("win"):+ return # sh is POSIX++ # Force the inline fallback: shadow `specify_cli` with an empty package+ # (no `events` submodule) so `from specify_cli.events import ...` raises+ # ModuleNotFoundError (an ImportError subclass), simulating a one-time+ # install where the package is unavailable at runtime.+ fake_dir = tmp_path / "_fake"+ (fake_dir / "specify_cli").mkdir(parents=True)+ (fake_dir / "specify_cli" / "__init__.py").write_text("", encoding="utf-8")+ env = dict(os.environ)+ env["PYTHONPATH"] = str(fake_dir)+ result = _sp.run(+ [_sys.executable, str(dispatcher), "speckit.boot", "session_start", "60"],+ input='{"tool_name":"x"}',+ capture_output=True,+ text=True,+ env=env,+ cwd=str(tmp_path),+ )+ # The inline resolver ran the script with the payload.+ assert out_file.exists(), f"inline fallback did not run script; stderr={result.stderr!r} rc={result.returncode}"+ assert out_file.read_text() == '{"tool_name":"x"}'++ def test_dispatcher_threads_per_handler_timeout(self, tmp_path):+ """S4: the generated dispatcher reads an optional 4th timeout arg and+ uses it for the inner subprocess, instead of a fixed 120s cap that+ would kill a handler configured for longer."""+ integration = ClaudeIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ install_integration_events(+ integration, tmp_path, manifest,+ {"pre_tool_use": [{"command": "speckit.tdd.validate", "timeout": 300}]},+ )+ content = (tmp_path / EVENTS_DISPATCHER_REL).read_text()+ # The dispatcher accepts a 4th argv element as the timeout.+ assert "sys.argv[3]" in content+ assert "timeout=timeout" in content++ def test_native_command_carries_resolved_timeout(self, tmp_path):+ """S4: the generated native hook command appends the resolved timeout+ so the dispatcher receives it. Claude uses seconds (default unit)."""+ from specify_cli.events import _dispatcher_command+ cmd = _dispatcher_command(+ ClaudeIntegration(), tmp_path, "speckit.x.y", "stop",+ timeout_seconds=300,+ )+ # R2: the raw seconds (no conversion, no buffer) are appended as the+ # 4th arg; the buffer goes on the native hook timeout field instead.+ assert " 300" in cmd++ def test_dispatcher_timeout_not_unit_converted_for_ms_adapters(self, tmp_path):+ """R2: the dispatcher arg is always seconds β for Gemini/Qwen/Tabnine+ (ms adapters) the timeout must NOT be converted to milliseconds+ (which previously yielded 60000 seconds)."""+ from specify_cli.events import _dispatcher_command+ from specify_cli.integrations.gemini import GeminiIntegration+ cmd = _dispatcher_command(+ GeminiIntegration(), tmp_path, "speckit.x.y", "pre_tool_use",+ timeout_seconds=60,+ )+ # 60 seconds (not 60000) is passed to the dispatcher.+ assert " 60" in cmd+ assert " 60000" not in cmd++ def test_sh_variant_uses_launcher_on_windows(self, tmp_path):+ """S5: on Windows the sh variant prefixes a bash/sh launcher so+ subprocess.run(shell=False) can execute the .sh script."""+ from specify_cli.events import _resolve_event_command_argv++ cmd_dir = tmp_path / ".specify" / "templates" / "commands"+ cmd_dir.mkdir(parents=True)+ (cmd_dir / "boot.md").write_text(+ "---\ndescription: \"Boot\"\nscripts:\n sh: scripts/bash/boot.sh\n---\nBody\n",+ encoding="utf-8",+ )+ sh_dir = tmp_path / ".specify" / "scripts" / "bash"+ sh_dir.mkdir(parents=True)+ (sh_dir / "boot.sh").write_text("#!/bin/sh\nexit 0\n", encoding="utf-8")++ argv = _resolve_event_command_argv(cmd_dir / "boot.md", tmp_path, None)+ assert argv is not None+ # On POSIX the script runs directly; on Windows a launcher prefixes it.+ if platform.system().lower().startswith("win"):+ assert PurePath(argv[0]).stem.lower() in ("bash", "sh")+ assert PurePath(argv[1]).as_posix().endswith(".specify/scripts/bash/boot.sh")+ else:+ assert PurePath(argv[0]).as_posix().endswith(".specify/scripts/bash/boot.sh")+++# -- Merge/teardown idempotency & safety (Tier 3) ----------------------------++def _claude_manifest(tmp_path):+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ manifest.remove = MagicMock()+ return manifest+++class TestMergeIdempotency:+ """#9/#11: marker recursion and full-clean-before-add."""++ def test_upgrade_does_not_duplicate_nested_hooks(self, tmp_path):+ """#9: re-running install replaces prior Specify inner hooks instead of+ appending a second matcher-group on every upgrade."""+ integration = ClaudeIntegration()+ config_path = tmp_path / ".claude/settings.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)++ events = {"pre_tool_use": [{"command": "speckit.tdd.validate"}]}+ for _ in range(2):+ manifest = _claude_manifest(tmp_path)+ install_integration_events(integration, tmp_path, manifest, events)++ data = json.loads(config_path.read_text())+ groups = data["hooks"]["PreToolUse"]+ # Exactly one matcher-group for Specify (no duplication).+ assert len(groups) == 1+ inner = groups[0]["hooks"]+ assert len(inner) == 1+ assert "speckit.tdd.validate" in inner[0]["command"]++ def test_override_change_removes_stale_event(self, tmp_path):+ """#11: when the resolved set changes from pre_tool_use to stop, the+ old marked pre_tool_use entry is removed, not left active."""+ integration = ClaudeIntegration()+ config_path = tmp_path / ".claude/settings.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)++ install_integration_events(+ integration, tmp_path, _claude_manifest(tmp_path),+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ install_integration_events(+ integration, tmp_path, _claude_manifest(tmp_path),+ {"stop": [{"command": "speckit.end"}]},+ )++ data = json.loads(config_path.read_text())+ assert "PreToolUse" not in data["hooks"]+ assert "Stop" in data["hooks"]+++class TestEmptyMapRemoval:+ """#3: --events false / empty resolved map strips prior hooks."""++ def test_empty_events_removes_prior_hooks(self, tmp_path):+ integration = ClaudeIntegration()+ config_path = tmp_path / ".claude/settings.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)++ install_integration_events(+ integration, tmp_path, _claude_manifest(tmp_path),+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ assert config_path.is_file()++ # Now resolve to empty (--events false): prior hooks must be removed.+ install_integration_events(integration, tmp_path, _claude_manifest(tmp_path), {})++ # The dispatcher is shared and left in place (#10); only native hooks+ # are stripped. The settings file had no user content β deleted (#14).+ assert not config_path.exists() or "hooks" not in json.loads(config_path.read_text())+++class TestTeardownDataSafety:+ """#14/#22/#23: preserve user content, delete Spec-Kit-created empties."""++ def test_remove_deletes_spec_kit_created_config(self, tmp_path):+ """#14: a config Spec Kit created from scratch is deleted (not left as+ ``{}``) so manifest.uninstall() doesn't preserve an empty stub."""+ integration = ClaudeIntegration()+ manifest = _claude_manifest(tmp_path)+ install_integration_events(+ integration, tmp_path, manifest,+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ config_path = tmp_path / ".claude/settings.json"+ assert config_path.is_file()++ remove_integration_events(integration, tmp_path, manifest)+ assert not config_path.exists()++ def test_remove_preserves_user_content_in_config(self, tmp_path):+ """#14: a pre-existing config with user content is kept (user hooks+ survive teardown)."""+ integration = ClaudeIntegration()+ config_path = tmp_path / ".claude/settings.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ config_path.write_text(json.dumps({+ "hooks": {+ "PreToolUse": [{+ "matcher": "Bash",+ "hooks": [{"type": "command", "command": "user-check"}],+ }]+ },+ "userSetting": True,+ }))++ manifest = _claude_manifest(tmp_path)+ install_integration_events(+ integration, tmp_path, manifest,+ {"stop": [{"command": "speckit.end"}]},+ )+ remove_integration_events(integration, tmp_path, manifest)++ data = json.loads(config_path.read_text())+ # User hook and setting preserved; Specify hook gone.+ assert data["userSetting"] is True+ assert "Stop" not in data.get("hooks", {})+ assert data["hooks"]["PreToolUse"][0]["matcher"] == "Bash"++ def test_forced_full_teardown_preserves_user_config(self, tmp_path):+ """S9: a full teardown(force=True) β which runs manifest.uninstall(+ force=True) after remove_events β must not delete a pre-existing user+ settings file whose owned entries were cleaned but user content kept.+ Uses a real manifest to exercise the uninstall path."""+ from specify_cli.integrations.manifest import IntegrationManifest++ integration = ClaudeIntegration()+ config_path = tmp_path / ".claude/settings.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ config_path.write_text(json.dumps({+ "hooks": {+ "PreToolUse": [{+ "matcher": "Bash",+ "hooks": [{"type": "command", "command": "user-check"}],+ }]+ },+ "userSetting": True,+ }))++ manifest = IntegrationManifest(integration.key, tmp_path, version="test")+ install_integration_events(+ integration, tmp_path, manifest,+ {"stop": [{"command": "speckit.end"}]},+ )+ manifest.save()++ # Full teardown: remove_events + manifest.uninstall(force=True).+ integration.teardown(tmp_path, manifest, force=True)++ assert config_path.exists(), (+ "Forced teardown deleted the user's settings file (S9)."+ )+ data = json.loads(config_path.read_text())+ assert data["userSetting"] is True+ assert data["hooks"]["PreToolUse"][0]["matcher"] == "Bash"++ def test_jsonc_config_not_reset_on_merge(self, tmp_path):+ """#22: a JSONC/unparseable native config is left untouched on merge."""+ integration = ClaudeIntegration()+ config_path = tmp_path / ".claude/settings.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ jsonc = '{\n // my comment\n "hooks": {}\n}\n'+ config_path.write_text(jsonc)++ install_integration_events(+ integration, tmp_path, _claude_manifest(tmp_path),+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ # User content preserved verbatim β not reset to {}.+ assert config_path.read_text() == jsonc++ def test_jsonc_opencode_config_not_reset(self, tmp_path):+ """#23: a malformed opencode.json is preserved, not reset to {}."""+ integration = OpencodeIntegration()+ config_path = tmp_path / "opencode.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ malformed = "{ not valid json"+ config_path.write_text(malformed)++ install_integration_events(+ integration, tmp_path, _claude_manifest(tmp_path),+ {"session_start": [{"command": "speckit.boot"}]},+ )+ assert config_path.read_text() == malformed+++class TestCopilotMergeTeardown:+ """#8: Copilot dedicated hooks JSON merges owned entries / teardown+ removes only owned entries."""++ def test_copilot_merge_preserves_user_hooks(self, tmp_path):+ integration = CopilotIntegration()+ config_path = tmp_path / ".github/hooks/speckit.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ config_path.write_text(json.dumps({+ "version": 1,+ "hooks": {+ "sessionStart": [{"type": "command", "bash": "user-hook"}],+ },+ }))++ install_integration_events(+ integration, tmp_path, _claude_manifest(tmp_path),+ {"session_start": [{"command": "speckit.boot"}]},+ )+ data = json.loads(config_path.read_text())+ entries = data["hooks"]["sessionStart"]+ bash_cmds = [e.get("bash") for e in entries]+ assert "user-hook" in bash_cmds+ assert any("speckit.boot" in c for c in bash_cmds)++ def test_copilot_teardown_removes_only_owned_entries(self, tmp_path):+ integration = CopilotIntegration()+ config_path = tmp_path / ".github/hooks/speckit.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ config_path.write_text(json.dumps({+ "version": 1,+ "hooks": {+ "sessionStart": [{"type": "command", "bash": "user-hook"}],+ },+ }))++ manifest = _claude_manifest(tmp_path)+ install_integration_events(+ integration, tmp_path, manifest,+ {"session_start": [{"command": "speckit.boot"}]},+ )+ remove_integration_events(integration, tmp_path, manifest)++ data = json.loads(config_path.read_text())+ # User hook preserved; Spec-Kit entry gone.+ assert data["hooks"]["sessionStart"][0]["bash"] == "user-hook"++ def test_copilot_teardown_deletes_spec_kit_only_file(self, tmp_path):+ """#8/#14: when the file held only Spec-Kit entries, teardown deletes it."""+ integration = CopilotIntegration()+ manifest = _claude_manifest(tmp_path)+ install_integration_events(+ integration, tmp_path, manifest,+ {"session_start": [{"command": "speckit.boot"}]},+ )+ config_path = tmp_path / ".github/hooks/speckit.json"+ assert config_path.is_file()+ remove_integration_events(integration, tmp_path, manifest)+ assert not config_path.exists()+++class TestSharedDispatcherRefcount:+ """#10: the shared .specify/events.py dispatcher is not deleted while+ another installed event-capable integration still references it."""++ def test_dispatcher_kept_when_other_integration_references_it(self, tmp_path):+ # Simulate two event-capable integrations installed: claude (the one+ # being uninstalled) and codex (still installed). The codex manifest+ # lists the dispatcher, so removing claude must not delete it.+ from specify_cli.integrations.codex import CodexIntegration++ claude = ClaudeIntegration()+ codex = CodexIntegration()++ # Install claude's events (writes dispatcher + claude config).+ claude_manifest = _claude_manifest(tmp_path)+ install_integration_events(+ claude, tmp_path, claude_manifest,+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ # Install codex's events (re-writes shared dispatcher + codex config).+ codex_manifest = MagicMock(spec=IntegrationManifest)+ codex_manifest.files = {}+ codex_manifest.record_file = MagicMock()+ codex_manifest.record_existing = MagicMock()+ codex_manifest.remove = MagicMock()+ install_integration_events(+ codex, tmp_path, codex_manifest,+ {"pre_tool_use": [{"command": "speckit.codex.check"}]},+ )++ # Persist a codex manifest on disk so the refcount check finds it.+ codex_disk = IntegrationManifest(codex.key, tmp_path, version="test")+ codex_disk._files = {EVENTS_DISPATCHER_REL: "x"}+ codex_disk.save()++ # Write the integration-state JSON so installed_integration_keys sees codex.+ import json as _json+ state_path = tmp_path / ".specify" / "integration.json"+ state_path.parent.mkdir(parents=True, exist_ok=True)+ state_path.write_text(_json.dumps({+ "default_integration": "claude",+ "installed_integrations": ["claude", "codex"],+ }))++ dispatcher_path = tmp_path / EVENTS_DISPATCHER_REL+ assert dispatcher_path.exists()++ # Removing claude should leave the dispatcher (codex still uses it).+ remove_integration_events(claude, tmp_path, claude_manifest)+ assert dispatcher_path.exists()+++class TestSafeWriteDestination:+ """#12: write targets are validated before any bytes are written."""++ def test_symlinked_config_dir_rejected(self, tmp_path):+ integration = ClaudeIntegration()+ # Create a symlinked .claude directory pointing outside the project.+ outside = tmp_path / "outside"+ outside.mkdir()+ linked = tmp_path / ".claude"+ os.symlink(outside, linked)++ with pytest.raises(ValueError, match="(?i)symlink|escapes|outside"):+ install_integration_events(+ integration, tmp_path, _claude_manifest(tmp_path),+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ # No content written through the symlink.+ assert not (outside / "settings.json").exists()++ def test_toml_teardown_rejects_symlinked_config(self, tmp_path):+ """R3: TOML teardown validates the destination before read/write, so a+ symlink swap after install can't make uninstall overwrite an external+ file."""+ from specify_cli.integrations.codex import CodexIntegration++ integration = CodexIntegration()+ manifest = _claude_manifest(tmp_path)+ install_integration_events(+ integration, tmp_path, manifest,+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ config_path = tmp_path / ".codex" / "config.toml"+ assert config_path.is_file()++ # Swap the config for a symlink pointing outside the project.+ outside = tmp_path / "outside.toml"+ outside.write_text("external = true\n")+ config_path.unlink()+ os.symlink(outside, config_path)++ with pytest.raises(ValueError, match="(?i)symlink|escapes|outside"):+ remove_integration_events(integration, tmp_path, manifest)+ # External file untouched.+ assert outside.read_text() == "external = true\n"++ def test_json_remover_rejects_symlinked_config(self, tmp_path):+ """Removers validate destination before reading or unlinking."""+ integration = ClaudeIntegration()+ manifest = _claude_manifest(tmp_path)+ install_integration_events(+ integration, tmp_path, manifest,+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ config_path = tmp_path / ".claude" / "settings.json"+ assert config_path.is_file()++ outside = tmp_path / "outside.json"+ outside.write_text('{"external": true}')+ config_path.unlink()+ os.symlink(outside, config_path)++ with pytest.raises(ValueError, match="(?i)symlink|escapes|outside"):+ remove_integration_events(integration, tmp_path, manifest)+ assert outside.read_text() == '{"external": true}'++ def test_plugin_remover_rejects_symlinked_plugin(self, tmp_path):+ """OpenCode plugin cleanup validates destination before unlinking."""+ integration = OpencodeIntegration()+ manifest = _claude_manifest(tmp_path)+ install_integration_events(+ integration, tmp_path, manifest,+ {"session_start": [{"command": "speckit.boot"}]},+ )+ plugin_path = tmp_path / ".opencode" / "plugin" / "speckit-events.ts"+ assert plugin_path.is_file()++ outside = tmp_path / "outside.ts"+ outside.write_text("// external")+ plugin_path.unlink()+ os.symlink(outside, plugin_path)++ manifest.files[".opencode/plugin/speckit-events.ts"] = "hash"+ with pytest.raises(ValueError, match="(?i)symlink|escapes|outside"):+ remove_integration_events(integration, tmp_path, manifest)+ assert outside.read_text() == "// external"+++# -- Validation & lifecycle (Tier 4) -----------------------------------------++class TestValidateEventsCommandType:+ """#17: command must be a non-empty string, not just truthy."""++ def test_non_string_command_rejected(self):+ from specify_cli.extensions import ValidationError+ data = {"events": {"pre_tool_use": {"command": ["speckit.tdd.validate"]}}}+ with pytest.raises(ValidationError, match="(?i)command.*string"):+ validate_events(data)++ def test_empty_string_command_rejected(self):+ from specify_cli.extensions import ValidationError+ data = {"events": {"pre_tool_use": {"command": " "}}}+ with pytest.raises(ValidationError, match="(?i)command.*string"):+ validate_events(data)+++class TestCollectExtensionEventsEnabledFlag:+ """#1: collect_extension_events honors the registry's enabled flag."""++ def test_disabled_extension_events_skipped(self, tmp_path):+ from specify_cli.extensions import ExtensionRegistry++ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ ext_dir.mkdir(parents=True)+ (ext_dir / "extension.yml").write_text(+ "extension:\n id: my-ext\n name: My Ext\n version: 1.0.0\n"+ " description: test\n"+ "schema_version: '1.0'\n"+ "requires:\n speckit_version: '>=0.1'\n"+ "provides:\n commands: []\n"+ "events:\n session_start:\n command: speckit.my-ext.boot\n",+ encoding="utf-8",+ )+ registry = ExtensionRegistry(tmp_path / ".specify" / "extensions")+ registry.add("my-ext", {"enabled": False})++ result = collect_extension_events(tmp_path)+ assert result == {}++ def test_enabled_extension_events_collected(self, tmp_path):+ from specify_cli.extensions import ExtensionRegistry++ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ ext_dir.mkdir(parents=True)+ (ext_dir / "extension.yml").write_text(+ "extension:\n id: my-ext\n name: My Ext\n version: 1.0.0\n"+ " description: test\n"+ "schema_version: '1.0'\n"+ "requires:\n speckit_version: '>=0.1'\n"+ "provides:\n commands: []\n"+ "events:\n session_start:\n command: speckit.my-ext.boot\n",+ encoding="utf-8",+ )+ registry = ExtensionRegistry(tmp_path / ".specify" / "extensions")+ registry.add("my-ext", {"enabled": True})++ result = collect_extension_events(tmp_path)+ assert result == {"session_start": [{"command": "speckit.my-ext.boot"}]}+++class TestRefreshIntegrationEvents:+ """#1: refresh_integration_events regenerates native config after+ extension state changes."""++ def test_refresh_strips_removed_extension_events(self, tmp_path):+ from specify_cli.events import refresh_integration_events+ from specify_cli.integrations.manifest import IntegrationManifest++ # Install claude with an event sourced from a (simulated) extension.+ integration = ClaudeIntegration()+ manifest = IntegrationManifest(integration.key, tmp_path, version="test")+ install_integration_events(+ integration, tmp_path, manifest,+ {"pre_tool_use": [{"command": "speckit.my-ext.check"}]},+ )+ manifest.save()+ config_path = tmp_path / ".claude/settings.json"+ assert config_path.is_file()++ # Record claude as installed so refresh finds it.+ state_path = tmp_path / ".specify" / "integration.json"+ state_path.parent.mkdir(parents=True, exist_ok=True)+ state_path.write_text(json.dumps({+ "default_integration": "claude",+ "installed_integrations": ["claude"],+ }))+ # No extension declares events now β refresh should strip the prior hook+ # (the config is deleted when no user content remains, #14).+ refresh_integration_events(tmp_path)++ if config_path.exists():+ data = json.loads(config_path.read_text())+ assert "PreToolUse" not in data.get("hooks", {})+ # If the file is gone, the hooks were stripped (and the empty config+ # deleted) β also correct.++ def test_refresh_emits_newly_declared_extension_events(self, tmp_path):+ from specify_cli.events import refresh_integration_events+ from specify_cli.integrations.manifest import IntegrationManifest++ integration = ClaudeIntegration()+ manifest = IntegrationManifest(integration.key, tmp_path, version="test")+ # Initially no events.+ manifest.save()+ config_path = tmp_path / ".claude/settings.json"++ # Declare an extension event on disk.+ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ ext_dir.mkdir(parents=True)+ (ext_dir / "extension.yml").write_text(+ "events:\n session_start:\n command: speckit.my-ext.boot\n",+ encoding="utf-8",+ )+ state_path = tmp_path / ".specify" / "integration.json"+ state_path.parent.mkdir(parents=True, exist_ok=True)+ state_path.write_text(json.dumps({+ "default_integration": "claude",+ "installed_integrations": ["claude"],+ }))++ refresh_integration_events(tmp_path)++ data = json.loads(config_path.read_text())+ assert "SessionStart" in data["hooks"]++ def test_refresh_honors_stored_events_false(self, tmp_path):+ """S7: a stored --events false must be honored across extension+ lifecycle refresh; passing None would re-enable events."""+ from specify_cli.events import refresh_integration_events+ from specify_cli.integrations.manifest import IntegrationManifest++ integration = ClaudeIntegration()+ manifest = IntegrationManifest(integration.key, tmp_path, version="test")+ manifest.save()+ config_path = tmp_path / ".claude/settings.json"++ # Declare an extension event on disk.+ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ ext_dir.mkdir(parents=True)+ (ext_dir / "extension.yml").write_text(+ "events:\n session_start:\n command: speckit.my-ext.boot\n",+ encoding="utf-8",+ )+ # Store the integration with --events false in parsed_options.+ state_path = tmp_path / ".specify" / "integration.json"+ state_path.parent.mkdir(parents=True, exist_ok=True)+ state_path.write_text(json.dumps({+ "default_integration": "claude",+ "installed_integrations": ["claude"],+ "integration_settings": {+ "claude": {"parsed_options": {"events": "false"}},+ },+ }))++ refresh_integration_events(tmp_path)++ # No hooks should have been re-created (CLI gate honored).+ if config_path.exists():+ assert "hooks" not in json.loads(config_path.read_text())+++# -- Override preserve-layers (#10) ------------------------------------------++class TestOverridePreserveLayers:+ """#10: an invalid override entry abandons the whole override and keeps+ the accumulated built-in + extension layers, instead of disabling all+ hooks."""++ def test_invalid_override_entry_keeps_prior_layers(self, tmp_path):+ override_file = tmp_path / ".specify" / "integration-events.yml"+ override_file.parent.mkdir(parents=True, exist_ok=True)+ # One valid entry, one invalid (non-string command) β the whole+ # override is ignored, built-in defaults survive.+ override_file.write_text(+ "integrations:\n"+ " claude:\n"+ " events:\n"+ " stop:\n"+ " command: speckit.valid.stop\n"+ " pre_tool_use:\n"+ " command: [not-a-string]\n",+ encoding="utf-8",+ )+ result = resolve_events(+ "claude",+ {"events": {"post_tool_use": {"command": "speckit.tdd.validate"}}},+ tmp_path,+ None,+ )+ # Built-in default survived (override was abandoned on the invalid entry).+ assert "post_tool_use" in result+ assert result["post_tool_use"] == [{"command": "speckit.tdd.validate"}]++ def test_explicit_empty_override_disables(self, tmp_path):+ """A fully-valid explicit `events: {}` override still disables."""+ override_file = tmp_path / ".specify" / "integration-events.yml"+ override_file.parent.mkdir(parents=True, exist_ok=True)+ override_file.write_text(+ "integrations:\n"+ " claude:\n"+ " events: {}\n",+ encoding="utf-8",+ )+ result = resolve_events(+ "claude",+ {"events": {"post_tool_use": {"command": "speckit.tdd.validate"}}},+ tmp_path,+ None,+ )+ assert result == {}++ def test_empty_handler_override_abandons_override(self, tmp_path):+ """C4: a malformed handler (`stop: []` or `stop: bad-value`) abandons+ the whole override and keeps prior layers, rather than disabling."""+ override_file = tmp_path / ".specify" / "integration-events.yml"+ override_file.parent.mkdir(parents=True, exist_ok=True)+ override_file.write_text(+ "integrations:\n"+ " claude:\n"+ " events:\n"+ " stop: []\n",+ encoding="utf-8",+ )+ result = resolve_events(+ "claude",+ {"events": {"post_tool_use": {"command": "speckit.tdd.validate"}}},+ tmp_path,+ None,+ )+ # Built-in default survived (override abandoned on the empty handler).+ assert "post_tool_use" in result++ def test_non_mapping_integration_entry_abandons_override(self, tmp_path):+ """C6: a non-mapping integration entry (`claude: bad`) is ignored as+ malformed, not treated as a valid explicit disable."""+ override_file = tmp_path / ".specify" / "integration-events.yml"+ override_file.parent.mkdir(parents=True, exist_ok=True)+ override_file.write_text(+ "integrations:\n"+ " claude: bad\n",+ encoding="utf-8",+ )+ result = resolve_events(+ "claude",+ {"events": {"post_tool_use": {"command": "speckit.tdd.validate"}}},+ tmp_path,+ None,+ )+ # Built-in default survived (override ignored as malformed).+ assert "post_tool_use" in result+++# -- Matcher string validation (C10) -----------------------------------------++class TestMatcherValidation:+ """C10: matcher must be a string; a non-string matcher is rejected at+ validation time so it can't crash by_matcher.setdefault later."""++ def test_non_string_matcher_rejected_in_manifest(self):+ from specify_cli.extensions import ValidationError+ data = {"events": {"pre_tool_use": {"command": "speckit.x.y", "matcher": []}}}+ with pytest.raises(ValidationError, match="(?i)matcher.*string"):+ validate_events(data)++ def test_non_string_matcher_rejected_in_override(self, tmp_path):+ override_file = tmp_path / ".specify" / "integration-events.yml"+ override_file.parent.mkdir(parents=True, exist_ok=True)+ # A matcher of [] would crash by_matcher.setdefault; the override must+ # be abandoned (built-in defaults survive) rather than crash.+ override_file.write_text(+ "integrations:\n"+ " claude:\n"+ " events:\n"+ " pre_tool_use:\n"+ " command: speckit.x.y\n"+ " matcher: []\n",+ encoding="utf-8",+ )+ result = resolve_events(+ "claude",+ {"events": {"stop": {"command": "speckit.end"}}},+ tmp_path,+ None,+ )+ # Built-in default survived (override abandoned on the bad matcher).+ assert "stop" in result+++class TestTimeoutValidation:+ """Validate that non-integer, boolean, or non-positive timeouts are rejected."""++ def test_non_int_timeout_rejected_in_manifest(self):+ from specify_cli.extensions import ValidationError+ data = {"events": {"pre_tool_use": {"command": "speckit.x.y", "timeout": "60"}}}+ with pytest.raises(ValidationError, match="(?i)timeout.*positive integer"):+ validate_events(data)++ def test_boolean_timeout_rejected_in_manifest(self):+ from specify_cli.extensions import ValidationError+ data = {"events": {"pre_tool_use": {"command": "speckit.x.y", "timeout": True}}}+ with pytest.raises(ValidationError, match="(?i)timeout.*positive integer"):+ validate_events(data)++ def test_zero_or_negative_timeout_rejected_in_manifest(self):+ from specify_cli.extensions import ValidationError+ data = {"events": {"pre_tool_use": {"command": "speckit.x.y", "timeout": 0}}}+ with pytest.raises(ValidationError, match="(?i)timeout.*positive integer"):+ validate_events(data)+++# -- Event command-ref canonicalization (C11) --------------------------------++class TestEventCommandRefCanonicalization:+ """C11: an event referencing a command that was auto-corrected is itself+ rewritten to the canonical name (mirrors hook reference rewriting)."""++ def test_event_command_ref_lifted_to_canonical(self, tmp_path):+ from specify_cli.extensions import ExtensionManifest+ import yaml as _yaml++ manifest_path = tmp_path / "extension.yml"+ manifest_path.write_text(+ _yaml.dump({+ "schema_version": "1.0",+ "extension": {+ "id": "my-ext",+ "name": "My Ext",+ "version": "1.0.0",+ "description": "test",+ },+ "requires": {"speckit_version": ">=0.1"},+ "provides": {+ "commands": [+ {"name": "speckit.my-ext.boot", "file": "commands/boot.md"}+ ]+ },+ "events": {+ "session_start": {"command": "my-ext.boot"},+ },+ }),+ encoding="utf-8",+ )+ manifest = ExtensionManifest(manifest_path)+ assert manifest.data["events"]["session_start"]["command"] == "speckit.my-ext.boot"+ assert any(+ "Event 'session_start' referenced command 'my-ext.boot'" in w+ for w in manifest.warnings+ )+++# -- Skipped-merge not tracked (S5) ------------------------------------------++class TestSkippedMergeNotTracked:+ """S5: when a merge is skipped on parse failure, the untouched file is+ not recorded in the manifest, so uninstall() won't later delete it."""++ def test_jsonc_native_config_not_tracked(self, tmp_path):+ integration = ClaudeIntegration()+ config_path = tmp_path / ".claude/settings.json"+ config_path.parent.mkdir(parents=True, exist_ok=True)+ jsonc = '{\n // my comment\n "hooks": {}\n}\n'+ config_path.write_text(jsonc)++ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ manifest.remove = MagicMock()++ install_integration_events(+ integration, tmp_path, manifest,+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ # The JSONC file must NOT have been recorded (would cause uninstall()+ # to delete it later). Only the dispatcher (which we wrote) is tracked.+ recorded_rels = [c.args[0] for c in manifest.record_existing.call_args_list]+ assert str(config_path.relative_to(tmp_path)) not in recorded_rels+ # User content preserved verbatim.+ assert config_path.read_text() == jsonc+++# -- Dispatcher manifest claim dropped on retain (S1) ------------------------++class TestDispatcherManifestClaimDroppedOnRetain:+ """S1: when the dispatcher is retained (another integration references+ it), this integration's manifest still drops its claim so the subsequent+ manifest.uninstall() in teardown() doesn't delete the shared file."""++ def test_full_teardown_keeps_dispatcher_when_other_references_it(self, tmp_path):+ from specify_cli.integrations.codex import CodexIntegration+ from specify_cli.integrations.manifest import IntegrationManifest++ claude = ClaudeIntegration()+ codex = CodexIntegration()++ # Install claude's events (writes dispatcher + claude config).+ claude_manifest = IntegrationManifest(claude.key, tmp_path, version="test")+ install_integration_events(+ claude, tmp_path, claude_manifest,+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ claude_manifest.save()++ # Install codex's events (re-writes shared dispatcher + codex config).+ codex_manifest = IntegrationManifest(codex.key, tmp_path, version="test")+ install_integration_events(+ codex, tmp_path, codex_manifest,+ {"pre_tool_use": [{"command": "speckit.codex.check"}]},+ )+ codex_manifest.save()++ # integration.json: both installed, codex is default.+ state_path = tmp_path / ".specify" / "integration.json"+ state_path.parent.mkdir(parents=True, exist_ok=True)+ state_path.write_text(json.dumps({+ "default_integration": "codex",+ "installed_integrations": ["claude", "codex"],+ }))++ dispatcher_path = tmp_path / EVENTS_DISPATCHER_REL+ assert dispatcher_path.exists()++ # Full teardown of claude (remove + manifest.uninstall): the dispatcher+ # must survive because codex's manifest still references it.+ remove_integration_events(claude, tmp_path, claude_manifest)+ claude_manifest.uninstall(tmp_path, force=True)++ assert dispatcher_path.exists(), (+ "Shared dispatcher was deleted by teardown() despite another "+ "integration referencing it (S1)."+ )++ def test_empty_map_upgrade_deletes_dispatcher_for_last_integration(self, tmp_path):+ """S3: an --events false upgrade (empty resolved map) of the last+ event-capable integration deletes the shared dispatcher instead of+ orphaning it (the new manifest wouldn't claim it and stale cleanup+ excludes it)."""+ from specify_cli.integrations.codex import CodexIntegration+ from specify_cli.integrations.manifest import IntegrationManifest++ claude = ClaudeIntegration()+ codex = CodexIntegration()+ # Install both so the dispatcher is shared.+ cm = IntegrationManifest(claude.key, tmp_path, version="test")+ install_integration_events(claude, tmp_path, cm, {"pre_tool_use": [{"command": "speckit.x"}]})+ cm.save()+ xm = IntegrationManifest(codex.key, tmp_path, version="test")+ install_integration_events(codex, tmp_path, xm, {"pre_tool_use": [{"command": "speckit.y"}]})+ xm.save()+ state_path = tmp_path / ".specify" / "integration.json"+ state_path.parent.mkdir(parents=True, exist_ok=True)+ state_path.write_text(json.dumps({+ "default_integration": "codex",+ "installed_integrations": ["claude", "codex"],+ }))+ dispatcher_path = tmp_path / EVENTS_DISPATCHER_REL+ assert dispatcher_path.exists()++ # Codex upgrades to --events false (empty map): claude still references+ # the dispatcher, so it must be retained.+ install_integration_events(codex, tmp_path, xm, {})+ xm.save()+ assert dispatcher_path.exists(), "Dispatcher deleted while claude still references it."++ # Now claude also goes --events false: no integration references the+ # dispatcher, so it must be deleted (not orphaned).+ install_integration_events(claude, tmp_path, cm, {})+ cm.save()+ assert not dispatcher_path.exists(), (+ "Dispatcher orphaned after the last event integration disabled events (S3)."+ )++ def test_fresh_manifest_upgrade_deletes_dispatcher_when_last(self, tmp_path):+ """S2: an upgrade passing a *fresh* manifest (that never recorded the+ dispatcher) still deletes the shared dispatcher when no other+ integration references it β the deletion isn't gated on the new+ manifest's claim."""+ from specify_cli.integrations.manifest import IntegrationManifest++ claude = ClaudeIntegration()+ # Install claude with an old manifest that records the dispatcher.+ old = IntegrationManifest(claude.key, tmp_path, version="test")+ install_integration_events(claude, tmp_path, old, {"pre_tool_use": [{"command": "speckit.x"}]})+ old.save()+ state_path = tmp_path / ".specify" / "integration.json"+ state_path.parent.mkdir(parents=True, exist_ok=True)+ state_path.write_text(json.dumps({+ "default_integration": "claude",+ "installed_integrations": ["claude"],+ }))+ dispatcher_path = tmp_path / EVENTS_DISPATCHER_REL+ assert dispatcher_path.exists()++ # Simulate the upgrade path: a fresh manifest (like+ # IntegrationManifest(key, project_root, version=...) in+ # _migrate_commands) that never recorded the dispatcher.+ fresh = IntegrationManifest(claude.key, tmp_path, version="test")+ assert EVENTS_DISPATCHER_REL not in fresh.files+ install_integration_events(claude, tmp_path, fresh, {})++ # The dispatcher must be deleted (no other integration references it),+ # not orphaned just because the fresh manifest didn't claim it.+ assert not dispatcher_path.exists(), (+ "Dispatcher orphaned after upgrade with a fresh manifest (S2)."+ )+++# -- Dispatcher stale-cleanup exclusion (C3) ---------------------------------++class TestDispatcherStaleExclusion:+ """C3: the shared dispatcher is excluded from the generic upgrade stale+ pass so an --events false upgrade doesn't delete it and break other+ installed event-capable integrations."""++ def test_dispatcher_in_stale_exclusions(self):+ from specify_cli.events import events_stale_exclusions+ exclusions = events_stale_exclusions("claude")+ assert EVENTS_DISPATCHER_REL in exclusions+++# -- Cursor version-only stub deletion (C5) ----------------------------------++class TestCursorVersionOnlyStubDeletion:+ """C5: a Spec-Kit-created Cursor file retaining only {"version": 1} after+ all owned hooks are removed is deleted, not left as a generated stub."""++ def test_version_only_cursor_file_deleted_on_teardown(self, tmp_path):+ integration = CursorAgentIntegration()+ manifest = MagicMock(spec=IntegrationManifest)+ manifest.files = {}+ manifest.record_file = MagicMock()+ manifest.record_existing = MagicMock()+ manifest.remove = MagicMock()++ install_integration_events(+ integration, tmp_path, manifest,+ {"session_start": [{"command": "speckit.boot"}]},+ )+ config_path = tmp_path / ".cursor/hooks.json"+ assert config_path.is_file()+ assert json.loads(config_path.read_text()).get("version") == 1++ remove_integration_events(integration, tmp_path, manifest)+ # No user content remained (only the Spec-Kit-managed version field) β+ # the file is deleted for a clean teardown, not left as a stub.+ assert not config_path.exists()+++# -- Non-destructive refresh (C12) -------------------------------------------++class TestNonDestructiveRefresh:+ """C12: refresh resolves first then installs once; a failure during install+ no longer destroys the working native config before the new one is written."""++ def test_refresh_failure_preserves_existing_config(self, tmp_path):+ from specify_cli.events import refresh_integration_events+ from specify_cli.integrations.manifest import IntegrationManifest++ integration = ClaudeIntegration()+ manifest = IntegrationManifest(integration.key, tmp_path, version="test")+ install_integration_events(+ integration, tmp_path, manifest,+ {"pre_tool_use": [{"command": "speckit.tdd.validate"}]},+ )+ manifest.save()+ config_path = tmp_path / ".claude/settings.json"+ original = config_path.read_text()++ # Declare an extension event so refresh would try to re-emit.+ ext_dir = tmp_path / ".specify" / "extensions" / "my-ext"+ ext_dir.mkdir(parents=True)+ (ext_dir / "extension.yml").write_text(+ "events:\n session_start:\n command: speckit.my-ext.boot\n",+ encoding="utf-8",+ )+ state_path = tmp_path / ".specify" / "integration.json"+ state_path.parent.mkdir(parents=True, exist_ok=True)+ state_path.write_text(json.dumps({+ "default_integration": "claude",+ "installed_integrations": ["claude"],+ }))++ # Force install_integration_events to fail mid-refresh. R3: the+ # failure is now surfaced as EventRefreshError (aggregated) rather+ # than silently swallowed.+ from specify_cli.events import EventRefreshError+ with patch(+ "specify_cli.events.install_integration_events",+ side_effect=RuntimeError("simulated write failure"),+ ):+ with pytest.raises(EventRefreshError, match="simulated write failure"):+ refresh_integration_events(tmp_path)++ # The pre-existing config was NOT destroyed before the failure+ # (install handles cleanup atomically; refresh no longer pre-strips).+ assert config_path.read_text() == originaldiff --git a/tests/test_extensions.py b/tests/test_extensions.pyindex fbf2b29a8..ad0ad9b31 100644--- a/tests/test_extensions.py+++ b/tests/test_extensions.py@@ -576,7 +576,7 @@ class TestExtensionManifest:with open(manifest_path, 'w') as f:yaml.dump(valid_manifest_data, f)- with pytest.raises(ValidationError, match="must provide at least one command or hook"):+ with pytest.raises(ValidationError, match="must provide at least one command, hook, or event"):ExtensionManifest(manifest_path)def test_hooks_only_extension(self, temp_dir, valid_manifest_data):