fix(hooks): normalize flat entries for Claude

[danielmeppiel]

fix(hooks): normalize flat entries for Claude

TL;DR

Claude integration now converts flat Copilot-style command entries into Claude's required matcher/hooks groups before merge. The same normalized shape is written to .claude/settings.json and the APM ownership sidecar, preventing Claude from rejecting the entire settings file.

Important

Closes #2062.

Problem (WHY)

• Flat hook entries targeting Claude were written unchanged, so Claude reported hooks: Expected array, but received undefined and skipped the settings file.
• The ownership sidecar also retained the invalid flat shape, making a settings-only repair unstable on later installs.
• [!] Authors could not use one flat manifest for both Copilot and Claude without manually maintaining target-specific shapes.

The fix keeps the change deterministic and testable: "Grounding outputs in deterministic tool execution transforms probabilistic generation into verifiable action."

Approach (WHAT)

#	Fix
1	Add a Claude sibling transform around the existing Gemini and Antigravity normalization path.
2	Wrap only flat entries with matcher: "*"; preserve already nested entries.
3	Transform before ownership marking so settings and sidecar stay structurally aligned.
4	Document the portable flat authoring contract in Starlight and the bundled APM guide.

Implementation (HOW)

File	Change
src/apm_cli/integration/hook_integrator.py	Extends the shared nested-entry helper with an optional default matcher and dispatches Claude entries through it before merge.
tests/unit/integration/test_hook_integrator_issue2062.py	Reproduces the package/consumer flow and asserts the exact settings and sidecar structures.
docs/src/content/docs/producer/author-primitives/hooks-and-commands.md	Shows flat source input and Claude's normalized output.
packages/apm-guide/.apm/skills/apm-usage/package-authoring.md	Records that one flat manifest can target both Copilot and Claude.

Diagrams

Legend: the dashed stage is the new target-specific normalization added before the existing ownership and write path.

flowchart LR
    subgraph Parse[Parse]
        P1[Flat hook entry]
    end
    subgraph Normalize[Normalize for target]
        N1[Claude matcher group]
    end
    subgraph Persist[Persist]
        W1[settings.json]
        W2[apm-hooks.json]
    end
    P1 --> N1
    N1 --> W1
    N1 --> W2
    classDef new stroke-dasharray: 5 5;
    class N1 new;

Loading

Trade-offs

• Reuse the shared transform instead of adding a separate merge path. This keeps target normalization next to the existing Gemini and Antigravity behavior and avoids duplicate wrapping logic.
• Use matcher: "*" only for newly wrapped entries. Existing nested Claude entries retain their authored matcher rather than being rewritten.
• Keep ownership metadata on the outer group. Moving it into command handlers would diverge from the sidecar's existing matching and cleanup contract.

Benefits

1. A flat PreToolUse command becomes one schema-valid Claude matcher group.
2. Settings and sidecar contain the same normalized hook content, with ownership metadata only in the sidecar.
3. Existing nested manifests and non-Claude target transforms remain covered by the 169-test relevant suite.
4. Package authors have one documented source shape for Copilot and Claude.

Validation

uv run --extra dev pytest tests/unit/integration/test_hook_integrator_issue2062.py tests/unit/integration/test_hook_integrator.py tests/unit/integration/test_hook_naked_format.py -q:

169 passed in 15.88s

uv run --extra dev pytest tests/unit tests/test_console.py -q:

exit 0

Lint mirror and mutation evidence

uv run --extra dev ruff check src/ tests/:

All checks passed!

uv run --extra dev ruff format --check src/ tests/:

1411 files already formatted

uv run --extra dev python -m pylint --disable=all --enable=R0801 --min-similarity-lines=10 --fail-on=R0801 src/apm_cli/:

Your code has been rated at 10.00/10

bash scripts/lint-auth-signals.sh:

[+] auth-signal lint clean

Disabling the Claude transform made test_hook_integrator_issue2062.py fail on the unchanged flat entry; restoring it returned the test to green.

Scenario Evidence

