@softspark/ai-toolkit 4.15.0 → 4.16.0

package/kb/reference/copilot-compatibility.md

@@ -0,0 +1,173 @@
+---
+title: "AI Toolkit - GitHub Copilot Compatibility"
+category: reference
+service: ai-toolkit
+tags: [copilot, compatibility, install, skills, prompts, instructions, agents, hooks]
+version: "1.0.0"
+created: "2026-07-15"
+last_updated: "2026-07-15"
+description: "Reference for how ai-toolkit integrates with GitHub Copilot — the five .github/ surfaces, their runtime context-loading semantics, and why the same skill is emitted as both a prompt file and a skill directory."
+---
+
+# AI Toolkit - GitHub Copilot Compatibility
+
+## Summary
+
+`ai-toolkit install --local --editors copilot` emits native GitHub Copilot
+customization files under `.github/`. Copilot is the toolkit's widest-surface
+editor target: a single skill can materialize into up to three distinct Copilot
+mechanisms (path-scoped instruction, invokable prompt, on-demand skill). All
+emitted paths are generated build artifacts and are `.gitignore`d — they are not
+committed source. This document explains what each surface is, **when each one
+enters the model context**, and why the same skill body appears in more than one
+file. Install/profile behavior is owned by `kb/reference/global-install-model.md`;
+config-path and capability tracking by `kb/reference/supported-tools-registry.md`.
+
+## Generated Surfaces
+
+| Surface | Path | Copilot mechanism |
+|---------|------|-------------------|
+| Repo-wide instructions | `.github/copilot-instructions.md` | Always-on repository custom instructions |
+| Path-scoped instructions | `.github/instructions/ai-toolkit-*.instructions.md` | Custom instructions gated by an `applyTo` glob |
+| Prompt files | `.github/prompts/ai-toolkit-*.prompt.md` | Reusable prompts, invoked as `/name` |
+| Native agents | `.github/agents/ai-toolkit-*.agent.md` | Custom agents in the agent picker |
+| Portable skills | `.github/skills/ai-toolkit-*/SKILL.md` (+ `reference/`, `scripts/`) | Agent Skills, injected on demand |
+| Lifecycle hooks | `.github/hooks/ai-toolkit.json` + runtime | Version-1 Copilot hooks (profile ≥ `standard`) |
+| Shared rules | root `AGENTS.md` | Read by Copilot code review and CLI |
+
+## Surface Loading Semantics
+
+The five customization surfaces do **not** all cost context the same way. This
+is the practical difference that governs token usage and any perceived
+"double loading":
+
+| Surface | Enters context… | Passive cost |
+|---------|-----------------|--------------|
+| `copilot-instructions.md` | Every chat request in the repo | Always-on |
+| `*.instructions.md` with `applyTo: "**"` | Every request (glob matches all files) | Effectively always-on |
+| `*.instructions.md` with a scoped glob (e.g. `**/*.py`) | Only when a matching file is in context | Path-scoped |
+| `*.prompt.md` | **Only** when the user runs `/<name>` | None until invoked |
+| `SKILL.md` | **Only** when Copilot chooses to use the skill (progressive disclosure) | None until triggered |
+| `*.agent.md` | Only when that agent is selected in the picker | None until selected |
+
+Instructions are auto-added to requests as soon as their `applyTo` glob matches;
+skills and prompts are pull-based, never injected passively.
+
+## Prompt ↔ Skill Duplication
+
+Every user-invocable skill is emitted **both** as a `.github/prompts/*.prompt.md`
+(so it is available as a `/slash-command`) **and** as a
+`.github/skills/<name>/SKILL.md` directory (so Copilot can auto-trigger it with
+its bundled `scripts/` and `reference/` assets). The two bodies are byte-identical
+after their frontmatter and Copilot execution-notes header; the differences are:
+
+- the prompt carries only a `description`; the skill adds `name` and bundles the
+  runnable assets the prompt does not ship;
+- the prompt's execution note treats the current request as task input, the
+  skill's note resolves relative paths against its own directory.
+
+**This is intentional, not a stale leftover, and does not cause a persistent
+double-load:**
+
+- Neither surface is always-on. The prompt loads only on explicit `/invoke`; the
+  skill loads only on trigger. Neither sits in `copilot-instructions.md` or in an
+  always-matching `applyTo`, so the shared body carries **zero** passive context
+  cost.
+- The same skill is registered from a **single** root (`.github/skills`), not
+  duplicated across `.claude/skills` or `.agents/skills` in the same repo, so
+  there is no duplicate skill registration.
+- The one edge case is a single turn where the user runs `/<name>` **and** Copilot
+  autonomously pulls the matching skill in the same request. That is a one-shot
+  redundancy of identical text — wasted tokens for that turn only, with no
+  conflicting instructions and no persistent effect.
+
+Neither surface can replace the other: the prompt has no bundled scanner or
+reference material, and the skill directory is not exposed as a slash command.
+The body is duplicated so each surface is self-contained.
+
+## Compatibility Read Paths
+
+Copilot also discovers project `.claude/skills` and `.agents/skills`, and
+personal `~/.agents/skills`. ai-toolkit still materializes self-contained native
+skills under `.github/skills` (and under the active Copilot config root for
+global installs) so that bundled assets and helper scripts remain available and
+`COPILOT_HOME` sessions do not depend on fallback discovery. The toolkit does not
+write the same skill into two roots at once, so fallback discovery never produces
+a duplicate registration.
+
+## Generated, Git-Ignored Artifacts
+
+All Copilot outputs are build products, regenerated on every install/generate,
+and listed in `.gitignore`:
+
+- `.github/copilot-instructions.md`
+- `.github/instructions/`
+- `.github/prompts/`
+- `.github/agents/`
+- `.github/skills/`
+- `.github/hooks/`
+
+Deleting them locally is safe (they are untracked and ignored); the next
+`ai-toolkit install --editors copilot` or generator run recreates them. The
+generator also cleans stale managed entries and byte-exact historical ai-toolkit
+files while preserving user-authored files.
+
+## Install & Profiles
+
+Authoritative behavior lives in `kb/reference/global-install-model.md`. In brief:
+
+- **All profiles (including `minimal`)** emit root `AGENTS.md`,
+  `.github/copilot-instructions.md`, native `.github/agents`, and portable
+  self-contained `.github/skills`.
+- **`standard`, `strict`, `full`** additionally emit scoped `.github/instructions`,
+  `.github/prompts`, and native version-1 `.github/hooks`.
+- **`minimal`** omits instructions, prompts, and hooks.
+
+Moving an existing project down to `minimal` removes only marked or byte-exact
+historical ai-toolkit instructions/prompts/hooks; unmanaged project files stay.
+
+## Auto-Detection
+
+The installer treats Copilot as configured when any of these markers exist:
+`.github/copilot-instructions.md`, `.github/instructions`, `.github/prompts`,
+`.github/agents`, `.github/skills`, `.github/hooks`, `.github/mcp.json`.
+`ai-toolkit update` then picks up Copilot automatically.
+
+## Generators & CLI
+
+Copilot has no dedicated `ai-toolkit copilot-*` subcommand; it is produced by
+`ai-toolkit install --editors copilot` (add `--local` for project scope) or by
+running the generators directly:
+
+- `scripts/generate_copilot.py` — instructions, prompts, native agents, and
+  portable skill directories (`> .github/copilot-instructions.md` with no target
+  argument; multi-surface emission with a target directory).
+- `scripts/generate_copilot_hooks.py` — version-1 hook config plus a
+  self-contained repository/config-root runtime.
+
+## Behavioral Limits
+
+- Prompt files are available only in VS Code, Visual Studio, and JetBrains IDEs;
+  GitHub.com and the CLI use instructions, skills, agents, and `AGENTS.md`.
+- Custom agents emit native `.agent.md` with `name` and `description`; `tools` is
+  omitted rather than guessing editor-specific aliases.
+- Prompt and skill bodies strip Claude-only interpolation (`$ARGUMENTS`,
+  `CLAUDE_SKILL_DIR`) and delegation APIs; hooks use the GitHub version-1 schema
+  with camelCase event names.
+
+## Verification
+
+- `scripts/generate_copilot.py` / `generate_copilot_hooks.py` contract tests
+  (`tests/test_copilot.bats`, `tests/test_copilot_hooks.bats`).
+- Release layout check in `kb/procedures/release-verification-sop.md` asserts the
+  `.github/{agents,skills,instructions,prompts,hooks}` surfaces.
+- `validate.py --strict` + `audit_skills.py --ci` in CI.
+
+## Related
+
+- `kb/reference/global-install-model.md`
+- `kb/reference/supported-tools-registry.md`
+- `kb/reference/codex-cli-compatibility.md`
+- `kb/reference/opencode-compatibility.md`
+- `kb/reference/skills-catalog.md`
+- `kb/reference/agents-catalog.md`

