@softspark/ai-toolkit 4.9.0 → 4.10.1

package/CHANGELOG.md

@@ -7,6 +7,33 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.10.1 — Copilot AGENTS.md install + Claude KB-first rule (2026-06-23)
+
+Patch release. Fixes two governance regressions found in the editor-update audit: Copilot installs now emit the root `AGENTS.md` surface documented in the registry, and Claude Code receives the KB-first rule in `CLAUDE.md`, which it actually reads. Test count: 1195 → 1198.
+
+### Fixed
+- **GitHub Copilot local install now emits root `AGENTS.md`.** `ai-toolkit install --local --editors copilot` writes the generated agent catalog into a `TOOLKIT:copilot-agents` section without clobbering existing Codex/opencode `TOOLKIT:ai-toolkit` sections or user-authored content. Dry-run output and tests now cover the `.github/copilot-instructions.md + AGENTS.md` contract.
+- **Claude Code KB-first rule restored in the right instruction file.** `CLAUDE.md` now explicitly requires `smart_query()` or `hybrid_search_kb()` before technical/project answers; the prior generated `AGENTS.md` placement was not sufficient for Claude Code runtime enforcement.
+- **Codex PostToolUse no longer emits unsupported `suppressOutput`.** `loop-guard.sh` no longer forces `AI_TOOLKIT_HOOK_FORMAT=json`; under Codex it stays quiet/plain unless the generator explicitly opts into a supported JSON schema.
+- **Npm package excludes local Claude session artifacts.** `package.json` now excludes `app/**/.claude/**` so ignored maintainer-local session files cannot leak into `npm pack`.
+
+### Changed
+- **Editor registry/docs aligned with implementation.** README, architecture overview, and the supported-tools registry now describe Copilot's root `AGENTS.md` emission consistently.
+- **Ecosystem doctor baseline refreshed.** Snapshot updated for upstream Claude Code and Gemini CLI documentation content hash drift; no generator changes were required.
+
+## v4.10.0 — Per-repo session storage outside the repo + drop dead session-context hook (2026-06-17)
+
+Minor release. Session lifecycle hooks stop writing auto-generated files into each project's `.claude/` directory and store them per-repo under `~/.softspark/ai-toolkit/`. The dead `session-context.sh` hook (write-only, no consumer) is removed across all editor generators. Test count: 1197 → 1195.
+
+### Changed
+- **Session lifecycle hooks store artifacts outside the repo.** `save-session.sh`, `session-end.sh`, `session-start.sh`, and `pre-compact.sh` now read/write the auto-generated session files (`session-context.md`, `session-end.md`, `session-context.md.checkpoints`, `decisions.md`) under `~/.softspark/ai-toolkit/sessions/<repo-key>/` instead of the project's `.claude/` directory. `<repo-key>` is the git work-tree root path (fallback: cwd) with `/` replaced by `-`, keyed per repo so projects stay isolated. Stops these files from piling up in every repository. New shared helper `app/hooks/_session-paths.sh` is the single source of path resolution. No migration of pre-existing in-repo files: the new store starts fresh, old `.claude/session-*.md` left for the user to delete.
+- **Constitution Art. I §5** updated to point proactive checkpointing at the per-repo session store.
+
+### Removed
+- **Dropped the dead `session-context.sh` hook.** It fired on `SessionStart` and wrote an environment snapshot (`~/.softspark/ai-toolkit/sessions/<id>.json`: pwd, git branch/status, node/python versions) that no hook, script, or tool ever read — pure write-only dead code (Constitution Art. VI.1). Removed the script, its `app/hooks.json` wiring, its entries across all 7 editor hook generators (cursor, windsurf, codex, devin, augment, gemini, opencode), its tests, and its catalog/overview docs. Editors that had it as the sole entry for an event (windsurf `post_setup_worktree`, codex `PostCompact`, gemini `BeforeModel`, devin `SessionStart`) drop that event. Not related to the session-storage change above — it never wrote to the repo.
+
+---
+
 ## v4.9.0 - Epistemic integrity rules + deep-research skill + custom-rule leak fix (2026-06-15)
 
 Minor release. Adds a constitution article on injection resistance and grounding, a new web-research methodology skill, and an anti-sycophancy/formatting pass across the voice layer. Also fixes a leak where a maintainer's personal registered rules were baked into the toolkit's own committed editor files. Skill count: 107 → 108. Constitution: 6 → 7 articles. Test count: 1196 → 1197.

package/README.md

@@ -6,16 +6,18 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-108-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1197%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1198%20passing-success)](tests/)
 
-## What's New in v4.9.0
+## What's New in v4.10.1
 
-v4.9.0 hardens the toolkit's epistemics and fixes a leak where a maintainer's personal rules were baked into the toolkit's own committed editor files.
+v4.10.1 fixes editor-governance gaps found in the release audit.
 
