feat: generalize session markers to support Codex, Amp, etc

[rsnodgrass]

Summary

Adds SupportsSession() and SessionID() methods to the Agent interface, enabling agent-agnostic session identification across all 15 coding agents and 2 orchestrators. Generalizes session marker naming and documentation from Claude-specific to agent-agnostic terminology. Wires the env-var fallback into the prime flow so Codex, Amp, and Claude Code sessions create markers even outside hook context.

Changes

• agentx interface: Add AgentSession interface with SupportsSession() and SessionID() methods, embedded in Agent
• Agent implementations: Implement on all agents — session-supporting agents return env var sources (Claude Code, Codex, Amp) or empty string for hook-only agents; non-session agents return false/empty
• Prime flow wiring: Fallback to agent.SessionID(env) when hook stdin doesn't provide a session ID — enables Codex (CODEX_THREAD_ID), Amp (AMP_THREAD_URL), and Claude Code (CLAUDE_CODE_SESSION_ID) to create session markers natively
• Session markers: Rename ClaudeSessionID → AgentSessionID, ReadClaudeHookInput() → ReadAgentHookInput(), etc.
• Documentation: Add comprehensive doc comments on marker lifecycle, purpose, and cleanup strategy (markers in /tmp are ephemeral, OS cleans on reboot)
• Tests: Sweep test for all 15 agents' session support, unit tests for env-var agents, integration test for fallback path

flowchart TD
    A[ox agent prime] --> B{Hook stdin<br/>has session_id?}
    B -- Yes --> D[Use hook session ID]
    B -- No --> C{agent.SupportsSession()?}
    C -- Yes --> E[agent.SessionID env]
    C -- No --> F[No session tracking]
    E --> G{SessionID non-empty?}
    G -- Yes --> D
    G -- No --> F
    D --> H[Write/check session marker]

Loading

Verification

• All short tests pass (go test -short ./cmd/ox/ ./pkg/agentx/...)
• Integration test passes (TestSessionIDFallbackFromEnvVar)
• Build succeeds with no new lint issues

Session Recording

View session recording

Co-Authored-By: SageOx ox@sageox.ai

Summary by CodeRabbit

Release Notes

• New Features

  • Extended session support and idempotency tracking across multiple coding agents, with environment variable configuration options for agent session retrieval.

• Improvements

  • Generalized session management architecture for improved cross-agent compatibility and fallback session ID handling.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a09e3a2 and 9eb1a2f.

📒 Files selected for processing (28)

• cmd/ox/agent_prime.go
• cmd/ox/prime_idempotent_integration_test.go
• cmd/ox/prime_idempotent_test.go
• cmd/ox/prime_session_marker.go
• cmd/ox/prime_session_marker_test.go
• pkg/agentx/agent.go
• pkg/agentx/agent_test.go
• pkg/agentx/agents/aider.go
• pkg/agentx/agents/amp.go
• pkg/agentx/agents/amp_test.go
• pkg/agentx/agents/claudecode.go
• pkg/agentx/agents/claudecode_test.go
• pkg/agentx/agents/cline.go
• pkg/agentx/agents/codepuppy.go
• pkg/agentx/agents/codex.go
• pkg/agentx/agents/codex_test.go
• pkg/agentx/agents/cody.go
• pkg/agentx/agents/continue.go
• pkg/agentx/agents/copilot.go
• pkg/agentx/agents/cursor.go
• pkg/agentx/agents/droid.go
• pkg/agentx/agents/goose.go
• pkg/agentx/agents/kiro.go
• pkg/agentx/agents/opencode.go
• pkg/agentx/agents/session_test.go
• pkg/agentx/agents/windsurf.go
• pkg/agentx/orchestrators/conductor.go
• pkg/agentx/orchestrators/openclaw.go

---

📝 Walkthrough

Walkthrough

The PR generalizes Claude-specific session handling to agent-agnostic context across the codebase. It introduces a new AgentSession interface, renames session-related functions and types (ClaudeSessionID → AgentSessionID, ReadClaudeHookInput → ReadAgentHookInput, etc.), implements the new interface across all agent types, and updates tests accordingly.

Changes

