feat(codex): full profile and the same eleven lifecycle hooks under Codex - #620

The craftsmanship gate failed in CI: test_codex_plugin_contract.py had grown
to 323 lines, over the 300-line cap.

I missed it locally because the gate scopes itself to
`git diff --name-only --diff-filter=ACMR <base>...HEAD`, which only sees
committed work. I ran it while the change was still in the working tree, so
the target-file list was empty and the gate had nothing to scan. Running it
after committing reproduces the CI failure exactly. This is not a difference
between the local and CI comparison points; both resolve the same base ref.

The five hook-manifest contracts move to a sibling
test_codex_plugin_hooks_contract.py, which asserts hooks/hooks.json, while the
original keeps the package identity, the marketplace entries and the MCP
server command. No assertion was trimmed to fit the cap. The event-name test
splits into one for the event vocabulary and one for the matchers, and gains
an assertion that PostCompact stays unwired, so the count goes from 13 to 14.
Shared traversal moves into `_every_hook` and `_dispatched` helpers rather
than being repeated in each test.

214 and 153 lines, both under the cap.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH

…bounds

The mcp-host-config job failed with `ModuleNotFoundError: No module named
'mcp'`. Moving its codex-cli case to `--profiles full` in d39a92b made it
call `full_tool_bounds()`, which reads the registries and pulls the MCP SDK
that job deliberately never installs (ADR-1077).

Installing the SDK there would be the wrong fix, because the call was wrong
for a second reason that has nothing to do with dependencies. The bounds come
from THIS checkout's registries, while that job's command is
`uvx --from "hypermnesia-mcp[postgresql,sqlite]" ...`, which resolves the
published release. A PR that adds a tool moves this checkout's bounds while
the published wheel still advertises the old count, so the job would have
failed on a correct change. That is the same defect ADR-1077 was written
about, pointed the other way: a second source of truth waiting to disagree
with the first.

`--published-surface` marks a case whose command resolves a released
artifact. It keeps every other full-profile check (the 'full' profile marker
in the initialize instructions, a non-empty tools/list, memory_stats present
and callable, the empty-resources and session_recall shims) and drops only
the count bound, the one assertion that cannot be true of a foreign artifact.
Keeping the call unreachable is also what preserves ADR-1077's SDK-less
invariant for that job, so no dependency is added anywhere.

Tool-count coverage for codex-cli at the full profile is unaffected. It lives
in the two `python scripts/verify_mcp_hosts.py -- hypermnesia-mcp` calls in
the test and release-deps jobs (ci.yml:271 and :553), which pass no --clients
or --profiles and so exercise all three clients across both profiles against
this checkout's installed entry point, in jobs that do install the SDK.

ADR-1077's guard was too weak: it checked only that the script stays
IMPORTABLE without the SDK, which never protected the call. The new
`test_the_sdk_less_job_never_binds_a_release_to_this_checkouts_bounds` reads
the job out of ci.yml and fails if a full-profile case there omits the flag.
Verified to fail when the flag is removed.

ADR-1077 carries a dated revision recording all of this, so the "verifies
lean profiles only" claim is no longer left contradicting the code; the
generated mirror is regenerated from the canonical wiki page.

Reproduced both directions locally against a stub stdio server with `mcp`
blocked by the same meta_path blocker tests_py/test_tool_surface.py uses:
without the flag, `ImportError: mcp`, exit 1; with it, `PASS codex-cli/full:
initialize + discovery + memory_stats (59 tools)`, exit 0.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH

An independent review found three docs still describing the reduced Codex
design this PR removed. All three verified at the PR head before fixing.

plugins/hypermnesia-mcp-codex/SECURITY.md was the serious one: it told a
reviewer the package runs "the read-only or idempotent-write `lean` tool
profile" and "installs no hooks", both false. It now discloses what the
package can actually do: the full profile advertises and accepts `forget` and
the wiki_purge/wiki_migrate class, and eleven hooks run, of which
decision_gate reads patched files' contents and can block a tool call,
post_tool_capture persists tool output by default, session_lifecycle spawns a
detached subprocess, and post_commit_reindex may reindex the repository. It
also says how to opt back down: --profile lean, or drop the hooks reference.

README.md said "a 10-tool lean surface" 37 lines after the table in the same
file already said "all 57 tools" for the same plugin.

docs/shared-host-memory.md said the bundled plugin keeps a ten-tool lean
profile and cannot author an ADR. It now separates the bundled plugin (full,
can author) from a --profile lean process (cannot), which is what the test it
cites actually exercises. The neighbouring claim that the hosts lack
equivalent lifecycle hooks was stale the same way and is corrected.

