ctx init installs non-functional Claude Code hooks: flat schema (silently ignored) + ignores CLAUDE_CONFIG_DIR

[DamieMoon]

Summary

ctx init reports Hooks ✓ / Statusline ✓ but the hooks it writes never execute on current Claude Code. Two independent defects combine:

1. Wrong schema — ctx init writes the flat hook form {"type":"command","command":...} directly into the event array. Current Claude Code requires the nested matcher-group form {"hooks":[{"type":"command","command":...}]} and silently ignores flat entries. (The README §3 "Agent hooks" example shows the same flat form and is likewise affected.)
2. Wrong file — ctx init hardcodes ~/.claude/settings.json. Claude Code honors the CLAUDE_CONFIG_DIR environment variable to relocate its config directory; when it is set, the live settings file is $CLAUDE_CONFIG_DIR/settings.json and ~/.claude/settings.json is not read. ctx init ignores CLAUDE_CONFIG_DIR.

Either defect alone makes the hooks dead; together they produce a silent false-positive (Hooks ✓) while ctx brief/ctx persist never fire.

A third, minor issue: hasHookEntry() only inspects a top-level command key, so it cannot detect already-installed nested entries — re-running ctx init would keep appending duplicates.

The statusline step is affected by defect (2) as well: its JSON shape (statusLine: {type, command}) is correct, but it is written to the same hardcoded ~/.claude/settings.json, so it does not render when CLAUDE_CONFIG_DIR points elsewhere.

Environment

• ctx: v2.4.7 (CLI + daemon)
• Claude Code: v2.1.x (Linux/Unix install with CLAUDE_CONFIG_DIR set to an XDG-style dir)
• Hook events affected: SubagentStart, SubagentStop (the events ctx init configures)

Authoritative schema (current Claude Code)

Per the Claude Code hooks docs, every event maps to an array of matcher-group objects — including events that don't support matchers (SubagentStart/SubagentStop/UserPromptSubmit/Stop/…). The matcher key may be omitted or empty for non-tool events, but the hooks wrapper is mandatory. A bare {type,command} without the hooks wrapper is explicitly invalid.

Required:

{
  "hooks": {
    "SubagentStart": [
      { "hooks": [ { "type": "command", "command": "ctx brief --hook" } ] }
    ],
    "SubagentStop": [
      { "hooks": [ { "type": "command", "command": "ctx persist --hook" } ] }
    ]
  }
}

What ctx init writes today (does not execute):

{
  "hooks": {
    "SubagentStart": [ { "type": "command", "command": "ctx brief --hook" } ],
    "SubagentStop":  [ { "type": "command", "command": "ctx persist --hook" } ]
  }
}

Reproduction

1. On a Claude Code install where CLAUDE_CONFIG_DIR points at an XDG-style config dir, run ctx init and accept the hooks + statusline prompts.
2. Observe ctx init reports Hooks ✓ and writes them to ~/.claude/settings.json.
3. Spawn any subagent. The SubagentStart/SubagentStop hooks do not run (no ctx brief/ctx persist invocation).

Evidence (deterministic A/B/A)

Pointing the SubagentStart/SubagentStop hooks at a probe script that appends to a logfile when executed, in the correct settings file ($CLAUDE_CONFIG_DIR/settings.json), changing only the schema between runs:

FLAT   schema → logfile EMPTY                         (hooks did NOT execute)
NESTED schema → "FIRED SubagentStart", "FIRED SubagentStop"   (both executed)

Same script, same file, same session — the only variable was flat vs nested. Nested firing after a mid-session edit also confirms Claude Code reloads settings live, so the flat "empty" result is genuine (not a reload artifact).

Root cause (go/internal/cli/init.go)

• claudeSettingsPath() returns filepath.Join(home, ".claude", "settings.json") unconditionally (Unix branch) — no CLAUDE_CONFIG_DIR check, no awareness of the XDG ~/.config/claude-code/settings.json location used by newer installs.
• stepHooks() constructs each entry as {"type":"command","command":...} and appends it directly to the event array — the flat (now-invalid) form.
• hasHookEntry() only reads a top-level command; it does not recurse into a nested hooks[], so it misreports correctly-nested entries as "missing" and re-appends on every run.

