fix(hooks): render nested hook metadata as plain JSON

[Abhishek Acharya (abhishekacharya200)]

Description

hook_contract._freeze turns hook metadata into MappingProxyType and tuples, all the way down. The native renderers in hook_native_formats.py only did dict(handler.metadata) and dict(binding.metadata), and returned raw entries as-is, so nested mappings such as env stayed frozen. json.dumps then failed during apm install / apm update with Object of type mappingproxy is not JSON serializable.

This adds _thaw next to _freeze in hook_contract.py, so the contract that freezes metadata also owns turning it back into plain JSON values. Mappings become new dicts, lists and tuples become new lists, and scalars pass through unchanged. hook_native_formats.py uses it for handler metadata, binding metadata and raw entries in both the nested and flat render paths. The IR stays frozen, and there is no default=str, no dropped metadata and no consent bypass.

Issue and approved scope

Issue: #3167

Human scope-approval comment: #3167 (comment)

This PR completes the approved scope.

Fixes #3167

Type of change

• Bug fix
• New feature
• Documentation
• Maintenance / refactor

Testing

• Tested locally
• All existing tests pass
• Added tests for new functionality (if applicable)

New tests in tests/integration/test_architecture_contract_guards.py, next to the existing native-edge tests:

• JSON round trip for Claude, Codex, Gemini, and nested (PreToolUse) and flat (PreInvocation) Antigravity. Each one checks that nested env, arrays, extension metadata and scalars are kept, along with the command and the timeout unit.
• Hook-group metadata and raw entries round trip, including mappings inside arrays.
• Changing the rendered output does not change the frozen IR.
• Gemini's in-place _copilot_keys_to_gemini conversion keeps env.

All 8 new tests fail on main with Object of type mappingproxy is not JSON serializable and pass with this change. ruff check, ruff format --check, scripts/check_test_assertions.py and scripts/check_exact_test_duplicates.py are clean. In pytest tests/unit tests/integration -k hook, 1136 tests pass. The 11 that fail also fail on main on my Windows machine (symlink and hook-execution tests).

CLI reproduction, without running any hooks. A local package has .apm/hooks/check.json containing {"hooks":{"PreToolUse":[{"type":"command","command":"echo check","env":{"APM_TEST":"value"}}]}}, and a project depends on it with targets: [claude, codex]:

# main
$ apm install
  [x] 1 package failed:
    +- ../hookpkg -- Failed to integrate primitives from local package: Object of type mappingproxy is not JSON serializable
[x] Installation failed with 1 error(s) in 0.1s. No install transaction changes were committed.

# this branch
$ apm install
[*] Installed 1 APM dependency in 0.2s.

With this branch, .claude/settings.json and .codex/hooks.json both contain the handler with "env": {"APM_TEST": "value"}.

The hooks guide now states that nested handler and hook-group fields such as env are written to native JSON unchanged. CHANGELOG.md has an entry under Unreleased > Fixed.

Spec conformance (OpenAPM v0.1)

• N/A -- this PR does not change OpenAPM-observable behaviour.

[Copilot]

🟡 Changes recommended

The canonical thawing path lacks its required static architecture guard, and the changelog entry omits the PR reference.

2 open findings

• Require architecture and mutation guards for canonical _thaw rendering · New
• Add pull request reference to the Unreleased changelog entry · New

What changed in this PR

Fixes nested hook metadata serialization while preserving immutable hook IR.

Changes:

• Adds recursive metadata thawing at native render boundaries.
• Adds regression coverage across supported renderers.
• Updates documentation and changelog.

File	Description
src/​apm_cli/​hook_contract.py	Adds recursive metadata thawing.
src/​apm_cli/​integration/​hook_native_formats.py	Thaws metadata before native rendering.
tests/​integration/​test_architecture_contract_guards.py	Tests serialization and IR independence.
docs/​src/​content/​docs/​producer/​author-primitives/​hooks-and-commands.md	Documents nested metadata preservation.
CHANGELOG.md	Records the bug fix.

🧠 Review effort: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Abhishek Acharya (abhishekacharya200)]

@microsoft-github-policy-service agree

[microsoft-github-policy-service]

Abhishek Acharya (@abhishekacharya200) the command you issued was incorrect. Please try again.

Examples are:

@microsoft-github-policy-service agree

and

@microsoft-github-policy-service agree company="your company"