Two new guards, both mutation-checked by reintroducing each original sentence
and confirming a failure:

- test_codex_prose_does_not_contradict_the_shipped_manifests reads the
  manifests and fails if the prose claims no hooks while plugin.json declares
  them, or a ten-tool surface while .mcp.json passes no --profile. Conditioned
  on the manifests, so reverting the design relaxes the guard rather than
  stranding it. It bans the drifted wordings, not the words, so the docs can
  still explain --profile lean as an opt-in.
- test_codex_security_doc_discloses_what_the_package_can_do fails if the
  security doc stops naming the destructive tools or the two hooks with
  effects beyond writing to the memory store.

scripts/check_doc_claims.py could not have caught any of this, measured
rather than assumed. Every one of its five patterns matches a NUMBER beside a
keyword (TOOL_CLAIM wants "N memory|standalone|MCP tools"), and none matched
any of the three sentences, README.md included, which that gate already
scans. "installs no hooks" has no number at all; "10-tool" and "ten-tool"
never take the keyword form. Separately, four of the five relevant files are
not in SCANNED_FILES. Widening that tuple alone would have caught nothing and
bought false confidence, so the gate is left alone and the gap is reported.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH

Five findings from an independent review of the final state. All five
verified against the PR head first; all five fixes mutation-checked.

1. --published-surface took the only tool-surface check with it. Dropping the
   checkout-derived bounds was right; leaving nothing but a memory_stats
   presence test was not, since a packaging regression that dropped whole
   registries from the published wheel would still have passed. A released
   full profile is a superset of that release's own lean profile, so
   LEAN_TOOL_NAMES is a floor that holds across versions. It needs no MCP SDK,
   so the ADR-1077 invariant is untouched. Confirmed against the real
   published wheel: PASS codex-cli/full (59 tools, 12.14s).

2. The denylist lost in the file split is back. The package's own SECURITY.md
   promises no skills, apps or agents and no installer, which is testable:
   test_codex_plugin_ships_an_mcp_server_and_hooks_and_nothing_else asserts
   it, with `hooks` moved from the denied set to the required one.

3. Ten of eleven hooks had no timeout and took Codex's 600-second default,
   against Claude's 5 to 30 on the same hooks. A latency budget is part of
   behaviour, so this PR's parity claim did not hold. Codex documents a
   special default and maximum only for SessionEnd and Interrupt, so every
   other budget is settable and is now the Claude manifest's own number.
   auto_recall on UserPromptSubmit is the sharp case: 5 seconds, where 600
   would have let a stalled uvx resolve hold up every prompt for ten minutes.
   decision_gate and no_deps_gate still declare none, because the Claude
   manifest declares none for them either and both hosts default a command
   hook to 600 seconds; declaring nothing on both sides is the parity case.
   A cold cache will exceed these budgets, which costs one skipped
   enrichment: both hosts cancel a timed-out hook and discard its output, and
   Claude Code's reference is explicit that a timed-out PreToolUse hook
   "doesn't block the tool call". The test now derives every expected value
   from the Claude manifest instead of restating literals.

4. The ci.yml regression guard checked for --published-surface anywhere in
   the mcp-host-config job body, so a second --profiles full case added later
   would have been covered by the first one's flag. It now scopes to each
   invocation. Mutation-checked with exactly that shape: a second unflagged
   full-profile case, which the old check passed and the new one catches.

5. --published-surface was a blanket flag threaded into every case of a run.
   Rather than document the currently-safe scope, mcp_host_cli.check_selection
   refuses it outside a single client and single profile, following the
   --command-includes-profile precedent in the same file. It cannot widen
   silently now.

scripts/verify_mcp_hosts.py had one line of headroom under the 300-line cap,
so the CLI surface moves to scripts/mcp_host_cli.py: defining flags is a
separate concern from driving the contract, nothing outside imported those
four helpers, and full_tool_bounds() stays put so ADR-1077 and
tests_py/test_tool_surface.py need no churn. 235 and 108 lines.

Mutation results, each reverted after:

    CAUGHT  1  published full surface missing the lean names
    CAUGHT  2  plugin.json regrows an `agents` key
    CAUGHT  3  auto_recall loses its 5s budget
    CAUGHT  3b SessionEnd set to 30s (over the Codex maximum)
    CAUGHT  4  second --profiles full case, unflagged
    CAUGHT  5  --published-surface across two clients

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH

Round-4 review findings. Both confirmed ones reproduced before fixing.