package/kb/reference/enterprise-config-guide.md

@@ -10,7 +10,7 @@ tags:
   - multi-repo
 doc_type: reference
 created: "2026-04-11"
-last_updated: "2026-04-11"
+last_updated: "2026-07-23"
 description: "Comprehensive guide for setting up and using ai-toolkit configuration inheritance. Covers base config creation, project setup, enforcement rules, CI integration, and troubleshooting."
 ---
 
@@ -77,7 +77,9 @@ ai-toolkit config check       # CI enforcement check
 |-------|------|-------------|
 | `extends` | string | Base config source (npm, git URL, local path) |
 | `profile` | enum | `minimal`, `standard`, `strict`, `full`, `offline-slm` |
+| `toolOutputFilter` | object | Native Bash result filtering policy: mode, profiles, savings thresholds, and recovery limits |
 | `agents` | object | `enabled`, `disabled`, `custom` arrays |
+| `plugins` | object | Resolved `enabled` and `disabled` plugin intent |
 | `rules` | object | `inject`, `remove` arrays |
 | `constitution` | object | `amendments` array (article 8+ only) |
 | `enforce` | object | Non-overridable constraints (base configs only) |
@@ -146,10 +148,34 @@ Base configs can define non-overridable constraints via the `enforce` block:
 | Constraint | Effect |
 |------------|--------|
 | `minHookProfile` | Projects cannot use a weaker hook profile |
