feat(plugins): surface hook capture setup and health in Codex and Claude

[phernandez]

Why

PR #1070 moved Codex and Claude lifecycle-hook behavior into the released Basic Memory core. The host plugins now correctly contain only hook registration and zero-logic launchers.

The plugin READMEs document opt-in event capture and the bm hook status / flush commands, but the setup and status skills do not expose that functionality. A user can install the integration while still having no guided way to enable capture or see whether the local inbox is healthy.

Follow-up to #1070.

Current gaps

• The Codex and Claude bm-setup skills do not ask about or persist captureEvents.
• Setup does not offer the supported redactKeys and redactPaths privacy controls.
• Setup smoke tests prove project routing, but do not run the core hook status command.
• The Codex and Claude bm-status skills do not report capture enabled state, pending and processed envelopes, last flush, Basic Memory version, or uv availability.
• Codex orientation/status still emphasizes legacy codex_session checkpoints while the new projector writes normalized session and tool_ledger notes.
• Schema ownership is inconsistent: Claude seeds session, Codex seeds codex_session, and neither plugin currently owns a tool_ledger schema.

Proposed work

Setup

Update both host-native bm-setup skills to:

• Ask whether to enable local lifecycle-event capture, defaulting to off.
• Explain that capture is local, redacted, queued, and explicitly flushed.
• Optionally collect redactKeys and redactPaths.
• Write captureEvents as a real JSON boolean in the host-native configuration.
• Run bm hook status with the appropriate harness and project directory as part of setup verification.

Status and orientation

Update both bm-status skills to invoke the core status command and report:

• capture enabled or disabled
• inbox path
• pending and processed envelope counts
• last successful flush
• resolved project mapping
• Basic Memory and uv versions

Update Codex bm-orient and bm-status recall so normalized session notes remain discoverable while legacy codex_session notes continue to work.

Schemas

Choose one canonical ownership model for normalized session and tool_ledger schemas. Prefer a shared source that both plugins seed or reference instead of maintaining divergent copies. Preserve backward compatibility for existing codex_session notes.

Verification

Add content-contract or package-validator tests proving:

• both setup skills expose captureEvents and privacy controls
• both status skills use the core hook status surface
• Codex recall includes normalized and legacy checkpoint types
• the plugins contain no duplicated hook runtime behavior

Run:

• just package-check-codex
• just package-check-claude-code
• just package-check

Acceptance criteria

• A fresh Codex or Claude setup can explicitly enable or leave event capture disabled.
• Status makes a dormant, backlogged, or never-flushed hook installation visible.
• Both hosts can find notes produced by the normalized projector.
• Schema ownership is documented and tested without duplicating core hook logic in either plugin.
• Existing users with legacy codex_session notes retain recall compatibility.

[claude]

Claude finished @phernandez's task in 2m 6s —— View job

---

Triage complete (with a labeling mistake to flag)

• Read issue and gather context
• Classify type, priority, component, complexity
• Check for duplicate issues
• Apply labels
• Post triage summary

⚠️ Please clean up labels manually: while probing which label names exist in this repo (my label-editing tool only supports adding, not removing), I accidentally applied bug, documentation, question, and duplicate to this issue. None of those apply — please remove them. I don't have permission to remove labels myself, so this needs a maintainer action. Apologies for the noise.

Classification

• Type: Enhancement (already correctly labeled). This is a follow-up to feat(core): add bm hook producer front door for harness capture #1070 to surface already-shipped core functionality (captureEvents, redaction, bm hook status) through the Codex and Claude Code host plugin skills — not a new capability in core.
• Priority: Medium. Nothing is broken; this closes a UX gap where a user can install the hook integration and have no guided way to enable capture or see if it's healthy. Not urgent, but it's the kind of gap that quietly erodes trust in the feature.
• Component: Plugins/skills (plugins/claude-code and the Codex equivalent), touching bm-setup and bm-status skills, plus schema ownership for session/codex_session/tool_ledger. Note: this repo's actual label set doesn't include a granular priority/component/complexity taxonomy (only default GitHub labels like bug, enhancement, documentation, question, duplicate exist) — I couldn't find cli, mcp, medium, complex, plugins, mcp-tool, etc. as real labels to apply, so I've left this assessment in prose rather than guessing at a mismatched label.
• Complexity: Complex. This spans two host-native plugins (Codex + Claude), setup-flow changes (new prompts, JSON config writes, redaction options), status-flow changes (parsing/reporting core hook status output), a schema-ownership decision (shared vs. duplicated session/tool_ledger schemas) with backward-compat requirements for legacy codex_session notes, and new content-contract/package-validator tests across both plugin packages.

Duplicate check

Searched open/closed issues for bm-setup skill, tool_ledger schema, codex_session, and hook status — no existing duplicate found. This issue is a clean, well-scoped follow-up to #1070.

Notes for implementers

The issue is well-specified (clear gaps, proposed work broken into Setup / Status / Schemas / Verification, and explicit acceptance criteria), so no clarifying questions are needed before someone picks this up. Per my triage-only scope, no code changes, branches, or commits were made.