feat(plugins): surface hook capture setup and health

[phernandez]

Why

PR #1070 moved Codex and Claude lifecycle-hook behavior into Basic Memory core, but the host plugin setup and status skills did not expose the new capture controls or health surface. Users could install working hooks while still lacking a guided way to enable event capture, extend redaction, or see whether envelopes were pending and had ever flushed.

Closes #1117.

What Changed

• Added explicit, default-off captureEvents setup for both Codex and Claude Code.
• Added guided redactKeys and redactPaths configuration with local/privacy boundaries.
• Made both bm-status skills invoke the core hook status command and report configuration, versions, shared inbox depth, and last-flush state.
• Made Codex orientation and status recall both legacy codex_session checkpoints and normalized session projections.
• Documented schema ownership: plugins own direct-note schemas; core owns normalized session and tool_ledger projector contracts.
• Extended both package validators with content contracts for the new setup, status, recall, and schema-ownership behavior.
• Added a Codex plugin job to Consolidated Packages CI so GitHub runs the existing Codex target alongside the Claude package job.

Implementation Details

The plugins remain host-native packaging and guidance only. No hook runtime behavior moved back out of core, and capture remains opt-in.

The status skills treat bm hook status as authoritative for the effective harness configuration. Inbox counters are explicitly described as shared across supported harnesses so a Claude backlog is not misattributed to Codex, or vice versa.

Normalized session and tool_ledger artifacts remain core-owned projections. Codex continues to seed and recall codex_session for deliberate and legacy checkpoints while also querying normalized session notes. This avoids maintaining divergent projector schemas in each plugin.

Testing

Automated

• uv run python scripts/validate_codex_plugin.py plugins/codex: passed
• uv run python scripts/validate_claude_plugin.py plugins/claude-code: passed
• just package-check-codex: passed
• just package-check-claude-code: passed, including strict Claude plugin validation
• uv run pytest tests/test_codex_plugin_package.py tests/test_claude_plugin_hooks.py -q: 18 passed
• just fast-check: passed; only existing Python 3.14 asyncio-policy deprecation warnings were reported
• just package-check: passed

Manual

• uv run bm hook status --harness codex --project-dir .: resolved the Codex repo settings and reported capture off, the shared inbox, last flush, Basic Memory version, and uv version.
• uv run bm hook status --harness claude --project-dir .: resolved the Claude project settings and reported the same health surface.

Risks / Follow-ups

• These are agent skill contracts, so the package validators intentionally pin the required capture and health guidance to prevent documentation drift.
• captureEvents remains false by default; no new event data is recorded without explicit user opt-in.
• The shared inbox counters are global rather than per-harness; the skills disclose that limitation.
• Brigade-inspired lifecycle and memory-care ideas remain tracked separately in Explore Brigade-inspired harness receipts, context packs, and memory care #1118.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 68f54fa30a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Require a hook-capable Basic Memory for setup

When a user follows this skill with an older local basic-memory that still satisfies the prerequisite above (>= 0.19.0), this new mandatory smoke test fails because hook status only exists with the new core hook front door. The user can complete the interview and write settings, then be told to fix a project/launcher problem even though they followed the documented install path; bump the prerequisite to a version that includes bm hook status or make this check fall back/optional for older launchers.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Require a hook-capable Basic Memory for setup

The precondition for this skill accepts any basic-memory/bm that can print a version, but this newly required verification uses hook status, which older Basic Memory installs do not provide. In that environment setup now writes .codex/basic-memory.json and then fails the final check despite a reachable CLI; require a hook-capable version or keep trying a newer launcher such as uvx basic-memory when the first launcher lacks the hook command.

Useful? React with 👍 / 👎.