> 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/spec.md).

# Session Specification

**Session ID**: `phase09-session01-contracts-and-naming-baseline` **Phase**: 09 - Codex Provider-Neutral Foundation **Status**: Not Started **Created**: 2026-05-31 **Package**: packages/protocol **Package Stack**: TypeScript shared protocol contracts, Vitest protocol tests, package README contract notes

***

## 1. Session Overview

This session starts Phase 09 by moving the shared protocol vocabulary from a Claude-centered naming baseline to a provider-neutral contract that can describe both Claude Code and Codex CLI hook events. The work belongs in `packages/protocol` first because later hook runtime, CLI installer, server ingest, and web product sessions should consume one typed source of truth instead of duplicating provider strings and event names.

The session adds `codex-cli` as a supported hero CLI, introduces provider-neutral hook event constants while preserving deprecated Claude aliases, and expands safe ingest payload fields for Codex lifecycle and tool metadata. The changes must preserve existing Claude Code behavior and `/event` compatibility with `eventName ?? hook` payloads and type-only compatibility inputs.

Privacy boundaries are part of the contract. Codex fields may be accepted only when they are compact, optional, and safe to summarize. Raw prompts, transcript paths or contents, patch bodies, command output, MCP argument bodies, token-like values, provider credentials, and broad absolute paths must not become required or promoted shared payload fields.

***

## 2. Objectives

