> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase09-session01-contracts-and-naming-baseline/implementation-notes.md). # Implementation Notes **Session ID**: `phase09-session01-contracts-and-naming-baseline` **Package**: packages/protocol **Started**: 2026-05-31 06:10 **Last Updated**: 2026-05-31 06:37 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 18 / 18 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### 2026-05-31 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Tools available * [x] Directory structure ready *** ### Task T001 - Verify Phase 08 completion and protocol ownership **Started**: 2026-05-31 06:10 **Completed**: 2026-05-31 06:11 **Duration**: 1 minute **Notes**: * Confirmed the active session is Phase 09 Session 01 with package scope `packages/protocol`. * Verified Phase 08 Session 08 is listed as completed in spec-system state before changing contracts. * Reviewed protocol README ownership notes and confirmed this session should stay protocol-first. **Files Changed**: * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T001 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T001 review outcome. *** ### Task T002 - Review current protocol exports **Started**: 2026-05-31 06:11 **Completed**: 2026-05-31 06:12 **Duration**: 1 minute **Notes**: * Reviewed `packages/protocol/src/index.ts`; the package barrel re-exports `heroes.ts` and `ingest.ts`, so added contracts will be available without new barrel wiring. * Reviewed existing `HeroCli`, `CLAUDE_HOOK_EVENT_NAMES`, `ClaudeHookEventName`, and ingest guard exports for compatibility requirements. * Searched downstream references to confirm Claude-named exports may remain in use during the transition and should be true aliases. **Files Changed**: * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T002 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T002 review outcome. *** ### Task T003 - Review existing protocol tests **Started**: 2026-05-31 06:12 **Completed**: 2026-05-31 06:13 **Duration**: 1 minute **Notes**: * Reviewed `packages/protocol/tests/ingest.test.ts` and identified existing compatibility assertions for Claude hook dispatch names, OpenClaw type-only payloads, hook families, bounds, and response envelopes. * Confirmed new tests should preserve the existing Claude expectations while adding provider-neutral names and Codex-safe fixture coverage. **Files Changed**: * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T003 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T003 review outcome. *** ### Task T004 - Add Codex CLI metadata helpers **Started**: 2026-05-31 06:13 **Completed**: 2026-05-31 06:15 **Duration**: 2 minutes **Notes**: * Added `codex-cli` to the shared `HeroCli` values. * Added exhaustive CLI display metadata and helper functions for labels and provider families. * Updated Claude-only model wording to provider-neutral wording. **Files Changed**: * `packages/protocol/src/heroes.ts` - added CLI vocabulary, metadata, and helper exports. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T004 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T004 implementation details. **BQC Fixes**: * Contract alignment: used `satisfies Record` so missing CLI metadata fails typecheck (`packages/protocol/src/heroes.ts`). *** ### Task T005 - Add provider-neutral hook event constants **Started**: 2026-05-31 06:15 **Completed**: 2026-05-31 06:17 **Duration**: 2 minutes **Notes**: * Added `AGENT_HOOK_EVENT_NAMES` and `AgentHookEventName` as the primary provider-neutral vocabulary. * Kept `CLAUDE_HOOK_EVENT_NAMES` and `ClaudeHookEventName` as deprecated aliases that reference the provider-neutral source. * Added `isAgentHookEventName` and kept `isClaudeHookEventName` as a compatibility guard. **Files Changed**: * `packages/protocol/src/ingest.ts` - added provider-neutral event names and aliases. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T005 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T005 implementation details. **BQC Fixes**: * Contract alignment: deprecated Claude exports reference the provider-neutral array directly so alias values cannot drift (`packages/protocol/src/ingest.ts`). *** ### Task T006 - Add Codex lifecycle event names **Started**: 2026-05-31 06:17 **Completed**: 2026-05-31 06:18 **Duration**: 1 minute **Notes**: * Added `SubagentStart`, `PreCompact`, and `PostCompact` to the shared hook event vocabulary. * Updated the provider-neutral guard path so these lifecycle names are recognized without removing existing Claude names. **Files Changed**: * `packages/protocol/src/ingest.ts` - added lifecycle names and guard coverage. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T006 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T006 implementation details. **BQC Fixes**: * Contract alignment: new lifecycle names flow through `AgentHookEventName`, alias types, and guards from the same source array (`packages/protocol/src/ingest.ts`). *** ### Task T007 - Add optional safe Codex metadata fields **Started**: 2026-05-31 06:18 **Completed**: 2026-05-31 06:19 **Duration**: 1 minute **Notes**: * Added optional `turnId`, `permissionMode`, `hookEventName`, `agentId`, `agentType`, `toolName`, and `mcpToolName` fields to the shared ingest base payload. * Kept provider-specific values optional and compact instead of requiring raw local handler data. * Added an `AgentLifecycleIngestPayload` shape for the new Codex lifecycle names. **Files Changed**: * `packages/protocol/src/ingest.ts` - added safe optional metadata fields and lifecycle payload shape. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T007 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T007 implementation details. **BQC Fixes**: * Trust boundary enforcement: promoted fields are optional compact metadata, with comments excluding raw transcripts, prompts, patches, command output, MCP argument bodies, tokens, credentials, and broad paths (`packages/protocol/src/ingest.ts`). *** ### Task T014 - Update provider-neutral hero comments **Started**: 2026-05-31 06:19 **Completed**: 2026-05-31 06:20 **Duration**: 1 minute **Notes**: * Reworded hero CLI and model comments to describe provider-neutral protocol vocabulary instead of Anthropic-only assumptions. **Files Changed**: * `packages/protocol/src/heroes.ts` - updated provider-neutral comments. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T014 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T014 implementation details. *** ### Task T015 - Update ingest privacy comments **Started**: 2026-05-31 06:20 **Completed**: 2026-05-31 06:21 **Duration**: 1 minute **Notes**: * Added source comments that transcript paths and other raw provider data are local-only handler inputs, not shared promoted ingest fields. **Files Changed**: * `packages/protocol/src/ingest.ts` - documented promoted metadata privacy boundary. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T015 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T015 implementation details. **BQC Fixes**: * Error information boundaries: comments explicitly keep sensitive local provider data out of shared payload contracts (`packages/protocol/src/ingest.ts`). *** ### Task T008 - Update protocol README ownership notes **Started**: 2026-05-31 06:21 **Completed**: 2026-05-31 06:23 **Duration**: 2 minutes **Notes**: * Added Phase 09 provider-neutral ownership notes to the protocol package README. * Documented that downstream hooks, server ingest, CLI installers, and web labels should consume protocol contracts first. * Kept Codex language scoped to protocol readiness and avoided runtime installation, hosted validation, and custom slash command claims. **Files Changed**: * `packages/protocol/README_protocol.md` - added Phase 09 provider-neutral baseline notes. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T008 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T008 implementation details. **BQC Fixes**: * Contract alignment: README routes later package behavior through protocol-owned contracts before downstream implementation (`packages/protocol/README_protocol.md`). *** ### Task T009 - Create hero CLI contract tests **Started**: 2026-05-31 06:23 **Completed**: 2026-05-31 06:25 **Duration**: 2 minutes **Notes**: * Added focused tests for `codex-cli` in `HeroCli`. * Added metadata helper assertions for labels, provider families, and provider labels. * Added exhaustive metadata key coverage against every `HERO_CLI_VALUES` entry. **Files Changed**: * `packages/protocol/tests/heroes.test.ts` - added hero CLI contract tests. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T009 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T009 test details. **BQC Fixes**: * Contract alignment: test compares metadata keys with the complete CLI value list (`packages/protocol/tests/heroes.test.ts`). *** ### Task T010 - Update ingest event-name tests **Started**: 2026-05-31 06:25 **Completed**: 2026-05-31 06:28 **Duration**: 3 minutes **Notes**: * Added assertions for `AGENT_HOOK_EVENT_NAMES`, Codex lifecycle event names, and `isAgentHookEventName`. * Verified deprecated Claude event-name exports reference the provider-neutral array and still guard existing names. **Files Changed**: * `packages/protocol/tests/ingest.test.ts` - updated event-name and alias coverage. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T010 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T010 test details. **BQC Fixes**: * Contract alignment: tests assert deprecated Claude aliases stay tied to provider-neutral event constants (`packages/protocol/tests/ingest.test.ts`). *** ### Task T011 - Preserve Claude and OpenClaw compatibility tests **Started**: 2026-05-31 06:28 **Completed**: 2026-05-31 06:29 **Duration**: 1 minute **Notes**: * Added type-level coverage for existing Claude `PreToolUse` payloads. * Added `/event` fallback coverage for payloads that use `hook` instead of `eventName`. * Added type-only OpenClaw compatibility payload coverage that does not require hook event names. **Files Changed**: * `packages/protocol/tests/ingest.test.ts` - added Claude and OpenClaw compatibility fixtures. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T011 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T011 test details. **BQC Fixes**: * Contract alignment: tests keep existing Claude and OpenClaw ingest shapes accepted by `EventIngestPayload` (`packages/protocol/tests/ingest.test.ts`). *** ### Task T012 - Add Codex safe metadata fixtures **Started**: 2026-05-31 06:29 **Completed**: 2026-05-31 06:30 **Duration**: 1 minute **Notes**: * Added Codex lifecycle payload fixtures for `SubagentStart`, `PreCompact`, and `PostCompact`. * Covered optional `turnId`, `permissionMode`, `hookEventName`, `agentId`, `agentType`, `toolName`, and compact `mcpToolName` fields. **Files Changed**: * `packages/protocol/tests/ingest.test.ts` - added Codex-safe ingest fixtures. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T012 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T012 test details. **BQC Fixes**: * Trust boundary enforcement: Codex fixtures use compact metadata only and omit raw prompt, transcript, patch, command output, MCP argument, token, and credential data (`packages/protocol/tests/ingest.test.ts`). *** ### Task T013 - Add negative privacy assertions **Started**: 2026-05-31 06:30 **Completed**: 2026-05-31 06:31 **Duration**: 1 minute **Notes**: * Added type-level assertions that blocked raw provider field names are not promoted keys of `EventIngestPayload`. * Added runtime fixture assertions excluding transcript paths, raw patch bodies, prompt bodies, command output, MCP argument bodies, tokens, and credentials from promoted Codex payloads. **Files Changed**: * `packages/protocol/tests/ingest.test.ts` - added negative privacy assertions. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T013 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T013 test details. **BQC Fixes**: * Error information boundaries: tests keep sensitive local provider data out of promoted shared payload fixtures (`packages/protocol/tests/ingest.test.ts`). *** ### Task T016 - Run focused protocol Vitest coverage **Started**: 2026-05-31 06:31 **Completed**: 2026-05-31 06:33 **Duration**: 2 minutes **Notes**: * Ran focused Vitest coverage for hero and ingest contract tests. * Result: 2 test files passed, 11 tests passed. **Files Changed**: * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T016 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T016 verification result. *** ### Task T017 - Run typecheck and focused Biome check **Started**: 2026-05-31 06:33 **Completed**: 2026-05-31 06:34 **Duration**: 1 minute **Notes**: * Ran `npm --workspace packages/protocol run typecheck`; result passed. * Ran focused `npx biome check` for touched protocol source and test files; result passed with no fixes applied. **Files Changed**: * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T017 complete. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T017 verification result. *** ### Task T018 - Run ASCII, LF, diff, and no-overclaim review **Started**: 2026-05-31 06:34 **Completed**: 2026-05-31 06:37 **Duration**: 3 minutes **Notes**: * Ran ASCII checks for touched protocol and session files; result passed. * Ran CRLF checks for touched protocol and session files; result passed. * Ran `git diff --check`; result passed. * Manually reviewed changed protocol README, source, and tests for no-overclaim language. Codex wording remains scoped to protocol contracts and explicitly excludes runtime installation, server behavior changes, hosted transfer, and custom slash command support. **Files Changed**: * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/tasks.md` - marked T018 complete and completed the session checklist. * `.spec_system/specs/phase09-session01-contracts-and-naming-baseline/implementation-notes.md` - recorded T018 verification result. *** ## Session Summary **Completed**: 2026-05-31 06:37 **Implemented**: * Added `codex-cli` to the shared hero CLI contract with exhaustive display metadata helpers. * Added provider-neutral ingest event constants and guards while preserving deprecated Claude aliases. * Added Codex lifecycle event names and optional compact Codex metadata fields. * Added tests for hero metadata, provider-neutral event names, Claude compatibility, Codex-safe fixtures, OpenClaw type-only compatibility, and blocked raw provider fields. * Updated protocol README ownership notes with explicit no-overclaim boundaries. **Verification**: * `npx vitest run packages/protocol/tests/heroes.test.ts packages/protocol/tests/ingest.test.ts` - passed, 2 files, 11 tests. * `npm --workspace packages/protocol run typecheck` - passed. * `npx biome check packages/protocol/src/heroes.ts packages/protocol/src/ingest.ts packages/protocol/tests/heroes.test.ts packages/protocol/tests/ingest.test.ts packages/protocol/README_protocol.md` - passed. * ASCII and CRLF checks for touched protocol and session files - passed. * `git diff --check` - passed. **BQC Summary**: * Contract alignment fixes applied across hero metadata, ingest aliases, lifecycle events, and tests. * Trust boundary and error-information boundary checks applied to keep raw provider data out of promoted Codex fixtures and docs. *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase09-session01-contracts-and-naming-baseline/implementation-notes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.