-| `requiredPlugins` | Must be installed in all projects |
+| `requiredPlugins` | Adds each required name to the effective `plugins.enabled` intent and prevents projects from disabling it |
 | `forbidOverride` | These components cannot be overridden |
 | `requiredAgents` | Must be enabled in all projects |
 
+`requiredPlugins` is configuration enforcement, not an installer. It makes the
+effective intent explicit and causes validation to reject a conflicting
+`plugins.disabled` entry. Install the named plugin pack separately with
+`ai-toolkit plugin install <name>` or your organization deployment workflow.
+
+### Native tool-output filtering
+
+Projects can opt into the dependency-free output filter without changing the
+organization-wide default:
+
+```json
+{
+  "toolOutputFilter": {
+    "mode": "observe",
+    "profiles": ["repeat-lines", "tap-success"]
+  }
+}
+```
+
+`ai-toolkit install --local` materializes the effective policy as the managed
+`.claude/ai-toolkit-output-filter.json` file. `off` is the default, `observe`
+collects metadata without changing model-visible output, and `safe` permits
+replacement only when every invariant and exact-recovery check succeeds.
+
 ### Overrides
 
 Projects can override base settings, but must declare intent:

package/kb/reference/global-install-model.md

@@ -3,9 +3,9 @@ title: "Global Install Model"
 category: reference
 service: ai-toolkit
 tags: [install, global, claude, codex, plugins, local-setup]
-version: "3.3.0"
+version: "3.3.1"
 created: "2026-03-26"
-last_updated: "2026-07-14"
+last_updated: "2026-07-15"
 description: "Reference description of Claude Code global install, Claude app plugin export, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -165,6 +165,9 @@ Claude Code hooks do **not** live in project-local settings. They are merged onl
 self-contained `.github/skills`. Profiles `standard`, `strict`, and `full`
 add scoped `.github/instructions`, `.github/prompts`, and native version-1
 `.github/hooks`. Profile `minimal` omits those three additional directories.
+When an existing project moves from `standard`, `strict`, or `full` to
+`minimal`, the installer removes only marked or byte-exact historical ai-toolkit
+instructions, prompts, and hooks. Unmanaged project files remain in place.
 
 Global install emits personal instructions, scoped instructions, agents, and
 skills under the active Copilot config root; profile `standard` and above adds
@@ -223,4 +226,5 @@ Global-only editor MCP configs are not written during `install --local`. Use `ai
 - `kb/reference/distribution-model.md`
 - `kb/reference/merge-friendly-install-model.md`
 - `kb/reference/codex-cli-compatibility.md`
+- `kb/reference/copilot-compatibility.md`
 - `kb/reference/mcp-editor-compatibility.md`

package/kb/reference/hooks-catalog.md

@@ -3,9 +3,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.7.0"
+version: "1.8.0"
 created: "2026-03-27"
-last_updated: "2026-07-14"
+last_updated: "2026-07-23"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -13,7 +13,7 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ## Overview
 
-ai-toolkit provides 28 global hook entries across 14 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions, plus a separate `statusLine` command. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
+ai-toolkit provides 29 global hook entries across 14 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions, plus a separate `statusLine` command. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
 
 ## Supported Surface
 
@@ -29,7 +29,11 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 ```
 
 **File locations:**
+
 - Scripts: `~/.softspark/ai-toolkit/hooks/*.sh`
+- Output-filter runtime: `~/.softspark/ai-toolkit/scripts/output_filter_hook.py`, `output_filter_cli.py`, and `tool_output_filter/`
+- Global output-filter policy: `~/.softspark/ai-toolkit/hooks/output-filter-policy.json`
+- Managed project policy: `<project>/.claude/ai-toolkit-output-filter.json`
 - Config: `~/.claude/settings.json` → `hooks` key
 - Source: `ai-toolkit/app/hooks/*.sh` + `app/hooks.json`
 
