> 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/phase17-session06-hook-context-and-provider-skill-parity/spec.md). # Session Specification **Session ID**: `phase17-session06-hook-context-and-provider-skill-parity` **Phase**: 17 - Notice Board Coordination Parity **Status**: Not Started **Created**: 2026-06-05 **Package**: apps/hooks **Package Stack**: JavaScript *** ## 1. Session Overview This session restores Notice Board context lookup in the local hook runtime so agents can receive current coordination messages at prompt start without turning raw hook telemetry into shared content. Sessions 01 through 03 restored the canonical Notice Board model, persistence, routes, and WebSocket behavior. Session 05 added command-access parity, so hooks can now remind agents to use the supported CLI path when a provider cannot safely inject context. The main implementation target is `apps/hooks/src/factionos-hero-active.js`. It already reads provider input, resolves the session id, posts the existing `hero_active` event, and exits silently. This session adds a bounded GET to `/notice-board/context?sessionId=`, formats safe additional context only when the provider supports that contract, and treats empty, malformed, timed out, or unreachable context responses as no context while preserving the ordinary mission-start event path. The privacy boundary is the core risk. Notice Board context is explicit coordination only. Hook output, diagnostics, spool entries, and tests must not expose raw prompts, transcripts, terminal output, command bodies, file contents, secrets, absolute local paths, logs, exports, replay buffers, scans, media drafts, diagnostics, backups, or quarantined historical content. *** ## 2. Objectives 1. Add bounded Notice Board context GET support to the hook runtime using the current server URL, auth token, timeout, and failure handling patterns. 2. Update `factionos-hero-active.js` to fetch prompt-start context without breaking the existing `hero_active` event behavior. 3. Emit bounded provider-safe additional context plus the Notice Board posting reminder only for providers with an explicit safe output contract. 4. Add focused hook tests for context present, empty, malformed, unreachable, auth header, timeout, provider-safe output, and privacy redaction. *** ## 3. Prerequisites ### Required Sessions * [x] `phase17-session01-protocol-notice-contract-parity` - provides canonical Notice Board vocabulary and blocked-content rules consumed by downstream packages. * [x] `phase17-session02-server-notice-manager-persistence-and-context` - provides bounded active-room context lookup behavior. * [x] `phase17-session03-server-routes-and-websocket-parity` - provides `GET /notice-board/context?sessionId=` and the local auth-aware server boundary. * [x] `phase17-session05-cli-notice-commands` - provides command-access parity for providers that cannot safely receive additional hook context. ### Required Tools/Knowledge * Node 26.2.0 or newer with npm workspaces. * JavaScript ESM hook handlers in `apps/hooks/src`. * Existing hook helper patterns in `apps/hooks/src/_lib.js`. * Existing process-based hook runtime tests in `apps/hooks/tests`. * Claude-style `hookSpecificOutput.additionalContext` legacy evidence and current provider-safe Codex fallback behavior. ### Environment Requirements * Work from the repository root. * Use package-relative monorepo paths from the repo root. * Keep all generated and edited files ASCII-only with Unix LF line endings. * Use fake HTTP servers in tests; do not require a live local FactionOS server. *** ## 4. Scope ### In Scope (MVP) * Agents using a safe additional-context provider can receive bounded Notice Board context on `UserPromptSubmit` - implement in `apps/hooks/src/factionos-hero-active.js`. * Agents receive the reminder `Post brief updates to the Notice Board as you work (use factionos notice or the notice-board command).` through the same safe context channel - append only through explicit provider-safe output. * Hooks fetch `/notice-board/context?sessionId=` using `FACTIONOS_SERVER_URL` with fallback `http://localhost:2468`. * Hooks include `Authorization: Bearer ` only when `FACTIONOS_AUTH_TOKEN` is configured. * Hooks use the existing bounded timeout default from `FACTIONOS_HOOK_TIMEOUT_MS` and do not block indefinitely. * Hooks treat empty context, missing session id, malformed JSON, wrong response shape, non-2xx status, unreachable server, and timeout as no context. * Hooks still post the ordinary `hero_active` event and preserve current session id, TTY, CLI, cwd, subagent, prompt, and name behavior. * Hook diagnostics remain compact and sanitized. * Hook output never includes raw prompts, transcripts, terminal output, secrets, absolute paths, file contents, command bodies, unsafe server payloads, logs, diagnostics, backups, or quarantined historical content. * Focused hook tests cover context present, empty context, malformed response, unreachable server, auth header, timeout, provider-safe output, redaction, and existing post-event behavior. ### Out of Scope (Deferred) * CLI command implementation - Reason: Session 05 completed the `factionos notice` command group. * Server route implementation - Reason: Session 03 completed canonical Notice Board routes. * Web UI rendering - Reason: Session 04 completed cockpit Notice Board rendering. * Worker relay behavior - Reason: Session 07 owns War Room Worker relay and catch-up. * Automatic mission lifecycle posts - Reason: Session 09 owns automatic status and completion posts. * Codex plugin packaging or trusted hook-state changes - Reason: direct user-level Codex hooks remain the supported release path. *** ## 5. Technical Approach ### Architecture Extend `apps/hooks/src/_lib.js` with a small bounded JSON GET helper for local server reads. It should share the same server URL, auth token, timeout, user agent, URL parsing, and compact diagnostics posture as `postEvent`, but it must not spool failures because context lookup is opportunistic. The helper should return a simple success/no-context result so hook handlers can degrade without branching on low-level HTTP errors. Add helper functions for Notice Board context shaping and provider-safe output. The shaping layer should accept only a string `context` field from the server, cap the combined output, reject blocked text patterns, and append the fixed posting reminder. The output layer should emit the current safe `hookSpecificOutput.additionalContext` shape only for providers with that contract. For Codex or unknown providers, the handler should remain silent and rely on the Session 05 CLI commands for parity. Update `factionos-hero-active.js` so the ordinary `hero_active` POST path and the context lookup run in a deterministic, bounded sequence. Context lookup must not prevent event posting, and event posting must not prevent a safe context response when the provider supports it. Tests should spawn the real hook process against fake HTTP servers and assert stdout, stderr, POST bodies, GET paths, auth headers, timeout behavior, and sanitized output. ### Design Patterns * Local helper reuse: keep URL, auth, timeout, and diagnostic behavior in `_lib.js` instead of duplicating HTTP code in the handler. * Opportunistic context fetch: context failures degrade to no context and do not create spool entries or user-visible errors. * Explicit provider gate: only write stdout for providers with a documented additional-context contract. * Privacy-first formatter: allow bounded coordination strings and block raw prompts, transcripts, command bodies, broad paths, secrets, and file-like payloads before output. * Process-level tests: verify the installed hook behavior by spawning Node scripts, matching current hook runtime coverage. ### Technology Stack * JavaScript ESM in `apps/hooks`. * Node `http` and `https` modules for bounded local server reads. * Existing hook environment loader in `apps/hooks/src/env.js`. * Existing Vitest process harness patterns under `apps/hooks/tests`. * No new runtime dependencies. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | -------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------- | | `apps/hooks/tests/heroActiveNoticeContext.test.js` | Focused fake-server tests for context lookup, output gating, auth, timeout, and privacy | \~320 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------- | | `apps/hooks/src/_lib.js` | Add bounded JSON GET helper, context formatter, provider output gate, and sanitizer support | \~180 | | `apps/hooks/src/factionos-hero-active.js` | Fetch Notice Board context and emit provider-safe reminder while preserving `hero_active` POST behavior | \~70 | | `apps/hooks/README_hooks.md` | Document hook context lookup, provider-safe output, CLI parity fallback, and privacy boundary | \~60 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `factionos-hero-active.js` calls `GET /notice-board/context?sessionId=` on prompt start when a usable session id is available. * [ ] The GET request uses `FACTIONOS_SERVER_URL` and includes bearer auth only when `FACTIONOS_AUTH_TOKEN` is configured. * [ ] A valid `{ context }` response is included in bounded provider-safe additional-context output for supported providers. * [ ] The fixed Notice Board posting reminder is included in the same provider-safe output. * [ ] Empty context produces no noisy output beyond the reminder for supported providers, and no output for providers without a safe context contract. * [ ] Malformed responses, non-2xx responses, unreachable server, timeout, and missing session id are treated as no context. * [ ] The existing `hero_active` POST behavior, session aliasing, prompt truncation, and silent failure path continue to work. ### Testing Requirements * [ ] Hook tests cover context present, no context, malformed response, unreachable server, auth header, timeout, provider-safe output, and privacy redaction. * [ ] Hook tests assert normal stdout/stderr silence for providers without a safe additional-context contract. * [ ] Hook tests assert existing POST payload behavior remains intact. * [ ] Focused hook tests run successfully. * [ ] ASCII and LF validation passes for new session files. ### Non-Functional Requirements * [ ] Hook handlers remain timeout-bound and never block indefinitely. * [ ] Hook output does not expose raw prompts, transcripts, terminal output, command bodies, file contents, secrets, absolute local paths, logs, diagnostics, backups, or quarantined historical content. * [ ] Context lookup failures do not create spool entries or noisy diagnostics. * [ ] This session does not imply hosted identity, hosted storage, public collaboration safety, production auditability, real executors, plugin trust, or trusted erasure. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * `factionos-hero-active.js` currently reads the prompt, logs compact prompt length only, posts `hero_active`, and exits with status 0. * `_lib.js` already owns `SERVER_URL`, optional auth token usage, timeout parsing, redaction helpers, and sanitized diagnostics. * Current hook design keeps stdout and stderr empty during normal operation. This session should keep that behavior for providers without an explicit additional-context output contract. * The legacy evidence used `hookSpecificOutput.additionalContext`; use it as source evidence for compatible provider output, not as a reason to weaken the current privacy boundary. * The Session 05 CLI commands are the fallback path for providers that cannot receive hook-injected context safely. ### Potential Challenges * Provider output contract mismatch: Gate stdout on provider detection and add tests proving Codex/unknown providers remain silent. * Context lookup racing the event POST: Keep both paths bounded and ensure one failure does not prevent the other expected behavior. * Unsafe server payloads: Treat non-string context or context matching blocked private patterns as no context. * Test flakiness around timeouts: Use local fake servers and short controlled timeout env values. ### Relevant Considerations * \[P03-apps/cli+apps/hooks] **Narrow diagnostics beat raw dumps**: Hook diagnostics and tests should use statuses, counts, durations, bytes, and sanitized identifiers instead of raw context. * \[P10-apps/cli+apps/hooks] **Do not mutate user-owned Codex config**: This session changes hook runtime behavior only; it does not change install, uninstall, trusted state, or plugin packaging. * \[P11] **Do not blur fixture replay with live trust review**: Tests prove hook output shaping, not provider trust state or `/hooks` review completion. * \[P07] **Redaction is boundary-specific**: The hook output boundary needs its own blocking and minimization checks. * \[P03] **Vitest projects**: Use focused hook tests first, then broader root tests during phase gates. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Hook context lookup could delay or block prompt start if the server stalls. * Provider-safe output could leak raw prompts, paths, commands, or unsafe server payloads if formatting is too permissive. * Adding stdout output for unsupported providers could break existing hook expectations or surface context in terminals. *** ## 9. Testing Strategy ### Unit Tests * Test helper-level response parsing, context bounding, reminder insertion, blocked-pattern rejection, provider output gating, and auth header behavior through process-level fake-server fixtures. ### Integration Tests * Spawn `apps/hooks/src/factionos-hero-active.js` with controlled environment variables and fake HTTP servers to verify GET and POST behavior together. * Verify unreachable and timeout cases still exit 0 and do not print unsafe output. ### Manual Testing * Run a focused Vitest command for the new hook context test file. * Optionally pipe a sanitized `UserPromptSubmit` fixture into `factionos-hero-active.js` with a fake or local server to inspect provider output behavior. ### Edge Cases * Missing session id. * Context route returns `{ context: "" }`. * Context route returns malformed JSON. * Context route returns non-string or oversized `context`. * Context contains token-like strings, absolute paths, transcript labels, command bodies, or file-content-like text. * Context server times out while `/event` POST succeeds. * `/event` POST fails while context GET succeeds for a supported provider. *** ## 10. Dependencies ### External Libraries * None. Use existing Node `http` and `https` modules plus current project dependencies. ### Other Sessions * **Depends on**: `phase17-session03-server-routes-and-websocket-parity`, `phase17-session05-cli-notice-commands` * **Depended by**: `phase17-session10-validation-documentation-and-handoff` *** ## 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/phase17-session06-hook-context-and-provider-skill-parity/spec.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.