-- **Constitution Article VII — Epistemic & Injection Integrity**: embedded or untrusted text is data, not commands (no privilege escalation or exfiltration); never fabricate files, APIs, or citations; declare ungrounded when sources come back empty. Constitution: 6 → 7 articles.
-- **`deep-research` skill**: multi-source web research methodology — retrieve-vs-answer gate, complexity-scaled search budget, source-conflict skepticism, adversarial verification, attribution-without-reproduction. Skill count: 107 → 108.
-- **Anti-sycophancy + formatting discipline**: `golden-rules` gains "Honesty Over Agreeableness"; `brand-voice` gains list-gating, minimum-substance bullets, and mode carve-outs (code quality never reduced, auto-escalation, disclosure-on-pushback).
-- **Custom-rule leak fixed**: `AGENTS.md`, `GEMINI.md`, and `.github/copilot-instructions.md` no longer embed a maintainer's personal `~/.softspark/ai-toolkit/rules/` content, gated behind the new `AI_TOOLKIT_NO_CUSTOM_RULES` flag with a regression test.
+- **Copilot local installs now emit root `AGENTS.md`**: `ai-toolkit install --local --editors copilot` writes the generated agent catalog into a `TOOLKIT:copilot-agents` section while preserving existing Codex/opencode sections and user text.
+- **Claude Code KB-first enforcement restored**: `CLAUDE.md` now carries the mandatory `smart_query()` / `hybrid_search_kb()` rule before technical/project answers, instead of relying on generated `AGENTS.md`.
+- **Codex PostToolUse hook output fixed**: `loop-guard.sh` no longer forces Claude-style JSON with `suppressOutput` under quiet Codex hooks.
+- **Release packaging hardened**: local `.claude` session artifacts under `app/` are excluded from `npm pack`, even if they exist in a maintainer checkout.
+- **Docs and ecosystem baseline refreshed**: README, registry, and architecture docs now match the Copilot implementation; ecosystem-doctor snapshot is refreshed for upstream Claude/Gemini docs hash drift.
+- **Test count**: 1195 → 1198.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -104,7 +106,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` + `.cursor/skills/*` | ✅ | project (`~/.cursor/mcp.json` for MCP only) |
 | Windsurf (Devin Desktop) | `~/.codeium/.../global_rules.md` + `~/.codeium/windsurf/skills/*` + `.devin/rules/*.md` + `.windsurf/rules/*.md` (legacy) | ✅ | global + project |
 | Gemini CLI | `~/.gemini/GEMINI.md` | ✅ | global |
-| GitHub Copilot | `.github/copilot-instructions.md` | — | project |
+| GitHub Copilot | `.github/copilot-instructions.md` + `.github/instructions/*` + `.github/prompts/*` + `AGENTS.md` | — | project |
 | Cline | `~/Documents/Cline/Rules/*.md` + `~/.cline/skills/*` + `.clinerules/*.md` | — | global + project |
 | Roo Code | `~/.roo/rules/*.md` + `.roomodes` + `.roo/rules/*.md` | — | global rules + project |
 | Aider | `~/.aider.conf.yml` + `.aider.conf.yml` + `CONVENTIONS.md` | — | global + project |
@@ -148,7 +150,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1197 tests)
+├── tests/               # Bats test suite (1198 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "4.9.0",
+  "version": "4.10.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/constitution.md

@@ -21,7 +21,7 @@ status: IMMUTABLE
 - Exceeding limits requires explicit user override
 
 ### Section 5: Proactive Context Checkpointing
-- During multi-step tasks (>5 tool calls), update `.claude/session-context.md` after each major milestone
+- During multi-step tasks (>5 tool calls), append milestones to the per-repo session-context store after each major milestone. Auto-generated session files live under `~/.softspark/ai-toolkit/sessions/<repo-root-with-/-as->/` (the repo work-tree root path with `/` replaced by `-`), NOT inside the project repo. Append agent checkpoints to `session-context.md.checkpoints` in that directory; the Stop hook folds them into the session summary
 - Checkpoint MUST include: current objective, completed steps, pending steps, files modified, key decisions
 - Minimum frequency: after every completed task phase, workflow stage, or subagent handoff
 - Agent SHOULD checkpoint before any risky or destructive operation

package/app/hooks/_session-paths.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# _session-paths.sh — shared per-repo session storage paths for lifecycle hooks.
+#
+# All auto-generated session artifacts live OUTSIDE the project repo, under a
+# per-repo subdirectory of ~/.softspark/ai-toolkit/sessions/. This keeps generated
+# files (session context, handoff note, checkpoints, decisions) from polluting
+# every project's .claude/ directory.
+#
+# Usage (in a hook script):
+#   source "$(dirname "$0")/_session-paths.sh"
+# Then use the exported SESSION_* paths.
+#
+# Repo key: the git work-tree root (fallback: cwd) with "/" replaced by "-",
+# mirroring Claude Code's own ~/.claude/projects/<encoded-path> convention so the
+# location is derivable by an agent, not an opaque hash.
+
+_session_repo_root() {
+    if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+        local top
+        top="$(git rev-parse --show-toplevel 2>/dev/null)"
+        if [ -n "$top" ]; then
+            printf '%s' "$top"
+            return 0
+        fi
+    fi
+    pwd
+}
+
+SESSION_REPO_ROOT="$(_session_repo_root)"
+SESSION_REPO_KEY="${SESSION_REPO_ROOT//\//-}"
+SESSION_DIR="$HOME/.softspark/ai-toolkit/sessions/$SESSION_REPO_KEY"
+SESSION_CONTEXT_FILE="$SESSION_DIR/session-context.md"
+SESSION_CHECKPOINTS_FILE="$SESSION_DIR/session-context.md.checkpoints"
+SESSION_END_FILE="$SESSION_DIR/session-end.md"
+SESSION_DECISIONS_FILE="$SESSION_DIR/decisions.md"
+
+export SESSION_REPO_ROOT SESSION_REPO_KEY SESSION_DIR
+export SESSION_CONTEXT_FILE SESSION_CHECKPOINTS_FILE SESSION_END_FILE SESSION_DECISIONS_FILE
+
+unset -f _session_repo_root

package/app/hooks/loop-guard.sh

@@ -53,7 +53,6 @@ fi
 COUNT=$(grep -cxF "$HASH" "$LOG" 2>/dev/null | tr -d ' ')
 [ -z "$COUNT" ] && COUNT=0
 if [ "$COUNT" -ge "$THRESHOLD" ]; then
-    export AI_TOOLKIT_HOOK_FORMAT=json
     hook_emit_context "PostToolUse" \
         "Loop guard: the same ${TOOL_NAME} action has repeated ${COUNT}x within the last ${WINDOW} steps. If you are not making progress, stop and reassess — try a different approach or ask the user — instead of retrying the identical action."
 fi

package/app/hooks/pre-compact.sh

@@ -8,6 +8,8 @@
 
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_session-paths.sh
+source "$(dirname "$0")/_session-paths.sh"
 
 # ---------------------------------------------------------------------------
 # 1. Mandatory reload reminder (highest priority — always survives)
@@ -32,9 +34,9 @@ fi
 # ---------------------------------------------------------------------------
 # 3. Current task state (medium priority — what we're doing)
 # ---------------------------------------------------------------------------
-if [ -f ".claude/session-context.md" ]; then
+if [ -f "$SESSION_CONTEXT_FILE" ]; then
     echo "=== Session Context ==="
-    cat ".claude/session-context.md"
+    cat "$SESSION_CONTEXT_FILE"
     echo "======================="
 fi
 
@@ -55,10 +57,10 @@ fi
 # ---------------------------------------------------------------------------
 # 5. Key decisions file (if user has been noting decisions this session)
 # ---------------------------------------------------------------------------
-if [ -f ".claude/decisions.md" ]; then
+if [ -f "$SESSION_DECISIONS_FILE" ]; then
     echo "=== Key Decisions This Session ==="
     # Only show last 10 lines to keep token budget tight
-    tail -10 ".claude/decisions.md"
+    tail -10 "$SESSION_DECISIONS_FILE"
     echo "=================================="
 fi
 

package/app/hooks/save-session.sh

@@ -6,16 +6,18 @@
 
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_session-paths.sh
+source "$(dirname "$0")/_session-paths.sh"
 
 # Read from stdin (Claude Code passes JSON with .session_id, .last_assistant_message)
 INPUT=$(cat)
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
 LAST_MSG=$(echo "$INPUT" | jq -r '.last_assistant_message // "No summary available"' 2>/dev/null | head -5)
 
-SESSION_FILE=".claude/session-context.md"
+SESSION_FILE="$SESSION_CONTEXT_FILE"
 
 if [ -n "$SESSION_ID" ]; then
-    mkdir -p .claude
+    mkdir -p "$SESSION_DIR"
 
     # Gather git state for richer context
     GIT_BRANCH=""

package/app/hooks/session-end.sh

@@ -7,13 +7,14 @@
 
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_session-paths.sh
+source "$(dirname "$0")/_session-paths.sh"
 
-STATE_DIR=".claude"
-SESSION_FILE="$STATE_DIR/session-context.md"
-HANDOFF_FILE="$STATE_DIR/session-end.md"
+SESSION_FILE="$SESSION_CONTEXT_FILE"
+HANDOFF_FILE="$SESSION_END_FILE"
 STAMP="$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date)"
 
-mkdir -p "$STATE_DIR"
+mkdir -p "$SESSION_DIR"
 
 {
     echo "# Session End Snapshot"
@@ -28,9 +29,9 @@ mkdir -p "$STATE_DIR"
 } > "$HANDOFF_FILE"
 
 if [ -f "$SESSION_FILE" ]; then
-    echo "SessionEnd: wrote .claude/session-end.md and preserved existing .claude/session-context.md for the next session."
+    echo "SessionEnd: wrote $HANDOFF_FILE and preserved existing session-context for the next session."
 else
-    echo "SessionEnd: wrote .claude/session-end.md. Consider persisting open tasks in .claude/session-context.md before ending long workstreams."
+    echo "SessionEnd: wrote $HANDOFF_FILE. Consider persisting open tasks in the session-context file before ending long workstreams."
 fi
 
 exit 0

package/app/hooks/session-start.sh

@@ -6,6 +6,8 @@
 
 # shellcheck source=_locate-toolkit.sh
 source "$(dirname "$0")/_locate-toolkit.sh"
+# shellcheck source=_session-paths.sh
+source "$(dirname "$0")/_session-paths.sh"
 
 emit_context() {
     [ "${AI_TOOLKIT_HOOK_QUIET:-0}" = "1" ] && return 0
@@ -51,7 +53,7 @@ if [ -n "$VERSION_MSG" ]; then
 fi
 
 # 3. Load session context (if available)
-SESSION_FILE=".claude/session-context.md"
+SESSION_FILE="$SESSION_CONTEXT_FILE"
 if [ -f "$SESSION_FILE" ] && [ "${AI_TOOLKIT_HOOK_QUIET:-0}" != "1" ] && [ "${AI_TOOLKIT_HOOK_VERBOSE:-0}" = "1" ]; then
     printf '%s\n' "=== Session Context ==="
     cat "$SESSION_FILE"

package/app/hooks.json

@@ -20,16 +20,6 @@
                         "command": "\"$HOME/.softspark/ai-toolkit/hooks/mcp-health.sh\""
                     }
                 ]
-            },
-            {
-                "_source": "ai-toolkit",
-                "matcher": "startup|compact",
-                "hooks": [
-                    {
-                        "type": "command",
-                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/session-context.sh\""
-                    }
-                ]
             }
         ],
         "Notification": [

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-06-09T22:04:06Z",
+  "last_run": "2026-06-23T07:06:46Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "f4c5995e8333a4d5",
+      "docs_hash": "a0c51061febc16c4",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -66,7 +66,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "e6f6b4d9d4057cb0",
+      "docs_hash": "c20e5688ed230a66",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -122,10 +122,10 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.170 (Claude Code)"
+      "version": "2.1.186 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "806fa530c90e227d",
+      "docs_hash": "858fa542e2aacde5",
       "headings": [
         "API Reference",
         "Best Practices",
@@ -168,7 +168,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "1b4a56a8e918d721",
+      "docs_hash": "eeb0e17a839b09bd",
       "headings": [
         "API",
         "API Reference",
@@ -235,10 +235,10 @@
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.138.0"
+      "version": "codex-cli 0.142.0"
     },
     "cursor": {
-      "docs_hash": "b68e4adf6e21f543",
+      "docs_hash": "86b6d48e8ab40d90",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -254,7 +254,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "a0e9a213229063c8",
+      "docs_hash": "c3ba6d09d810f9c3",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -296,7 +296,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "ead818d74ead1f2e",
+      "docs_hash": "df7c22e121dbb3d1",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -317,6 +317,7 @@
         "Still need help?"
       ],
       "markers": {
+        "AGENTS.md": false,
         "Copilot Chat": true,
         "Copilot Workspace": false,
         "Copilot cloud agent": true,
@@ -329,7 +330,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "5ea5426c4445e746",
+      "docs_hash": "e6c90b9d937dd9f0",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -346,7 +347,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "f546c8b741790cb8",
+      "docs_hash": "302de3ac69940747",
       "headings": [
         "Add features",
         "Ask questions",
@@ -406,8 +407,9 @@
       }
     },
     "windsurf": {
-      "docs_hash": "91034c064d9f8290",
+      "docs_hash": "cdd657d4d684c68a",
       "headings": [
+        "Accounts",
         "Advanced",
         "Agent Command Center",
         "App Deploys",
@@ -420,15 +422,15 @@
         "On this page",
         "Recommended Plugins",
         "Releases",
+        "Security",
         "Terminal",
         "Usage",
         "Welcome to Devin Desktop",
         "Windsurf Plugins",
         "Workflows",
-        "\u200b1. Select setup flow",
-        "\u200b2. Choose editor theme",
-        "\u200b3. Sign up / Log in",
-        "\u200b4. Let\u2019s Surf!",
+        "\u200b1. Select your preferred theme",
+        "\u200b2. Log In / Sign Up",
+        "\u200b3. Start Building with Devin!",
         "\u200bCustom App Icons (beta)",
         "\u200bDevin Desktop Next",
         "\u200bForgot to Import VS Code Configurations?",
@@ -436,8 +438,7 @@
         "\u200bOnboarding",
         "\u200bSet Up",
         "\u200bThings to Try",
-        "\u200bUninstall Devin Desktop",
-        "\u200bUpdate Devin Desktop"
+        "\u200bUninstall Devin Desktop"
       ],
       "markers": {
         "AGENTS.md": true,

package/kb/reference/architecture-overview.md

@@ -54,7 +54,7 @@ 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 .github/copilot-instructions.md (sources _common.py)
+    generate_copilot.py      # Generates Copilot .github/* surfaces; install also injects AGENTS.md
     generate_gemini.py       # Generates GEMINI.md (sources _common.py)
     generate_cline.py        # Generates .clinerules (sources _common.py)
     generate_roo_modes.py    # Generates .roomodes
@@ -109,7 +109,7 @@ 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), `.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 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`.
 
 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`).
 
@@ -269,7 +269,6 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 |------|---------|--------|--------|
 | SessionStart | Session start + compact | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
 | SessionStart | Session start | `mcp-health.sh` | Check MCP runtime availability |
-| SessionStart | Session start | `session-context.sh` | Capture environment snapshot |
 | Notification | Claude waiting for input | *(inline)* | macOS desktop notification |
 | PreToolUse | Before Bash | `guard-destructive.sh` | Block destructive commands |
 | PreToolUse | Before file ops (Bash, Read, Edit, Write, MultiEdit, Glob, Grep, NotebookEdit, mcp\_filesystem) | `guard-path.sh` | Block wrong-user path hallucination |

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

@@ -116,16 +116,22 @@ by default because Codex currently renders `additionalContext` as visible hook
 context in the TUI. This keeps prompt-submit output quiet while preserving hook
 side effects and blocking decisions such as search-first Stop enforcement.
 
-Codex `UserPromptSubmit` JSON output is event-specific. When emitting context,
-the hook must include the event name alongside the context:
+Codex hooks must not force Claude-only JSON output fields such as
+`suppressOutput`. In particular, advisory `PostToolUse` hooks like
+`loop-guard.sh` run in quiet/plain mode under Codex; they keep side effects but
+do not emit hidden Claude-style context unless a future Codex runtime explicitly
+supports that schema.
+
+If a future Codex runtime enables JSON context output for `UserPromptSubmit`,
+the output must be event-specific and include the event name alongside the
+context:
 
 ```json
 {
   "hookSpecificOutput": {
     "hookEventName": "UserPromptSubmit",
     "additionalContext": "..."
-  },
-  "suppressOutput": true
+  }
 }
 ```
 

package/kb/reference/hooks-catalog.md

@@ -47,13 +47,21 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 **Actions:**
 1. Injects MANDATORY reminder to follow CLAUDE.md rules
 2. Injects REMINDER about tests and documentation
-3. Loads session context from `.claude/session-context.md` (if exists)
+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.
+`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
+> `~/.softspark/ai-toolkit/sessions/<repo-key>/`, where `<repo-key>` is the git
+> work-tree root path (fallback: cwd) with `/` replaced by `-` (mirrors Claude
+> Code's own `~/.claude/projects/` convention). This keeps generated files from
+> piling up in every project's `.claude/` directory. Path resolution lives in the
+> shared helper `app/hooks/_session-paths.sh`.
 
 ### Notification — `notify-waiting.sh`
 
@@ -192,10 +200,10 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/save-session.sh` |
 | Fires | After every Claude response |
 
-**Action:** Writes enriched session context to `.claude/session-context.md` for cross-session persistence. Captures:
+**Action:** Writes enriched session context to the per-repo session store (`~/.softspark/ai-toolkit/sessions/<repo-key>/session-context.md`) for cross-session persistence. Captures:
 - Session ID and last assistant message (first 5 lines)
 - Git branch, uncommitted change count, and diff stat (last 5 lines)
-- Agent-written checkpoints from `.claude/session-context.md.checkpoints` (if present — written by proactive checkpointing per Constitution Art. I §5)
+- Agent-written checkpoints from `session-context.md.checkpoints` in the same store (if present — written by proactive checkpointing per Constitution Art. I §5)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -263,9 +271,9 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 **Actions (prioritized — higher priority items survive tighter token budgets):**
 1. **Mandatory reload reminder** — always emitted, instructs Claude to re-read CLAUDE.md and active tasks
 2. **Active instincts** — lists each instinct with confidence score and pattern name from `.claude/instincts/*.md`
-3. **Session context** — preserves task state from `.claude/session-context.md` (if exists)
+3. **Session context** — preserves task state from the per-repo session store (if exists)
 4. **Git working state** — branch name, uncommitted change count, last commit (if inside a git repo)
-5. **Key decisions** — last 10 lines from `.claude/decisions.md` (if exists)
+5. **Key decisions** — last 10 lines from `decisions.md` in the per-repo session store (if exists)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -278,7 +286,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/session-end.sh` |
 | Fires | When a Claude session ends |
 
-**Action:** Writes `.claude/session-end.md` with a lightweight handoff note for the next session and reminds the next session to review preserved context.
+**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.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -351,17 +359,6 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 **Action:** Non-blocking (always exits 0). Inspects Bash commands containing `git commit`. Extracts the commit message from the `-m` flag and checks it against Conventional Commits format (`type: description`, where type is one of feat/fix/docs/refactor/test/chore/ci/perf/style/revert). Emits an advisory warning if the message does not match — the commit is not blocked, only nudged. Commands without `git commit` or without a `-m` message (e.g. interactive commits) are ignored.
 
-### SessionStart — `session-context.sh`
-
-| Field | Value |
-|-------|-------|
-| Event | `SessionStart` |
-| Matcher | *(all)* |
-| Script | `~/.softspark/ai-toolkit/hooks/session-context.sh` |
-| Fires | Session start |
-
-**Action:** Captures an environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json`. Records working directory, git branch, git status summary, Node.js version, Python version, and timestamp. Used by other hooks and tools to access session metadata without re-running discovery commands. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
-
 ---
 
 ## New Hooks (Constitution Art. VI Enforcement)
@@ -520,8 +517,8 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
     ├── _locate-toolkit.sh        # NEW: shared $TOOLKIT_DIR locator
     ├── _hook-io.sh               # NEW: shared multi-editor payload/output adapter
     ├── _search-capability.sh     # NEW: capability-aware search-first enforcement
+    ├── _session-paths.sh         # NEW: per-repo session storage path resolver
     ├── session-start.sh
-    ├── session-context.sh
     ├── guard-destructive.sh
     ├── guard-path.sh
     ├── guard-config.sh
@@ -549,7 +546,7 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
 
 ~/.claude/settings.json
 └── hooks:          # Hook definitions referencing ~/.softspark/ai-toolkit/hooks/
-    ├── SessionStart       → session-start.sh, mcp-health.sh, session-context.sh
+    ├── SessionStart       → session-start.sh, mcp-health.sh
     ├── Notification       → notify-waiting.sh
     ├── PreToolUse         → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh, revert-guard.sh
     ├── UserPromptSubmit   → user-prompt-submit.sh, track-usage.sh
@@ -590,7 +587,7 @@ Windsurf rebranded to Devin Desktop (2026-06-02); the Cascade agent — and its
 Devin CLI uses a **Claude-compatible** hook format (docs.devin.ai/cli/extensibility/hooks). Key facts driving the generator:
 
 - **Standalone file shape:** in `.devin/hooks.v1.json` the entire file IS the hooks object — no top-level `"hooks"` wrapper key (unlike `.claude/settings.json`).
-- **Events:** Claude-style PascalCase — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SessionStart`. `post_setup_worktree` has no Devin equivalent (`session-context.sh` moves to `SessionStart`); `post_cascade_response` maps to `Stop` (which carries no response text on stdin).
+- **Events:** Claude-style PascalCase — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`. `post_cascade_response` maps to `Stop` (which carries no response text on stdin).
 - **Matchers:** regex against the Devin **tool name** (`read`, `edit`, `exec`, `grep`, `glob`, `mcp__<server>__<tool>`) — NOT Claude's `Bash`/`Edit`, so the shared guards reliably fire.
 - **Block contract:** the guard scripts emit `{"decision":"block","reason":...}` on stdout (plain mode) AND exit 2 — Devin honors both. Hooks run **without** `AI_TOOLKIT_HOOK_FORMAT=json` because Devin expects the flat `{"decision","reason"}` shape, not Claude's `hookSpecificOutput` envelope.
 - **Stdin payload:** flat `{ "hook_event_name", "tool_name", "tool_input" }` — already handled by `_hook-io.sh` via its `.tool_name` / `.tool_input.*` branches, so no normalizer change was needed.

package/kb/reference/opencode-compatibility.md

@@ -79,7 +79,7 @@ Each command file carries the prompt in its markdown body (built from the SKILL.
 
 | opencode event             | Bash hook(s)                                                       |
 |----------------------------|--------------------------------------------------------------------|
-| `session.created`          | `session-start.sh` + `session-context.sh` + `mcp-health.sh`        |
+| `session.created`          | `session-start.sh` + `mcp-health.sh`                               |
 | `session.compacted`        | `pre-compact.sh` + `pre-compact-save.sh` (PreCompact equivalent)   |
 | `session.deleted`          | `session-end.sh` + `save-session.sh`                               |
 | `message.updated`          | `user-prompt-submit.sh` + `track-usage.sh`                         |

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.6.0"
+version: "1.7.0"
 created: "2026-04-23"
-last_updated: "2026-06-10"
+last_updated: "2026-06-23"
 description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code + 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
 ---
 
@@ -28,7 +28,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `claude-code` |
 | Docs | https://code.claude.com/docs (platform.claude.com/docs 307-redirects here) |
 | Release notes | https://github.com/anthropics/claude-code/releases |
-| Changelog | https://code.claude.com/docs/en/changelog (lists current 2.1.170) |
+| Changelog | https://code.claude.com/docs/en/changelog (lists current 2.1.186) |
 | Config paths | `~/.claude/settings.json`, `.claude/settings.json` (project, committed), `.claude/settings.local.json`, `CLAUDE.md`, `.claude/rules/*.md`, `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `~/.claude/themes/*.json` (v2.1.118+) |
 | 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` |
@@ -79,8 +79,8 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Release notes | https://github.blog/changelog/label/copilot/ |
 | Config paths | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `.github/prompts/*.prompt.md`, `AGENTS.md` |
 | Our generators | `scripts/generate_copilot.py` |
-| Tracked capabilities | `copilot-instructions.md`, Copilot Chat, Copilot Workspace, Copilot cloud agent, `applyTo`, custom agents, prompt files, `instructions.md`, MCP |
-| Tier notes | Custom agents (`.github/agents/*.agent.md`) and repo-level MCP config are Pro/Pro+/Business/Enterprise only and intentionally not integrated (class C per ecosystem-sync SOP). |
+| Tracked capabilities | `copilot-instructions.md`, Copilot Chat, Copilot Workspace, Copilot cloud agent, `applyTo`, custom agents, prompt files, `instructions.md`, `AGENTS.md`, MCP |
+| Tier notes | Custom agents (`.github/agents/*.agent.md`) and repo-level MCP config are Pro/Pro+/Business/Enterprise only and intentionally not integrated (class C per ecosystem-sync SOP). Copilot code review reads the nearest `AGENTS.md` automatically since the 2026-06-18 GA (all tiers); `ai-toolkit install --local --editors copilot` injects a `TOOLKIT:copilot-agents` section generated from `generate_agents_md.py` without clobbering Codex/opencode sections in the same file. The 4000-char cap on `copilot-instructions.md` / `*.instructions.md` was also removed (2026-06-12). |
 
 ### Gemini CLI
 
@@ -93,7 +93,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Our generators | `scripts/generate_gemini.py`, `scripts/generate_gemini_hooks.py` (profile>=standard), `scripts/generate_gemini_commands.py` (profile=full), `scripts/generate_gemini_skills.py` (profile=full) |
 | Tracked capabilities | `GEMINI.md`, `mcpServers`, tools, `settings.json`, `BeforeTool`, `AfterTool`, `BeforeToolSelection`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `Notification`, `PreCompress`, `SessionStart`, `SessionEnd`, `SKILL.md`, `activate_skill`, custom commands, `gemini-extension.json` (no native `Stop` event — generator maps Stop-equivalent to `AfterAgent`; 11 documented hook events total) |
 | Version probe | `gemini --version` |
-| Latest upstream | v0.45.2 (2026-06-05). NOTE: Gemini CLI drops free/paid tiers 2026-06-18 in favor of Antigravity CLI (we ship `generate_antigravity.py`); enterprise Code Assist keeps Gemini CLI. |
+| Latest upstream | v0.47.0 (2026-06-18). NOTE: Gemini CLI dropped free/paid individual tiers on 2026-06-18 in favor of Antigravity CLI (we ship `generate_antigravity.py`); enterprise Code Assist and paid API keys keep Gemini CLI, so the integration stays. The 11 hook events are unchanged. v0.48 preview migrates the `coreTools` setting to `tools.core` (a tool-allowlist key we do not emit, so no generator change). |
 
 ### Cline
 
@@ -165,12 +165,12 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Field | Value |
 |-------|-------|
 | ID | `codex-cli` |
-| Docs | https://developers.openai.com/codex (live docs site; config pages split into `/codex/config-basic`, `/codex/config-reference`, `/codex/config-advanced` plus `/codex/hooks`, `/codex/skills`; latest stable codex-cli 0.138.0, 2026-06) |
+| Docs | https://developers.openai.com/codex (live docs site; config pages split into `/codex/config-basic`, `/codex/config-reference`, `/codex/config-advanced` plus `/codex/hooks`, `/codex/skills`; latest stable codex-cli 0.142.0, 2026-06) |
 | Release notes | https://github.com/openai/codex/releases |
 | Config paths | `AGENTS.md`, `.agents/skills/*/SKILL.md`, `.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_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/`. |
-| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire all 10 to shared toolkit hook scripts, mirroring the Claude Code mapping in `app/hooks.json`. |
+| 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, mirroring the Claude Code mapping in `app/hooks.json`. `PostCompact` is not wired (its only hook was the removed environment-snapshot probe). |
 | Tracked handler types | `command` (emitted by default); `prompt` and `agent` available upstream but authored by hand |
 | Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path) |
 | Version probe | `codex --version` |
@@ -187,7 +187,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
-| Watch item | v1.16.0 (2026-06-05) ships an experimental v2 skill registry (flat-file skills, `slash` frontmatter key) — undocumented as of 2026-06-09; re-check next sync before touching `generate_opencode*.py`. |
+| Watch item | v1.16.0 (2026-06-05) shipped an experimental v2 skill registry (flat-file skills, `slash` frontmatter key). As of the 2026-06-23 sync (upstream v1.17.9) it is still undocumented and not stabilized: the skills docs show only the nested `SKILL.md` layout with no `slash` key, so `generate_opencode*.py` is unchanged. Re-check next sync. |
 
 ---
 

package/kb/reference/unique-features.md

@@ -27,7 +27,6 @@ Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are
 |-------|--------|--------|
 | SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts + reset session-edit state |
 | SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
-| SessionStart | `session-context.sh` | Capture environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json` |
 | Notification | `notify-waiting.sh` | Cross-platform desktop notification |
 | PreToolUse | `guard-destructive.sh` | Block `rm -rf`, `DROP TABLE`, etc. |
 | PreToolUse | `guard-path.sh` | Block wrong-user path hallucination |