@@ -50,10 +54,11 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 3. Loads session context from the per-repo session store (if exists)
 4. Loads active instincts from `.claude/instincts/*.md` (if any)
 
-By default the hook performs session-state reset, stale search-flag cleanup, and
-update notification side effects without printing informational stdout. Set
-`AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context for
-debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
+By default the hook resets edit state for a new native session, preserves it
+when the source is `compact`, performs stale search-flag cleanup, and checks
+for updates without printing informational stdout. Set
+`AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context
+for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
 
 > **Session storage:** auto-generated session artifacts (context, handoff note,
 > checkpoints, decisions) are stored **outside the project repo** under
@@ -173,6 +178,59 @@ arms the corrective Stop hook.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
+### PostToolUse (native Bash output filter): `filter-tool-output.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `PostToolUse` |
+| Matcher | `Bash` |
+| Script | `~/.softspark/ai-toolkit/hooks/filter-tool-output.sh` |
+| Fires | After a successful Claude Code Bash tool call |
+
+The hook is disabled by default and runs last among the installed
+`PostToolUse` handlers. Its modes are:
+
+| Mode | Behavior |
+|------|----------|
+| `off` | Shell fast path exits before Python starts |
+| `observe` | Evaluates eligible output and writes content-free metadata, but emits no replacement |
+| `safe` | Replaces eligible output only after invariants pass and the exact native response is stored for recovery |
+
+Only explicitly allowlisted test, lint, typecheck, and validation command
+shapes are eligible. Failed or interrupted tools, non-empty stderr, image or
+binary results, pipes, redirects, deployment, migrations, audits, security
+scanners, malformed payloads, unavailable recovery, and any uncertain case
+remain unchanged.
+
+The per-project policy `<project>/.claude/ai-toolkit-output-filter.json` is
+honored only when **both** checks pass: the project root is registered in
+`~/.softspark/ai-toolkit/projects.json`, and the sibling regular file
+`<project>/.claude/.ai-toolkit-output-filter.owner` holds the ai-toolkit owner
+marker. `ai-toolkit install --local` writes both. Registration is required
+because the owner marker is a public constant, so a cloned or untrusted
+checkout must never be able to self-enable filtering by shipping its own
+marker. An unregistered project, a missing or foreign marker, or a symlinked
+project root or `.claude` directory falls back to the installed global policy
+at `~/.softspark/ai-toolkit/hooks/output-filter-policy.json`, which ships as
+`off`.
+
+`jq` is a required system dependency (`python3 scripts/check_deps.py`
+verifies it alongside `python3`, `git`, and `node`); without it `guard-path.sh`
+blocks file tools rather than skipping path validation.
+
+Recovery data is private and session-scoped under
+`~/.softspark/ai-toolkit/sessions/<repo-key>/output-filter/`. Telemetry records
+only profile/version, byte and line counts, latency, outcome, and fallback
+reason. Recovery-backed modes require a bounded native session ID containing
+only ASCII letters, digits, underscores, or hyphens. Three consecutive
+profile, invariant, or recovery safety failures open a session circuit
+breaker. Set `AI_TOOLKIT_OUTPUT_FILTER_DISABLE=1` for an immediate bypass.
+
+The replacement adapter is Claude Code-specific. Claude Chat/Cowork exports
+exclude it, and the generated hooks for other editors do not activate it.
+The `minimal` hook profile and `AI_TOOLKIT_DISABLED_HOOKS=filter-tool-output`
+bypass it before the Python runtime starts.
+
 ### Stop (quality check) — `quality-check.sh`
 
 | Field | Value |
@@ -286,9 +344,13 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/session-end.sh` |
 | Fires | When a Claude session ends |
 
-**Action:** Writes `session-end.md` to the per-repo session store (`~/.softspark/ai-toolkit/sessions/<repo-key>/`) with a lightweight handoff note for the next session and reminds the next session to review preserved context.
+**Action:** Removes private output-filter artifacts and isolated edit state for
+the ending native session, then writes `session-end.md` to the per-repo session store
+(`~/.softspark/ai-toolkit/sessions/<repo-key>/`) with a lightweight handoff note
+for the next session.
 
-Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+The handoff note is skipped when `TOOLKIT_HOOK_PROFILE=minimal`; recovery and
+edit-state cleanup still run.
 
 ### TeammateIdle — inline
 
@@ -313,7 +375,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/guard-config.sh` |
 | Fires | Before any file write/edit operation |
 
