[AI] Run agent hooks and skills in Codex-based harnesses (ChatGPT desktop app) (#8462)

* [AI] Run agent hooks and skills in Codex-based harnesses (ChatGPT desktop app)

The ChatGPT desktop app (and Codex CLI/IDE) never picked up the repo's
agent skills or lifecycle hooks:

- Skills: Codex surfaces scan .agents/skills, not .claude/skills. Add a
  symlink mirror so both harness families load the same skill files.
- Hooks: Codex lifecycle hooks are feature-flagged; enable them in the
  project .codex/config.toml and document the trust steps (project
  .codex layer trust + one-time /hooks trust) required for them to run.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FMdDFdaErx9dqieTGh8ETg

* [AI] Drop .agents/skills/README.md; document the mirror in AGENTS.md instead

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FMdDFdaErx9dqieTGh8ETg

* [AI] Ignore .agents/** in knip like .claude/**

The .agents/skills symlink mirror exposes skill reference files under a
path knip scanned, flagging highlight-element.js as an unused file.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FMdDFdaErx9dqieTGh8ETg

---------

Co-authored-by: Claude <noreply@anthropic.com>

.agents/skills/committing-actual-changes

@@ -0,0 +1 @@
+../../.claude/skills/committing-actual-changes

.agents/skills/review-actual-pr

@@ -0,0 +1 @@
+../../.claude/skills/review-actual-pr

.agents/skills/writing-actual-docs

@@ -0,0 +1 @@
+../../.claude/skills/writing-actual-docs

.agents/skills/writing-release-notes

@@ -0,0 +1 @@
+../../.claude/skills/writing-release-notes

.codex/config.toml

@@ -1,8 +1,10 @@
 # Codex project hooks for actualbudget/actual.
 #
 # Codex discovers project config by walking up to the .git root, so this file
-# applies to the whole repo. The hook scripts are shared with Claude Code and
-# Cursor (see scripts/agent-hooks/). Codex's Bash hook is Claude-compatible
+# applies to the whole repo — and to every Codex surface: the Codex CLI, the
+# Codex IDE extension, and the ChatGPT desktop app all read the same config
+# layers. The hook scripts are shared with Claude Code and Cursor (see
+# scripts/agent-hooks/). Codex's Bash hook is Claude-compatible
 # (tool_input.command), so the git guard is reused directly; exit code 2 + stderr
 # blocks the call.
 #
@@ -13,7 +15,21 @@
 # Bash/git guard and the Stop check work regardless. The file hooks are fully
 # effective under Claude Code and Cursor.
 #
-# Non-managed hooks must be trusted once via `/hooks` in the Codex CLI.
+# For hooks to run (any surface, including the ChatGPT desktop app):
+#   1. Lifecycle hooks must be enabled — done by the [features] flag below.
+#   2. The project's .codex/ layer must be trusted. An untrusted project skips
+#      this whole file (hooks included), silently.
+#   3. Each non-managed hook must be trusted once via `/hooks` (hash-pinned, so
+#      editing a hook re-requires trust). Trust is recorded in shared Codex
+#      state, so trusting via the CLI also covers the desktop app and IDE.
+#
+# Repo skills for Codex surfaces are mirrored in .agents/skills/ (symlinks to
+# .claude/skills/) — Codex scans .agents/skills, not .claude/skills.
+
+# Lifecycle hooks are feature-flagged; enable them for this project so all
+# surfaces run the [hooks] tables below once the layer is trusted.
+[features]
+lifecycle_hooks = true
 
 # Block unsafe git/workspace commands ([AI] prefix, --no-verify, force-push,
 # push-to-main, git config writes, yarn-from-a-workspace).

AGENTS.md

@@ -349,6 +349,10 @@ describe('ComponentName', () => {
 - `/.nano-staged.json` - pre-commit format/lint config (run via Husky)
 - `/.claude/settings.json`, `/.codex/config.toml`, `/.cursor/hooks.json` - agent
   hook wiring; shared scripts live in `/scripts/agent-hooks/`
+- `/.agents/skills/` - symlink mirror of `/.claude/skills/` so Codex-based
+  harnesses (Codex CLI, IDE extension, ChatGPT desktop app) discover the same
+  skills; when adding a skill, create it in `/.claude/skills/` and add a
+  matching relative symlink here
 - `/tsconfig.json` - Root TypeScript configuration
 - `/.cursorignore`, `/.gitignore` - Ignored files
 - `/yarn.lock` - Dependency lockfile (Yarn 4)

knip.json

@@ -11,7 +11,7 @@
   "workspaces": {
     ".": {
       "entry": ["bin/*.mts"],
-      "ignore": ["lage.config.js", ".claude/**"]
+      "ignore": ["lage.config.js", ".claude/**", ".agents/**"]
     },
     "packages/api": {
       "entry": ["index.browser.ts", "browser-worker.ts", "e2e/**/*.{ts,mjs}"],

upcoming-release-notes/chatgpt-desktop-agent-hooks.md

@@ -0,0 +1,6 @@
+---
+category: Maintenance
+authors: [MatissJanis]
+---
+
+Make Codex-based agent harnesses (ChatGPT desktop app, Codex CLI/IDE) run the repo agent hooks and discover the shared skills