LLM-25226 Add codex-update-compat skill for future Codex migrations

- add reusable Codex skill for updating Codex versions safely
- include migration workflow for typecheck/test-driven compatibility fixes
- document common app-server schema breakages and event-mapping patterns
- include QA-oriented notes for env-dependent auth/keychain test failures

Author: Aleksandr Slapoguzov

.agents/skills/codex-update-compat/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: codex-update-compat
+description: Upgrade Codex in this repository and resolve compatibility regressions caused by app-server schema/protocol changes. Use when bumping Codex/npm package versions, regenerating `src/app-server` types, fixing TypeScript errors after update, repairing event mappings, and updating tests/snapshots to match new Codex behavior (especially model list, thread/session fields, sandbox policy shape, and tool/event notifications).
+---
+
+# Codex Update Compat
+
+Use this workflow to safely upgrade Codex and close update-induced regressions.
+
+## Workflow
+
+1. Inspect update scope before changing code.
+Run:
+```bash
+git log --oneline -n 5
+git show --name-only --oneline -n 1
+```
+Focus first on `package.json`, `package-lock.json`, and generated `src/app-server/**` changes.
+
+2. Run typecheck and tests immediately.
+Run:
+```bash
+npm run typecheck
+npm test
+```
+Treat type errors as the migration guide for required protocol changes.
+
+3. Fix runtime compatibility in source files.
+Typical hotspots:
+- `src/CodexAcpClient.ts`: thread start/resume params and initialize capabilities
+- `src/AgentMode.ts`: sandbox policy shape changes
+- `src/CodexEventHandler.ts`: new/changed server notifications
+- `src/CodexAcpServer.ts`: history replay for new `ThreadItem` variants
+- `src/CodexToolCallMapper.ts`: mapping new tool-like items to ACP events
+
+4. Fix test fixtures and snapshots.
+Update typed fixtures for new required fields instead of weakening types.
+Then update snapshots only after behavior is intentionally verified.
+
+5. Re-run targeted suites, then full checks.
+Run focused tests for touched behavior, then:
+```bash
+npm run typecheck
+npm test
+```
+
+## Non-Trivial Changes: Ask Before Finalizing
+
+When migration requires behavior decisions (not only schema fixes), ask the user first. Examples:
+- Enabling/disabling experimental flags (`persistExtendedHistory`, `experimentalApi`)
+- User-visible messaging changes for new events (e.g., model reroute wording)
+- Converting integration tests to mocks or skipping env-dependent tests
+
+## Event Mapping Rule
+
+Do not silently drop new event/item variants if they should be visible to users.
+Map them to ACP updates:
+- Tool-like operations -> `tool_call` / `tool_call_update`
+- Informational reasoning/infra events -> `agent_thought_chunk` (if user-meaningful)
+- Internal/noise events -> explicit no-op case (documented in switch)
+
+## References
+
+For common break patterns and ready fixes, read:
+- `references/codex-update-playbook.md`

.agents/skills/codex-update-compat/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Codex Update Compat"
+  short_description: "Upgrade Codex and resolve compatibility"
+  default_prompt: "Update Codex, run typecheck/tests, and fix app-server compatibility regressions."

.agents/skills/codex-update-compat/references/codex-update-playbook.md

@@ -0,0 +1,74 @@
+# Codex Update Playbook
+
+Use this checklist when Codex version bumps cause compile/test breakage.
+
+## Common Type Breakages
+
+1. New required model fields.
+Symptoms:
+- `Property 'hidden' is missing in type ...`
+Fix:
+- Add `hidden: false` (or expected value) in all `Model` fixtures.
+
+2. Thread shape expansion.
+Symptoms:
+- Missing `status`, `agentNickname`, `agentRole`, `name` in `Thread`.
+Fix:
+- Add these fields in test fixtures and mocks.
+
+3. Thread item schema changes.
+Symptoms:
+- `agentMessage` missing `phase`.
+Fix:
+- Add `phase: null` unless specific phase is required by test.
+
+4. Rate limits payload changes.
+Symptoms:
+- Missing `limitId` / `limitName` in `RateLimitSnapshot`.
+Fix:
+- Include `limitId` and `limitName` under `rateLimits` snapshot object.
+- If notification wrapper changed, map from new shape in handler.
+
+5. Sandbox policy contract changes.
+Symptoms:
+- Missing `access` for read-only or `readOnlyAccess` for workspace-write policy.
+Fix:
+- Provide required nested objects in policy fixtures and runtime mapping.
+
+6. Thread start/resume required flags.
+Symptoms:
+- Missing `persistExtendedHistory`.
+Fix:
+- Set explicitly in `threadStart` and `threadResume` params.
+- Keep `false` unless user confirms enabling experimental behavior.
+
+## Event Compatibility Patterns
+
+1. New tool-like items/events.
+Approach:
+- Add mapper function in `CodexToolCallMapper.ts`.
+- Emit `tool_call` on start and `tool_call_update` on completion.
+- Include meaningful `kind`, `title`, and `rawInput`.
+
+2. Streaming/progressive session events.
+Approach:
+- Keep stable `toolCallId`.
+- First event: `tool_call`, subsequent events: `tool_call_update`.
+- Completion event should set `status: completed` or `failed`.
+
+3. Informational infra events (e.g., model reroute).
+Approach:
+- Emit `agent_thought_chunk` with concise user-readable text.
+
+## Test Strategy
+
+1. Fix types first (`npm run typecheck`).
+2. Run focused tests for touched event/file.
+3. Update snapshots only after confirming expected behavior.
+4. Run full suite at end.
+
+## Known Env-Dependent Failures
+
+Authentication integration tests may fail on CI/local machines due OS keychain restrictions:
+- examples: `failed to save api key`, `logout failed`, `Operation not permitted`.
+Treat separately from migration regressions.