@softspark/ai-toolkit 4.14.0 → 4.15.0

package/kb/procedures/release-verification-sop.md

@@ -3,10 +3,10 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
-version: "1.6.0"
+version: "1.7.0"
 created: "2026-04-08"
-last_updated: "2026-07-02"
-description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, installs, Claude app plugin export, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. v1.6.0 adds the Claude Chat/Cowork plugin validation and replaces the retired Cascade hook surface with Devin hooks."
+last_updated: "2026-07-14"
+description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit. Verifies CLI, native Codex and GitHub Copilot surfaces, Claude app export, doctor, validation, tests, eject, provenance, SARIF, and per-skill permissions."
 ---
 
 # SOP: Release Verification
@@ -31,31 +31,31 @@ Verifies all critical paths from the user's perspective.
 
 ## Quick Checklist (TL;DR)
 
-13 commands — if all pass, the release is ready:
+14 commands — if all pass, the release is ready:
 
 ```bash
 # Pre-commit (Phase 0)
 python3 scripts/generate_agents_md.py > AGENTS.md           # 1. Regenerate AGENTS.md
 python3 scripts/generate_llms_txt.py > llms.txt             # 2. Regenerate llms.txt
 python3 scripts/validate.py --strict                        # 3. Validation passed?
-npm test > /tmp/npm-test.log 2>&1 && grep -c '^ok ' /tmp/npm-test.log && ! grep -q '^not ok' /tmp/npm-test.log  # 5. All tests passed? (single run, cached)
+npm test > /tmp/npm-test.log 2>&1 && grep -c '^ok ' /tmp/npm-test.log && ! grep -q '^not ok' /tmp/npm-test.log  # 4. All tests passed? (single run, cached)
 
 # Post-install verification (Phases 1-7)
-ai-toolkit --version                                        # 6. Version OK?
-ai-toolkit status                                           # 7. Status OK?
-ai-toolkit doctor                                           # 8. Health check passed?
-ai-toolkit install --dry-run                                # 9. Global install OK?
-python3 scripts/audit_skills.py --ci                        # 10. Security audit clean?
+ai-toolkit --version                                        # 5. Version OK?
+ai-toolkit status                                           # 6. Status OK?
+ai-toolkit doctor                                           # 7. Health check passed?
+ai-toolkit install --dry-run                                # 8. Global install OK?
+python3 scripts/audit_skills.py --ci                        # 9. Security audit clean?
 
 # Supply-chain verification (Phase 8, v2.8.0+)
-python3 scripts/audit_skills.py --sarif | python3 -c "import json,sys; assert json.load(sys.stdin)['version']=='2.1.0'; print('SARIF OK')"   # 11. SARIF 2.1.0 well-formed?
-python3 scripts/audit_skills.py --permissions | head -30    # 12. Broad-access skills reviewed?
-npm view @softspark/ai-toolkit@X.Y.Z --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['dist']['attestations']['provenance']['predicateType']=='https://slsa.dev/provenance/v1'; print('PROVENANCE OK')"   # 13. Provenance attested on npm?
-python3 scripts/claude_app.py verify                         # 14. Claude Chat/Cowork plugin contract valid?
+python3 scripts/audit_skills.py --sarif | python3 -c "import json,sys; assert json.load(sys.stdin)['version']=='2.1.0'; print('SARIF OK')"   # 10. SARIF 2.1.0 well-formed?
+python3 scripts/audit_skills.py --permissions | head -30    # 11. Broad-access skills reviewed?
+npm view @softspark/ai-toolkit@X.Y.Z --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['dist']['attestations']['provenance']['predicateType']=='https://slsa.dev/provenance/v1'; print('PROVENANCE OK')"   # 12. Provenance attested on npm?
+python3 scripts/claude_app.py verify                         # 13. Claude Chat/Cowork plugin contract valid?
 
 # Deep-coverage verification (Phase 9, v3.0.0+)
 META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
-diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) && echo "OK: registry matches"   # 15. Registry <-> generators drift?
+diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) && echo "OK: registry matches"   # 14. Registry <-> generators drift?
 ```
 
 ---