-**Action:** Blocks (exit 2) edits to linter and formatter config files — `.eslintrc`, `.eslintrc.*`, `eslint.config.*`, `.prettierrc`, `.prettierrc.*`, `prettier.config.*`, `tsconfig.json`, `tsconfig.*.json` — unless the request contains an explicit acknowledgment phrase (e.g. "intentionally editing config"). Returns a human-readable explanation to Claude so it can ask the user for confirmation before retrying.
+**Action:** Always blocks (exit 2) edits to protected linter and formatter configuration: ESLint, Prettier, TypeScript, Stylelint, Biome, `ruff.toml`, and Ruff sections in `pyproject.toml`. Prompt text and acknowledgment phrases do not bypass the guard. A user who explicitly authorizes a protected edit must deliberately remove the guard for that operation.
 
 ### SessionStart — `mcp-health.sh`
 
@@ -335,7 +397,12 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/governance-capture.sh` |
 | Fires | After any tool use |
 
-**Action:** Non-blocking (always exits 0). Logs security-sensitive operations (Bash commands, file writes to sensitive paths, large writes) to `~/.softspark/ai-toolkit/governance.log` with ISO timestamp, session ID, tool name, and a content excerpt. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+**Action:** Non-blocking (always exits 0). Logs recognized
+dangerous-command categories and writes to sensitive filenames to
+`~/.softspark/ai-toolkit/governance.log` with an ISO timestamp, normalized
+session ID, tool name, and a bounded category or path detail. It does not
+store the full command or file content. Skipped when
+`TOOLKIT_HOOK_PROFILE=minimal`.
 
 ### PreCompact — `pre-compact-save.sh`
 
@@ -346,7 +413,11 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/pre-compact-save.sh` |
 | Fires | Before context compaction |
 
-**Action:** Saves a timestamped context snapshot to `~/.softspark/ai-toolkit/compactions/YYYY-MM-DD_HH-MM-SS.txt`. Captures session ID, working directory, git branch and status, and environment metadata. Provides an audit trail of what was in context at each compaction point. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+**Action:** Saves a timestamped context snapshot to
+`~/.softspark/ai-toolkit/compactions/YYYY-MM-DD_HH-MM-SS_<session>.txt`.
+Captures the bounded normalized session ID, working directory, and git branch.
+Provides an audit trail for compaction boundaries. Skipped when
+`TOOLKIT_HOOK_PROFILE=minimal`.
 
 ### PreToolUse (commit quality) — `commit-quality.sh`
 
@@ -426,7 +497,23 @@ First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`.
 | Script | `~/.softspark/ai-toolkit/hooks/search-tracker.sh` |
 | Fires | After any search-style tool call |
 
-**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag` (per-session, keyed by `session_id` from the hook stdin payload, falling back to `transcript_path` basename, then `default`). Pairs with `user-prompt-submit.sh` (sets the flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag is still set). Search provider detection parses actual MCP server names from `mcpServers`, `mcp_servers`, or `mcp` config blocks; hook matchers and permission allowlists do not count as providers. Codex Stop enforcement also scans the recent `$CODEX_HOME/log/codex-tui.log` window (default `~/.codex/log/codex-tui.log`) for `ToolCall: mcp__...__smart_query` and `tool.name="smart_query"`-style entries because Codex MCP tool calls may not fire the shared `PostToolUse` tracker. Together the hooks enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs and without cross-session interference when multiple Claude Code windows run in parallel.
+**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag`
+for the bounded normalized native session. Identity lookup accepts
+`session_id`, Augment `conversation_id` / `conversationId`,
+`CLAUDE_SESSION_ID`, or the transcript basename before falling back to
+`default`. It pairs with `user-prompt-submit.sh` (sets the flag on long
+technical prompts only when a search provider is detected or strict mode is
+enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag
+is still set). Search provider detection parses actual MCP server names from
+`mcpServers`, `mcp_servers`, or `mcp` config blocks; hook matchers and
+permission allowlists do not count as providers. Codex Stop enforcement also
+scans the recent `$CODEX_HOME/log/codex-tui.log` window (default
+`~/.codex/log/codex-tui.log`) for `ToolCall:
+mcp__...__smart_query` and `tool.name="smart_query"`-style entries because
+Codex MCP tool calls may not fire the shared `PostToolUse` tracker. Together
+the hooks enforce the global CLAUDE.md GOLDEN RULE without breaking
+offline/no-RAG installs and without cross-session interference when multiple
+runtime windows run in parallel.
 
 Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -473,7 +560,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 | Component | Purpose |
 |-----------|---------|
-| `scripts/session_state.py` | Append-only edit log keyed by session_id. Cleared on SessionStart. Read by revert-guard, test-cohesion, quality-gate. |
+| `scripts/session_state.py` | Isolated edit state keyed by a hash of the normalized native session ID. Reset on SessionStart and cleaned on SessionEnd. Read by revert-guard and quality-gate. |
 | `scripts/test_cohesion.py` | Resolves changed paths → test commands via cohesion map. First-match-wins. Stdlib-only. |
 | `app/hooks/test-cohesion-map.json` | Toolkit-default path → tests mapping (used when no project map exists). |
 | `app/hooks/_locate-toolkit.sh` | Shared bash helper that exports `$TOOLKIT_DIR` for hooks needing scripts/. |
@@ -507,8 +594,9 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
 ```
 ~/.softspark/ai-toolkit/
 ├── rules/          # Registered rules (add-rule.sh)