1. The prose-drift guard's own regex was broken. `\b` after "tool" never
   matches the plural, because the `s` in "tools" is a word character, so
   LEAN_SURFACE_CLAIM matched only the singular forms:

       MISSED  'The lean profile is exactly these ten tools:'
       MISSED  '10 tools'
       MISSED  'ten tools'
       MATCH   'a 10-tool lean surface'
       MATCH   'its ten-tool `lean` profile'

   The missed line is the exact historical wording the guard was written to
   catch. `tools?\b` now covers both, and a new test asserts every wording on
   both patterns, plus three benign lines this package really ships so the
   guard cannot become a tripwire on its own documentation.

2. README claimed "9 lifecycle hooks" in the banner and "nine" in prose while
   this PR put "eleven" in the same file, and docs/ROADMAP.md said 9 too.
   HOOK_MODULES has had 11 entries since #605, so this predates the PR but
   the PR made it a self-contradiction. Fixed in all three places, written as
   digits so the doc-claim gate can see them, and the gate gains a
   `lifecycle hooks` family counted from the allowlist rather than declared.
   That is the general fix: it covers both files and any future one, instead
   of pinning the banner line alone.

3. `--published-surface` paired with `--profiles lean` validated, and would
   have compared a released artifact against this checkout's LEAN_TOOL_NAMES:
   the same checkout-versus-release coupling ADR-1077's revision removed for
   full. check_selection now refuses the pairing.

5. Disclosed the per-edit cost, which neither docs/codex-plugin.md nor the
   package's SECURITY.md mentioned. One edit fires up to five `uvx` hook
   processes (two before the call, three after); a patch touching several
   files still costs five, since host_dispatch runs the module once per
   derived event inside one process. Measured 2026-09-22 (macOS 26.6.2 arm64,
   uv 0.11.3, warm cache, published 4.23.1): 0.18s to 0.21s per process in
   steady state, first invocation of a module 1.3s to 5.1s while its caches
   fill, roughly 0.4s of the total in the blocking path.

6, 7, 8. Shared helpers: tests_py/scripts/_codex_plugin_support.py now holds
   the paths, the JSON reader and one `hook_index` scan, following the
   `_craftsmanship_support.py` precedent in the same package. That removes
   the three independent module-name scans (`_claude_timeouts`, `_dispatched`
   and an inline `_matcher_for`) and the duplicated `_json`. The duplicated
   `PLUGIN_ROOT / "scripts"` assertion is now made once, where it belongs.
   test_cross_host_manifests.py keeps its own `_json`: different signature,
   different module, and folding it in would widen this change for nothing.

The new pattern test pushed test_codex_plugin_contract.py to 318 lines, so
the prose guards move to test_codex_plugin_docs_contract.py. They assert the
docs; what stays asserts the manifests. 225 and 115 lines.

4 was already reported as a disclosed trade-off and is unchanged: the
published floor proves a superset of the lean names, not an upper bound. I
found no way to tighten it that does not reintroduce the coupling finding 3
just closed.

While verifying, the "57 tools" drift I had been carrying since round 1
turned out not to be drift: `standalone_tool_names()` is 57 and
UPSTREAM_TOOL_NAMES adds 3, so the live 59 I measured sits inside the 57..60
bounds. The docs are right and the item is withdrawn.

Mutation results, each reverted after:

    CAUGHT  1  SECURITY.md regains 'these ten tools:' (plural)
    CAUGHT  2  README banner back to '9 lifecycle hooks'
    CAUGHT  2b ROADMAP back to '9 lifecycle hooks'
    CAUGHT  3  --published-surface with --profiles lean

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH

The Lint job died on `ModuleNotFoundError: No module named 'mcp_server'` and
gated out the whole pipeline. My fault, from the previous commit.

