aws-samples / aws-samples/sample-oh-my-aidlcops
aidlc plugin fails to load: hooks/hooks.json missing required top-level "hooks" wrapper
- Dominant language
- Python
- Stars
- 20
- Forks
- 5
- Avg merge
- 27m
- Merged PRs (30d)
- 1
Description
### Issue
`aidlc` plugin fails to load: `hooks/hooks.json` missing required top-level `"hooks"` wrapper
### Summary
**Plugin:** `aidlc@oh-my-aidlcops` v0.4.0-preview.1
**Claude Code version:** 2.1.228
**What happened**
Installing the `aidlc` plugin via:
```
/plugin marketplace add https://github.com/aws-samples/sample-oh-my-aidlcops
/plugin install aidlc@oh-my-aidlcops --scope project
```
registers successfully, but the plugin fails to load:
```
claude plugin list --json
...
"errors": [
"Hook load failed: [\n {\n \"expected\": \"record\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"hooks\"\n ],\n \"message\": \"Invalid input: expected record, received undefined\"\n }\n]"
]
```
`claude plugin details aidlc@oh-my-aidlcops` confirms all 4 hooks (SessionStart, PreToolUse, Stop, StopFailure) and the `ontology-wiki` skill fail to register as a result.
**Root cause**
`plugins/aidlc/hooks/hooks.json` defines the event keys at the **top level** of the file:
```json
{
"SessionStart": [ ... ],
"PreToolUse": [ ... ],
"Stop": [ ... ],
"StopFailure": [ ... ]
}
```
Claude Code's plugin loader expects the event keys nested one level deeper, under a top-level `"hooks"` key — confirmed by diffing against working plugins (e.g. `claude-plugins-official/plugins/claude-security/hooks/hooks.json`, `ruflo-core`'s `hooks/hooks.json`):
```json
{
"description": "...",
"hooks": {
"SessionStart": [ ... ],
"PreToolUse": [ ... ],
"Stop": [ ... ],
"StopFailure": [ ... ]
}
}
```
Without that wrapper, the loader's schema validation fails on the missing `hooks` record and the whole plugin errors out.
**Fix**
Wrap the existing content of each affected `hooks/hooks.json` in a `"hooks"` key:
```diff
{
+ "hooks": {
"SessionStart": [
{
"_oma": "oma-session-start",
"hooks": [
{
"type": "command",
"command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start-ontology.sh\""
}
]
}
],
"PreToolUse": [ ... ],
"Stop": [ ... ],
"StopFailure": [ ... ]
+ }
}
```
Applying this locally to the installed plugin cache resolves the issue — `claude plugin details` then reports all 4 hooks and the `ontology-wiki` skill loading with no errors.
Since `hooks/hooks.json` is likely generated by `oma-compile` from the DSL `hooks:` block (per the comments in `session-start-ontology.sh` / `stop-gate.sh`), the fix probably belongs in the compiler template rather than by hand-editing each generated file.
**Affected plugins:** `aidlc` and `agenticops` both ship `hooks/hooks.json` with event keys at the top level (missing the `"hooks"` wrapper). `ai-infra` and `modernization` already have the correct wrapper, so those two load fine.
Contributor guide
Research direction
Start with plugins/aidlc/hooks/hooks.json and compare its structure with the working hook files described in the issue. Trace oma-compile from the hooks: DSL and the comments in session-start-ontology.sh and stop-gate.sh, then verify the affected aidlc and agenticops plugins with claude plugin details; done means all four hooks and the ontology-wiki skill load without errors.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bash
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 58/100