@softspark/ai-toolkit 4.5.1 → 4.7.0

package/scripts/ecosystem_tools.json

@@ -1,21 +1,23 @@
 {
   "schema_version": 1,
   "description": "Authoritative registry of tools ai-toolkit integrates with. Consumed by scripts/ecosystem_doctor.py to detect upstream doc/version drift.",
-  "last_updated": "2026-05-30",
+  "last_updated": "2026-06-10",
   "tools": [
     {
       "id": "claude-code",
       "display_name": "Claude Code",
       "kind": "primary",
       "urls": {
-        "docs": "https://platform.claude.com/docs/en/claude-code",
+        "docs": "https://code.claude.com/docs",
         "release_notes": "https://github.com/anthropics/claude-code/releases",
-        "changelog": null
+        "changelog": "https://code.claude.com/docs/en/changelog"
       },
       "config_paths": [
         "~/.claude/settings.json",
+        ".claude/settings.json",
         ".claude/settings.local.json",
         "CLAUDE.md",
+        ".claude/rules/*.md",
         ".claude/agents/*.md",
         ".claude/skills/*/SKILL.md",
         "~/.claude/themes/*.json"
@@ -60,7 +62,8 @@
         "hook handler: command",
         "hook handler: prompt",
         "hook handler: agent",
-        "hook handler: mcp_tool"
+        "hook handler: mcp_tool",
+        "hook handler: http"
       ],
       "version_probe": {
         "kind": "command",
@@ -79,7 +82,6 @@
       "config_paths": [
         ".cursorrules",
         ".cursor/rules/*.mdc",
-        ".cursor/rules/*.md",
         "AGENTS.md",
         ".cursor/mcp.json",
         "~/.cursor/mcp.json",
@@ -92,11 +94,18 @@
         ".codex/skills/*/SKILL.md",
         "~/.codex/skills/*/SKILL.md",
         ".cursor/agents/*.md",
+        "~/.cursor/agents/*.md",
+        ".claude/agents/*.md",
+        "~/.claude/agents/*.md",
+        ".codex/agents/*.md",
+        "~/.codex/agents/*.md",
         ".cursor/hooks.json"
       ],
       "our_generators": [
         "scripts/generate_cursor_rules.py",
         "scripts/generate_cursor_mdc.py",
+        "scripts/generate_cursor_hooks.py",
+        "scripts/generate_cursor_agents.py",
         "scripts/generate_cursor_skills.py"
       ],
       "capability_markers": [
@@ -118,11 +127,17 @@
       "display_name": "Windsurf",
       "kind": "editor",
       "urls": {
-        "docs": "https://docs.windsurf.com",
-        "release_notes": "https://windsurf.com/changelog",
-        "changelog": "https://windsurf.com/changelog"
+        "docs": "https://docs.devin.ai/desktop",
+        "release_notes": "https://docs.devin.ai/desktop/changelog",
+        "changelog": "https://docs.devin.ai/desktop/changelog"
       },
       "config_paths": [
+        ".devin/rules/*.md",
+        ".devin/workflows/*.md",
+        ".devin/skills/*/SKILL.md",
+        ".devin/config.json",
+        ".devin/config.local.json",
+        "~/.config/devin/config.json",
         ".windsurfrules",
         ".windsurf/rules/*.md",
         ".windsurf/workflows/*.md",
@@ -136,8 +151,10 @@
       "our_generators": [
         "scripts/generate_windsurf.py",
         "scripts/generate_windsurf_rules.py",
-        "scripts/generate_windsurf_skills.py"
+        "scripts/generate_windsurf_skills.py",
+        "scripts/generate_windsurf_hooks.py"
       ],
+      "status_note": "Windsurf rebranded to Devin Desktop on 2026-06-02. .devin/ is the primary read+write workspace tree; .windsurfrules, .windsurf/* and ~/.codeium/windsurf/* are legacy read-only fallbacks. Our generators dual-emit .devin/* + .windsurf/*. Cascade agent is available only through 2026-07-01 (Devin Local is the default agent since 2026-06-02); the .windsurf/hooks.json surface emitted by generate_windsurf_hooks.py is Cascade-scoped and dies with Cascade — migrate to the Devin CLI lifecycle-hooks surface (docs.devin.ai/cli/extensibility/hooks/*) before that date. Devin CLI ('Devin for Terminal', launched 2026-04-29) shares the Devin Local harness, reads AGENTS.md and the same SKILL.md standard; not yet tracked as a separate registry entry.",
       "capability_markers": [
         "Cascade",
         "windsurfrules",
@@ -202,6 +219,7 @@
         ".gemini/skills/*/SKILL.md",
         ".agents/skills/*/SKILL.md",
         "~/.gemini/skills/*/SKILL.md",
+        "~/.agents/skills/*/SKILL.md",
         ".gemini/extensions/gemini-extension.json"
       ],
       "our_generators": [
@@ -214,17 +232,21 @@
         "settings.json",
         "BeforeTool",
         "AfterTool",
+        "BeforeToolSelection",
         "BeforeAgent",
         "AfterAgent",
         "BeforeModel",
+        "AfterModel",
+        "Notification",
+        "PreCompress",
         "SessionStart",
         "SessionEnd",
-        "Stop",
         "SKILL.md",
         "activate_skill",
         "custom commands",
         "gemini-extension.json"
       ],
+      "status_note": "Gemini CLI drops free + paid (AI Pro/Ultra) tiers on 2026-06-18 in favor of the new Antigravity CLI (we ship generate_antigravity.py); enterprise Gemini Code Assist Standard/Enterprise keeps full Gemini CLI support. The .gemini/* generators remain valid for the enterprise audience.",
       "version_probe": {
         "kind": "command",
         "command": "gemini --version"
@@ -242,14 +264,21 @@
       "config_paths": [
         ".clinerules/*.md",
         ".clinerules/workflows/*.md",
+        ".clinerules/skills/*/SKILL.md",
+        ".clinerules/hooks/",
         ".cline/rules/*.md",
         ".cline/hooks/",
+        ".cline/plugins/",
         ".cline/skills/*/SKILL.md",
-        "~/.cline/rules/*.md",
+        "~/.cline/rules/",
         "~/.cline/hooks/",
+        "~/.cline/plugins/",
         "~/.cline/skills/*/SKILL.md",
+        "~/Documents/Cline/Rules/Hooks/",
         "~/.cline/data/settings/cline_mcp_settings.json",
-        ".claude/skills/*/SKILL.md"
+        ".claude/skills/*/SKILL.md",
+        "AGENTS.md",
+        "~/.agents/AGENTS.md"
       ],
       "our_generators": [
         "scripts/generate_cline.py",
@@ -266,7 +295,9 @@
         "hooks",
         "skills",
         "subagents",
-        "conditional rules"
+        "conditional rules",
+        "AGENTS.md",
+        "plugins"
       ],
       "version_probe": null
     },
@@ -275,10 +306,12 @@
       "display_name": "Roo Code",
       "kind": "editor",
       "urls": {
-        "docs": "https://docs.roocode.com",
+        "docs": "https://roocodeinc.github.io/Roo-Code",
         "release_notes": "https://github.com/RooCodeInc/Roo-Code/releases",
         "changelog": null
       },
+      "status": "archived",
+      "status_note": "Upstream RooCodeInc/Roo-Code repo archived/read-only as of 2026-05-15, frozen at v3.54.0; docs.roocode.com 301-redirects to roocodeinc.github.io/Roo-Code. A community fork reportedly continues maintenance. JSON .roomodes is NOT deprecated; both generators remain valid.",
       "config_paths": [
         ".roomodes",
         ".roo/rules/*.md",
@@ -354,11 +387,16 @@
       },
       "config_paths": [
         ".augment/rules/*.md",
-        ".augment/guidelines.md",
+        ".augment-guidelines",
         ".augment/agents/*.md",
         ".augment/commands/*.md",
         ".augment/skills/*/SKILL.md",
+        ".augment/settings.json",
+        ".augment/settings.local.json",
+        ".claude/skills/*/SKILL.md",
+        ".agents/skills/*/SKILL.md",
         "~/.augment/rules/*.md",
+        "~/.augment/user-guidelines.md",
         "~/.augment/agents/*.md",
         "~/.augment/commands/*.md",
         "~/.augment/settings.json",
@@ -366,7 +404,11 @@
       ],
       "our_generators": [
         "scripts/generate_augment.py",
-        "scripts/generate_augment_rules.py"
+        "scripts/generate_augment_rules.py",
+        "scripts/generate_augment_agents.py",
+        "scripts/generate_augment_commands.py",
+        "scripts/generate_augment_skills.py",
+        "scripts/generate_augment_hooks.py"
       ],
       "capability_markers": [
         ".augment",
@@ -385,6 +427,7 @@
         "SessionStart",
         "SessionEnd",
         "Stop",
+        "Notification",
         "ACP Mode"
       ],
       "version_probe": null
@@ -399,6 +442,11 @@
         "changelog": null
       },
       "config_paths": [
+        ".agents/rules/*.md",
+        ".agents/workflows/*.md",
+        ".agents/skills/*/SKILL.md",
+        ".agents/hooks.json",
+        ".agents/mcp_config.json",
         ".agent/rules/*.md",
         ".agent/workflows/*.md",
         ".agent/skills/*/SKILL.md",
@@ -408,6 +456,7 @@
       "our_generators": [
         "scripts/generate_antigravity.py"
       ],
+      "status_note": "Antigravity CLI (GA 2026-05-19) reads workspace skills from .agents/skills/ (plural); the IDE still uses .agent/skills/ (singular) — our generator dual-emits the skill pointer to both. CLI hooks live in .agents/hooks.json with Claude-style event names (PreToolUse, not BeforeTool) and a JSON stdin/stdout decision contract. CLI MCP config is .agents/mcp_config.json with a required serverUrl field (url/httpUrl rejected silently); the GLOBAL MCP config path is reported inconsistently across sources (~/.gemini/antigravity-cli/ vs ~/.gemini/config/), so only the workspace path is registered until verified via agy inspect. Official docs are fully JS-rendered — the doctor is blind to them; verify changes manually each sync.",
       "capability_markers": [
         "Antigravity",
         "agent manager",
@@ -416,6 +465,7 @@
         "workflows",
         "rules",
         "skills",
+        "hooks",
         "AGENTS.md",
         "GEMINI.md",
         "agent permissions"
@@ -427,20 +477,19 @@
       "display_name": "Codex CLI",
       "kind": "editor",
       "urls": {
-        "docs": "https://github.com/openai/codex",
+        "docs": "https://developers.openai.com/codex",
         "release_notes": "https://github.com/openai/codex/releases",
         "changelog": null
       },
       "config_paths": [
         "AGENTS.md",
-        ".agents/rules/*.md",
         ".agents/skills/*/SKILL.md",
         ".codex/hooks.json",
+        ".codex/config.toml",
         "~/.codex/config.toml"
       ],
       "our_generators": [
         "scripts/generate_codex.py",
-        "scripts/generate_codex_rules.py",
         "scripts/generate_codex_hooks.py",
         "scripts/generate_codex_skills.py"
       ],
@@ -486,8 +535,13 @@
         ".opencode/plugins/*",
         ".opencode/skills/*/SKILL.md",
         "AGENTS.md",
-        ".claude/skills/*/SKILL.md"
+        ".claude/skills/*/SKILL.md",
+        ".agents/skills/*/SKILL.md",
+        "~/.config/opencode/skills/*/SKILL.md",
+        "~/.claude/skills/*/SKILL.md",
+        "~/.agents/skills/*/SKILL.md"
       ],
+      "status_note": "opencode v1.16.0 (2026-06-05) ships an experimental v2 skill registry with flat-file skills and a 'slash' frontmatter key; undocumented as of 2026-06-09. Watch item: re-check next sync whether the v2 format reaches the documented SKILL.md spec before touching generate_opencode*.py. Note sst/opencode redirects to anomalyco/opencode.",
       "our_generators": [
         "scripts/generate_opencode.py",
         "scripts/generate_opencode_agents.py",

package/scripts/generate_antigravity.py

@@ -1,25 +1,29 @@
 #!/usr/bin/env python3
-"""Generate Antigravity IDE ``.agent/rules/``, ``.agent/workflows/``, and
+"""Generate Antigravity IDE ``.agents/rules/``, ``.agents/workflows/``, and
 skill pointer files.
 
+Antigravity 2.0 reads rules/workflows from the plural ``.agents/`` directory by
+default; singular ``.agent/`` is still accepted as a backward-compatible
+fallback (Antigravity checks plural first, then singular). We emit plural.
 Antigravity reads rules from:
   * ``GEMINI.md`` (highest priority) — generated by ``generate_gemini.py``
   * ``AGENTS.md`` (cross-tool) — generated by ``generate_agents_md.py``
-  * ``.agent/rules/*.md`` — per-category rule files (this generator)
-  * ``.agent/workflows/*.md`` — workflow templates (this generator)
-
-Antigravity also supports the Agent Skills standard via ``.agent/skills/
-<skill-name>/SKILL.md`` (the changelog entry "Agent Skills now available in
-Antigravity" confirms this surface). We do not duplicate our full skill
-catalogue into ``.agent/skills/``; instead we emit a single pointer skill
-that teaches Antigravity to look up the real catalogue in
-``~/.softspark/ai-toolkit/app/skills/`` (global install) or
+  * ``.agents/rules/*.md`` — per-category rule files (this generator)
+  * ``.agents/workflows/*.md`` — workflow templates (this generator)
+
+Antigravity also supports the Agent Skills standard. The IDE reads
+``.agent/skills/<skill-name>/SKILL.md`` (singular), while the Antigravity CLI
+(GA 2026-05-19) reads ``.agents/skills/`` (plural) — so the skill pointer is
+dual-emitted to both. We do not duplicate our full skill catalogue; instead we
+emit a single pointer skill that teaches Antigravity to look up the real
+catalogue in ``~/.softspark/ai-toolkit/app/skills/`` (global install) or
 ``.claude/skills/`` (local install).
 
 Usage:
   python3 scripts/generate_antigravity.py [target-dir]
 
-Writes files directly to target-dir/.agent/{rules,workflows,skills}/.
+Writes rules/workflows to target-dir/.agents/{rules,workflows}/ and the skill
+pointer to target-dir/.agent/skills/ (IDE) + target-dir/.agents/skills/ (CLI).
 """
 from __future__ import annotations
 
@@ -78,11 +82,17 @@ def _pointer_skill_md() -> str:
 
 
 def _write_skill_pointer(target_dir: Path) -> None:
-    """Write the pointer SKILL.md under .agent/skills/<name>/."""
-    skill_dir = target_dir / ".agent" / "skills" / POINTER_SKILL_NAME
-    skill_dir.mkdir(parents=True, exist_ok=True)
-    (skill_dir / "SKILL.md").write_text(_pointer_skill_md(), encoding="utf-8")
-    print(f"  Generated: .agent/skills/{POINTER_SKILL_NAME}/SKILL.md")
+    """Write the pointer SKILL.md for both the IDE and the CLI surface.
+
+    The IDE reads ``.agent/skills/`` (singular); the Antigravity CLI reads
+    ``.agents/skills/`` (plural).
+    """
+    content = _pointer_skill_md()
+    for tree in (".agent", ".agents"):
+        skill_dir = target_dir / tree / "skills" / POINTER_SKILL_NAME
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+        print(f"  Generated: {tree}/skills/{POINTER_SKILL_NAME}/SKILL.md")
 
 
 # ---------------------------------------------------------------------------
@@ -93,16 +103,17 @@ def generate(target_dir: Path, *,
              language_modules: list[str] | None = None,
              rules_dir: Path | None = None,
              emit_skill_pointer: bool = True) -> None:
-    """Write ``.agent/rules/``, ``.agent/workflows/``, and ``.agent/skills/``.
+    """Write ``.agents/{rules,workflows}/`` and the dual skill pointers.
 
-    ``emit_skill_pointer`` controls whether the pointer SKILL.md is written.
-    Set to ``False`` if you manage ``.agent/skills/`` yourself.
+    ``emit_skill_pointer`` controls whether the pointer SKILL.md is written
+    to ``.agent/skills/`` (IDE) and ``.agents/skills/`` (CLI). Set to
+    ``False`` if you manage those directories yourself.
     """
     rules = dict(STANDARD_RULES)
     rules.update(build_language_rules(language_modules))
     rules.update(build_registered_rules(rules_dir))
-    write_rules(target_dir, rules, ".agent/rules")
-    write_rules(target_dir, STANDARD_WORKFLOWS, ".agent/workflows")
+    write_rules(target_dir, rules, ".agents/rules")
+    write_rules(target_dir, STANDARD_WORKFLOWS, ".agents/workflows")
     if emit_skill_pointer:
         _write_skill_pointer(target_dir)
 

package/scripts/generate_augment_agents.py

@@ -2,12 +2,12 @@
 """Generate ``.augment/agents/ai-toolkit-*.md`` files for Augment Code.
 
 Each ai-toolkit agent in ``app/agents/`` is mirrored as an Augment native
-subagent. Augment's subagent frontmatter (per docs.augmentcode.com) supports:
+subagent. Augment's subagent frontmatter (per docs.augmentcode.com/cli/subagents)
+documents: name, description, color, model, tools, disabled_tools.
 
     ---
     name: <slug>
     description: "<single-line description>"
-    model: inherit            # or explicit model id
     color: <color-name>       # optional UI hint
     tools: [Read, Write, ...]
     disabled_tools: []
@@ -17,9 +17,10 @@ subagent. Augment's subagent frontmatter (per docs.augmentcode.com) supports:
 
 Design choices:
 
-* ``model: inherit`` is used unconditionally. ai-toolkit stores short aliases
-  (``opus``/``sonnet``/``haiku``) that do not map to Augment's full model ids
-  without assuming a provider, so we defer to the user's default model.
+* ``model`` is omitted. The docs state "If not specified, the CLI default model
+  is used" and do not document ``inherit`` as a value. ai-toolkit stores short
+  aliases (``opus``/``sonnet``/``haiku``) that do not map to Augment's full
+  model ids, so we omit the field to defer to the CLI default.
 * ``tools`` are passed through verbatim from the source file, normalized into
   YAML flow-list form (``[Read, Write, ...]``) so Augment parses them as a
   native list.
@@ -79,11 +80,9 @@ def _render_augment_agent(agent_file: Path) -> str:
     lines: list[str] = ["---"]
     lines.append(f"name: {name}")
     lines.append(f'description: "{safe_desc}"')
-    # Augment recommends ``model: inherit`` for plugins that want to follow
-    # the user's active model selection. ai-toolkit agents are authored with
-    # short aliases that do not map to Augment's provider-qualified ids, so
-    # we deliberately emit ``inherit`` instead of translating.
-    lines.append("model: inherit")
+    # `model` is omitted: Augment's docs say the CLI default model is used when
+    # absent, and `inherit` is not a documented value. Our short aliases do not
+    # map to Augment's provider-qualified ids, so we defer to the CLI default.
     if color:
         lines.append(f"color: {color}")
     if tools:

package/scripts/generate_augment_commands.py

@@ -5,13 +5,13 @@ User-invocable skills become Augment custom slash commands. Knowledge skills
 (``user-invocable: false``) are excluded — they load automatically via
 AGENTS.md/rules context instead of ``/`` invocation.
 
-Per docs.augmentcode.com, Augment custom commands are plain markdown files
-with an optional YAML frontmatter header. The body of the file IS the prompt
-(no ``template:`` field, no TOML). Supported frontmatter fields:
+Per docs.augmentcode.com/cli/custom-commands, Augment custom commands are plain
+markdown files with an optional YAML frontmatter header. The body of the file IS
+the prompt (no ``template:`` field, no TOML). The documented frontmatter fields
+are ``description``, ``argument-hint``, and ``model`` (no ``agent`` field):
 
     ---
     description: "<short one-liner shown in the palette>"
-    agent: <optional agent slug to route into>
     argument-hint: "<optional hint shown after the command name>"
     ---
 
@@ -44,20 +44,9 @@ def _skill_body(skill_file: Path) -> str:
     return parts[2].lstrip("\n") if len(parts) >= 3 else text
 
 
-def _map_agent_name(value: str) -> str:
-    """Map ai-toolkit agent names to our prefixed Augment subagent slugs."""
-    value = value.strip()
-    if not value:
-        return value
-    if value.startswith(COMMAND_PREFIX):
-        return value
-    return f"{COMMAND_PREFIX}{value}"
-
-
 def _render_augment_command(skill_file: Path) -> str:
     """Render a single Augment command .md file from a user-invocable skill."""
     description = frontmatter_field(skill_file, "description")
-    agent_field = frontmatter_field(skill_file, "agent")
     argument_hint = frontmatter_field(skill_file, "argument-hint")
     body = _skill_body(skill_file).rstrip()
 
@@ -65,8 +54,6 @@ def _render_augment_command(skill_file: Path) -> str:
     if description:
         safe_desc = description.replace('"', "'")
         lines.append(f'description: "{safe_desc}"')
-    if agent_field:
-        lines.append(f"agent: {_map_agent_name(agent_field)}")
     if argument_hint:
         safe_hint = argument_hint.replace('"', "'")
         lines.append(f'argument-hint: "{safe_hint}"')

package/scripts/generate_augment_hooks.py

@@ -1,11 +1,13 @@
 #!/usr/bin/env python3
 """Generate Augment settings.json hooks block.
 
-Augment stores hooks in `~/.augment/settings.json` (user scope) — there is no
-per-workspace hooks file. `/etc/augment/settings.json` exists for system-wide
-policy and we never write there. The generator accepts an optional target
-directory; when omitted it defaults to the user's `$HOME` and writes
-`~/.augment/settings.json`.
+Augment reads hooks from several settings.json layers (per
+docs.augmentcode.com/cli/hooks): `<workspace>/.augment/settings.local.json`,
+`<workspace>/.augment/settings.json`, `~/.augment/settings.json` (user scope),
+and `/etc/augment/settings.json` (system policy). This generator writes the
+user-scope file: it accepts an optional target directory and defaults to the
+user's `$HOME`, writing `~/.augment/settings.json`. Project-local hook emission
+for `--local` installs is a possible future extension.
 
 Augment hook events (per docs.augmentcode.com/cli/hooks.md):
     PreToolUse, PostToolUse, SessionStart, SessionEnd, Stop

package/scripts/generate_codex.py

@@ -13,6 +13,12 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from codex_skill_adapter import codex_skill_description
+from dir_rules_shared import (
+    rule_code_style,
+    rule_output_mode,
+    rule_security,
+    rule_testing,
+)
 from emission import (
     agents_dir,
     skills_dir,
@@ -54,6 +60,23 @@ def _emit_skills() -> str:
     return "\n".join(lines)
 
 
+def _emit_coding_rules() -> str:
+    """Inline the universal coding-rule bodies so Codex receives them.
+
+    Codex reads project instructions only from AGENTS.md (and AGENTS.override.md);
+    it does not read a ``.agents/rules/`` directory. Workflow + quality standards
+    are already emitted above, so this adds code-style, testing, security, and
+    output-mode under a single ``## Coding Rules`` section (H1 demoted to H3).
+    """
+    sections: list[str] = []
+    for rule_fn in (rule_code_style, rule_testing, rule_security, rule_output_mode):
+        body = rule_fn().rstrip()
+        if body.startswith("# "):
+            body = "### " + body[2:]
+        sections.append(body)
+    return "## Coding Rules\n\n" + "\n\n".join(sections)
+
+
 def main() -> None:
     print_toolkit_start()
 
@@ -86,6 +109,11 @@ def main() -> None:
     print()
     print(generate_workflow_guidelines())
 
+    # Universal coding rules — Codex reads instructions only from AGENTS.md,
+    # so inline them here (previously emitted to the unread .agents/rules/).
+    print()
+    print(_emit_coding_rules())
+
     print_toolkit_end()
 
     # Registered custom rules from ~/.softspark/ai-toolkit/rules/

package/scripts/generate_codex_hooks.py

@@ -8,7 +8,8 @@ Codex exposes 10 lifecycle events (PascalCase in config.toml / hooks.json):
 ``PreToolUse``, ``PostToolUse``, ``PermissionRequest``, ``PreCompact``,
 ``PostCompact``, ``SessionStart``, ``UserPromptSubmit``, ``SubagentStart``,
 ``SubagentStop``, ``Stop``. PreToolUse/PostToolUse only support the ``Bash``
-matcher. We currently wire the subset defined in ``CODEX_HOOKS`` below.
+matcher. We wire all 10 events in ``CODEX_HOOKS`` below to the shared toolkit
+hook scripts, mirroring the Claude Code mapping in ``app/hooks.json``.
 
 Handler types in Codex: ``command`` (what we emit), ``prompt``, and ``agent``.
 Reference: codex-rs/config/src/hook_config.rs.
@@ -39,6 +40,12 @@ CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
         ("Bash", "commit-quality.sh"),
         ("Bash", "revert-guard.sh"),
     ],
+    "PostToolUse": [
+        # Fires after Bash/apply_patch/MCP tool output. Capture governance
+        # signals and detect repetition loops (mirrors app/hooks.json).
+        ("Bash", "governance-capture.sh"),
+        ("Bash", "loop-guard.sh"),
+    ],
     "PermissionRequest": [
         # Fires when Codex asks the user to approve a tool call. Our guard
         # reviews the tool input and can veto destructive patterns before the
@@ -49,6 +56,21 @@ CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
         ("", "user-prompt-submit.sh"),
         ("", "track-usage.sh"),
     ],
+    "SubagentStart": [
+        ("", "subagent-start.sh"),
+    ],
+    "SubagentStop": [
+        ("", "subagent-stop.sh"),
+    ],
+    "PreCompact": [
+        # Capture session memory before Codex compacts the conversation.
+        ("", "pre-compact.sh"),
+        ("", "pre-compact-save.sh"),
+    ],
+    "PostCompact": [
+        # Re-establish working context after compaction.
+        ("", "session-context.sh"),
+    ],
     "Stop": [
         ("", "quality-check.sh"),
         ("", "save-session.sh"),

package/scripts/generate_cursor_agents.py

@@ -2,25 +2,24 @@
 """Generate ``.cursor/agents/ai-toolkit-*.md`` files for Cursor IDE.
 
 Each ai-toolkit agent is mirrored as a Cursor custom agent. Per Cursor's
-docs (docs.cursor.com -> custom agents), agent files use YAML frontmatter:
+subagent docs (cursor.com/docs/subagents) the frontmatter schema documents
+only these fields:
 
     ---
-    name: <slug>
-    description: "<one-line summary shown in the picker>"
-    model: <model-id>     # optional, inherits user default if absent
-    color: <color-name>   # optional UI hint
-    tools: [Read, Write, ...]  # list of allowed tool names
+    name: <slug>              # lowercase letters and hyphens
+    description: "<one-line summary shown in the Task picker>"
+    model: inherit            # `inherit` (default) or a specific model id
     ---
 
     <system prompt body>
 
 Design choices:
 
-* ``model`` is omitted. Our agents store short aliases (``opus``, ``sonnet``,
-  ``haiku``) that do not map to Cursor's provider-qualified model ids.
-  Omitting the field makes Cursor fall back to the user's default model,
-  which is the same behaviour our opencode generator uses.
-* ``tools`` is emitted as a YAML flow-list parsed verbatim from the source.
+* ``model: inherit`` is emitted — the documented default value. Our agents
+  store short aliases (``opus``/``sonnet``/``haiku``) that do not map to
+  Cursor's provider-qualified model ids, so we use the literal ``inherit``.
+* ``tools`` and ``color`` are NOT emitted — the current Cursor schema documents
+  only name/description/model/readonly/is_background (tools/color were dropped).
 * Files are prefixed ``ai-toolkit-`` so install/uninstall can identify ours.
 * Regeneration removes stale ``ai-toolkit-*.md`` files whose source agent
   no longer exists, but leaves user-authored agents untouched.
@@ -53,34 +52,19 @@ def _agent_body(agent_file: Path) -> str:
     return parts[2].lstrip("\n")
 
 
-def _parse_tools(tools_raw: str) -> list[str]:
-    """Parse the comma-separated ``tools:`` frontmatter value into a list."""
-    if not tools_raw:
-        return []
-    return [t.strip() for t in tools_raw.split(",") if t.strip()]
-
-
 def _render_cursor_agent(agent_file: Path) -> str:
     """Render a single Cursor custom agent .md file."""
     name = frontmatter_field(agent_file, "name")
     description = frontmatter_field(agent_file, "description")
-    color = frontmatter_field(agent_file, "color")
-    tools_raw = frontmatter_field(agent_file, "tools")
-    tools = _parse_tools(tools_raw)
 
     safe_desc = description.replace('"', "'")
 
     lines: list[str] = ["---"]
     lines.append(f"name: {name}")
     lines.append(f'description: "{safe_desc}"')
-    # model intentionally omitted — Cursor falls back to the user default.
-    if color:
-        lines.append(f"color: {color}")
-    if tools:
-        tools_flow = ", ".join(tools)
-        lines.append(f"tools: [{tools_flow}]")
-    else:
-        lines.append("tools: []")
+    # `inherit` is the documented default model value; our short aliases do not
+    # map to Cursor's provider-qualified model ids.
+    lines.append("model: inherit")
     lines.append("---")
     lines.append("")
     body = _agent_body(agent_file).rstrip()