@@ -123,10 +123,10 @@ ai-toolkit status
 ```
 
 **Verify `--dry-run`:**
-- [ ] Agents >= 44
-- [ ] Skills >= 99
+- [ ] Agents: 44
+- [ ] Skills: 108
 - [ ] Hooks merged into settings.json
-- [ ] "Other AI Tools" section lists documented global targets (with `--editors`): aider, antigravity, augment, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf. Scope varies (v4.12.0+): cursor = `~/.cursor/hooks.json` only, copilot = `~/.copilot/` instructions, antigravity = `~/.gemini/*/skills` pointer; Cursor and Antigravity RULES still install only via `--local` (no mergeable global rules file)
+- [ ] "Other AI Tools" lists documented global targets (with `--editors`): aider, antigravity, augment, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf. Scope varies: Codex uses `$CODEX_HOME` (default `~/.codex`) plus `$HOME/.agents/skills`; Copilot uses `$COPILOT_HOME` (default `~/.copilot`); cursor has only `~/.cursor/hooks.json`; antigravity has the `~/.gemini/*/skills` pointer. Cursor and Antigravity rules remain project-only.
 
 **Verify `status`:**
 - [ ] Version matches expected
@@ -195,7 +195,7 @@ python3 scripts/audit_skills.py --ci
 ```
 
 **Verify validate.py:**
