sync-upstream-features

name	sync-upstream-features
description	Investigate whether the latest hook events and features from Claude Code / Codex CLI are covered by tmux-agent-sidebar's current implementation, and report gaps. Use on requests like "check diff with upstream", "look for new hooks", "check changelog for unsupported features". Does not implement anything.

Sync Upstream Features — Gap Reporter

A skill that fetches the latest documentation and changelogs from Claude Code and Codex CLI, and reports gaps against this project's implementation. Does not implement anything — only outputs a gap list.

How This Project Works

Before reporting, you need to understand this project's architecture.

Hook Event Reception

This project uses Claude Code / Codex settings.json hooks to receive events. hook.sh receives JSON from stdin and passes it to the Rust binary's hook subcommand.

Mapping between upstream hook events and internal event names used by this project:

Upstream Hook Event	Internal Event Name	Notes
SessionStart	session-start
SessionEnd	session-end
UserPromptSubmit	user-prompt-submit
Notification	notification
Stop	stop
StopFailure	stop-failure
SubagentStart	subagent-start
SubagentStop	subagent-stop
PostToolUse	activity-log	Important: PreToolUse/PostToolUse are not used directly. Instead, a custom activity-log event passes tool_name, tool_input, tool_response from the PostToolUse hook

Items to Exclude from Report

The following are unrelated to the sidebar monitoring TUI and should NOT be reported as gaps:

• PreToolUse / PostToolUse / PostToolUseFailure: Already handled via activity-log. No need to handle these directly
• PermissionRequest: For permission UI control. Sidebar only displays, doesn't need this
• PreCompact / PostCompact: Compaction doesn't affect sidebar
• InstructionsLoaded: CLAUDE.md loading is unrelated to sidebar
• ConfigChange: Config change monitoring is outside sidebar scope
• FileChanged: File change monitoring is outside sidebar scope
• Elicitation / ElicitationResult: MCP elicitation is outside sidebar scope
• session_id, transcript_path fields: Information not used by sidebar

Note: Do NOT exclude WorktreeCreate / WorktreeRemove. The sidebar displays worktree information, so these events are useful for monitoring.

Items to Report

Only report gaps relevant to sidebar agent monitoring:

• New status-changing events: Events that affect agent state (running/waiting/idle/error)
• Permission modes: Missing variants in PermissionMode enum
• Notification types: New notification types that affect status display
• Tool tracking: Missing entries in activity.rs color mapping or label.rs label extraction
• Codex adapter: Newly supported events in Codex CLI (only if Codex actually sends the event)
• JSON fields: Overlooked fields in already-handled events that directly improve sidebar display
• New hook events: Events related to agent lifecycle or state tracking (e.g., TaskCreated, TaskCompleted, PermissionDenied, TeammateIdle)

Known Deferred Gaps

These gaps are intentionally left unfixed. Report them only when the trigger condition is met — otherwise include them in the coverage table as Partial (deferred) with a one-line pointer to this section instead of repeating the full analysis.

• TaskCreated extra fields (teammate_name, team_name, task_description)
  • Current state: src/adapter/claude.rs captures only task_id and task_subject. The src/cli/hook.rs handler for AgentEvent::TaskCreated is a no-op ("Redundant with activity-log; TaskCreate tool use already recorded") because the TaskCreate tool's PostToolUse already writes the activity log entry via the activity-log path.
  • Why deferred: With the handler doing nothing, capturing the extra fields would be dead code. The fields have no consumer today.
  • Trigger to revisit: Claude Code Agents Teams feature becomes a target for the sidebar — e.g. showing per-teammate task assignment in the activity log or a new UI panel for team state. When that work starts, capture teammate_name / team_name / task_description and thread them into whichever layer needs them (likely src/cli/label.rs for a richer TaskCreate label, or a new field on AgentEvent::TaskCreated consumed by a new handler).

Procedure

1. Fetch Upstream Documentation

Fetch latest information from the following URLs:

Source	URL	Focus
Claude Code Changelog	https://code.claude.com/docs/en/changelog	New hook events, permission modes, tools
Claude Code Hooks Reference	https://code.claude.com/docs/en/hooks	JSON schema for each hook event
Codex CLI Features	https://developers.openai.com/codex/cli/features	Execution modes, flags
Codex Releases	https://github.com/openai/codex/releases	New features, new events

2. Read Current Implementation

Identify supported features from the following files:

Check Item	File	What to Look For
Supported hook events	src/adapter/claude.rs	parse() match arms
Codex supported events	src/adapter/codex.rs	parse() match arms
Internal event definitions	src/event.rs	AgentEvent enum variants
Permission modes	src/tmux.rs	PermissionMode enum and from_str()
Tracked tools	src/activity.rs	tool_color_index() match arms
Labeled tools	src/cli/label.rs	extract_tool_label() match arms
Event handlers	src/cli/hook.rs	handle_event() match arms

3. Report Gaps

Report only gaps matching "Items to Report." Do NOT include items from "Items to Exclude from Report."

Categories

• Hook Events: Events present upstream but missing from adapter that would be useful for sidebar monitoring
• Permission Modes: Missing variants in PermissionMode enum
• Notification Types: New notification types
• JSON Fields: Overlooked fields in already-handled events that could improve display
• Tools: Tools not covered in activity.rs / label.rs
• Codex-specific: Codex adapter gaps (only if the event is confirmed to be actually sent)

4. Assign Priority

Assign priority to each gap:

• High: Status display is wrong or information is missing (e.g., missing permission mode, overlooked error type)
• Medium: Display is correct but additional information could improve it (e.g., new hook event support, new tool color)
• Low: Nice to have but low impact (e.g., additional label extraction, features not yet widely adopted)

5. Output Format

Output the report in the following structure.

5.1 Coverage Table

First, output a table of all upstream hook events with current coverage status. Include ALL upstream events, including those in "Items to Exclude."

Format:

Hook Event	Added in Version	Status	Notes
SessionStart	(initial)	Covered
TaskCreated	v2.1.84	Not covered	...
PreToolUse	(initial)	Out of scope	Handled via activity-log

• Added in Version: The version when the event was added to Claude Code. Identify from changelog. Use (initial) for events present from the start. Use Unknown if unidentifiable.
• Status: Covered / Not covered / Partial / Out of scope
  • Covered: Match arm exists in adapter's parse()
  • Not covered: No match arm in adapter, and the event is useful for sidebar monitoring
  • Partial: Match arm exists but has field omissions or field name mismatches
  • Out of scope: Not relevant to sidebar monitoring (matches "Items to Exclude")

Also output the following tables:

Permission Modes:

Mode	Status	Notes
default	Covered
dontAsk	Not covered	Falls back to Default

Tools (Color Mapping + Label Extraction):

Show only not-covered / partial tools.

Tool	Added in Version	Color	Label	Notes
PowerShell	v2.1.84	Not covered	Not covered	Windows only
TaskList	(initial)	Covered	Not covered

5.2 Gap Details

For items marked Not covered / Partial in the coverage table (excluding Out of scope), output details by priority.

Each gap should include:

• Item name
• Added in version
• Upstream spec: Brief description
• Current state
• Affected files

5.3 Summary

Rules for coverage table accuracy:

1. List adapter match arms before writing: Before writing the table, enumerate ALL string literals in src/adapter/claude.rs's parse() match arms ("session-start", "session-end", etc.). Do not mark an event as "Covered" unless it appears in this enumeration.
2. Cross-table consistency check: Verify no contradictions between the coverage table and gap details.
3. All-category completeness check: Verify no gaps are missing for permission modes and tools.