schema_version: runtime-report-v1
chunk: "000264"
title: Lightweight Codex Hook Work Registration Integration
generated_at: "2026-05-18T22:16:00.000Z"
status: implemented
summary:
  - Added a Runtime-owned Codex hook adapter that routes hook events into the existing work-session/work-step model.
  - Added tool classification for read-only, filesystem, shell, test, validation, service, authority-sensitive, and unknown Codex actions.
  - Added role classification with evidence-backed Runtime Executor, Runtime Supervisor, Dispatcher, Developer, QA, and Codex fallback behavior.
  - Added a Node hook facade at ai/commands/codex-hook.mjs for hook runners to invoke without shell-owned logic.
  - Added a Codex hook capability smoke and runtime tests.
reused_runtime_apis:
  - runtimeWorkSessionSnapshot
  - startRuntimeWorkSession
  - heartbeatRuntimeWorkSession
  - completeRuntimeWorkSession
  - failRuntimeWorkSession
  - startRuntimeWorkStep
  - heartbeatRuntimeWorkStep
  - completeRuntimeWorkStep
  - failRuntimeWorkStep
  - validateRequiredWorkRegistration
  - runtimeWorkHistory
extended_runtime_apis:
  - runCodexHookWorkRegistration
  - inspectCodexHooksCapability
  - runCodexHooksCapabilitySmoke
verified_hook_events:
  local_codex_version: codex-cli 0.130.0
  hooks_feature_enabled: true
  event_names_visible_in_local_docs: false
  project_hook_config_verified: false
  adapter_events_supported:
    - UserPromptSubmit
    - PreToolUse
    - PostToolUse
    - Stop
hook_enablement:
  enabled_by_default: false
  reason: Local Codex exposes the stable hooks feature, but installed help/package text does not document project-local hook event wiring or event names.
  trusted_setup_entrypoint: ai/commands/codex-hook.mjs
no_second_work_model:
  status: enforced
  evidence: The adapter writes through existing Runtime work-session/work-step APIs and creates no hook-specific .tmp state store.
role_classification:
  policy:
    validation_execute: Runtime Executor
    test_execute: Runtime Executor
    service_action: Runtime Supervisor
    authority_sensitive_dispatcher_or_commit: Dispatcher
    filesystem_write_with_active_developer_chunk: Developer
    qa_review_command: QA
    fallback: Codex
  unknown_role_behavior: Use actor_role Codex with role_confidence unknown; do not infer lifecycle role.
qa_false_active_prevention:
  status: enforced
  rule: QA is marked active only for explicit QA role input or qa review command evidence.
  smoke_evidence: qa review command classified as activity qa_reviewing and step_type qa_review.
close_gate_enforcement:
  remains_primary: true
  note: Hook checks are passive fast triggers. Existing wrapper registration, lifecycle validation, and close-gate validation remain the hard enforcement path.
unsupported_or_unverified:
  - Project-local Codex hook config syntax/event wiring was not verified from installed CLI help/package text.
  - Log parsing was not implemented. It remains a last-resort fallback only if official hook invocation cannot be wired reliably.
validation:
  codex_hook_capability_smoke: passed
  typecheck: passed
  build: passed
  runtime_tests: passed
  summary_validate: passed
  typed_qa_review: passed
  state_journal_validate: passed
  daemon_freshness: fresh
  full_validation: passed
  full_validation_note: "ok: true; scorecard degraded by known historical close_commit/reconciliation context, not this chunk."
