@softspark/ai-toolkit 4.9.0 → 4.10.0

package/CHANGELOG.md

@@ -7,6 +7,19 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## 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,16 @@
 [![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-1195%20passing-success)](tests/)
 
-## What's New in v4.9.0
+## What's New in v4.10.0
 
-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.0 gets auto-generated session files out of your repositories and removes a dead lifecycle hook.
 
-- **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.
+- **Per-repo session storage outside the repo**: `save-session.sh`, `session-end.sh`, `session-start.sh`, and `pre-compact.sh` now keep `session-context.md`, `session-end.md`, checkpoints, and `decisions.md` under `~/.softspark/ai-toolkit/sessions/<repo-key>/` instead of each project's `.claude/` — no more generated files piling up in every repo. Keyed per repo (git root with `/` → `-`) so projects stay isolated.
+- **No silent migration**: the new store starts fresh; pre-existing in-repo `.claude/session-*.md` are left for you to delete.
+- **Dropped the dead `session-context.sh` hook**: it wrote a `${SESSION}.json` environment snapshot nobody ever read (Constitution Art. VI.1). Removed across `app/hooks.json` and all 7 editor hook generators (cursor, windsurf, codex, devin, augment, gemini, opencode).
+- **Test count**: 1197 → 1195.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -148,7 +148,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 (1195 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.0",
   "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/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/kb/reference/architecture-overview.md

@@ -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/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

@@ -170,7 +170,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |

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

@@ -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 |
@@ -9043,13 +9042,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 +9195,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 +9266,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 +9281,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 +9354,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 +9512,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 +9541,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 +9582,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 +11053,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`                         |
@@ -12062,7 +12058,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
@@ -12244,7 +12240,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.0",
   "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.0",
   "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",

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_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/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