I verified the diagnosis against the code rather than accepting it. The Lint
job's only setup is `pip install --no-deps --require-hashes -r
requirements/lint.txt`, and that file resolves to ruff alone: no editable
install, no PYTHONPATH. `python scripts/check_doc_claims.py` puts `scripts/`
on sys.path rather than the repository root, so `mcp_server` is not importable
there at all.

The ADR-1077 precedent I cited does not transfer, and that was the error.
`full_tool_bounds()` is reached only from one case in `mcp-host-config`, which
the previous commit made sure never calls it without the SDK.
`canonical_hook_count()` is called unconditionally from `collect_failures`, so
a late import buys nothing: the call always happens.

Every sibling in doc_claim_sources.py takes `read_fn` and parses text;
`canonical_hook_count` was the only one importing a module. It now reads
`mcp_server/hooks/entry.py` as source and evaluates the HOOK_MODULES
frozenset literal with `ast` (stdlib, no dependency). The source of truth is
still the allowlist, and there is still no second copy of the number.

Reproduced the job's constraint rather than trusting the dev environment: a
fresh venv with only requirements/lint.txt installed, run with no PYTHONPATH
from the repository root. That environment confirms `mcp_server` is
unimportable as the gate sees it, and all three Lint steps now pass in it:

    ruff format --check .            -> 3404 files already formatted, exit 0
    ruff check .                     -> All checks passed!, exit 0
    python scripts/check_doc_claims.py -> doc claims OK, exit 0

The repro is faithful, not merely green: putting the importing version back
into that same venv reproduces the CI failure exactly, `ModuleNotFoundError:
No module named 'mcp_server'`, exit 1.

New LintJobEnvironmentTests pins it. One test blocks `mcp_server` with the
same meta_path blocker tests_py/test_tool_surface.py uses for the SDK and
runs `collect_failures` with `scripts/` on sys.path; the other checks the
text parse still equals `len(HOOK_MODULES)`, so reading text did not trade
correctness for portability. Mutation-checked: restoring the importing
version fails the first test.

The unit fixture gains its own `mcp_server/hooks/entry.py` stand-in with a
four-name allowlist, the way it already carries CATALOGUE, PINNED_TEST and
BIBLIOGRAPHY for the other families. Four rather than the live eleven so that
adding a hook to Cortex does not edit this file.

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH

Round-6 review findings, all verified before fixing.

A tautological assertion is replaced. `HOOKS_PATH.is_relative_to(PLUGIN_ROOT)`
could never fail: the support module defines HOOKS_PATH AS
`PLUGIN_ROOT / "hooks/hooks.json"`, so it tested a constant, not the ignore
file it sat beside. The test now walks every file the Codex package ships and
asserts each is covered by a directory entry in .mcpbignore, and separately
that no `!` line re-includes one. Mutation-checked with a re-include, which
the three neighbouring membership assertions all pass and only this catches.

The doc-claim gate now scans the Codex package's own README and SECURITY.md
and the two repository docs that describe it. Probed first: no claim pattern
matches anything in those four files today, so this adds coverage without
changing a verdict.

The hook-count family only ever saw digits, and most claims were spelled out.
Every claim family in this gate is digit-only by convention, so the seven
remaining "eleven" occurrences become "11" rather than teaching one family to
read number words. The gate went from seeing 2 hook-count claims to 10,
across 6 files.

`session_lifecycle` does NOT reliably survive Codex's 3-second SessionEnd
ceiling, and the document said it did while also saying a cold cache could
lose the run. Measured, warm uv cache, the manifest's own command against a
SessionEnd event: 3.46s, 1.03s, 0.97s. The first run exceeds the maximum.
Detaching consolidation (#610) makes the remaining work small enough to
attempt, not small enough to guarantee. Recorded as a named limitation with
the numbers rather than reconciled in prose: it costs the session record of
the first session after an install or upgrade, and prewarming does not help
because the measurement is already warm. It needs a decision, not an edit,
and the report to the owner says so.

decision_gate and no_deps_gate keep no timeout, and the reasoning is now
written down instead of implied. A timeout on a gate fails OPEN: Claude Code's
reference says a timed-out PreToolUse hook "doesn't block the tool call ... so
don't count on a stalled hook to act as a gate." A tight ceiling would trade a
rare long wait for silently ungated edits. Warm, these cost 0.16s to 0.26s;
the long wait is only the first cold resolve. The same exposure exists on
Claude Code today, so it belongs to both manifests, and narrowing it on one
host would break the parity a test now enforces.

preemptive_context's `Read` matcher has no Codex equivalent, and that is a
host limitation rather than a wiring gap. Codex's tool table has no read tool:
shell commands and unified exec both match as `Bash`. Reading a file there is
a shell command, and preemptive_context keys on `tool_input.file_path`, which
a shell event does not carry, so matching `Bash` would spawn a uvx process per
shell command for a guaranteed no-op. Documented as a one-sided gap; the
edit-triggered half still fires through apply_patch.

The duplicated uvx guard string across all 11 entries is left as acknowledged
debt with a note naming the test that keeps the copies honest. Generating both
manifests from one template is the real fix and is out of scope here.

Mutation results, each reverted after:

    CAUGHT  .mcpbignore re-includes the hooks directory
    CAUGHT  .mcpbignore loses the plugin directory entry
    CAUGHT  codex README gains '9 lifecycle hooks'
    CAUGHT  docs/codex-plugin.md gains '9 lifecycle hooks'

Co-Authored-By: Claude Sonnet 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH

Signed-off-by: cdeust <[email protected]>

Signed-off-by: cdeust <[email protected]>