> 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/phase12-session01-codex-plugin-packaging/codex-plugin-packaging-decision.md). # Codex Plugin Packaging Decision **Session ID**: `phase12-session01-codex-plugin-packaging` **Date**: 2026-05-31 **Package**: Cross-cutting **Status**: Final **Decision**: Defer Codex plugin packaging for the first Codex release. *** ## Summary FactionOS should not ship a Codex plugin package in this release. Direct user-level Codex hooks installed by `factionos init --cli codex` remain the supported baseline. The gate fails because plugin packaging does not currently add a concrete maintenance, distribution, or trust-review benefit over the already validated direct hook path. Current Codex plugin docs confirm that plugin-bundled hooks are still non-managed hooks and still require user review and trust through the same `/hooks` flow. Packaging would add marketplace, cache, install-state, and bundled-file maintenance work without reducing the release's trust-review or privacy burden. No `.codex-plugin/` manifest, repo marketplace, plugin cache workflow, or plugin-bundled hook runtime is created by this session. *** ## Source References | Source | Use | | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `.spec_system/PRD/phase_12/PRD_phase_12.md` | Phase 12 criteria and non-goals. | | `.spec_system/PRD/phase_12/session_01_codex_plugin_packaging.md` | Session-specific ship-or-defer scope. | | `.spec_system/PRD/phase_12/session_02_release_closeout_and_rollout_readiness.md` | Downstream release closeout dependency. | | `.spec_system/specs/phase11-session03-end-to-end-validation-and-integration-fixes/codex-e2e-validation-record.md` | Direct user-level Codex install, status, doctor, uninstall, ingest, browser, privacy, and quality evidence. | | `apps/cli/README_cli.md` | Current direct installer, status, doctor, uninstall, and no-overclaim contract. | | `apps/hooks/README_hooks.md` | Current hook map, handler reuse, trust review, and redaction boundaries. | | `docs/api/event-api-hook-contracts.md` | Current Codex event contract and unsupported claim boundaries. | | `docs/development.md` | Contributor workflow for direct Codex hook checks. | | `https://developers.openai.com/codex/hooks` | Current Codex hook locations, trust review, plugin-bundled hook behavior, and supported events. | | `https://developers.openai.com/codex/plugins/build` | Current plugin structure, manifest, marketplace, cache, local install, bundled hooks, and publish status. | | `https://developers.openai.com/codex/cli/reference#codex-plugin-marketplace` | Current Codex marketplace CLI behavior. | *** ## Criteria Matrix | Criterion | Result | Evidence | Release implication | | ------------------------------------------------------------------------------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | | Direct user-level Codex hooks install, run, diagnose, and uninstall correctly. | Pass | Phase 11 recorded isolated install, idempotent reinstall, status, doctor, uninstall, runtime health, fixture replay, browser replay, focused tests, typecheck, format, lint, diff, ASCII/LF, and sensitive-string review as passing. | Keep direct hooks as the supported path. | | Plugin packaging gives a concrete maintenance, distribution, or trust-review benefit over direct hook installation. | Fail | OpenAI plugin and hook docs say plugin-bundled hooks still require `/hooks` review and trust. No repo marketplace, workspace sharing, or public plugin directory requirement is part of this first release. | Do not add plugin packaging as release scope. | | The plugin can reuse the same hook maps, handlers, docs, and privacy rules rather than creating a second runtime path. | Partial | `apps/hooks/hooks.codex.json` and handlers are reusable in concept, but a plugin package would need bundled files, install-cache validation, dependency packaging, and lifecycle docs distinct from the current CLI installer. | Reuse is plausible later but not enough to proceed now. | | Plugin install, hook trust, cache refresh, and uninstall can be validated without storing secrets or raw local payloads. | Partial | Isolated homes can validate mechanics, but live trust review still requires human interaction and must not use trust-bypass flags. Local plugins load from Codex cache after marketplace install, adding cache refresh evidence that direct hooks do not need. | Validation cost exists without release benefit. | Gate rule: proceed only if every criterion passes. The gate does not pass. *** ## Decision Gate Proceed branch requirements: 1. Direct hooks are already validated end to end. 2. Plugin packaging adds a concrete maintenance, distribution, or trust-review benefit that direct hooks do not provide. 3. The package reuses the same hook maps, handlers, docs, and privacy rules. 4. Isolated validation can cover plugin install, cache refresh, hook trust review, and uninstall without raw payload or secret evidence. Failure handling: * If any requirement fails, do not create `.codex-plugin/` files. * Do not create a repo marketplace entry. * Do not represent plugin install, cache refresh, trust, or uninstall as passed. * Update stable docs to state that direct user-level hooks remain supported and plugin packaging is explicitly deferred. Selected branch: defer, because requirement 2 fails and requirements 3 and 4 are only partial. *** ## Direct Hook Baseline Map | Area | Current direct-hook behavior | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Install | `factionos init --cli codex` writes user-level Codex hooks to `CODEX_HOME` when set, otherwise the Codex user config directory. | | Hook map | `apps/hooks/hooks.codex.json` is the source template. The CLI interpolates the installed hooks package root and managed environment values. | | User-owned hooks | Existing user-owned hooks, matchers, events, and unknown top-level fields are preserved. | | Backup | The first raw Codex `hooks.json` is backed up to `hooks.backup.factionos.json` when present. | | Diagnostics | `factionos status --cli codex` and `factionos doctor --cli codex` report compact posture, counts, backup state, feature state, and `/hooks` review guidance. | | Uninstall | `factionos uninstall --cli codex` restores the first-run backup when available or removes only FactionOS-managed Codex command hooks. | | Trust | Users open a new Codex CLI session and review loaded hooks with `/hooks`. FactionOS does not mark trust decisions. | *** ## Direct Hook Evidence Evaluation | Capability | Result | Evidence note | | -------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Install | Pass | Phase 11 isolated `factionos init --cli codex --faction orc` added managed Codex hooks and preserved one unmanaged hook plus unknown top-level state. | | Run and ingest | Pass | Phase 11 fixture replay accepted lifecycle, Bash, `apply_patch`, MCP, permission, subagent, degraded, unknown, and stop events through local ingest and browser display. | | Status | Pass | `factionos status --cli codex` reported compact hook posture, counts, backup state, feature state, and `/hooks` guidance without raw payload labels. | | Doctor | Pass | `factionos doctor --cli codex` reported actionable Codex posture without raw payload labels or broad local path output. | | Uninstall | Pass | `factionos uninstall --cli codex` restored the first-run backup when present, removed managed hooks, preserved unmanaged hooks, and did not claim trusted erasure. | | Trust review | Unavailable for automation | Live `/hooks` trust review requires human interaction. Phase 11 recorded this as an explicit exception and did not use trust-bypass flags. | Conclusion: direct user-level hooks are sufficient for first-class local Codex support, with trust review documented as an explicit manual step. *** ## Plugin Packaging Review Current Codex plugin packaging can bundle lifecycle hooks through `hooks/hooks.json` or a manifest `hooks` entry. Those hooks load when the plugin is enabled, alongside user, project, and managed hooks. Installing or enabling a plugin does not automatically trust its hooks; Codex skips plugin-bundled hooks until the user reviews and trusts the current hook definition. Current marketplace mechanics add a catalog layer and cache layer. Codex reads repo or personal marketplace files, installs plugins into a Codex plugin cache, and loads the installed copy from that cache path. For local plugins, changed files require updating the marketplace source copy and restarting Codex so the local install can pick up the new files. That packaging model is useful when FactionOS needs team distribution, workspace sharing, bundled skills, MCP servers, app integrations, or stable plugin publish metadata. This release does not need those surfaces to support first-class local Codex hooks. ## Plugin Value Evaluation | Value area | Assessment | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Maintenance | No current win. The direct installer already reuses `hooks.codex.json`, backs up user hooks, merges managed entries, and supports uninstall. A plugin package would add cache and marketplace maintenance. | | Distribution | No current release need. This repo has no stated team marketplace, workspace sharing, or public plugin directory requirement for Session 02 closeout. | | Trust review | No win. Plugin-bundled hooks remain non-managed and require the same `/hooks` review. | | Runtime reuse | Plausible later, but not free. The hook map and handlers can be reused, but packaging must still prove bundled files, dependencies, `PLUGIN_ROOT`, cache refresh, and uninstall behavior. | | Privacy | No improvement. The same redaction rules remain required; plugin packaging adds another install/cache surface to review. | *** ## Reusable Hook Asset Map | Asset | Current role | Plugin reuse note | | ---------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `apps/hooks/hooks.codex.json` | Provider-specific Codex source template used by the CLI installer. | Could be adapted as plugin `hooks/hooks.json` later because it already uses `PLUGIN_ROOT` placeholders before direct install interpolation. | | `apps/hooks/src/factionos-*.js` | Shared local hook handlers for Claude and Codex event families. | A plugin would need to bundle or depend on these files without forking behavior. | | `apps/hooks/src/_lib.js` and `apps/hooks/src/env.js` | Shared timeout, POST, redaction, spool, logging, and environment helpers. | Must remain the single privacy and failure-path implementation if packaging is reopened. | | `apps/cli/src/installers/codex.js` | Direct install, merge, backup, status, doctor, and uninstall behavior. | Should remain the baseline path; plugin packaging should not replace it without new release evidence. | | `apps/hooks/README_hooks.md` | Hook runtime, trust, map, and redaction contract. | Plugin docs must reuse this wording and avoid a second privacy contract. | | `docs/api/event-api-hook-contracts.md` | API and Codex hook event contract. | Plugin packaging cannot change the event contract without focused tests and docs. | Reusable privacy rules: * Keep handlers timeout-bounded and quiet. * Do not emit approval decisions for Codex. * Redact prompt bodies, command output, raw patch bodies, MCP argument bodies, transcript paths, agent transcript paths, token-like values, broad local paths, and raw spool payloads. * Keep diagnostics and tracked evidence to labels, counts, booleans, compact IDs, and safe source refs. *** ## No-Overclaim Fields This decision does not claim any of the following: * Plugin packaging is shipped. * A `.codex-plugin/plugin.json` manifest exists in this repo. * A repo or personal marketplace entry exists for FactionOS. * Plugin install, plugin cache refresh, plugin enablement, or plugin uninstall has passed. * Plugin-bundled hooks bypass `/hooks` trust review. * Project-local `.codex/` trusted state is created. * Codex auth, provider, model, profile, telemetry, account, API key, or trusted project settings are mutated. * Hosted auth, hosted storage, analytics capture, push, tunnel, public replay hosting, or remote execution is added. * Uninstall is broad trusted erasure. *** ## Final Decision Defer Codex plugin packaging. The supported release path is: 1. Link or install the FactionOS CLI. 2. Run `factionos init --cli codex` or `factionos init --cli all`. 3. Start a new Codex CLI session. 4. Review loaded hooks with `/hooks`. 5. Use `factionos status --cli codex`, `factionos doctor --cli codex`, and `factionos uninstall --cli codex` for posture and cleanup. Session 02 can safely say plugin packaging is explicitly deferred because direct user-level hooks are simpler, safer, validated, and sufficient for this first Codex release. *** ## Selected Branch Artifact Branch artifact: explicit no-manifest deferral. Validated repository state: * `.codex-plugin/` is absent. * `.agents/plugins/marketplace.json` is absent. * `plugins/` is absent. This absence is intentional for the selected branch. The validation plan records plugin install, cache refresh, plugin trust review, and plugin uninstall as not applicable rather than passed. *** ## Release Implications And Known Limitations Session 02 release closeout can claim: * First-class local Codex CLI support through user-level hooks. * Direct installer, status, doctor, and uninstall support for selected Codex hook state. * Explicit `/hooks` trust-review guidance. * Plugin packaging intentionally deferred. Session 02 must not claim: * Codex plugin availability. * Plugin install, plugin cache refresh, plugin enablement, plugin trust review, or plugin uninstall validation. * Automatic hook trust, trust bypass, or project-local trusted `.codex/` setup. * Hosted identity, hosted storage, analytics capture, remote execution, production-hosted validation, or broad trusted erasure. Known limitations to carry forward: * Live `/hooks` trust review remains manual and interactive. * Codex plugin packaging may be useful later for team distribution, workspace sharing, bundled skills, MCP config, app integrations, or official plugin publishing. * Direct hooks are user-level and local-first; project-local `.codex/` setup is not created by this release. *** ## Future Reconsideration Gate Reconsider a FactionOS Codex plugin only when at least one concrete distribution need exists: * A repo or team marketplace is required for multiple developers. * FactionOS ships bundled Codex skills, MCP server config, apps, or connector metadata that benefits from one install surface. * Workspace sharing is a release goal. * Plugin cache/install/update/uninstall can be validated with isolated homes and without raw payload evidence. * Plugin docs can describe trust review honestly without implying bypass. Even then, direct user-level hooks should remain available unless a later release record proves a safer replacement path. --- # 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/phase12-session01-codex-plugin-packaging/codex-plugin-packaging-decision.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.