1. Add `codex-cli` support and provider display metadata to the shared hero contract.
2. Rename Claude-only hook event vocabulary to provider-neutral exported names while keeping backward-compatible aliases.
3. Add Codex lifecycle event names and safe optional ingest fields without requiring raw sensitive payloads.
4. Add focused protocol tests proving Claude compatibility, Codex contract acceptance, and blocked raw transcript path promotion.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase08-session08-release-candidate-validation-and-documentation-closeout` - provides completed release closeout and explicit residual-risk wording for future phases.
* [x] `phase08-session01-release-requirements-and-risk-baseline` - provides release claim discipline and no-overclaim boundaries.
* [x] `phase03-session03-subagent-lineage-and-mission-graph-runtime` - provides current subagent lineage vocabulary and safe degraded metadata.
* [x] `phase01-session01-event-ingest-contract-reconciliation` - provides current `/event` compatibility baseline.

### Required Tools/Knowledge

* TypeScript literal-array contract patterns in `packages/protocol/src/ingest.ts`.
* Hero and model contract patterns in `packages/protocol/src/heroes.ts`.
* Protocol package export style in `packages/protocol/src/index.ts`.
* Focused Vitest protocol tests in `packages/protocol/tests/ingest.test.ts` and adjacent tests.
* Phase 09 PRD provider constraints and Codex hook event baseline.

### Environment Requirements

* Node 20+ and npm workspaces installed.
* No Codex, Claude, OpenAI, Anthropic, Cloudflare, hosted, or provider credentials are required.
* Session implementation must stay inside `packages/protocol` except for spec-system state files created by `plansession`.

***

## 4. Scope

### In Scope (MVP)

* Maintainers can type Codex heroes - add `codex-cli` to `HeroCli` and add provider display metadata helpers for CLI labels and provider families.
* Protocol consumers can use provider-neutral hook event names - introduce `AGENT_HOOK_EVENT_NAMES` or equivalent plus a deprecated `CLAUDE_HOOK_EVENT_NAMES` alias.
* Codex lifecycle events are known to the contract - include `SubagentStart`, `PreCompact`, and `PostCompact` alongside existing hook events.
* Codex-safe optional fields are represented - add optional `turnId`, `permissionMode`, `hookEventName`, `agentId`, `agentType`, `toolName`, and compact `mcpToolName` where appropriate.
* Claude compatibility remains stable - tests prove existing Claude hook names, aliases, first-class hook types, lineage types, and type-only OpenClaw compatibility still work.
* Sensitive raw fields stay out of promoted payloads - tests assert `transcript_path` and `transcriptPath` are not part of the shared promoted ingest payload shape.
* Package docs reflect provider-neutral ownership - update `packages/protocol/README_protocol.md` to route later hook, server, CLI, and web work through protocol contracts first.

### Out of Scope (Deferred)

* Codex CLI hook installation - *Reason: Phase 10 owns installer behavior and user-owned Codex configuration boundaries.*
* Hook runtime normalization in `apps/hooks` - *Reason: Phase 09 Session 02 owns handler normalization and redaction behavior.*
* Codex hook map and Codex-specific handlers - *Reason: Phase 09 Session 03 owns `hooks.codex.json` and handler coverage.*
* Server, web, CLI, or hook runtime behavior changes - *Reason: this session is protocol-first and should only add compile-time contracts.*
* Custom Codex slash command claims - *Reason: current Phase 09 baseline does not support claiming custom slash command behavior.*

***

## 5. Technical Approach

### Architecture

Keep the change protocol-owned and pure. `packages/protocol/src/heroes.ts` should continue to export the `HeroCli` union while adding a compact metadata map or helper functions for CLI display labels and provider families. The helper should cover existing CLI values and `codex-cli`, use exhaustive typing, and avoid pushing display decisions into app packages before product integration sessions.

`packages/protocol/src/ingest.ts` should expose provider-neutral hook event constants as the new primary vocabulary. The deprecated Claude-named export should remain an alias to avoid breaking existing imports. Codex lifecycle event names should be included in the primary array, and type guards should use the provider-neutral vocabulary while preserving alias guard exports when compatibility requires them.

Optional Codex fields should be added to shared ingest payload interfaces only as compact metadata. They should not require a runtime handler to send raw prompts, transcript paths, patch bodies, terminal output, MCP argument bodies, token-like values, or provider credentials. If a value is not safe to promote, leave it as local-only handler input for Session 02 normalization.

### Design Patterns

* Protocol-first ownership: add shared contracts in `packages/protocol` before downstream packages consume them.
* Backward-compatible aliases: keep old exports working while new provider-neutral names become primary.
* Exhaustive metadata: use typed records or helper functions so new `HeroCli` values cannot be forgotten.
* Negative privacy tests: assert raw transcript path field names are absent from promoted shared payload fixtures.
* Optional-safe fields: Codex-specific metadata must be optional and bounded by contract wording.

### Technology Stack

* TypeScript 5.9 in `packages/protocol`.
* Vitest protocol tests through the root Vitest configuration.
* npm workspace typecheck for `packages/protocol`.
* Biome formatting and repo `git diff --check` validation.

***

## 6. Deliverables

### Files to Create

| File                                     | Purpose                                                                | Est. Lines |
| ---------------------------------------- | ---------------------------------------------------------------------- | ---------- |
| `packages/protocol/tests/heroes.test.ts` | Focused tests for `HeroCli`, `codex-cli`, and display metadata helpers | \~90       |

### Files to Modify

| File                                     | Changes                                                                                                                             | Est. Lines |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/heroes.ts`        | Add `codex-cli`, provider metadata helpers, and provider-neutral comments                                                           | \~70       |
| `packages/protocol/src/ingest.ts`        | Add provider-neutral hook constants, Claude aliases, Codex lifecycle names, and safe optional Codex fields                          | \~120      |
| `packages/protocol/tests/ingest.test.ts` | Assert provider-neutral names, alias compatibility, Codex event acceptance, optional safe fields, and raw transcript path exclusion | \~130      |
| `packages/protocol/README_protocol.md`   | Document Phase 09 protocol ownership and downstream package routing                                                                 | \~45       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `HeroCli` includes `codex-cli`.
* [ ] CLI display metadata covers every `HeroCli` value and exposes a Codex label without downstream duplication.
* [ ] Provider-neutral hook event constants include current Claude events plus `SubagentStart`, `PreCompact`, and `PostCompact`.
* [ ] Deprecated Claude-named hook event exports remain available as aliases.
* [ ] Event ingest payload types accept optional safe Codex fields: `turnId`, `permissionMode`, `hookEventName`, `agentId`, `agentType`, `toolName`, and compact `mcpToolName`.
* [ ] Type-only OpenClaw compatibility inputs and existing Claude hook payload tests remain valid.
* [ ] Shared promoted payload fixtures do not include `transcript_path` or `transcriptPath`.

### Testing Requirements

* [ ] Protocol hero tests written and passing.
* [ ] Protocol ingest tests updated and passing.
* [ ] `npm --workspace packages/protocol run typecheck` passes.
* [ ] Manual contract review confirms no raw prompt, transcript, patch, command output, MCP args, token, credential, or broad path fields become required.

### Non-Functional Requirements

* [ ] Existing Claude Code behavior is unchanged beyond names and compatibility aliases.
* [ ] Contracts remain local-first and credential-free.
* [ ] Provider-neutral naming does not imply Codex installation, hook runtime support, hosted transfer, or custom slash commands.
* [ ] Later server, web, CLI, and hook changes can consume the protocol contract without redefining provider values.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `git diff --check` passes.

