Repository navigation
[Bug]: A hook with a list-valued command passes manifest validation, then crashes extension add and leaves files behind #5080
Description
Bug Description
ExtensionManifest checks only that a hook's command is truthy (src/specify_cli/extensions/__init__.py:435), so a list such as command: [speckit.test-ext.hello] is accepted. During install, HookExecutor.register_hooks uses the command as a dictionary key (__init__.py:5872), which raises TypeError: unhashable type: 'list'.
By then the extension directory has been copied and the agent skill has been written. The except handler in install_from_directory only rolls back when the generic agent is active (__init__.py:3132). With any other agent the files stay on disk, and no registry entry is written. The TypeError is not one of the exceptions specify extension add handles, so the user sees a raw traceback.
Steps to Reproduce
Save this as repro.py and run uv run python -I repro.py from the repository root.
import os, tempfile, traceback
from pathlib import Path
from typer.testing import CliRunner
from specify_cli import app
root = Path(tempfile.mkdtemp())
ext = root / "test-ext"
(ext / "commands").mkdir(parents=True)
(ext / "commands/hello.md").write_text("---\ndescription: hi\n---\n\nHello $ARGUMENTS\n")
(ext / "extension.yml").write_text("""schema_version: "1.0"
extension: {id: test-ext, name: Test, version: 1.0.0, description: d}
requires: {speckit_version: ">=0.1.0"}
provides:
commands:
- {name: speckit.test-ext.hello, file: commands/hello.md, description: x}
hooks:
after_tasks:
command: [speckit.test-ext.hello]
""")
proj = root / "project"
(proj / ".specify").mkdir(parents=True)
(proj / ".claude/skills").mkdir(parents=True)
os.chdir(proj)
r = CliRunner().invoke(app, ["extension", "add", "--dev", str(ext)])
print("exit code:", r.exit_code)
print("".join(traceback.format_exception(r.exception)[-3:]))
print("registry:", (proj / ".specify/extensions/.registry").read_text()
if (proj / ".specify/extensions/.registry").exists() else "<none>")
print("left on disk:", sorted(str(p.relative_to(proj)) for p in proj.rglob("*") if "test-ext" in str(p)))Expected Behavior
The manifest is rejected with a ValidationError and nothing is installed. extensions/EXTENSION-API-REFERENCE.md:72 documents the field as command: string. The ExtensionManifest.__init__ docstring says it "Raises: ValidationError: If manifest is invalid" (__init__.py:243-244).
Actual Behavior
exit code: 1
registry: <none>
left on disk: ['.claude/skills/speckit-test-ext-hello', '.claude/skills/speckit-test-ext-hello/SKILL.md', '.specify/extensions/test-ext', '.specify/extensions/test-ext/.specify-dev', '.specify/extensions/test-ext/.specify-dev/agent-commands', '.specify/extensions/test-ext/.specify-dev/agent-commands/claude', '.specify/extensions/test-ext/.specify-dev/agent-commands/claude/speckit-test-ext-hello', '.specify/extensions/test-ext/.specify-dev/agent-commands/claude/speckit-test-ext-hello/SKILL.md', '.specify/extensions/test-ext/commands', '.specify/extensions/test-ext/commands/hello.md', '.specify/extensions/test-ext/extension.yml']
The command exits 1. The extension is not in the registry, but .claude/skills/speckit-test-ext-hello/SKILL.md and .specify/extensions/test-ext/ remain on disk.
Specify CLI Version
1.2.4.dev0 (main at 27d14e2)
AI Agent
Claude Code
Operating System
Linux 6.18 (Ubuntu container)
Python Version
Python 3.12.3
Error Logs
File "<checkout>/src/specify_cli/extensions/__init__.py", line 3084, in install_from_directory
hook_executor.register_hooks(manifest)
File "<checkout>/src/specify_cli/extensions/__init__.py", line 5872, in register_hooks
if command in new_entries:
^^^^^^^^^^^^^^^^^^^^^^
TypeError: unhashable type: 'list'
Additional Context
Hook command values of other non-string types (a mapping, for example) take the same path. The failure-path rollback only covers the generic agent, so any other failure after command registration (for example, an unwritable .specify/extensions.yml) is likely to leave the same leftovers. That was not tested separately. Rejecting non-string hook commands in _validate would fix the reported case.
Also reproduced on macOS (Darwin 25.6, arm64) with Python 3.14.4 and uv run python -I repro.py against 27d14e2; the output matches the above.
AI Disclosure
Found and reproduced with Claude Code (model: Claude Opus 4.8), run autonomously under human supervision. The human reporter re-ran every reproduction above before filing.
Activity
fix(extensions): point the hook command comment at validate_events()
fix(extensions): reject hook commands that are not strings (#5146)
github-actions commentedon Oct 29, 2026
Bug assessment — hook-command-list-crash: Invalid · severity low
Bug Assessment: List-valued hook command crashes extension add
commandpasses manifest validation, then crashesextension addand leaves files behind #5080Report (summarized)
Issue author @hnipps reports that a manifest with
hooks.after_tasks.commandset to a list (instead of a string) passes validation, then crashes during install withTypeError: unhashable type: 'list', leaving extension files/skills on disk and no registry entry.Provided traceback points to:
src/specify_cli/extensions/__init__.py:3084(hook_executor.register_hooks(manifest))src/specify_cli/extensions/__init__.py:5872(if command in new_entries:)Symptom
Historically (per the report), an invalid hook command type (
command: [ ... ]) was accepted during manifest validation and later failed during hook registration, producing a raw traceback and partial on-disk leftovers.Expected behavior is manifest rejection as
ValidationErrorbefore installation side effects.Reproduction
hooks.<event>.commandas a list (e.g.command: [speckit.test-ext.hello]).specify extension add --dev <extension-dir>.[NEEDS CLARIFICATION: reproduction against current
mainHEAD was not demonstrated in this issue; report references prior state at commit27d14e2.]Suspected Code Paths
src/specify_cli/extensions/__init__.py:439-441— manifest validation now enforces hookcommandas a non-empty string (Hook '<name>' missing required 'command' string). This directly blocks the reported payload shape.src/specify_cli/extensions/__init__.py:436— inline note explicitly references#5080, indicating this exact bug path has already been addressed.src/specify_cli/extensions/__init__.py:3088—register_hooks(manifest)is still the sink where bad hook data would fail if validation were bypassed.src/specify_cli/extensions/__init__.py:3136— rollback-on-exception remains gated to the generic-agent command-registration path (if register_commands and generic_active and manifest.commands:).src/specify_cli/extensions/command_add.py:338-345— CLI catchesValidationErrorandExtensionError, so current validation failure should be rendered as user-facing error text instead of raw traceback.Root Cause Hypothesis
The originally reported crash was caused by insufficient hook-command type validation in
ExtensionManifest._validate(); truthy non-string values reachedHookExecutor.register_hooks()where dictionary-key usage required hashable string commands. In current code, this root cause is fixed by explicit type/emptiness checks before install side effects begin, and the implementation contains an in-code#5080marker at that guard. Confidence: high.Proposed Remediation
Preferred: No further code change for the specific reported defect. The current implementation already rejects non-string hook commands during manifest validation (
__init__.py:439-441), matching documented contract (extensions/EXTENSION-API-REFERENCE.md,hooks -> command: string) and preventing the downstreamTypeErrorpath.Given this, close as no-longer-reproducible on current code (fixed in-tree).
Alternatives (optional):
commandfails withValidationErrorbefore any extension files/agent artifacts are created.Files likely to change:
tests/extension install/manifest validation coverage for hook command type.Tests to add or update:
hooks.<event>.commandas list/map/int/bool ->ValidationError.Risks & Considerations
__init__.py:3136guard), but that is broader than this report and not substantiated here as a current repro.Open Questions
main?]