-├── state/          # Per-session runtime state (NEW)
-│   ├── session-edits.json         # Append-only edit log per session
+├── state/          # Per-session runtime state
+│   ├── session-edits-<hash>.json  # Isolated edit state, removed at SessionEnd
+│   ├── session-edits.json         # Compatibility alias for the active session
 │   ├── search-required-<sid>.flag # Per-session: set by user-prompt-submit, cleared by search-tracker/stop-search-check, GC'd at SessionStart (>60min)
 │   ├── loaded-instructions.log    # Audit trail of which rules entered context
 │   └── test-cohesion-last.log     # Last cohesion test command output
@@ -580,6 +668,7 @@ Beyond the global Claude Code hooks above, editor profiles emit native hook file
 | Augment | `.augment/settings.json` (hooks block) | `generate_augment_hooks.py` | Claude-style events |
 | GitHub Copilot | `.github/hooks/ai-toolkit.json`; user `$COPILOT_HOME/hooks/ai-toolkit.json` | `generate_copilot_hooks.py` | GitHub version 1, camelCase events (profile ≥ `standard`) |
 | Codex CLI | `.codex/hooks.json`; user `$CODEX_HOME/hooks.json` | `generate_codex_hooks.py` | Native Codex schema, PascalCase events, command ownership markers |
+| OpenCode | `.opencode/plugins/ai-toolkit-hooks.js`; user `~/.config/opencode/plugins/ai-toolkit-hooks.js` | `generate_opencode_plugin.py` | Native JavaScript plugin hooks |
 
 ### Cursor hooks (`.cursor/hooks.json`)
 

package/kb/reference/opencode-compatibility.md

@@ -162,6 +162,7 @@ The opencode integration is verified by:
 - `kb/reference/skills-catalog.md`
 - `kb/reference/agents-catalog.md`
 - `kb/reference/codex-cli-compatibility.md`
+- `kb/reference/copilot-compatibility.md`
 - `kb/reference/architecture-overview.md`
 - `kb/reference/global-install-model.md`
 - `kb/reference/mcp-editor-compatibility.md`

package/kb/reference/supported-tools-registry.md

@@ -3,9 +3,9 @@ title: "Supported Tools Registry"
 category: reference
 service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
-version: "1.10.0"
+version: "1.11.0"
 created: "2026-04-23"
-last_updated: "2026-07-14"
+last_updated: "2026-07-23"
 description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code, Claude Chat/Cowork, and 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
 ---
 