***

## 8. Implementation Notes

### Key Considerations

* Keep the session narrow. Protocol changes should make later Codex work possible without wiring Codex runtime behavior now.
* Backward compatibility matters because server, web, hook, and docs references may still import Claude-named constants during the transition.
* Codex lifecycle support should be type-level only in this session. Runtime handling starts in Session 02 and Session 03.
* Display metadata helpers should be simple and stable enough for later web labels, but this session should not update web UI.
* Do not promote transcript paths into shared ingest payloads. Session 02 may read local-only handler input for safe ID derivation, but shared contracts should not require or encourage raw path storage.

### Potential Challenges

* Alias drift: mitigate by making deprecated Claude-named arrays reference the provider-neutral array instead of copying values.
* Exhaustiveness gaps: mitigate with tests that compare metadata keys to all `HeroCli` values.
* Overclaiming Codex support: keep docs clear that protocol readiness is not hook installation or runtime validation.
* Sensitive field creep: add tests and comments around raw transcript path exclusion and optional compact metadata only.
* Downstream compile breakage: use existing export names and type aliases where needed so current imports continue to typecheck.

### Relevant Considerations

* \[P03-packages/protocol] **Protocol leads cross-package work**: shared event, REST, WebSocket, and domain types should change in `packages/protocol` before other packages consume them.
* \[P07] **Redaction is boundary-specific**: future hook payloads need explicit minimization at each boundary and should expose labels, counts, booleans, and compact ids only.
* \[P03] **Stable docs are the current contract**: package README updates should describe current protocol ownership without treating archived or historical examples as runtime authority.
* \[P08] **Release-candidate evidence is claim-scoped**: protocol contract support is not release proof for Codex runtime behavior, hosted identity, production validation, or trusted erasure.
* \[Security] **P06-S07-HOSTED-VALIDATION**: no production-hosted or provider-backed validation should be implied by local protocol tests.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* A deprecated alias could diverge from the provider-neutral source and break existing Claude Code imports.
* Optional Codex fields could accidentally become required or imply raw transcript, patch, prompt, MCP, or command output storage.
* `codex-cli` could be added to the union without metadata, causing downstream labels or filters to fall through.
* Provider-neutral docs could overstate protocol readiness as installed Codex runtime support.

***

## 9. Testing Strategy

### Unit Tests

* Test `HeroCli` metadata helpers for every current CLI value plus `codex-cli`.
* Test provider-neutral hook event names for current Claude events plus Codex lifecycle additions.
* Test deprecated Claude hook event aliases and guards still accept existing names.
* Test optional Codex-safe metadata fields in `EventIngestPayload` fixtures.
* Test type-only OpenClaw compatibility payloads remain accepted by the shared union.
* Test serialized promoted fixtures do not contain `transcript_path` or `transcriptPath`.

### Integration Tests

* Run `npx vitest run packages/protocol/tests/heroes.test.ts packages/protocol/tests/ingest.test.ts`.
* Run `npm --workspace packages/protocol run typecheck`.
* Run focused Biome check for touched package files.

### Manual Testing

* Review `packages/protocol/README_protocol.md` to confirm it routes later hook, server, CLI, and web work through protocol-first contracts.
* Review changed types for no Codex installation, hosted transfer, runtime validation, or custom slash command claims.
* Review changed payload fields for privacy-safe optional metadata only.

### Edge Cases

* Existing imports of `CLAUDE_HOOK_EVENT_NAMES` and `ClaudeHookEventName`.
* Unknown provider strings passed as runtime payload values.
* `codex-cli` display metadata missing from helper maps.
* Codex lifecycle names present in `hook` rather than `eventName`.
* Type-only compatibility payloads that do not carry hook event names.
* Accidental inclusion of `transcript_path`, `transcriptPath`, raw patch, raw prompt, command output, or MCP argument fields in promoted payload fixtures.

***

## 10. Dependencies

### External Libraries

* None expected. Use existing TypeScript, Vitest, npm workspace, and Biome tooling.

### Other Sessions

* **Depends on**: `phase08-session08-release-candidate-validation-and-documentation-closeout`
* **Depended by**: `phase09-session02-hook-runtime-normalization`, `phase09-session03-codex-hook-map-and-codex-specific-handlers`, `phase10-session03-server-ingest-codex-lifecycle`, `phase10-session04-web-codex-awareness`

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# 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/spec.md?ask=<question>&goal=<endgoal>
```

`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.