Add OpenCode and Codex CLI agent support

[Avyukth]

Closes #245
Closes #266
Relates to #281

Summary

Adds two new AI coding agent integrations to the Entire CLI: OpenCode and Codex CLI. Both agents support full session checkpointing via hooks — capturing transcripts, file changes, prompts, and metadata on shadow branches.

As part of this work, duplicated framework code was extracted into a shared commit pipeline ("$(hooks_common_session.go)"), directly addressing issue #281's goal of separating framework from agent-specific logic. The three agent handlers (Codex, OpenCode, Gemini) that previously duplicated ~250 lines of commit logic are now thin wrappers calling a shared "$(commitAgentSession())" function.

~3,000 lines across 16 files (all new code from main's perspective).

---

Framework Extraction (addresses #281)

The shared "$(hooks_common_session.go)" consolidates duplicated logic from Codex, OpenCode, and Gemini handlers:

Extracted Function	Replaces	Purpose
"$(commitAgentSession())"	"$(commitCodexSession)", "$(commitOpenCodeSession)", "$(commitGeminiSession)"	Core commit pipeline: load state → detect changes → save via strategy
"$(createContextFile())"	"$(createContextFileForCodex)", "$(createContextFileForOpenCode)", "$(createContextFileForGemini)"	Unified context.md generation (single + multi-prompt)
"$(transitionSessionTurnEnd())"	Was in Claude Code handlers, used by all agents	Session phase state machine transition
"$(logFileChanges())"	Was in Gemini handlers, used by all agents	Stderr logging of modified/new/deleted files

Each agent handler is now a thin wrapper that populates an "$(agentCommitContext)" struct:

• Codex: provides transcript-extracted modified files, single prompt
• OpenCode: sets "$(useGitStatusForModified: true)" (no transcript parsing), single prompt
• Gemini: adds token usage calculation, multi-prompt array, transcript step tracking

This reduces the barrier for adding new agents — a new handler only needs to populate the context struct and call "$(commitAgentSession())".

Not yet extracted (future #281 work): Claude Code's "$(commitWithMetadata)" has unique subagent/summarization/incremental-checkpoint logic that requires its own pattern. The "$(Agent)" interface itself is also unchanged — broader interface refactoring is deferred to the core team per #281.

---

OpenCode Agent

• TypeScript plugin system: generates "$(.opencode/plugins/entire.ts)" that subscribes to "$(session.created)" and "$(session.status)" (busy/idle) events via BunShell
• 3 hooks: "$(session-created)" (SessionStart), "$(session-busy)" (per-turn state capture), "$(session-idle)" (Stop/checkpoint)
• Per-turn pre-prompt state capture via "$(session-busy)" hook — captures untracked files before agent starts each turn for accurate new-file detection
• File change detection via git status with pre-prompt untracked baseline (OpenCode sessions are opaque JSON — no transcript-based file extraction possible)
• Session storage: reads from XDG data directory ("$(~/.local/share/opencode/storage/session/)")
• Recursive session file discovery via "$(filepath.WalkDir)" (OpenCode nests sessions under "$(/)" subdirectories)

Codex CLI Agent

• TOML-based notify hook: installs "$(notify = ["entire", "hooks", "codex", "agent-turn-complete"])" in "$(.codex/config.toml)"
• Parses Codex JSONL rollout transcripts for file change extraction ("$(file_change)", "$(function_call)", "$(event_msg/patch_apply_begin)" items)
• Codex sends notify payload via argv (not stdin) — handler reads from last positional argument via "$(GetCurrentHookArgs())"
• Post-turn state capture — captures untracked files after each turn completes as baseline for next turn's file detection (Codex has no before-turn hook in codex-rs)
• Recursive session file discovery via "$(filepath.WalkDir)" (Codex uses date-based "$(YYYY/MM/DD/)" directory structure)
• Session storage: reads from "$(~/.codex/sessions/)" (respects "$(CODEX_HOME)" env var)
• Local dev mode resolves project path at write-time via "$(paths.RepoRoot())" (Codex executes notify as direct argv without shell expansion)

Shared Infrastructure

• "$(hooks_common_session.go)" — shared commit pipeline with "$(agentCommitContext)" struct
• Hook registry entries for both agents in "$(hook_registry.go)"
• "$(currentHookArgs)" + "$(GetCurrentHookArgs())" for agents that pass payloads via positional args
• "$(fileExistsAndIsRegular())" helper to distinguish files from directories

---

Key Implementation Details

Codex argv payload handling:
Codex's Rust source ("$(user_notification.rs)") calls "$(command.arg(notify_payload))" with "$(stdin(Stdio::null()))". The hook registry captures positional args via "$(cobra.ArbitraryArgs)" and stores them in "$(currentHookArgs)". The handler reads from "$(args[len(args)-1])" when available, falling back to stdin.

OpenCode session-busy hook:
OpenCode fires "$(session.status)" with "$(type: "busy")" when the agent starts processing each turn. The TypeScript plugin pipes this to "$(entire hooks opencode session-busy)", which calls "$(CapturePrePromptState(sessionID, ""))" to snapshot untracked files before the agent modifies anything. The subsequent "$(session-idle)" handler uses "$(commitAgentSession())" with "$(useGitStatusForModified: true)".

Codex post-turn state capture (workaround):
Codex only exposes "$(AfterAgent)" and "$(AfterToolUse)" hooks — no "before turn" event exists. As a workaround, "$(handleCodexAgentTurnComplete)" captures state after each turn completes ("$(CapturePrePromptState)" at the end), which serves as the baseline for the next turn's "$(DetectFileChanges)".

File existence checks:
"$(fileExistsAndIsRegular())" replaces "$(fileExists())" for transcript path validation. Codex's "$(ParseHookInput)" sets "$(SessionRef)" to "$(~/.codex/sessions)" (a directory). Without the regular-file check, "$(copyFile(dir, ...))" would fail with "is a directory".

Codex JSONL file extraction:
Supports three event formats from Codex rollout transcripts:

• "$(response_item)" with "$(file_change)" items (direct file path)
• "$(response_item)" with "$(function_call)" items (write_file, apply_diff, edit_file, create_file)
• "$(event_msg)" with "$(patch_apply_begin)" payload (HashMap keys are file paths — actual production format from "$(exec_events.rs)")

Uses "$(bufio.NewReader)" + "$(ReadBytes('\n'))" instead of "$(bufio.Scanner)" to handle JSONL lines exceeding 64KB.

TOML hook installation (Codex):
"$(InstallHooks)" parses "$(.codex/config.toml)" line-by-line, preserving user content and comments. When a user-configured "$(notify)" line exists and "$(--force)" isn't set, installation is skipped to avoid duplicate TOML keys.

---

Feature Comparison: Claude Code vs OpenCode vs Codex

Hook Coverage

Hook Event	Claude Code	OpenCode	Codex
Session Start	"$(session-start)"	"$(session-created)"	—
Session End	"$(session-end)"	—	—
Per-Turn State Capture	"$(user-prompt-submit)"	"$(session-busy)"	post-turn (workaround)
Turn Complete / Checkpoint	"$(stop)"	"$(session-idle)"	"$(agent-turn-complete)"
Pre-Task (subagent)	"$(pre-task)"	—	—
Post-Task (subagent)	"$(post-task)"	—	—
Post-Todo (incremental)	"$(post-todo)"	—	—
Total	7	3	1

File Change Detection

Method	Claude Code	Codex	OpenCode
Transcript-based (modified)	Write/Edit/NotebookEdit tool calls	file_change, function_call, patch_apply_begin	None (opaque JSON)
Git-status-based (new/deleted)	With pre-prompt baseline	With pre-prompt baseline	With pre-prompt baseline
Git-status-based (modified)	No	No	Yes (primary method)

Agent Interfaces Implemented

Interface	Claude Code	Codex	OpenCode
"$(Agent)"	Yes	Yes	Yes
"$(HookSupport)"	Yes	Yes	Yes
"$(HookHandler)"	Yes	Yes	Yes
"$(TranscriptAnalyzer)"	Yes	No	No
"$(TranscriptChunker)"	Yes	Yes	No

Remaining Gaps (Agent Limitations)

Gap	Reason
Codex: no true before-turn hook	Only "$(AfterAgent)" and "$(AfterToolUse)" exist in codex-rs
OpenCode: no transcript parsing	Sessions stored as opaque JSON, no tool-call data accessible
Codex/OpenCode: no token tracking	Neither agent exposes token usage in payloads or transcripts
Codex/OpenCode: no subagent support	Neither has a subagent/task architecture
OpenCode: no session-end hook	No event fires when session is explicitly closed

---

Test Plan

• "$(mise run fmt)" — no formatting issues
• "$(mise run lint)" — 0 new issues
• "$(mise run test)" — all unit tests pass
• "$(mise run test:ci)" — full CI suite with race detection passes
• "$(mise run test:integration)" — integration tests pass
• Manual: "$(entire enable --agent opencode)" installs "$(.opencode/plugins/entire.ts)"
• Manual: "$(entire enable --agent codex)" installs notify hook in "$(.codex/config.toml)"
• Manual: idempotent re-enable ("$(entire enable --agent opencode)" twice)
• Manual: "$(entire hooks codex agent-turn-complete '{...}')" reads from argv
• Manual: "$(entire hooks opencode session-idle)" reads from stdin pipe
• OpenCode tests verify 3 hooks, session-busy parsing, plugin content includes busy handler
• Codex tests verify argv payload reading, JSONL event extraction, TOML hook installation

🤖 Generated with Claude Code