aws-samples / aws-samples/sample-oh-my-aidlcops

aidlc plugin fails to load: hooks/hooks.json missing required top-level "hooks" wrapper

Open
#87 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.