Cohort / File(s)	Summary
Core Session Marker Logic cmd/ox/prime_session_marker.go, cmd/ox/prime_session_marker_test.go	Generalizes session handling from Claude-specific to agent-agnostic terminology. Replaces ClaudeSessionID with AgentSessionID, renames ReadClaudeHookInput → ReadAgentHookInput, WriteToClaudeEnvFile → WriteToAgentEnvFile, and IsClaudeHookContext → IsAgentHookContext. Updates marker path/status logic and public API signatures.
Agent Prime Idempotent Logic cmd/ox/agent_prime.go, cmd/ox/prime_idempotent_test.go, cmd/ox/prime_idempotent_integration_test.go	Aligns session handling from Claude-specific to agent-centric context. Adds fallback to derive agent_session_id from environment if not provided by hook input. Updates marker reading/writing to use AgentSessionID. Changes environment write path from WriteToClaudeEnvFile to WriteToAgentEnvFile. Adds new test suite TestSessionIDFallbackFromEnvVar to verify env var fallback behavior.
Agent Interface Extension pkg/agentx/agent.go, pkg/agentx/agent_test.go	Introduces new AgentSession interface with SupportsSession() bool and SessionID(env Environment) string methods. Updates Agent interface to embed AgentSession, extending agent capabilities.
Agent Implementations - Session Support pkg/agentx/agents/amp.go, pkg/agentx/agents/amp_test.go, pkg/agentx/agents/claudecode.go, pkg/agentx/agents/claudecode_test.go, pkg/agentx/agents/codex.go, pkg/agentx/agents/codex_test.go	Adds session support methods to agents that manage sessions via environment variables. AMP returns AMP_THREAD_URL, ClaudeCode returns CLAUDE_CODE_SESSION_ID, Codex returns CODEX_THREAD_ID. Includes test coverage for session ID retrieval and fallback behavior.
Agent Implementations - Hook-Based Sessions pkg/agentx/agents/copilot.go, pkg/agentx/agents/cursor.go, pkg/agentx/agents/cline.go, pkg/agentx/agents/droid.go, pkg/agentx/agents/kiro.go, pkg/agentx/agents/opencode.go, pkg/agentx/agents/windsurf.go	Adds session support methods returning true for SupportsSession() and empty string for SessionID(), indicating these agents provide session IDs via hook stdin JSON rather than environment variables.
Agent Implementations - No Session Support pkg/agentx/agents/aider.go, pkg/agentx/agents/cody.go, pkg/agentx/agents/continue.go, pkg/agentx/agents/codepuppy.go, pkg/agentx/agents/goose.go	Adds session support methods returning false for SupportsSession() and empty string for SessionID(), indicating these agents do not have native session concepts.
Orchestrator Implementations pkg/agentx/orchestrators/conductor.go, pkg/agentx/orchestrators/openclaw.go	Adds session support methods returning false for SupportsSession() and empty string for SessionID(), aligning orchestrators with the new interface requirements.
Session Support Test Suite pkg/agentx/agents/session_test.go	Adds comprehensive unit tests covering session support across all agent implementations. Organizes tests into three categories: env-var agents (ClaudeCode, Codex, Amp), hook-only agents (Cursor, Windsurf, Copilot, Cline, Kiro, Droid, OpenCode), and non-session agents (Aider, Goose, Cody, Continue, CodePuppy).

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• fix(agentx): improve Amp agent detection and accuracy #62: Modifies Amp agent session/thread identification via AMP_THREAD_URL environment variable, directly extending agent session capabilities introduced in this PR.
• Allow ox to work with codex #97: Updates agent session/priming code in cmd/ox/agent_prime.go with agent-agnostic session ID handling, following the same refactoring pattern as this PR.
• feat(agentx): add orchestrator detection with X-Orchestrator header #60: Modifies cmd/ox/agent_prime.go initialization path and adds orchestrator propagation logic, touching the same session handling code affected by this PR.

Suggested labels

session, sageox

Poem

🐰 A rabbit's delight in agent sessions true,
From Claude-specific paths to vistas anew!
Each agent now learns its session to keep,
Whether from hooks or env vars so deep.
Generalized handling, a hop toward the sky! 🌟

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ryan/muscat-work

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}