> 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/phases/phase_01/session_01_event_ingest_contract_reconciliation.md).

# Session 01: Event Ingest Contract Reconciliation

**Session ID**: `phase01-session01-event-ingest-contract-reconciliation` **Packages**: packages/protocol, apps/server, apps/hooks **Status**: Complete **Estimated Tasks**: \~18-22 **Estimated Duration**: 2-4 hours

***

## Objective

Reconcile `/event` ingest, hook payload names, OpenClaw-compatible payloads, and shared protocol event types so current runtime behavior is explicit, typed, and tested.

***

## Scope

### In Scope (MVP)

* Compare current `/event` dispatch against direct hook and OpenClaw evidence.
* Decide which historical event names become first-class supported behavior.
* Preserve opaque fallback for unknown named events.
* Add typed protocol coverage before server behavior changes.
* Add focused tests for supported hook payloads, type-only compatibility, and missing dispatch keys.
* Update contract docs for the exact shipped behavior.

### Out of Scope

* UI redesign for event display.
* War Room relay implementation.
* Full orchestration controls such as spawn, resume, fork, and handoff.

***

## Prerequisites

* [ ] Review `docs/api/event-api-hook-contracts.md`.
* [ ] Review current `packages/protocol/src/events.ts`.
* [ ] Review current `/event` route tests in `apps/server/tests/`.

***

## Deliverables

1. Protocol updates or explicit no-change notes for hook ingest event shapes.
2. Server ingest behavior that accepts the selected compatibility payloads.
3. Hook fixture tests and server route tests for supported and unsupported payloads.
4. Documentation updates that distinguish shipped compatibility from planned parity.

***

## EXAMPLES Implementation Sources

| Source                                          | Feature / Contract                                                                     | Tests Required                                                                                           | Documentation Owner                                                  |
| ----------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `EXAMPLES/findings/claude-hook-contract.md`     | Claude hook event names, prompt/tool/stop/permission expectations, and failure posture | Server `/event` tests and hook fixture tests for mapped Claude hook payloads                             | `apps/hooks/README_hooks.md`, `docs/api/event-api-hook-contracts.md` |
| `EXAMPLES/1st-pass-artifacts/hooks-config.json` | Original hook registration shape and managed hook names                                | Installer or fixture tests that prove current hook names match supported ingest                          | `apps/hooks/README_hooks.md`                                         |
| `EXAMPLES/1st-pass-artifacts/hooks-bundle/`     | Original hook payload builders and guard scripts                                       | Payload fixtures for active, idle, tool, permission, file, bash, and subagent paths selected for support | `apps/hooks/README_hooks.md`                                         |
| `EXAMPLES/1st-pass-artifacts/openclaw-SKILL.md` | Non-Claude cookbook with type-based payloads                                           | Compatibility tests for accepted OpenClaw-style payloads or explicit unsupported tests                   | `docs/api/README_api.md`, `docs/api/event-api-hook-contracts.md`     |
| `EXAMPLES/findings/websocket-events.txt`        | Event names emitted after ingest and expected fanout families                          | Event-shape tests for generated WebSocket frames after ingest                                            | `packages/protocol/README_protocol.md`                               |

***

## Success Criteria

* [ ] Supported hook payloads create the expected hero, mission, tool, permission, or opaque event outcomes.
* [ ] Payloads with only `type` are either intentionally supported or explicitly documented as unsupported with tests.
* [ ] Unknown named events remain accepted without crashing and emit bounded opaque mission events.
* [ ] Protocol, server, hook docs, and tests agree on the same ingest vocabulary.


---

# 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/phases/phase_01/session_01_event_ingest_contract_reconciliation.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.