-- [ ] Agents >= 44, Skills >= 99, Tests >= 900
+- [ ] Agents: 44, Skills: 108, Tests: exactly the current README badge count
 - [ ] Hook events: 14, Hook scripts: >= 30
 - [ ] Plugin packs >= 10, KB documents >= 20
 - [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
@@ -340,9 +340,9 @@ These verify the native-surface generators shipped in v3.0.0 actually emit the r
 
 ```bash
 D=/tmp/aitk-profile-full-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
-ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex \
-  --profile full --codex-skills --dry-run 2>&1 \
-  | grep -E "\\.cursor/(hooks\\.json|agents)|\\.devin/hooks\\.v1\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.agents/skills"
+ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex,copilot \
+  --profile full --dry-run 2>&1 \
+  | grep -E "\\.cursor/(hooks\\.json|agents)|\\.devin/hooks\\.v1\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.codex/(agents|hooks)|\\.agents/skills|\\.github/(agents|skills|instructions|prompts|hooks)"
 ```
 
 **Verify** — at least the following lines appear:
@@ -350,26 +350,29 @@ ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex \
 - [ ] `.devin/hooks.v1.json`
 - [ ] `.gemini/settings.json` hooks AND `.gemini/commands/`
 - [ ] `.augment/agents/` + `.augment/commands/` + `$HOME/.augment/settings.json`
-- [ ] `.agents/skills/` (Codex native discovery path; refreshed by `--codex-skills`)
+- [ ] `.codex/hooks.json` + `.codex/hooks/` + `.codex/agents/`
+- [ ] `.agents/skills/` (Codex native discovery path)
+- [ ] `.github/agents/` + `.github/skills/` + `.github/instructions/` + `.github/prompts/` + `.github/hooks/`
 
-### 9.2 `--codex-skills` is orthogonal to `--profile`
+### 9.2 Codex skills are profile-independent
 
 ```bash
 D=/tmp/aitk-codex-skills-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors codex --profile minimal --dry-run 2>&1 \
+  | grep -q "Would generate: .agents/skills" && echo "OK: Codex skills emit at minimal"
 ai-toolkit install --local --editors codex --profile standard --codex-skills --dry-run 2>&1 \
-  | grep -q "Would refresh: .agents/skills" && echo "OK: --codex-skills refreshes .agents/skills without --profile full"
-ai-toolkit install --local --editors codex --profile full --dry-run 2>&1 \
-  | grep -q "Would generate: .agents/skills" && echo "OK: Codex skills use .agents/skills at profile full"
+  | grep -q "Would refresh: .agents/skills" && echo "OK: legacy flag explicitly refreshes the same catalog"
 ```
 
 **Verify:**
-- [ ] `--codex-skills` refreshes `.agents/skills/` at any profile
-- [ ] `--profile full` never emits `.codex/skills/`; Codex skills use `.agents/skills/`
+- [ ] Selecting Codex emits all skills under `.agents/skills/` at every profile
+- [ ] `--codex-skills` remains an explicit refresh alias; it is not required for installation
+- [ ] No profile emits `.codex/skills/`
 
 ### 9.3 Breaking-change surfaces land on `--profile standard`
 
-v3.0.0 moved two surfaces from opt-in to default:
-- Copilot directory layout (`.github/instructions/`, `.github/prompts/`)
+The standard profile must include:
+- Copilot scoped instructions, prompts, custom agents, portable skills, and hooks
 - Gemini hooks (`.gemini/settings.json`)
 
 ```bash
@@ -377,10 +380,12 @@ D=/tmp/aitk-breaking-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
 ai-toolkit install --local --editors copilot,gemini --profile standard --dry-run 2>&1 \
   | tee /tmp/aitk-breaking.log
 grep -q "\\.github/instructions/" /tmp/aitk-breaking.log && echo "OK: Copilot dir layout at standard"
+grep -q "\\.github/agents/.*\\.github/skills/" /tmp/aitk-breaking.log && echo "OK: Copilot agents and skills at standard"
+grep -q "\\.github/hooks/" /tmp/aitk-breaking.log && echo "OK: Copilot hooks at standard"
 grep -q "\\.gemini/settings\\.json hooks" /tmp/aitk-breaking.log && echo "OK: Gemini hooks at standard"
 ```
 
-**Verify both lines print `OK:`**. If either is missing, a regression has unwound the v3.0.0 breaking change.
+**Verify all four lines print `OK:`**. If any is missing, native Copilot or Gemini coverage has regressed.
 
 ### 9.4 Install is idempotent
 
@@ -404,8 +409,8 @@ The bats suite validates JSON shape at generation time. This re-checks that what
 
 ```bash
 D=/tmp/aitk-json-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
-ai-toolkit install --local --editors cursor,windsurf,gemini,augment --profile full >/dev/null 2>&1
-for f in .cursor/hooks.json .devin/hooks.v1.json .gemini/settings.json $HOME/.augment/settings.json; do
+ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex,copilot --profile full >/dev/null 2>&1
+for f in .cursor/hooks.json .devin/hooks.v1.json .gemini/settings.json .codex/hooks.json .github/hooks/ai-toolkit.json "$HOME/.augment/settings.json"; do
   [ -f "$f" ] && python3 -c "import json; json.load(open('$f'))" && echo "OK: $f"
 done
 ```
@@ -493,8 +498,8 @@ ai-toolkit eject /tmp/test # retry
 | Tests | `npm test`: N/N passed, 0 failures |
 | Eject | Standalone `.claude/` with real files AND `output-styles/` directory |
 | Guards | Destructive commands blocked |
-| Deep coverage | `--profile full` emits all 9 v3.0.0 native surfaces; `--codex-skills` works orthogonally |
-| Breaking changes | Copilot directory layout + Gemini hooks emit at `--profile standard` (v3.0.0 contract) |
+| Deep coverage | `--profile full` emits every documented native surface, including Codex agents/skills/hooks and Copilot agents/skills/hooks |
+| Profile contract | Codex skills emit at every profile without `--codex-skills`; Copilot standard emits agents, skills, instructions, prompts, and hooks |
 | Idempotence | Second `install` run produces byte-identical output in every managed path |
 | Live JSON | Every generated `.json` file on disk parses as valid JSON |
 | Registry | `supported-tools-registry.md` enumerates every `scripts/generate_*.py` we ship |

package/kb/reference/architecture-overview.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.4.6"
+version: "1.4.7"
 created: "2026-03-23"
-last_updated: "2026-06-10"
+last_updated: "2026-07-14"
 description: "Architecture of ai-toolkit: directory layout, Claude app export, global install model, editor-aware MCP install, Codex translation layer, skill tiers, and integration with projects."
 ---
 
@@ -55,7 +55,8 @@ ai-toolkit/
     generate_agents_md.py    # Regenerates AGENTS.md
     generate_cursor_rules.py # Generates .cursorrules (sources _common.py)
     generate_windsurf.py     # Generates .windsurfrules (sources _common.py)
-    generate_copilot.py      # Generates Copilot .github/* surfaces; install also injects AGENTS.md
+    generate_copilot.py      # Generates Copilot instructions, agents, and portable skills
+    generate_copilot_hooks.py # Generates native Copilot hooks + self-contained runtime
     generate_gemini.py       # Generates GEMINI.md (sources _common.py)
     generate_cline.py        # Generates .clinerules (sources _common.py)
     generate_roo_modes.py    # Generates .roomodes
@@ -112,11 +113,26 @@ Machine (global)                              Project (local)
 - `--editors cursor,aider` — install only selected editors
 - (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs
 
-Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.devin/rules/*.md` + `.windsurf/rules/*.md` (dual-emit since the Devin Desktop rebrand), `.github/instructions/*.instructions.md` + `.github/prompts/*.prompt.md` + root `AGENTS.md` for Copilot agent instructions, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agents/rules/*.md`, `CONVENTIONS.md`). Full-profile installs also emit native skill pointer catalogues for Cursor, Windsurf, and Cline. Codex local install additionally generates `AGENTS.md` (universal coding rules inlined — Codex reads only AGENTS.md, not `.agents/rules/`), `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
+Each editor gets its documented directory-based format. Copilot receives root
+`AGENTS.md`, `.github/copilot-instructions.md`, native `.github/agents`, and
+self-contained `.github/skills` in every profile. Profile `standard` and above
+also emits `.github/instructions`, `.github/prompts`, and native
+`.github/hooks`. The user target writes the supported personal surfaces below
+`$COPILOT_HOME` (default `~/.copilot`) and does not generate prompt files there.
+Full-profile installs also emit native skill pointer catalogues for Cursor,
+Windsurf, and Cline. Codex local install generates `AGENTS.md`,
+`.agents/skills/*`, `.codex/agents/*.toml`, `.codex/hooks.json`, and
+self-contained `.codex/hooks/*`. Global Codex install writes its user-owned
+surfaces below `$CODEX_HOME` (default `~/.codex`) while user skills remain in
+the documented shared `$HOME/.agents/skills/` directory. Experimental plugin
+packs can layer their rules, skills, and hooks onto that Codex user target.
 
 Claude Chat/Desktop/Cowork is deliberately outside `--editors`: the app does not scan filesystem configuration under `~/.claude`. `ai-toolkit claude-app export` creates a self-contained plugin ZIP with skills, agents, Cowork hooks, app-native rules, and bundled hook dependencies. It also emits the compact text that users paste into Cowork global instructions. Updating requires re-export and re-upload because the app owns its plugin store.
 
-If a project already has `.mcp.json`, local install mirrors its `mcpServers` entries into `.claude/settings.local.json` plus any selected editors with project-scoped native MCP files (`.cursor/mcp.json`, `.github/mcp.json`).
+If a project already has `.mcp.json`, local install mirrors its `mcpServers`
+entries into `.claude/settings.local.json` plus any selected editors with
+project-scoped native MCP files: `.cursor/mcp.json`, `.github/mcp.json`,
+`.roo/mcp.json`, and `.codex/config.toml`.
 
 ## CLI Commands
 
@@ -226,12 +242,12 @@ See `kb/reference/codex-cli-compatibility.md` for the detailed mapping.
 Current native adapters:
 - Claude Code: `.claude/settings.local.json` and `~/.claude/settings.json`
 - Cursor: `.cursor/mcp.json` and `~/.cursor/mcp.json`
-- GitHub Copilot: `.github/mcp.json` and `~/.copilot/mcp-config.json`
+- GitHub Copilot: `.github/mcp.json` and `$COPILOT_HOME/mcp-config.json` (default `~/.copilot/mcp-config.json`)
 - Gemini CLI: `.gemini/settings.json` and `~/.gemini/settings.json`
 - Windsurf: `~/.codeium/windsurf/mcp_config.json`
 - Cline: `~/.cline/data/settings/cline_mcp_settings.json`
 - Augment: `~/.augment/settings.json`
-- Codex CLI: `~/.codex/config.toml`
+- Codex CLI: `.codex/config.toml` and `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`)
 
 See `kb/reference/mcp-editor-compatibility.md` for the support matrix and scope rules.
 

package/kb/reference/codex-cli-compatibility.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - Codex CLI Compatibility"
 category: reference
 service: ai-toolkit
 tags: [codex, compatibility, install, skills, hooks]
-version: "1.0.3"
+version: "1.0.4"
 created: "2026-04-12"
-last_updated: "2026-05-25"
+last_updated: "2026-07-14"
 description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, and plugin packs to Codex CLI."
 ---
 
@@ -15,15 +15,16 @@ description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, a
 
 Codex CLI now receives the full `ai-toolkit` skill catalog during local install.
 
-Native Codex-compatible skills are linked directly into `.agents/skills/`. Skills
-that depend on Claude-only orchestration primitives are generated as Codex
-wrappers that preserve the original workflow intent while translating execution
-to Codex subagents and plan tracking.
+Native Codex-compatible skills are linked directly into `.agents/skills/`.
+Skills that contain Claude-only tools, prompt placeholders, or skill-directory
+variables are generated as Codex wrappers. The wrappers preserve workflow intent
+using semantic subagent and planning guidance instead of version-specific tool
+signatures.
 
-Experimental plugin packs can also target a global Codex surface with
+Experimental plugin packs can also target the Codex user surface with
 `ai-toolkit plugin install --editor codex`, which layers plugin-specific skills,
-rules, and hooks into `HOME` without changing the project-local core install
-model.
+rules, and hooks onto the active `CODEX_HOME` without changing project-local
+configuration.
 
 ## Local Install Outputs
 
@@ -32,18 +33,46 @@ model.
 - `AGENTS.md` (project root; universal coding rules inlined — Codex reads instructions only from AGENTS.md, not `.agents/rules/`)
 - `.agents/skills/*`
 - `.codex/hooks.json`
+- `.codex/hooks/*` (self-contained executable hook assets)
+- `.codex/agents/*.toml`
+- `.codex/config.toml` when project MCP servers are selected
+
+Project-local Codex paths never follow `CODEX_HOME`; the variable selects the
+user configuration root only.
+
+## Global Core Install Outputs
+
+`ai-toolkit install --editors codex` writes Codex-owned user files below the
+active `CODEX_HOME` (default `~/.codex`):
+
+- `$CODEX_HOME/AGENTS.md`
+- `$CODEX_HOME/agents/*.toml`
+- `$CODEX_HOME/hooks.json`
+- `$CODEX_HOME/ai-toolkit-hooks/*`
+
+The portable user skill catalog intentionally remains under
+`$HOME/.agents/skills/*`. This is Codex's documented shared user-skill discovery
+path, not a Codex-owned config-root path. A configured `CODEX_HOME` must be an
+existing absolute directory; the installer preserves user guidance, custom
+agents, and unrelated hook handlers inside it.
+
+Sources: [Codex environment variables](https://learn.chatgpt.com/codex/config-file/environment-variables),
+[AGENTS.md discovery](https://learn.chatgpt.com/codex/agent-configuration/agents-md),
+[Codex skills](https://developers.openai.com/codex/skills).
 
 ## Global Plugin Outputs
 
 `ai-toolkit plugin install --editor codex <pack>` bootstraps or reuses:
 
-- `~/.codex/AGENTS.md` (the documented global instruction file; pack rules are marker-injected here, not written as unread `~/.agents/rules/` files)
-- `~/.agents/skills/*`
-- `~/.codex/hooks.json`
+- `$CODEX_HOME/AGENTS.md` (default `~/.codex/AGENTS.md`; pack rules are marker-injected here, not written as unread `.agents/rules/` files)
+- `$HOME/.agents/skills/*`
+- `$CODEX_HOME/hooks.json`
+- `$CODEX_HOME/ai-toolkit-hooks/*`
 
 Plugin packs only add their own runtime-specific layer on top of the generated
-Codex base. Shared hook scripts and plugin scripts still live in
-`~/.softspark/ai-toolkit/`.
+Codex base. Codex hooks no longer depend on executable paths under
+`~/.softspark/ai-toolkit/`; project assets live beside `.codex/hooks.json`, and
+user assets live under `$CODEX_HOME/ai-toolkit-hooks/`.
 
 ## Skill Translation Model
 
@@ -51,43 +80,46 @@ Two delivery modes are used for Codex:
 
 | Mode | How it is installed | Use case |
 |------|----------------------|----------|
-| Native | Symlink to `app/skills/<name>/` | Skills whose `allowed-tools` are already supported in Codex |
-| Adapted | Generated wrapper directory in `.agents/skills/<name>/` | Skills that rely on Claude-only `Agent`, `Team*`, or `Task*` primitives |
+| Native | Symlink to `app/skills/<name>/` | Skills with portable tools, prompts, and paths |
+| Adapted | Generated wrapper directory in `.agents/skills/<name>/` | Skills with Claude-only tools, prompt placeholders, path variables, or orchestration APIs |
 
 Adapted skills keep the same support assets (`reference/`, `scripts/`, `assets/`)
 via symlinks, but rewrite `SKILL.md` to Codex-native guidance.
 
-## Claude-to-Codex Tool Mapping
+## Claude-to-Codex Semantic Mapping
 
-The adapter rewrites Claude-specific delegation guidance to the closest Codex
-runtime primitives:
+The adapter deliberately avoids embedding runtime function names or guessed
+signatures. Generated guidance describes stable intent:
 
-| Claude-oriented primitive | Codex replacement |
-|---------------------------|------------------|
-| `Agent(...)` | `spawn_agent(..., fork_context=True, ...)` |
-| `SendMessage` | `send_input` |
-| `TaskCreate` / `TaskList` / `TaskUpdate` | `update_plan` or explicit checklist tracking |
-| `TaskGet` / `TaskOutput` | `wait_agent` |
-| `TaskStop` / `TeamDelete` | `close_agent` |
-| Agent teams | Multiple spawned subagents with explicit file ownership |
+| Claude-oriented concept | Codex guidance |
+|-------------------------|----------------|
+| Delegated agent call | Delegate a narrow task to a suitable Codex-native subagent |
+| Agent redirection | Use the subagent controls available in the current client |
+| Task bookkeeping | Use the planning mechanism available in the current client or an explicit checklist |
+| Waiting for a task | Wait only when the next critical-path step depends on the delegated result |
+| Agent teams | Coordinate subagents with explicit, non-overlapping ownership |
+| Prompt input placeholder | Use the task details supplied by the user |
+| Claude skill-directory variable | Use the installed skill directory containing `SKILL.md` |
 
 ## Adapted Skill Classes
 
-The main adapted group is multi-agent orchestration:
+The adapted group includes multi-agent orchestration:
 
 - `/orchestrate`
 - `/workflow`
 - `/swarm`
 - `/subagent-development`
 
-The adapter also covers skills that previously depended only on Claude's
-`Agent` primitive, such as:
+It also includes any skill that contains Claude-only prompt or path variables,
+even when its tool list is otherwise portable. Examples include:
 
 - `/tdd`
 - `/write-a-prd`
 - `/qa-session`
 - `/triage-issue`
 - `/architecture-audit`
+- `/build`
+- `/cve-scan`
 
 ## Hook Compatibility
 
@@ -111,11 +143,26 @@ environment-snapshot probe). Claude-only events such as `TaskCompleted`,
 are not available in `.codex/hooks.json`. Handler types: only `command` runs;
 `prompt` and `agent` are parsed by Codex but not yet executed.
 
-`inject-hook` automatically propagates these 9 Codex-compatible events to
-`~/.codex/hooks.json` (global layer). Non-Codex events are silently skipped.
-`remove-hook` cleans both Claude and Codex targets.
-
-Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. The generated
+The generator merges these Codex-compatible events into project or user
+`hooks.json`, preserving unrelated user handlers and replacing only commands
+marked as ai-toolkit-owned. Project commands resolve their assets from the git
+root; core user commands use `$CODEX_HOME/ai-toolkit-hooks/`.
+
+Hook JSON is parsed from the snapshot held by the same secure transaction that
+writes generated handlers, installs executable assets, and removes stale
+managed assets. A failure in any of those stages rolls back the whole upgrade.
+Existing file permissions are retained; new `hooks.json` files use a secure
+`0600` base filtered by umask, while new executable hook assets are explicitly
+installed as `0755`.
+
+After installation or any hook change, open `/hooks` in Codex and review/trust
+the exact definitions. Project hooks additionally require a trusted `.codex`
+project layer. The installer never bypasses hook trust.
+
+Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. Native
+`SessionStart`, `PreCompact`, and MCP-health adapters use Codex instruction and
+config terminology (`AGENTS.md`, `.codex/config.toml`) instead of Claude-only
+paths. The generated
 `UserPromptSubmit` governance hook does not set `AI_TOOLKIT_HOOK_FORMAT=json`
 by default because Codex currently renders `additionalContext` as visible hook
 context in the TUI. This keeps prompt-submit output quiet while preserving hook
@@ -147,6 +194,18 @@ Plain-text informational hook context is also silent by default in the shared
 hook helper. Set `AI_TOOLKIT_HOOK_VERBOSE=1` only when debugging hook output
 outside the Codex UI.
 
+## MCP Configuration
+
+Codex MCP servers are supported at both documented scopes:
+
+- project: `.codex/config.toml` (trusted project layers only)
+- user: `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`)
+
+The adapter renders `[mcp_servers.<name>]` for STDIO and Streamable HTTP
+transports. It validates documented transport, timeout, tool-filter, and
+approval fields, preserves unrelated TOML bytes/comments, and owns only its
+marker-bounded block. Invalid TOML and symlinked roots are rejected unchanged.
+
 ## Behavioral Limits
 
 Codex wrappers preserve workflow intent, but not every Claude runtime behavior
@@ -158,7 +217,8 @@ Known limits:
 - No separate task object model equivalent to Claude `Task*` APIs
 - Hook event coverage is narrower than Claude Code
 - MCP search tool calls may not fire the shared `PostToolUse` search tracker,
-  so `stop-search-check.sh` also checks `~/.codex/log/codex-tui.log` for
+  so `stop-search-check.sh` also checks `$CODEX_HOME/log/codex-tui.log` (default
+  `~/.codex/log/codex-tui.log`) for
   `smart_query`, `hybrid_search_kb`, `crag_search`, `multi_hop_search`, and
   `verify_answer` calls after the search-first flag timestamp before blocking.
   The scan is bounded to a recent log window, but sized to tolerate noisy Codex

package/kb/reference/extension-api.md

@@ -3,9 +3,9 @@ title: "Extension API Reference"
 category: reference
 service: ai-toolkit
 tags: [extension-api, inject-rule, inject-hook, inject-mcp, mcp-templates, integration, editors]
-version: "1.5.0"
+version: "1.8.0"
 created: "2026-04-07"
-last_updated: "2026-05-12"
+last_updated: "2026-07-14"
 description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, inject-mcp, remove-* variants, and editor-aware MCP template management."
 ---
 
@@ -23,8 +23,8 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
 |---------|-------------|-----------|------------|
 | `inject-rule <file.md>` | `~/.claude/CLAUDE.md` | Legacy HTML comment markers (`<!-- TOOLKIT:name -->`) | Yes |
 | `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/rules/` | Unregister and remove generated Claude rule file | Yes |
-| `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` | JSON `_source` tag per entry, URL cached + registered | Yes |
-| `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source`, unregister URL source | Yes |
+| `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` + `$CODEX_HOME/hooks.json` | Claude `_source` ownership plus native Codex command translation | Yes |
+| `remove-hook <name>` | `~/.claude/settings.json` + `$CODEX_HOME/hooks.json` | Strip exact source ownership in both schemas, unregister URL source | Yes |
 | `inject-mcp <file.json\|url> [name] [--force]` | `~/.mcp.json` + every editor with `global_path` | JSON `_source` tag per server, URL cached + registered, full editor propagation | Yes |
 | `remove-mcp <name>` | `~/.mcp.json` + every editor with `global_path` | Strip all servers with matching `_source`, clean editor configs, unregister URL | Yes |
 | `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + sync to `~/.claude/rules/ai-toolkit-registered-*.md` on next `update` | Yes |
@@ -73,6 +73,9 @@ npx @softspark/ai-toolkit inject-hook https://example.com/my-tool-hooks.json
 
 # With explicit source name
 npx @softspark/ai-toolkit inject-hook https://example.com/hooks.json my-tool-hooks
+
+# Local source name plus explicit target directory
+npx @softspark/ai-toolkit inject-hook ./hooks.json my-tool-hooks /custom/target
 ```
 
 **Implementation:** `scripts/inject_hook_cli.py`, `scripts/hook_sources.py`, `scripts/url_fetch.py`.
@@ -103,13 +106,45 @@ npx @softspark/ai-toolkit inject-hook https://example.com/hooks.json my-tool-hoo
 
 **Idempotency:** Re-running strips all existing entries with the same source name, then appends the new ones. No duplicates accumulate.
 
-**Safety:** Entries tagged `"_source": "ai-toolkit"` are never modified or removed by this command. External tools cannot affect the toolkit's own hooks. Only HTTPS URLs are accepted.
-
-**Codex propagation:** Codex-compatible events (`SessionStart`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`) are automatically propagated to `~/.codex/hooks.json`. Non-Codex events are silently skipped. No extra flags needed.
+**Safety:** Entries tagged `"_source": "ai-toolkit"` are never modified or
+removed by this command. External tools cannot affect the toolkit's own hooks.
+Only HTTPS URLs are accepted. Claude settings, the source registry/cache, and
+Codex hooks are parsed from the byte snapshots captured after their trusted
+roots and parent directories are pinned. Every create, write, replace, unlink,
+and rollback runs relative to those descriptors with `O_NOFOLLOW`; a swapped
+ancestor cannot redirect the transaction, and an inode change after snapshot
+capture aborts instead of overwriting concurrent work. A later failure restores
+every touched file byte-for-byte. Existing file modes are preserved. New JSON
+configuration files are created with a secure `0600` base filtered by the
+current umask. Mutation requires POSIX `dir_fd` support. Native Windows Python
+fails closed before changing any file; use WSL for `inject-hook` and
+`remove-hook`. Read-only parsing and validation remain available.
+
+**Codex propagation:** command handlers for Codex's 10 documented events are
+translated into the native schema and merged into `$CODEX_HOME/hooks.json`
+(default `~/.codex/hooks.json`). The translated document never contains
+Claude's private `_source` key. Each command carries an exact, collision-resistant
+`AI_TOOLKIT_HOOK_OWNER=ai-toolkit-external-<source>-<digest>` marker; update and
+remove operations match only that owner. Existing core, plugin, and user
+handlers are preserved through the same validator and atomic writer used by the
+Codex generator.
+
+Only fields shared unambiguously by native command hooks are propagated:
+`matcher`, `type: command`, `command`, `commandWindows`, `timeout`,
+`statusMessage`, and `async`. Unsupported events, non-command handlers, and
+schema-specific extra fields are reported as skipped instead of being guessed.
+`command` must be non-empty. `timeout`, when present, is a positive integer in
+seconds; Codex defaults it to 600 seconds when omitted.
+`UserPromptSubmit` and `Stop` matchers are omitted only when empty; a non-empty
+matcher is skipped because Codex does not support it. `CODEX_HOME` must be an
+existing absolute non-symlink directory when configured.
 
 ## remove-hook
 
-Strips all hook entries from `~/.claude/settings.json` that carry a given `_source` tag. If the hook was URL-sourced, also unregisters the URL from `sources.json` and removes the cached file.
+Strips all hook entries from `~/.claude/settings.json` that carry a given
+`_source` tag and removes only the matching native command owner from the active
+Codex `hooks.json`. If the hook was URL-sourced, it also unregisters the URL
+from `sources.json` and removes the cached file.
 
 ```bash
 npx @softspark/ai-toolkit remove-hook my-tool-hooks
@@ -160,7 +195,15 @@ npx @softspark/ai-toolkit inject-mcp ./conflict.json --force
 
 **URL support:** When an HTTPS URL is provided, the JSON is fetched, validated, cached in `~/.softspark/ai-toolkit/mcp-templates/external/<name>.json`, and registered in `sources.json`. On every `ai-toolkit update`, URL-sourced templates are re-fetched and re-injected automatically. If the fetch fails during update, the cached version is used.
 
-**Editor propagation:** Every editor with a `global_path` in `EDITOR_SPECS` is updated -- Claude (`~/.claude.json`), Cursor (`~/.cursor/mcp.json`), GitHub Copilot (`~/.copilot/mcp-config.json`), Gemini CLI (`~/.gemini/settings.json`), Windsurf (`~/.codeium/windsurf/mcp_config.json`), Cline (`~/.cline/data/settings/cline_mcp_settings.json`), Augment (`~/.augment/settings.json`), Codex CLI (`~/.codex/config.toml`). Per-editor failures are non-fatal -- the command reports a warning and continues.
+**Editor propagation:** Every editor with a `global_path` in `EDITOR_SPECS` is
+updated: Claude (`~/.claude.json`), Cursor (`~/.cursor/mcp.json`), GitHub
+Copilot (`$COPILOT_HOME/mcp-config.json`, default
+`~/.copilot/mcp-config.json`), Gemini CLI (`~/.gemini/settings.json`), Windsurf
+(`~/.codeium/windsurf/mcp_config.json`), Cline
+(`~/.cline/data/settings/cline_mcp_settings.json`), Augment
+(`~/.augment/settings.json`), and Codex CLI (`$CODEX_HOME/config.toml`, default
+`~/.codex/config.toml`). Per-editor failures are non-fatal; the command reports
+a warning and continues.
 
 **Idempotency:** Re-running with the same source overwrites entries for that source cleanly -- no duplicates accumulate.