@@ -33,6 +33,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Our generators | — (Claude Code is the primary target; toolkit content ships directly as `.md` files and `settings.json` merges) |
 | Tracked hook events | Core: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`, `MessageDisplay`. Tool: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`. Turn: `Stop`, `StopFailure`, `UserPromptExpansion`. Subagent: `SubagentStart`, `SubagentStop`. Compaction: `PreCompact`, `PostCompact`. Permissions: `PermissionRequest`, `PermissionDenied`. Elicitation: `Elicitation`, `ElicitationResult`. Teams: `TaskCreated`, `TaskCompleted`, `TeammateIdle`. Worktrees/env: `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `FileChanged`, `ConfigChange`. Setup: `Setup`, `InstructionsLoaded` |
 | Tracked handler types | `command`, `prompt`, `agent`, `mcp_tool`, `http` (POST event JSON to allowlisted URLs via `allowedHttpHookUrls`) |
+| Tool-output replacement | Native `PostToolUse.updatedToolOutput`; ai-toolkit exposes dependency-free `off`, byte-identical `observe`, and opt-in recoverable `safe` modes for eligible successful Bash text |
 | Other capabilities | slash commands, MCP server/client, sub-agent, output style, `SKILL.md` (≥500 lines warn) |
 | Version probe | `claude --version` |
 | Notes | v2.1.169 added `disableBundledSkills` setting + `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` env var (hides bundled skills/built-in slash commands from the model; toolkit skills in `.claude/skills/` are unaffected — useful when toolkit skills overlap built-ins) and `claude --safe-mode` / `CLAUDE_CODE_SAFE_MODE` (starts with hooks, skills, agents, and CLAUDE.md disabled — first isolation step when debugging toolkit rule enforcement). `fallbackModel` settings key (v2.1.166) noted as not-adopted (class C, no toolkit surface writes model settings). |
@@ -52,6 +53,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Plugin layout | `.claude-plugin/plugin.json`, `skills/*/SKILL.md`, `agents/*.md`, `hooks/hooks.json`; ai-toolkit uses manifest paths under `claude-app/` for its generated app-only rules and hooks |
 | Our generator | `scripts/claude_app.py` (`ai-toolkit claude-app export`) |
 | Runtime split | Skills work in Chat (web/Desktop) and Cowork. Hooks and sub-agents run only in Cowork. Claude app does **not** scan Claude Code's `~/.claude/rules/`, `CLAUDE.md`, or `~/.claude/settings.json`. |
+| Tool-output replacement | Not shipped. The Claude Code-only filter hook and runtime are excluded from the app archive until Cowork has an independently verified replacement contract. |
 | Install/update | Export the ZIP, upload it from `Customize > Plugins`, then paste the generated global-instructions file into `Settings > Cowork > Global instructions`. Re-export/re-upload after toolkit updates. |
 
 ---
@@ -103,7 +105,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Our generators | `scripts/generate_copilot.py` (instructions, prompts, agents, and portable skill directories), `scripts/generate_copilot_hooks.py` (native version-1 hook config plus self-contained runtime) |
 | Global install | `ai-toolkit install --editors copilot` writes instructions, agents, skills, and, for profile ≥ `standard`, native hooks below `$COPILOT_HOME` when set or `~/.copilot` otherwise. VS Code Copilot and GitHub.com use repo `.github/` files, so local emission remains required. |
 | Tracked capabilities | `copilot-instructions.md`, Copilot Chat, Copilot Workspace, Copilot cloud agent, `applyTo`, custom agents, prompt files, `instructions.md`, `AGENTS.md`, MCP, skills, CLI hooks, `~/.copilot/` |
-| Compatibility notes | Custom agents use native `.agent.md` files with `name` and `description`; `tools` is omitted instead of guessing editor-specific aliases. Prompt and skill bodies remove Claude-only interpolation and delegation APIs. Hooks use the GitHub version-1 schema, camelCase event names, native decision payloads, and a repository/config-root-contained Python runtime instead of Claude hook scripts. Project MCP remains owned by the editor MCP sync path. Copilot code review also reads the nearest `AGENTS.md`; local install keeps its generated section separate from Codex/OpenCode sections. |
+| Compatibility notes | Custom agents use native `.agent.md` files with `name` and `description`; `tools` is omitted instead of guessing editor-specific aliases. Prompt and skill bodies remove Claude-only interpolation and delegation APIs. Hooks use the GitHub version-1 schema, camelCase event names, native decision payloads, and a repository/config-root-contained Python runtime instead of Claude hook scripts. Project MCP remains owned by the editor MCP sync path. Copilot code review also reads the nearest `AGENTS.md`; local install keeps its generated section separate from Codex/OpenCode sections. Surface loading semantics and the prompt/skill duplication are documented in `kb/reference/copilot-compatibility.md`. |
 
 ### Gemini CLI
 
@@ -170,7 +172,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Our generators | `scripts/generate_augment.py`, `scripts/generate_augment_rules.py`, `scripts/generate_augment_agents.py` (profile=full), `scripts/generate_augment_commands.py` (profile=full), `scripts/generate_augment_hooks.py` (profile=full, HOME-scoped), `scripts/generate_augment_skills.py` (profile=full) |
 | Global install | `ai-toolkit install --editors augment` writes `~/.augment/rules/ai-toolkit.md` **plus** (profile=full) `~/.augment/agents/`, `~/.augment/commands/`, and hooks in `~/.augment/settings.json` — all documented user-tier surfaces. A global-only Augment user previously got no hooks/agents/commands. Skills need no global emission: Auggie natively reads `~/.claude/skills/`. |
 | Tracked capabilities | `.augment`, Agent mode, Next Edit, MCP, context engine, Auggie CLI, `always_apply`, `agent_requested`, subagents, custom commands, `SKILL.md`, `PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`, `Stop`, `Notification`, ACP Mode, plugins/marketplace |
-| Latest / notes | Auggie CLI v0.31.0. Since v0.30.0 (2026-06-25) `PreToolUse`/`PostToolUse` hooks fire during sub-agent sessions, so our wired hook groups now run concurrently from parallel sub-agents — hook payload identifier is `conversation_id` (not `session_id`), a concurrency note to track. `Notification` is enum-only (doctor flipped its marker) — no dedicated handler documented, so class C (do NOT wire). Plugins/marketplace (`auggie plugin marketplace add`, `.augment-plugin`/`.claude-plugin` layouts, `enabledPlugins`/`autoUpdateMarketplaces` in settings) documented but not yet a shipping target. |
+| Latest / notes | Auggie CLI v0.31.0. Since v0.30.0 (2026-06-25) `PreToolUse`/`PostToolUse` hooks fire during sub-agent sessions. The shared hook input adapter normalizes Augment's `conversation_id`, so edit and quality state remains isolated across parallel sub-agents. `Notification` is enum-only (doctor flipped its marker), with no dedicated handler documented, so class C (do NOT wire). Plugins/marketplace (`auggie plugin marketplace add`, `.augment-plugin`/`.claude-plugin` layouts, `enabledPlugins`/`autoUpdateMarketplaces` in settings) are documented but not yet a shipping target. |
 | SPA caveat | Mintlify Next.js SPA; use `https://docs.augmentcode.com/<path>.md` siblings (discoverable via `/llms.txt`) for machine reads |
 
 ### Google Antigravity
@@ -198,7 +200,8 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Config paths | **Instructions:** project `AGENTS.md` (root→cwd chain, closest wins) and global `~/.codex/AGENTS.md` (`$CODEX_HOME/AGENTS.md`; `~/.codex/AGENTS.override.md` takes precedence). NOTE: `~/AGENTS.md` is NOT a global-instruction surface — Codex only reads it if a session's cwd is exactly `$HOME`. Plus `.agents/skills/*/SKILL.md`, `.codex/agents/*.toml`, `~/.codex/agents/*.toml`, `.codex/hooks.json`, `~/.codex/hooks.json`, `.codex/config.toml` (project layers, root→cwd, closest wins, trusted projects only), `~/.codex/config.toml`. |
 | Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_agents.py` (native custom-agent TOML), `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
 | Rules delivery | Universal coding rules are inlined into `AGENTS.md` (Codex reads instructions only from AGENTS.md, not `.agents/rules/`); language rules ship as `<lang>-rules` skills under `.agents/skills/`. Global install writes `~/.codex/AGENTS.md` (not `~/AGENTS.md`, which Codex never loads globally); plugin-pack rules are marker-injected into the same file. `project_doc_max_bytes` default is 32 KiB and Codex silently truncates AGENTS.md past that (see codex-cli-compatibility.md). |
-| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire 9 of these to shared toolkit hook scripts (via `generate_codex_hooks.py` AND `inject-hook` propagation, kept in sync), mirroring the Claude Code mapping in `app/hooks.json`. `PostCompact` is not wired (its only hook was the removed environment-snapshot probe). |
+| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire 9 through an explicit Codex map, including destructive-command and wrong-home path guards on both Bash `PreToolUse` and `PermissionRequest`. `PostCompact` is not wired (its only hook was the removed environment-snapshot probe). |
+| Tool-output replacement | Manual `ai-toolkit output-filter inspect` only. The Claude-specific `updatedToolOutput` adapter is not emitted into Codex hooks. |
 | Tracked handler types | `command` (emitted by default; the only handler Codex actually runs). `prompt` and `agent` are parsed by Codex but NOT yet executed, so hand-authored handlers of those types are inert. |
 | Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path), `.codex/agents/*.toml` (native custom agents) |
 | Version probe | `codex --version` |
@@ -212,6 +215,8 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Release notes | https://github.com/sst/opencode/releases (redirects to anomalyco/opencode) |
 | Config paths | `opencode.json`, `.opencode/agents/*.md`, `.opencode/commands/*.md`, `.opencode/plugins/*`, `.opencode/skills/*/SKILL.md` (v1.14+), `AGENTS.md`; skill fallback discovery: `.claude/skills/`, `.agents/skills/`, `~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.agents/skills/` |
 | Our generators | `scripts/generate_opencode.py`, `scripts/generate_opencode_agents.py`, `scripts/generate_opencode_commands.py`, `scripts/generate_opencode_json.py`, `scripts/generate_opencode_plugin.py` |
+| Hook isolation | Tool hooks preserve native `sessionID` as normalized `session_id`; exit code 2 from a blocking pre-tool guard is raised back to OpenCode instead of being ignored. |
+| Tool-output replacement | Manual `ai-toolkit output-filter inspect` only. No active OpenCode output adapter is shipped. |
 | Tracked plugin events | `session.created`, `session.compacted`, `session.deleted`, `message.updated`, `tool.execute.before`, `tool.execute.after`, `permission.asked`, `command.executed` |
 | Other capabilities | `opencode.json` config, primary + subagent modes, `@`-mention subagents, `/`-invocation commands, MCP (local + remote), plugin hooks in JS/TS, native `SKILL.md` discovery with Claude-compatible fallback, `permission.skill.*` matrix |
 | Version probe | `opencode --version` |