> 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_02_hook_runtime_safety.md).

# Session 02: Hook Runtime Safety

**Session ID**: `phase01-session02-hook-runtime-safety` **Packages**: apps/hooks, apps/cli **Status**: Not Started **Estimated Tasks**: \~16-20 **Estimated Duration**: 2-4 hours

***

## Objective

Harden hook scripts and listener bridge behavior so CLI hooks stay fast, silent, diagnosable, and safe when the local server or optional listener is unavailable.

***

## Scope

### In Scope (MVP)

* Audit current hook scripts against original hook-bundle behavior.
* Keep hook handlers dependency-light and under the documented latency target.
* Ensure normal hook operation avoids stdout and stderr noise.
* Improve diagnostics under the FactionOS home directory without storing raw payloads unnecessarily.
* Verify listener bridge startup, failure, and disconnect behavior.
* Cover file, bash, permission, subagent, prompt, active, idle, and stop paths that Phase 01 supports.

### Out of Scope

* Adding inbound chat commands.
* Docker or Apple Containers isolation.
* UI permission dialog redesign.

***

## Prerequisites

* [ ] Session 01 has identified the supported ingest vocabulary.
* [ ] Current hook scripts and hook map are readable in `apps/hooks/`.
* [ ] Hook tests can run without requiring Claude Code.

***

## Deliverables

1. Hook runtime fixes for supported handlers and listener flow.
2. Tests or fixtures that validate silence, exit behavior, payload shape, and unavailable-server fallback.
3. Updated hook README guidance for diagnostics, limits, and compatibility.

***

## EXAMPLES Implementation Sources

| Source                                           | Feature / Contract                                                                                 | Tests Required                                                                           | Documentation Owner                                    |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `EXAMPLES/1st-pass-artifacts/hooks-bundle/`      | Original handler set, shell wrappers, payload helpers, guard behavior, and diagnostics conventions | Script fixture tests for exit codes, emitted payload shape, silence, and redaction       | `apps/hooks/README_hooks.md`                           |
| `EXAMPLES/1st-pass-artifacts/ws-listener.js`     | Terminal listener bridge behavior and reconnect expectations                                       | Listener lifecycle tests for startup, server unavailable, malformed frames, and shutdown | `apps/hooks/README_hooks.md`, `apps/cli/README_cli.md` |
| `EXAMPLES/1st-pass-artifacts/spawn-listeners.sh` | Original listener spawning helper and shell integration                                            | CLI or hook fixture test for listener command construction where retained                | `apps/hooks/README_hooks.md`                           |
| `EXAMPLES/findings/claude-hook-contract.md`      | Claude hook lifecycle and payload constraints                                                      | Hook fixture tests for every supported Claude lifecycle path                             | `docs/api/event-api-hook-contracts.md`                 |

***

## Success Criteria

* [ ] Hook scripts return successfully when the local server is unavailable unless a guard intentionally denies an action.
* [ ] Normal hook operation is silent and bounded in latency.
* [ ] Diagnostic logs avoid full prompts, terminal output, secret values, and raw command payloads by default.
* [ ] Hook README clearly states supported hooks, diagnostics, and failure behavior.


---

# 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_02_hook_runtime_safety.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.