# Sync Upstream Features > 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. Use when this capability is needed. - Skill: `tomevault-io/sync-upstream-features` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/sync-upstream-features` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/sync-upstream-features/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/sync-upstream-features --- # 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. --- > Source: [hiroppy/tmux-agent-sidebar](https://github.com/hiroppy/tmux-agent-sidebar) — distributed by [TomeVault](https://tomevault.io).