Plugin lifecycle hooks for workspace preparation and quality providers

[shiny-code-bot]

Intent

Make Codex Lab plugin hooks sufficient for optional domain integrations like Odoo devkit workspace preparation plus JetBrains/PyCharm quality inspection, without baking Odoo or JetBrains logic into the coding harness.

Current Status

State: Waiting; repository-specific workspace and quality-provider consumers are proven, while the broader generic lifecycle remains unfinished.

The Odoo contract/consumer proof remains complete. #561/PR #562 established deterministic Codex Lab JetBrains routing, #566 closed after semantic Rust inspection coverage, and #310 completed the changed-file validation-provider runtime. These prove useful consumers without requiring provider-specific authority in generic core.

Next action when promoted: split the smallest generic detect/prepare and typed artifact-handoff slice, then treat normalized quality execution and cleanup/lease lifecycle as independent follow-ups.

Blocked by: no design or implementation dependency.

Waiting for: post-release provider sequencing.

Last verified: August 10, 2026.

Required Hooks And Contracts

• Workspace lifecycle hooks: after worktree/materialization/session start, plus workspace detect/prepare phases.
• Quality lifecycle hooks: quality prepare/run/closeout with normalized clean/findings/inconclusive/skipped results.
• Structured artifact handoff: per-session plugin artifact directory and typed descriptor outputs usable by later hooks/plugins.
• Cleanup lifecycle: best-effort cleanup hook after stop/failure/timeout for provider leases and temporary resources.
• Hook inputs should expose cwd, repo root, worktree root, main worktree when known, branch/head, and project markers.
• Capability discovery for providers such as workspace.prepare.odoo-devkit and quality.ideInspection.jetbrains.
• Exec-harness coverage for descriptor handoff, blocking results, and cleanup behavior.

Acceptance Criteria

• An Odoo plugin can detect workspace.toml, run odoo-devkit workspace sync for the active worktree, and emit a descriptor without Codex Lab core understanding Odoo.
• A JetBrains inspection plugin can consume that descriptor during quality closeout and block/report findings without Codex Lab core understanding JetBrains or PyCharm.
• Plugins can pass artifacts across lifecycle phases using a documented contract rather than ad hoc files.
• Cleanup hooks run sufficiently for provider leases/temp resources.
• Existing prompt/tool/stop hooks continue to work.

Out Of Scope

• Implementing Odoo-specific workspace generation in Codex Lab core.
• Implementing JetBrains inspection execution in Codex Lab core.
• Making Launchplane depend on local IDE state.

[cbusillo]

Direction checkpoint from the JetBrains/Odoo inspection planning thread:

Do not push more Odoo/JetBrains orchestration into jetbrains-inspection-api or the helper first. The WebStorm false-green/red-lane foundation is now complete upstream, and the remaining Odoo-aware inspection work should wait for Codex Lab to stabilize enough to host the generic lifecycle surface.

When this issue becomes actionable, the needed Codex Lab surface is likely broader than hooks alone:

• hooks for workspace detect/prepare, quality prepare/run/closeout, and cleanup;
• commands/CLI entrypoints so agents and tests can invoke those phases deterministically outside a full chat session;
• endpoints or local control surfaces, if Codex Lab runtime needs external tools/plugins to report provider state, descriptors, readiness, or cleanup results;
• typed artifact/descriptor handoff between phases so odoo-devkit can prepare a per-worktree IDE workspace and jetbrains-inspection can consume it without Codex Lab core understanding either Odoo or JetBrains;
• exec-harness scenarios proving descriptor handoff, blocking quality results, skipped/inconclusive states, and cleanup behavior.

This keeps the dependency direction clean:

1. Codex Lab provides generic lifecycle/artifact/quality-provider orchestration.
2. odoo-devkit emits the Odoo workspace descriptor for the active worktree.
3. jetbrains-inspection consumes the descriptor and runs PyCharm/Odoo-aware inspections.
4. jetbrains-inspection-api stays generic unless a truly generic IDE capability endpoint is required.

[cbusillo]

Planning update from #232 on July 1, 2026:

The feature ownership matrix now classifies plugins/skills/hooks as the convergence path for optional domain behavior. Core should keep generic plugin/skill/hook substrate and trust policy; domain behavior such as workspace prep, IDE inspection, Code Bridge setup, and agent role packs should move into plugins/skills/hooks where possible.

Next #149 work should focus on generic plugin-packaged skills/hooks and lifecycle artifact handoff, not Odoo/JetBrains-specific logic in core. See #232 Current Status for the durable matrix rows.