package/llms-full.txt

@@ -6286,7 +6286,7 @@ 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 .github/copilot-instructions.md (sources _common.py)
+    generate_copilot.py      # Generates Copilot .github/* surfaces; install also injects AGENTS.md
     generate_gemini.py       # Generates GEMINI.md (sources _common.py)
     generate_cline.py        # Generates .clinerules (sources _common.py)
     generate_roo_modes.py    # Generates .roomodes
@@ -6341,7 +6341,7 @@ 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), `.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 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`.
 
 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`).
 
@@ -6501,7 +6501,6 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 |------|---------|--------|--------|
 | SessionStart | Session start + compact | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
 | SessionStart | Session start | `mcp-health.sh` | Check MCP runtime availability |
-| SessionStart | Session start | `session-context.sh` | Capture environment snapshot |
 | Notification | Claude waiting for input | *(inline)* | macOS desktop notification |
 | PreToolUse | Before Bash | `guard-destructive.sh` | Block destructive commands |
 | PreToolUse | Before file ops (Bash, Read, Edit, Write, MultiEdit, Glob, Grep, NotebookEdit, mcp\_filesystem) | `guard-path.sh` | Block wrong-user path hallucination |
@@ -7182,16 +7181,22 @@ by default because Codex currently renders `additionalContext` as visible hook
 context in the TUI. This keeps prompt-submit output quiet while preserving hook
 side effects and blocking decisions such as search-first Stop enforcement.
 
-Codex `UserPromptSubmit` JSON output is event-specific. When emitting context,
-the hook must include the event name alongside the context:
+Codex hooks must not force Claude-only JSON output fields such as
+`suppressOutput`. In particular, advisory `PostToolUse` hooks like
+`loop-guard.sh` run in quiet/plain mode under Codex; they keep side effects but
+do not emit hidden Claude-style context unless a future Codex runtime explicitly
+supports that schema.
+
+If a future Codex runtime enables JSON context output for `UserPromptSubmit`,
+the output must be event-specific and include the event name alongside the
+context:
 
 ```json
 {
   "hookSpecificOutput": {
     "hookEventName": "UserPromptSubmit",
     "additionalContext": "..."
-  },
-  "suppressOutput": true
+  }
 }
 ```
 
@@ -9043,13 +9048,21 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 **Actions:**
 1. Injects MANDATORY reminder to follow CLAUDE.md rules
 2. Injects REMINDER about tests and documentation
-3. Loads session context from `.claude/session-context.md` (if exists)
+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.
+`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
+> `~/.softspark/ai-toolkit/sessions/<repo-key>/`, where `<repo-key>` is the git
+> work-tree root path (fallback: cwd) with `/` replaced by `-` (mirrors Claude
+> Code's own `~/.claude/projects/` convention). This keeps generated files from
+> piling up in every project's `.claude/` directory. Path resolution lives in the
+> shared helper `app/hooks/_session-paths.sh`.
 
 ### Notification — `notify-waiting.sh`
 
@@ -9188,10 +9201,10 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/save-session.sh` |
 | Fires | After every Claude response |
 
-**Action:** Writes enriched session context to `.claude/session-context.md` for cross-session persistence. Captures:
+**Action:** Writes enriched session context to the per-repo session store (`~/.softspark/ai-toolkit/sessions/<repo-key>/session-context.md`) for cross-session persistence. Captures:
 - Session ID and last assistant message (first 5 lines)
 - Git branch, uncommitted change count, and diff stat (last 5 lines)
-- Agent-written checkpoints from `.claude/session-context.md.checkpoints` (if present — written by proactive checkpointing per Constitution Art. I §5)
+- Agent-written checkpoints from `session-context.md.checkpoints` in the same store (if present — written by proactive checkpointing per Constitution Art. I §5)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9259,9 +9272,9 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 **Actions (prioritized — higher priority items survive tighter token budgets):**
 1. **Mandatory reload reminder** — always emitted, instructs Claude to re-read CLAUDE.md and active tasks
 2. **Active instincts** — lists each instinct with confidence score and pattern name from `.claude/instincts/*.md`
-3. **Session context** — preserves task state from `.claude/session-context.md` (if exists)
+3. **Session context** — preserves task state from the per-repo session store (if exists)
 4. **Git working state** — branch name, uncommitted change count, last commit (if inside a git repo)
-5. **Key decisions** — last 10 lines from `.claude/decisions.md` (if exists)
+5. **Key decisions** — last 10 lines from `decisions.md` in the per-repo session store (if exists)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9274,7 +9287,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/session-end.sh` |
 | Fires | When a Claude session ends |
 
-**Action:** Writes `.claude/session-end.md` with a lightweight handoff note for the next session and reminds the next session to review preserved context.
+**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.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9347,17 +9360,6 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 **Action:** Non-blocking (always exits 0). Inspects Bash commands containing `git commit`. Extracts the commit message from the `-m` flag and checks it against Conventional Commits format (`type: description`, where type is one of feat/fix/docs/refactor/test/chore/ci/perf/style/revert). Emits an advisory warning if the message does not match — the commit is not blocked, only nudged. Commands without `git commit` or without a `-m` message (e.g. interactive commits) are ignored.
 
-### SessionStart — `session-context.sh`
-
-| Field | Value |
-|-------|-------|
-| Event | `SessionStart` |
-| Matcher | *(all)* |
-| Script | `~/.softspark/ai-toolkit/hooks/session-context.sh` |
-| Fires | Session start |
-
-**Action:** Captures an environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json`. Records working directory, git branch, git status summary, Node.js version, Python version, and timestamp. Used by other hooks and tools to access session metadata without re-running discovery commands. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
-
 ---
 
 ## New Hooks (Constitution Art. VI Enforcement)
@@ -9516,8 +9518,8 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
     ├── _locate-toolkit.sh        # NEW: shared $TOOLKIT_DIR locator
     ├── _hook-io.sh               # NEW: shared multi-editor payload/output adapter
     ├── _search-capability.sh     # NEW: capability-aware search-first enforcement
+    ├── _session-paths.sh         # NEW: per-repo session storage path resolver
     ├── session-start.sh
-    ├── session-context.sh
     ├── guard-destructive.sh
     ├── guard-path.sh
     ├── guard-config.sh
@@ -9545,7 +9547,7 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
 
 ~/.claude/settings.json
 └── hooks:          # Hook definitions referencing ~/.softspark/ai-toolkit/hooks/
-    ├── SessionStart       → session-start.sh, mcp-health.sh, session-context.sh
+    ├── SessionStart       → session-start.sh, mcp-health.sh
     ├── Notification       → notify-waiting.sh
     ├── PreToolUse         → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh, revert-guard.sh
     ├── UserPromptSubmit   → user-prompt-submit.sh, track-usage.sh
@@ -9586,7 +9588,7 @@ Windsurf rebranded to Devin Desktop (2026-06-02); the Cascade agent — and its
 Devin CLI uses a **Claude-compatible** hook format (docs.devin.ai/cli/extensibility/hooks). Key facts driving the generator:
 
 - **Standalone file shape:** in `.devin/hooks.v1.json` the entire file IS the hooks object — no top-level `"hooks"` wrapper key (unlike `.claude/settings.json`).
-- **Events:** Claude-style PascalCase — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SessionStart`. `post_setup_worktree` has no Devin equivalent (`session-context.sh` moves to `SessionStart`); `post_cascade_response` maps to `Stop` (which carries no response text on stdin).
+- **Events:** Claude-style PascalCase — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`. `post_cascade_response` maps to `Stop` (which carries no response text on stdin).
 - **Matchers:** regex against the Devin **tool name** (`read`, `edit`, `exec`, `grep`, `glob`, `mcp__<server>__<tool>`) — NOT Claude's `Bash`/`Edit`, so the shared guards reliably fire.
 - **Block contract:** the guard scripts emit `{"decision":"block","reason":...}` on stdout (plain mode) AND exit 2 — Devin honors both. Hooks run **without** `AI_TOOLKIT_HOOK_FORMAT=json` because Devin expects the flat `{"decision","reason"}` shape, not Claude's `hookSpecificOutput` envelope.
 - **Stdin payload:** flat `{ "hook_event_name", "tool_name", "tool_input" }` — already handled by `_hook-io.sh` via its `.tool_name` / `.tool_input.*` branches, so no normalizer change was needed.
@@ -11057,7 +11059,7 @@ Each command file carries the prompt in its markdown body (built from the SKILL.
 
 | opencode event             | Bash hook(s)                                                       |
 |----------------------------|--------------------------------------------------------------------|
-| `session.created`          | `session-start.sh` + `session-context.sh` + `mcp-health.sh`        |
+| `session.created`          | `session-start.sh` + `mcp-health.sh`                               |
 | `session.compacted`        | `pre-compact.sh` + `pre-compact-save.sh` (PreCompact equivalent)   |
 | `session.deleted`          | `session-end.sh` + `save-session.sh`                               |
 | `message.updated`          | `user-prompt-submit.sh` + `track-usage.sh`                         |
@@ -11895,9 +11897,9 @@ title: "Supported Tools Registry"
 category: reference
 service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
-version: "1.6.0"
+version: "1.7.0"
 created: "2026-04-23"
-last_updated: "2026-06-10"
+last_updated: "2026-06-23"
 description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code + 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
 ---
 
@@ -11920,7 +11922,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `claude-code` |
 | Docs | https://code.claude.com/docs (platform.claude.com/docs 307-redirects here) |
 | Release notes | https://github.com/anthropics/claude-code/releases |
-| Changelog | https://code.claude.com/docs/en/changelog (lists current 2.1.170) |
+| Changelog | https://code.claude.com/docs/en/changelog (lists current 2.1.186) |
 | Config paths | `~/.claude/settings.json`, `.claude/settings.json` (project, committed), `.claude/settings.local.json`, `CLAUDE.md`, `.claude/rules/*.md`, `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `~/.claude/themes/*.json` (v2.1.118+) |
 | 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` |
@@ -11971,8 +11973,8 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Release notes | https://github.blog/changelog/label/copilot/ |
 | Config paths | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `.github/prompts/*.prompt.md`, `AGENTS.md` |
 | Our generators | `scripts/generate_copilot.py` |
-| Tracked capabilities | `copilot-instructions.md`, Copilot Chat, Copilot Workspace, Copilot cloud agent, `applyTo`, custom agents, prompt files, `instructions.md`, MCP |
-| Tier notes | Custom agents (`.github/agents/*.agent.md`) and repo-level MCP config are Pro/Pro+/Business/Enterprise only and intentionally not integrated (class C per ecosystem-sync SOP). |
+| Tracked capabilities | `copilot-instructions.md`, Copilot Chat, Copilot Workspace, Copilot cloud agent, `applyTo`, custom agents, prompt files, `instructions.md`, `AGENTS.md`, MCP |
+| Tier notes | Custom agents (`.github/agents/*.agent.md`) and repo-level MCP config are Pro/Pro+/Business/Enterprise only and intentionally not integrated (class C per ecosystem-sync SOP). Copilot code review reads the nearest `AGENTS.md` automatically since the 2026-06-18 GA (all tiers); `ai-toolkit install --local --editors copilot` injects a `TOOLKIT:copilot-agents` section generated from `generate_agents_md.py` without clobbering Codex/opencode sections in the same file. The 4000-char cap on `copilot-instructions.md` / `*.instructions.md` was also removed (2026-06-12). |
 
 ### Gemini CLI
 
@@ -11985,7 +11987,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Our generators | `scripts/generate_gemini.py`, `scripts/generate_gemini_hooks.py` (profile>=standard), `scripts/generate_gemini_commands.py` (profile=full), `scripts/generate_gemini_skills.py` (profile=full) |
 | Tracked capabilities | `GEMINI.md`, `mcpServers`, tools, `settings.json`, `BeforeTool`, `AfterTool`, `BeforeToolSelection`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `Notification`, `PreCompress`, `SessionStart`, `SessionEnd`, `SKILL.md`, `activate_skill`, custom commands, `gemini-extension.json` (no native `Stop` event — generator maps Stop-equivalent to `AfterAgent`; 11 documented hook events total) |
 | Version probe | `gemini --version` |
-| Latest upstream | v0.45.2 (2026-06-05). NOTE: Gemini CLI drops free/paid tiers 2026-06-18 in favor of Antigravity CLI (we ship `generate_antigravity.py`); enterprise Code Assist keeps Gemini CLI. |
+| Latest upstream | v0.47.0 (2026-06-18). NOTE: Gemini CLI dropped free/paid individual tiers on 2026-06-18 in favor of Antigravity CLI (we ship `generate_antigravity.py`); enterprise Code Assist and paid API keys keep Gemini CLI, so the integration stays. The 11 hook events are unchanged. v0.48 preview migrates the `coreTools` setting to `tools.core` (a tool-allowlist key we do not emit, so no generator change). |
 
 ### Cline
 
@@ -12057,12 +12059,12 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Field | Value |
 |-------|-------|
 | ID | `codex-cli` |
-| Docs | https://developers.openai.com/codex (live docs site; config pages split into `/codex/config-basic`, `/codex/config-reference`, `/codex/config-advanced` plus `/codex/hooks`, `/codex/skills`; latest stable codex-cli 0.138.0, 2026-06) |
+| Docs | https://developers.openai.com/codex (live docs site; config pages split into `/codex/config-basic`, `/codex/config-reference`, `/codex/config-advanced` plus `/codex/hooks`, `/codex/skills`; latest stable codex-cli 0.142.0, 2026-06) |
 | Release notes | https://github.com/openai/codex/releases |
 | Config paths | `AGENTS.md`, `.agents/skills/*/SKILL.md`, `.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_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/`. |
-| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire all 10 to shared toolkit hook scripts, mirroring the Claude Code mapping in `app/hooks.json`. |
+| 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, mirroring the Claude Code mapping in `app/hooks.json`. `PostCompact` is not wired (its only hook was the removed environment-snapshot probe). |
 | Tracked handler types | `command` (emitted by default); `prompt` and `agent` available upstream but authored by hand |
 | Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path) |
 | Version probe | `codex --version` |
@@ -12079,7 +12081,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
-| Watch item | v1.16.0 (2026-06-05) ships an experimental v2 skill registry (flat-file skills, `slash` frontmatter key) — undocumented as of 2026-06-09; re-check next sync before touching `generate_opencode*.py`. |
+| Watch item | v1.16.0 (2026-06-05) shipped an experimental v2 skill registry (flat-file skills, `slash` frontmatter key). As of the 2026-06-23 sync (upstream v1.17.9) it is still undocumented and not stabilized: the skills docs show only the nested `SKILL.md` layout with no `slash` key, so `generate_opencode*.py` is unchanged. Re-check next sync. |
 
 ---
 
@@ -12244,7 +12246,6 @@ Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are
 |-------|--------|--------|
 | SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts + reset session-edit state |
 | SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
-| SessionStart | `session-context.sh` | Capture environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json` |
 | Notification | `notify-waiting.sh` | Cross-platform desktop notification |
 | PreToolUse | `guard-destructive.sh` | Block `rm -rf`, `DROP TABLE`, etc. |
 | PreToolUse | `guard-path.sh` | Block wrong-user path hallucination |

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.9.0",
+  "version": "4.10.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.9.0",
+  "version": "4.10.1",
   "description": "AI coding toolkit: 108 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",
@@ -71,6 +71,8 @@
   "files": [
     "bin/",
     "app/",
+    "!app/**/.claude",
+    "!app/**/.claude/**",
     "!app/**/__pycache__",
     "!app/**/*.pyc",
     "scripts/",

package/scripts/ecosystem_tools.json

@@ -1,7 +1,7 @@
 {
   "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-06-10",
+  "last_updated": "2026-06-23",
   "tools": [
     {
       "id": "claude-code",
@@ -200,6 +200,7 @@
         "custom agents",
         "prompt files",
         "instructions.md",
+        "AGENTS.md",
         "MCP"
       ],
       "version_probe": null

package/scripts/generate_augment_hooks.py

@@ -42,7 +42,6 @@ AUGMENT_HOOKS: dict[str, list[tuple[str, str]]] = {
     "SessionStart": [
         ("", "session-start.sh"),
         ("", "mcp-health.sh"),
-        ("", "session-context.sh"),
     ],
     "PreToolUse": [
         ("launch-process", "guard-destructive.sh"),

package/scripts/generate_codex_hooks.py

@@ -33,7 +33,6 @@ CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
     "SessionStart": [
         ("startup|resume", "session-start.sh"),
         ("startup|resume", "mcp-health.sh"),
-        ("startup|resume", "session-context.sh"),
     ],
     "PreToolUse": [
         ("Bash", "guard-destructive.sh"),
@@ -67,10 +66,6 @@ CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
         ("", "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_copilot.py

@@ -17,6 +17,12 @@ This generator produces three surfaces, all on the OSS/Free/Pro tier
    Invoked manually in VS Code Copilot Chat via ``/name``. Written only
    when ``generate()`` is called with a target directory.
 
+GitHub Copilot code review (generally available 2026-06-18, all tiers) now
+automatically reads the root-level ``AGENTS.md`` when generating review
+feedback. We already emit that file via ``scripts/generate_agents_md.py``, so
+no Copilot-specific emission is added here; ``AGENTS.md`` is tracked in this
+tool's ``capability_markers`` in ``scripts/ecosystem_tools.json``.
+
 Features that live on Pro/Pro+/Business/Enterprise tiers are intentionally
 not generated (classified as class C in the ecosystem-sync SOP):
   * ``.github/agents/*.agent.md`` — custom agent profiles (tier-gated)

package/scripts/generate_cursor_hooks.py

@@ -38,7 +38,6 @@ CURSOR_HOOKS: dict[str, list[tuple[str, str]]] = {
     "sessionStart": [
         ("", "session-start.sh"),
         ("", "mcp-health.sh"),
-        ("", "session-context.sh"),
     ],
     "beforeShellExecution": [
         ("", "guard-destructive.sh"),

package/scripts/generate_devin_hooks.py

@@ -61,11 +61,6 @@ DEVIN_HOOKS: dict[str, list[tuple[str, list[str]]]] = {
     "Stop": [
         ("", ["quality-check.sh", "save-session.sh", "stop-search-check.sh"]),
     ],
-    # Cascade's post_setup_worktree has no Devin equivalent; session-context
-    # moves to SessionStart (Devin fires SessionStart when a session begins).
-    "SessionStart": [
-        ("", ["session-context.sh"]),
-    ],
 }
 
 

package/scripts/generate_gemini_hooks.py

@@ -40,7 +40,6 @@ GEMINI_HOOKS: dict[str, list[tuple[str, str]]] = {
     "SessionStart": [
         ("", "session-start.sh"),
         ("", "mcp-health.sh"),
-        ("", "session-context.sh"),
     ],
     "BeforeTool": [
         # run_shell_command covers Bash-equivalent destructive patterns
@@ -67,10 +66,6 @@ GEMINI_HOOKS: dict[str, list[tuple[str, str]]] = {
         ("", "save-session.sh"),
         ("", "stop-search-check.sh"),
     ],
-    "BeforeModel": [
-        # Light-weight observability slot. Reuses the session-context probe.
-        ("", "session-context.sh"),
-    ],
     "SessionEnd": [
         ("", "session-end.sh"),
     ],

package/scripts/generate_opencode_plugin.py

@@ -11,7 +11,7 @@ opencode lifecycle events. Coverage map:
 
   opencode event              -> ai-toolkit Bash hook(s)
   ---------------------------------------------------------------
-  session.created             -> session-start.sh + session-context.sh + mcp-health.sh
+  session.created             -> session-start.sh + mcp-health.sh
   session.compacted           -> pre-compact.sh + pre-compact-save.sh
   session.deleted             -> session-end.sh + save-session.sh
   message.updated             -> user-prompt-submit.sh + track-usage.sh
@@ -79,7 +79,6 @@ export const AiToolkitHooks = async ({ $, project, directory, worktree }) => ({
     switch (event.type) {
       case "session.created":
         await runHook($, "session-start.sh", payload);
-        await runHook($, "session-context.sh", payload);
         await runHook($, "mcp-health.sh", payload);
         break;
       case "session.compacted":

package/scripts/generate_windsurf_hooks.py

@@ -72,9 +72,6 @@ WINDSURF_HOOKS: dict[str, list[str]] = {
         "save-session.sh",
         "stop-search-check.sh",
     ],
-    "post_setup_worktree": [
-        "session-context.sh",
-    ],
 }
 
 

package/scripts/install_steps/ai_tools.py

@@ -352,6 +352,39 @@ def inject_with_rules(
     print(f"  Updated: {target_file}")
 
 
+def _inject_text_section(target_file: Path, section: str, text: str) -> None:
+    """Inject generated text into one marker section without touching others."""
+    target_file.parent.mkdir(parents=True, exist_ok=True)
+    existing = target_file.read_text(encoding="utf-8") if target_file.is_file() else ""
+    existing = _trim_trailing_blanks(_strip_section(existing, section))
+
+    parts: list[str] = []
+    if existing.strip():
+        parts.append(existing)
+        parts.append("")
+    parts.extend([
+        f"<!-- TOOLKIT:{section} START -->",
+        "<!-- Auto-injected by ai-toolkit. Re-run to update. -->",
+        "",
+        text.rstrip("\n"),
+        "",
+        f"<!-- TOOLKIT:{section} END -->",
+    ])
+
+    output = _collapse_blank_runs("\n".join(parts) + "\n").lstrip("\n")
+    target_file.write_text(output, encoding="utf-8")
+
+
+def _install_copilot_agents_md(cwd: Path) -> None:
+    """Emit root AGENTS.md for GitHub Copilot without clobbering other tools."""
+    generated = run_script("generate_agents_md.py", capture=True)
+    if not generated.strip():
+        print("  ERROR: generate_agents_md.py produced no output")
+        return
+    _inject_text_section(cwd / "AGENTS.md", "copilot-agents", generated)
+    print("  Updated: AGENTS.md (Copilot agent instructions)")
+
+
 def run_script(script_name: str, *args: str, capture: bool = False) -> str:
     """Run a script from the scripts/ directory (prefers .py over .sh)."""
     scripts_dir = toolkit_dir / "scripts"
@@ -724,7 +757,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
 
     # Editor-specific dry-run messages
     _EDITOR_DRY_RUN = {
-        "copilot":      "  Would inject: .github/copilot-instructions.md",
+        "copilot":      "  Would inject: .github/copilot-instructions.md + AGENTS.md",
         "cursor":       "  Would generate: .cursorrules + .cursor/rules/*.mdc",
         "windsurf":     "  Would generate: .windsurfrules + .devin/rules/*.md + .windsurf/rules/*.md",
         "cline":        "  Would generate: .clinerules/*.md",
@@ -949,6 +982,7 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
             cwd / ".github" / "copilot-instructions.md",
             rules_dir,
         )
+        _install_copilot_agents_md(cwd)
         # `standard` and above: emit path-specific instructions + prompt files
         # (directory mode). `minimal` stays backwards-compatible with v2.
         if add_copilot_dir:

package/app/hooks/session-context.sh

@@ -1,63 +0,0 @@
-#!/usr/bin/env bash
-# session-context.sh — Capture session context at start for later reference.
-#
-# Fires on: SessionStart
-# Saves environment snapshot to JSON for cross-hook and cross-session use.
-# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
-
-# shellcheck source=_profile-check.sh
-source "$(dirname "$0")/_profile-check.sh"
-
-# Read from stdin (Claude Code passes JSON with .session_id)
-INPUT=$(cat)
-SESSION=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
-[ -z "$SESSION" ] && SESSION="$$"
-SESSIONS_DIR="$HOME/.softspark/ai-toolkit/sessions"
-mkdir -p "$SESSIONS_DIR"
-
-CONTEXT_FILE="$SESSIONS_DIR/${SESSION}.json"
-
-# Gather context
-WORKDIR="$(pwd)"
-GIT_BRANCH=""
-GIT_STATUS=""
-if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-    GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "detached")
-    GIT_STATUS=$(git status --short 2>/dev/null | head -20)
-fi
-
-NODE_VERSION=""
-if command -v node >/dev/null 2>&1; then
-    NODE_VERSION=$(node --version 2>/dev/null)
-fi
-
-PYTHON_VERSION=""
-if command -v python3 >/dev/null 2>&1; then
-    PYTHON_VERSION=$(python3 --version 2>/dev/null | awk '{print $2}')
-fi
-
-CURRENT_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-
-# Write JSON using python3 for proper escaping
-python3 - "$CONTEXT_FILE" "$WORKDIR" "$GIT_BRANCH" "$GIT_STATUS" "$CURRENT_DATE" "$NODE_VERSION" "$PYTHON_VERSION" <<'PY'
-import json
-import sys
-import os
-
-context_file = sys.argv[1]
-data = {
-    "pwd": sys.argv[2],
-    "git_branch": sys.argv[3],
-    "git_status": sys.argv[4],
-    "date": sys.argv[5],
-    "node_version": sys.argv[6],
-    "python_version": sys.argv[7],
-}
-
-tmp = context_file + ".tmp"
-with open(tmp, "w") as f:
-    json.dump(data, f, indent=2)
-os.replace(tmp, context_file)
-PY
-
-exit 0