Proposed fix

1. claudeSettingsPath() — resolve the settings file as: CLAUDE_CONFIG_DIR/settings.json if the env var is set; else prefer ~/.config/claude-code/settings.json when it already exists; else fall back to ~/.claude/settings.json. (Writing to a file Claude Code does not read is the root of the silent failure.)
2. stepHooks() — emit the nested matcher-group shape, e.g. a small newHookGroup(cmd) helper returning {"hooks":[{"type":"command","command":cmd}]} (matcher omitted; these events are not tool-scoped).
3. hasHookEntry() — recurse into a nested hooks[] (in addition to the legacy flat command) so detection is idempotent against both shapes and re-runs don't append duplicates.
4. README §3 — update the "Agent hooks" example (and the statusLine note's surrounding context) to the nested matcher-group form.

I have these changes implemented and verified (gofmt/vet clean; package tests pass; the patched ctx init writes nested entries to the CLAUDE_CONFIG_DIR location, is idempotent on re-run, and the hooks fire under the A/B/A probe above). Happy to open a PR.

Impact

• Silent: ctx init claims success while subagent briefing/persistence never run, so users believe the integration is active when it is not.
• The flat form was likely valid against an earlier Claude Code hook schema; this is a platform-schema evolution that ctx init (and the README example) have not yet tracked.

Separate minor observation (not part of the fix above)

During ctx init, the version step prints Version … (parse error) [skip] for both a release build and a dev build — the latest-release comparison in stepVersion() fails to parse. Cosmetic (the step is non-fatal and skips cleanly), filed here only for awareness.

[GottZ]

Verified — thanks, this is an accurate report. Independently confirmed against the code and the current Claude Code docs:

• Defect 1 (flat schema): stepHooks() appends {"type":"command","command":…} directly into the event array (go/internal/cli/init.go:349-364). The nested matcher-group wrapper {"hooks":[{"type":"command","command":…}]} is mandatory for every event incl. matcher-less SubagentStart/SubagentStop, so the written hooks don't fire. Confirmed.
• Defect 2 (CLAUDE_CONFIG_DIR): claudeSettingsPath() (init.go:82-93) unconditionally writes ~/.claude/settings.json and never consults CLAUDE_CONFIG_DIR. Per the docs (claude-directory: "If you set CLAUDE_CONFIG_DIR, every ~/.claude path … lives under that directory instead"), this writes to a file Claude Code doesn't read. Confirmed — and it defeats the statusline step too (shared resolver).
• hasHookEntry() (init.go:280-292) only checks a top-level command, so it can't detect nested entries and re-appends on rerun. Confirmed.
• stepVersion() (parse error) — confirmed, cosmetic.
• Our README §3 and brief.go examples carry the same flat form, and init_test.go bakes it into fixtures — so this is a genuine schema-drift on our side, not a typo. We'll fix those alongside.

One correction to the proposed fix: the ~/.config/claude-code/settings.json fallback isn't a real Claude Code location (the documented locations are ~/.claude/, project .claude/, and the CLAUDE_CONFIG_DIR override). The resolver should be just: CLAUDE_CONFIG_DIR/settings.json if set, else ~/.claude/settings.json. Could you drop that XDG branch in the PR? With that one change — yes please, open the PR. We'll review the nested-schema + recursive-hasHookEntry parts and pull in the README/brief.go/test-fixture updates.

[GottZ]

Fixed in root (commit b3872f8 via PR #6, released in v2.5.0). ctx init now writes the nested matcher-group hook schema and honors CLAUDE_CONFIG_DIR; hasHookEntry detects both flat and nested shapes (idempotent re-runs); README + brief.go examples corrected. The proposed ~/.config/claude-code fallback was intentionally not added — CLAUDE_CONFIG_DIR (else ~/.claude) is the only documented resolution path. Thank you for the report, the A/B/A probe-script diagnosis, and the PR. 🙏