#	Scenario (user promise)	Principle(s)	Test(s) proving it	Type
1	Installing a package with flat hooks for Claude writes loadable matcher groups to settings and preserves ownership for later installs.	Portability by manifest, Multi-harness support, DevX	tests/unit/integration/test_hook_integrator_issue2062.py::test_claude_wraps_flat_hook_entries_in_settings_and_sidecar (regression-trap for #2062)	integration

How to test

• Run the issue regression test and observe 1 passed.
• Install a package containing a flat PreToolUse command with target claude.
• Inspect .claude/settings.json and confirm the entry has matcher: "*" plus a hooks array.
• Inspect .claude/apm-hooks.json and confirm the same outer shape includes _apm_source.
• Re-run the install and confirm the hook is not duplicated.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

[Copilot]

Pull request overview

Fixes Claude hook integration by normalizing flat (Copilot-style) hook entries into Claude’s nested matcher/hooks grouping prior to merge, keeping both .claude/settings.json and the APM ownership sidecar structurally aligned (and preventing Claude from skipping the whole settings file).

Changes:

• Extend the shared “wrap flat entries into nested groups” helper to optionally add a default matcher, and apply it for the claude target.
• Add a regression test covering settings + sidecar output shape for Claude (#2062).
• Document the “flat input -> nested Claude output” contract in Starlight docs and the bundled APM guide.

Show a summary per file

File	Description
src/apm_cli/integration/hook_integrator.py	Adds a Claude-specific normalization step and extends the shared nesting helper with default_matcher.
tests/unit/integration/test_hook_integrator_issue2062.py	New regression test ensuring Claude output is nested (and sidecar preserves ownership).
docs/src/content/docs/producer/author-primitives/hooks-and-commands.md	Documents portable flat hook entries and shows Claude’s normalized nested output.
packages/apm-guide/.apm/skills/apm-usage/package-authoring.md	Updates the packaged guide to describe the same flat->nested portability contract.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 3
• Review effort level: Low

[danielmeppiel]

APM Review Panel: ship_with_followups

Fixes Claude hook rejection by normalizing flat entries into matcher/hooks groups, keeping one portable manifest for both Copilot and Claude.

cc @danielmeppiel @sergio-sisternes-epam -- a fresh advisory pass is ready for your review.

All active panelists converged on a minimal, sound fix. The shared nested-entry helper is the right abstraction, no auth or supply-chain surface changes, and the runtime cost remains linear in the small hook-entry set. The remaining in-scope work is stronger CLI-level regression evidence and small documentation precision improvements.

Aligned with: portable by manifest; multi-harness support; pragmatic package authoring; OSS community feedback.

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	0	2	Clean shared-helper design; update one stale docstring.
CLI Logging Expert	0	0	2	No CLI output regression.
DevX UX Expert	0	0	2	Portable authoring contract is clear; explain the wildcard.
Supply Chain Security Expert	0	0	1	Global wildcard preserves flat-entry semantics.
OSS Growth Hacker	0	0	2	Lead release notes with write-once portability.
Doc Writer	0	1	1	Docs are accurate; keep mirrored guidance concise.
Test Coverage Expert	0	2	1	CLI test passes; assert sidecar and marker contract.
Performance Expert	0	0	2	O(entries) transform has negligible cost.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Top 5 follow-ups

1. [Test Coverage Expert] Assert the sidecar structure and use module-level pytestmark in the CLI integration test.
2. [Doc Writer] Keep the Starlight and bundled APM guide explanations concise and synchronized.
3. [OSS Growth Hacker] Add a user-benefit CHANGELOG line and scannable source/output captions.
4. [Supply Chain Security Expert] Explain that matcher: "*" preserves the global semantics of a flat entry.
5. [Performance Expert] Replace the per-call no-op lambda with a named helper for clarity.

Recommendation

Fold the CLI-level sidecar proof, mutation-break evidence, and small code/doc polish, then run a final panel pass.

---

Full per-persona findings

• Python Architect: update the shared-helper docstring to include Claude; commit the new CLI integration test.
• CLI Logging Expert: make the Claude wrapper docstring precise; optional transform debug breadcrumb.
• DevX UX Expert: explain matcher: "*" in both documentation surfaces.
• Supply Chain Security Expert: state that the wildcard is semantically equivalent to flat global hooks.
• OSS Growth Hacker: add benefit-led release notes and source/output captions.
• Auth Expert: inactive; no auth surface changed.
• Doc Writer: keep duplicate mirrored prose bounded while preserving required APM guide synchronization.
• Test Coverage Expert: assert .claude/apm-hooks.json, use module-level marker placement, and preserve nested-input behavior.
• Performance Expert: name the no-op key fixer; shallow copies are expected and safe.

_{This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.}

[danielmeppiel]

APM Review Panel: ship_now

Claude flat hook manifests now install as valid matcher groups while preserving existing settings and APM ownership metadata.

cc @danielmeppiel @sergio-sisternes-epam -- a fresh advisory pass is ready for your review.

All active panelists converge on shipping. The implementation reuses the existing target-normalization strategy, preserves the flat entry's global semantics with matcher: "*" and adds no auth, supply-chain, logging, or meaningful performance surface. The CLI integration test exercises a real apm install --target claude, while unit coverage protects sidecar ownership and already-nested input.

The only remaining observation is a contradictory style preference about representing the no-op key transform. The named helper was requested and folded in the prior pass; it is explicit and consistent with the callable strategy contract, so no further action is warranted.

Aligned with: portable by manifest; secure by default; multi-harness support; pragmatic package authoring; OSS community feedback.

Panel summary

Persona	B	R	N	Takeaway
Python Architect	0	0	1	Clean reuse of the shared target-normalization strategy.
CLI Logging Expert	0	0	0	No CLI output or logging surface changed.
DevX UX Expert	0	0	0	The portable source and generated Claude shape are clear.
Supply Chain Security Expert	0	0	0	Provenance and global matcher semantics are preserved.
OSS Growth Hacker	0	0	0	Benefit-led release and docs framing is ready.
Doc Writer	0	0	0	Starlight and the bundled guide are accurate and synchronized.
Test Coverage Expert	0	0	0	CLI, unit, and mutation-break evidence protect the user promise.
Performance Expert	0	0	0	The O(entries) in-memory transform is negligible.

B = blocking-severity findings, R = recommended, N = nits.
Counts are signal strength, not gates. The maintainer ships.

Folded in this run

• (panel) Added an empirical CLI integration test for apm install --target claude -- resolved in c3650318c1118a401300e472f7afca84a5809a57.
• (panel) Proved existing settings and valid nested hooks survive the install -- resolved in c3650318c1118a401300e472f7afca84a5809a57.
• (panel) Asserted normalized sidecar ownership and module-level integration marker placement -- resolved in c3650318c1118a401300e472f7afca84a5809a57.
• (panel) Clarified wildcard semantics, source/output captions, and the Copilot-and-Claude scope -- resolved in c4e290220d523ae54f055d6317cf3c9f6b97ce13.
• (panel) Added a benefit-led changelog entry and precise named Claude key strategy -- resolved in c3650318c1118a401300e472f7afca84a5809a57.

Copilot signals reviewed

Copilot review round 1 produced a summary and zero inline findings. Round 2 after the first push also produced zero inline findings.

Regression-trap evidence (mutation-break gate)

• tests/integration/test_claude_flat_hook_install_e2e.py::test_install_claude_nests_flat_hooks_and_preserves_settings -- deleted the Claude dispatch to _to_claude_hook_entries; the test failed on the unchanged flat entry; the guard was restored and the test passed.

Lint contract

The canonical ruff pair was silent at the final SHA. Pylint R0801 rated 10.00/10, the YAML/file-length/relative-path guards were clean, and scripts/lint-auth-signals.sh reported clean.

CI

All checks on exact head c4e290220d523ae54f055d6317cf3c9f6b97ce13 completed successfully or were intentionally skipped. CI run: https://github.com/microsoft/apm/actions/runs/29061945387

Mergeability status

PR	head SHA	CEO stance	iters	folds	defers	Copilot rounds	CI	mergeable	mergeStateStatus	notes
#2097	c4e2902	ship_now	2	5	0	2	green	MERGEABLE	BLOCKED	awaiting required review

Recommendation

All in-scope findings are folded, exact-SHA CI is green, and the regression test is mutation-proven. Ready for maintainer review.

---

Full per-persona findings

Python Architect

• [nit] An optional None key-fixer could replace the named no-op helper. The named helper was explicitly requested in the prior pass and keeps the strategy callable and intent grep-able, so no change is recommended.

CLI Logging Expert

No findings.

DevX UX Expert

No findings.

Supply Chain Security Expert

No findings.

OSS Growth Hacker

No findings.

Auth Expert -- inactive

PR touches hooks, tests, documentation, and changelog; no authentication surface changed.

Doc Writer

No findings.

Test Coverage Expert

No findings. Relevant tests passed, and the CLI regression test failed when the production guard was removed.

Performance Expert

No findings.

_{This panel is advisory. It does not block merge. Re-apply the panel-review label after addressing feedback to re-run.}