@softspark/ai-toolkit 4.15.1 → 4.16.0

package/CHANGELOG.md

@@ -7,6 +7,40 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.16.0 — Native tool-output filtering (2026-07-24)
+
+Minor release. Adds a dependency-free, opt-in native tool-output filter for Claude Code and hardens the enterprise configuration, session-isolation, and editor-adapter surfaces around it. The filter ships disabled; `observe` and `safe` are per-project opt-ins. No source catalog count change (44 agents, 108 skills).
+
+### BREAKING
+
+- **Unknown config keys rejected** — `.softspark-toolkit.json` and `ai-toolkit.config.json` are now validated against a closed set of top-level keys. Files carrying typos or unsupported keys that previously validated will fail `config validate` and `config check` until the key is removed.
+- **Constitution Article VII reserved** — reserved articles expand from I-VI to I-VII, so custom amendments must start at article 8 instead of 7. A base config that defines article 7 was valid before and now aborts validation.
+- **Plugin manifests require `requires`** — `plugin.json` must declare a non-empty `requires` map of non-empty string constraints. Existing manifests without the field fail schema validation.
+- **Lock files go stale on every toolkit version bump** — `.softspark-toolkit.lock.json` records the toolkit version and is reported stale when it differs from the running version. This is intentional integrity design: re-run `install --local` or `update --local` after upgrading to refresh the lock.
+
+### Added
+
+- **Native tool-output filter** — added a dependency-free, opt-in Claude Code `PostToolUse` filter with `off`, `observe`, and `safe` modes. The initial version handles only allowlisted successful Bash test and validation output through deterministic `repeat-lines` and `tap-success` profiles.
+- **Exact ephemeral recovery** — every safe replacement is preceded by a private, bounded, session-scoped copy of the exact native response object. Opaque handles support manual recovery and cleanup without storing commands, paths, session IDs, or raw output in telemetry.
+- **Output-filter operations** — added inspect, status, recover, and clean entry points under `ai-toolkit output-filter`, plus a deterministic benchmark script for the built-in profiles.
+- **Project policy inheritance** — `toolOutputFilter` participates in schema validation, inheritance, merge, lock, local install, and managed project-policy cleanup.
+- **GitHub Copilot compatibility reference** — added `kb/reference/copilot-compatibility.md` documenting the Copilot integration surface, with cross-links from the Codex CLI, opencode, and global-install references.
+
+### Fixed
+
+- **Hook safety** — `guard-path.sh` now blocks when `jq` is unavailable instead of silently skipping path validation. Codex Bash hooks apply the same path guard during `PreToolUse` and `PermissionRequest`.
+- **Filter eligibility** — allowlisted task names now use exact token boundaries, and recovery-backed filtering rejects unsafe or unbounded native session identifiers instead of creating mismatched cleanup paths.
+- **Session isolation** — edit tracking uses per-session state files, hook adapters preserve native OpenCode and Augment session identifiers, unsafe identifiers receive collision-resistant normalized names, and pre-compact snapshots prefer the payload session identifier.
+- **Editor adapter integrity** — OpenCode propagates guard exit code 2 as a blocked tool execution, Gemini preserves malformed settings, rejects symlinked destinations, and writes valid updates atomically, while Claude app exports omit the Claude Code-only output replacement hook.
+- **Statusline token trend** — the documented baseline file now drives a visible input/output token trend, including payloads without optional cost or effort fields.
+- **Brand-voice fact checks** — missing extracted facts now fail the quality gate, while inline-code extraction is restricted to identifier-shaped values to avoid false positives.
+- **Enterprise configuration** — config and lock readers reject non-object JSON and invalid UTF-8 without traceback, invalid output-filter updates preserve the last valid managed policy, and lock staleness checks cover lock format, toolkit version, source, resolved version, and content integrity. Constitution Articles I through VII remain reserved, `requiredPlugins` materializes enforceable enable intent, and plugin manifests validate non-empty dependency constraints.
+- **Recovery cleanup** — session end and global uninstall remove only validated ai-toolkit recovery artifacts, remain idempotent for foreign-only trees, and abort before other mutations when the recovery namespace is unsafe.
+- **Flaky pack-audit tests** — npm's update-notifier stderr no longer corrupts JSON parsing in the package-content tests (`npm_config_update_notifier=false` in the test environment).
+- **Linux-only test failures** — the jq-unavailable guard test hides `jq` via a stub `PATH` (plain `PATH=/bin` keeps `jq` visible on usrmerge systems where `/bin` is `/usr/bin`), and the foreign-recovery uninstall test now asserts the message `uninstall.py` actually prints. Both passed on macOS only because bash 3.2 does not enforce bare `[[ ]]` bats assertions.
+
+Hook entries: 28 → 29. Test count: 1377 → 1477.
+
 ## v4.15.1 — Copilot profile cleanup (2026-07-15)
 
 ### Fixed

package/README.md

@@ -6,15 +6,17 @@
 [![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-1377%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1477%20passing-success)](tests/)
 
-## What's New in v4.15.1
+## What's New in v4.16.0
 
-v4.15.1 fixes Copilot project upgrades and profile downgrades that could leave obsolete toolkit instructions, prompts, and hooks active.
+v4.16.0 adds a dependency-free, opt-in native tool-output filter for Claude Code and hardens the enterprise configuration surface around it.
 
-- **Complete legacy cleanup**: byte-exact generated files from v3.0.0 through v4.14.1 are recognized and removed when switching a project to `minimal`.
-- **No user-file deletion**: unmarked prompts and instructions that do not match a historical toolkit artifact remain untouched.
-- **Race-safe removal**: managed cleanup uses pinned directory descriptors and transactional rollback instead of path-based deletion.
+- **Native tool-output filter**: opt-in `PostToolUse` filter with `off`, `observe`, and `safe` modes; ships disabled, handles only allowlisted successful Bash test/validation output.
+- **Exact ephemeral recovery**: every safe replacement keeps a private, bounded, session-scoped copy of the original response, recoverable via `ai-toolkit output-filter recover`.
+- **Output-filter CLI**: `ai-toolkit output-filter status|inspect|recover|clean` plus a deterministic benchmark for the built-in profiles.
+- **Stricter config validation**: unknown top-level config keys are rejected, plugin manifests must declare `requires`, and lock files go stale on toolkit version bumps.
+- **GitHub Copilot compatibility reference**: new `kb/reference/copilot-compatibility.md` documenting the Copilot integration surface.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -89,7 +91,10 @@ ai-toolkit claude-app export --verify
 ```
 
 Re-export and re-upload after toolkit or registered-rule updates. Skills work
-in Chat and Cowork; hooks and sub-agents are active only in Cowork.
+in Chat and Cowork; hooks and sub-agents are active only in Cowork. The native
+tool-output replacement hook remains Claude Code-only and is excluded from the
+Claude app archive until that runtime has an independently verified replacement
+contract.
 
 ### Install Profiles
 
@@ -140,7 +145,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | `skills/` (hybrid) | 30 | Slash commands with agent knowledge base |
 | `skills/` (knowledge) | 46 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
 | `agents/` | 44 | Specialized agents across 10 categories |
-| `hooks/` | 28 entries / 14 events + statusLine | Quality gates, path safety, prompt governance, loop guard, session lifecycle |
+| `hooks/` | 29 entries / 14 events + statusLine | Quality gates, path safety, prompt governance, loop guard, output filtering, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
 | `constitution.md` | 7 articles | Machine-enforced safety rules |
 | `rules/` | auto-synced | Global/project rule files for Claude and other editors |
@@ -156,7 +161,7 @@ ai-toolkit/
 │   ├── agents/          # 44 agent definitions
 │   ├── skills/          # 108 skills (task / hybrid / knowledge)
 │   ├── rules/           # Source rules synced into Claude/editor rule files
-│   ├── hooks/           # Hook scripts (28 entries, 14 lifecycle events)
+│   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
 │   ├── claude-app/      # Generated Chat/Cowork plugin rules, hooks, instructions
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
 │   ├── output-styles/   # System prompt output style overrides
@@ -164,7 +169,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1377 tests)
+├── tests/               # Bats and Python test suite (1477 tests)
 └── CHANGELOG.md
 ```
 
@@ -176,7 +181,9 @@ ai-toolkit/
 
 **Machine-enforced constitution** — 7-article safety constitution enforced via `PreToolUse` hooks that actually block `rm -rf`, `DROP TABLE`, and irreversible operations. Not just documentation.
 
-**29 lifecycle hooks** — Executable scripts across 14 events (SessionStart → SessionEnd, plus InstructionsLoaded + ConfigChange). Guards, governance, quality gates, session persistence, MCP health checks, revert protection, test-cohesion enforcement, loop guard, search-first discipline. See [Hooks Catalog](kb/reference/hooks-catalog.md).
+**29 lifecycle hook entries:** Executable handlers across 14 events (SessionStart → SessionEnd, plus InstructionsLoaded + ConfigChange). Guards, governance, quality gates, session persistence, MCP health checks, revert protection, test-cohesion enforcement, loop guard, search-first discipline, and opt-in output filtering. See [Hooks Catalog](kb/reference/hooks-catalog.md).
+
+**Native tool-output filtering** — dependency-free, post-execution filtering for successful Claude Code Bash output, shipped **disabled by default** (`off`). Neither `off` nor `observe` ever replaces output; opt-in `safe` mode replaces only validated `repeat-lines` or `tap-success` results after exact ephemeral recovery is available. Failures, diagnostics, unsupported payloads, and unavailable recovery always pass through unchanged. See [Tool Output Filter](kb/reference/tool-output-filter.md).
 
 **Security scanning** — `/skill-audit` for code-level risks, `/cve-scan` for dependency CVEs. Both CI-ready with exit codes.
 
@@ -291,6 +298,7 @@ Need multi-agent coordination?
 | Ecosystem Comparison | [kb/reference/comparison.md](kb/reference/comparison.md) |
 | Codex CLI Compatibility | [kb/reference/codex-cli-compatibility.md](kb/reference/codex-cli-compatibility.md) |
 | opencode Compatibility | [kb/reference/opencode-compatibility.md](kb/reference/opencode-compatibility.md) |
+| GitHub Copilot Compatibility | [kb/reference/copilot-compatibility.md](kb/reference/copilot-compatibility.md) |
 | Maintenance SOP | [kb/procedures/maintenance-sop.md](kb/procedures/maintenance-sop.md) |
 
 ---

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

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.15.1",
+  "version": "4.16.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -8,7 +8,7 @@ Universal multi-agent system for software development. Works across all reposito
 |-----------|-------|
 | Agents | See agents catalog |
 | Skills | See skills catalog |
-| Hooks | 14 events / 28 entries (SessionStart ×2, Notification ×1, PreToolUse ×5, UserPromptSubmit ×2, PostToolUse ×5, Stop ×4, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1, InstructionsLoaded ×1, ConfigChange ×1) plus statusLine |
+| Hooks | 14 events / 29 entries (SessionStart ×2, Notification ×1, PreToolUse ×5, UserPromptSubmit ×2, PostToolUse ×6, Stop ×4, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1, InstructionsLoaded ×1, ConfigChange ×1) plus statusLine |
 
 ---
 
@@ -333,6 +333,7 @@ Lead Session (You)
 | `UserPromptSubmit` | Before prompt execution | Usage tracking (skill invocations) |
 | `PostToolUse` | After edit/write tools | Lightweight validation reminder |
 | `PostToolUse` | After search tools | Clears the per-session search-first flag |
+| `PostToolUse` | After successful Bash tools | Observes or safely replaces eligible text output after exact recovery is stored; Claude Code only |
 | `Stop` | After Claude response | Multi-language quality check + saves session context |
 | `Stop` | After Claude response | Blocks skipped search-first only when a real MCP/Web search provider is configured, with Codex log fallback |
 | `TaskCompleted` | Teammate marks task done | Multi-language lint + type check (blocking) |
@@ -341,7 +342,7 @@ Lead Session (You)
 | `SubagentStop` | Subagent completes | Handoff checklist for spawned subagents |
 | `Notification` | Claude notification | OS notification |
 | `PreCompact` | Before compaction | Saves context before compaction boundary |
-| `SessionEnd` | Claude session ends | Writes handoff snapshot for the next session |
+| `SessionEnd` | Claude session ends | Cleans owned output recovery, then writes the next-session handoff snapshot |
 
 ---
 
@@ -376,7 +377,7 @@ The `inject_section_cli.py` script provides a stable marker-based injection API.
 `scripts/compile_slm.py` compiles the full toolkit (20K+ tokens) into a minimal system prompt for Small Language Models (2K-16K tokens). Pipeline: Parse → Score → Compress → Pack → Emit. Supports 4 compression levels (ultra-light, light, standard, extended), 4 output formats (raw, ollama, json-string, aider), persona-aware scoring, and language-aware rule filtering. Profile `offline-slm` in `manifest.json`. Constitution is always included (non-negotiable).
 
 ### Config Inheritance (`extends`)
-`scripts/config_resolver.py`, `config_merger.py`, `config_validator.py`, `config_cli.py`, `config_scaffold.py`, `config_lock.py`. Enterprise configuration inheritance via `.softspark-toolkit.json` `extends` field. Resolves base configs from npm packages, Git URLs, or local paths. Layered deep merge with constitution immutability (Articles I-VII absolute), enforce constraints (`requiredAgents`, `forbidOverride`, `minHookProfile`), override validation (`override: true` + justification), and lock file (`.softspark-toolkit.lock.json`). CLI: `config validate`, `config diff`, `config init`, `config create-base`, `config check`. Integrated into `install --local` and `update --local` flows.
+`scripts/config_resolver.py`, `config_merger.py`, `config_validator.py`, `config_cli.py`, `config_scaffold.py`, `config_lock.py`. Enterprise configuration inheritance via `.softspark-toolkit.json` `extends` field. Resolves base configs from npm packages, Git URLs, or local paths. Layered deep merge with constitution immutability (Articles I-VII absolute), enforce constraints (`requiredAgents`, `requiredPlugins`, `forbidOverride`, `minHookProfile`), override validation (`override: true` + justification), and a source/version/integrity lock file (`.softspark-toolkit.lock.json`). `requiredPlugins` materializes configuration intent and does not install plugin packs. CLI: `config validate`, `config diff`, `config init`, `config create-base`, `config check`. Integrated into `install --local` and `update --local` flows.
 
 ### Project Registry
 `scripts/install_steps/project_registry.py`, `scripts/update_projects.py`, `scripts/projects_cli.py`. Tracks all `--local` installed projects in `~/.softspark/ai-toolkit/projects.json`. `ai-toolkit update` propagates to all registered projects in parallel via `ThreadPoolExecutor`. CLI: `ai-toolkit projects`, `--prune`, `remove <path>`.

package/app/hooks/_hook-io.sh

@@ -20,8 +20,11 @@ hook_prompt() {
 }
 
 hook_session_id() {
-    local sid
-    sid=$(hook_json '.session_id // empty')
+    local sid raw_sid digest
+    sid=$(hook_json '.session_id // .conversation_id // .conversationId // empty')
+    if [ -z "$sid" ] || [ "$sid" = "null" ]; then
+        sid="${CLAUDE_SESSION_ID:-}"
+    fi
     if [ -z "$sid" ] || [ "$sid" = "null" ]; then
         local tp
         tp=$(hook_json '.transcript_path // empty')
@@ -30,7 +33,19 @@ hook_session_id() {
         fi
     fi
     [ -z "$sid" ] && sid="default"
-    printf '%s' "$sid" | LC_ALL=C tr -c 'a-zA-Z0-9_-' '_'
+    raw_sid="$sid"
+    sid=$(printf '%s' "$sid" | LC_ALL=C tr -c 'a-zA-Z0-9_-' '_')
+    if [ "$sid" != "$raw_sid" ] || [ "${#sid}" -gt 160 ]; then
+        if command -v shasum >/dev/null 2>&1; then
+            digest=$(printf '%s' "$raw_sid" | shasum -a 256 | cut -d ' ' -f 1)
+        elif command -v sha256sum >/dev/null 2>&1; then
+            digest=$(printf '%s' "$raw_sid" | sha256sum | cut -d ' ' -f 1)
+        else
+            digest=$(printf '%s' "$raw_sid" | cksum | cut -d ' ' -f 1)
+        fi
+        sid="${sid:0:135}-${digest:0:24}"
+    fi
+    printf '%s' "$sid"
 }
 
 hook_command() {

package/app/hooks/ai-toolkit-statusline.sh

@@ -26,6 +26,7 @@
 #   AI_TOOLKIT_STATUSLINE_NO_GIT    — "1" hides git segment
 #   AI_TOOLKIT_STATUSLINE_NO_EFFORT — "1" hides effort segment
 #   AI_TOOLKIT_STATUSLINE_SHOW_COST — "1" appends Claude Code's reported cost
+#   AI_TOOLKIT_STATUSLINE_BASELINE  — totals JSON file used for token trend
 #   AI_TOOLKIT_STATUSLINE_DUMP      — "1" writes stdin to /tmp/cc-statusline-input.json
 #
 # Performance: ~50ms (single python3 parse of stdin, one git invocation).
@@ -62,7 +63,7 @@ if [ "${AI_TOOLKIT_STATUSLINE_DUMP:-0}" = "1" ] && [ -n "$INPUT" ]; then
 fi
 
 PARSED="$(printf '%s' "$INPUT" | python3 -c '
-import json, sys
+import json, os, sys
 def get(d, path):
     for k in path.split("."):
         d = d.get(k) if isinstance(d, dict) else None
@@ -77,6 +78,11 @@ def fmt_tokens(n):
     if n >= 1000:
         return f"{n/1000:.1f}k"
     return str(n)
+def as_int(n):
+    try:
+        return int(n)
+    except (TypeError, ValueError):
+        return 0
 try:
     d = json.loads(sys.stdin.read() or "{}")
 except Exception:
@@ -84,18 +90,34 @@ except Exception:
 cwd = get(d, "cwd") or ""
 model = get(d, "model.display_name") or get(d, "model.id") or ""
 ctx_pct = get(d, "context_window.used_percentage")
-in_tok = fmt_tokens(get(d, "context_window.total_input_tokens"))
-out_tok = fmt_tokens(get(d, "context_window.total_output_tokens"))
+in_raw = get(d, "context_window.total_input_tokens")
+out_raw = get(d, "context_window.total_output_tokens")
+in_tok = fmt_tokens(in_raw)
+out_tok = fmt_tokens(out_raw)
 cost = get(d, "cost.total_cost_usd")
 try:
     cost_str = f"{float(cost):.2f}" if cost != "" else ""
 except (TypeError, ValueError):
     cost_str = ""
 effort = get(d, "effort.level") or ""
-print(f"{cwd}\t{model}\t{ctx_pct}\t{in_tok}\t{out_tok}\t{cost_str}\t{effort}")
+trend = ""
+baseline_path = os.environ.get("AI_TOOLKIT_STATUSLINE_BASELINE", "")
+if baseline_path:
+    try:
+        with open(os.path.expanduser(baseline_path), encoding="utf-8") as baseline_file:
+            baseline = json.load(baseline_file)
+        baseline_total = baseline.get("total") if isinstance(baseline, dict) else None
+        if isinstance(baseline_total, (int, float)) and baseline_total > 0:
+            delta = (as_int(in_raw) + as_int(out_raw) - baseline_total) / baseline_total
+            arrow = "↓" if delta < 0 else "↑" if delta > 0 else "·"
+            trend = f"{arrow}{abs(delta) * 100:.0f}%"
+    except (OSError, json.JSONDecodeError, TypeError, ValueError):
+        pass
+fields = (cwd, model, ctx_pct, in_tok, out_tok, cost_str, effort, trend)
+print("\x1f".join(str(field) for field in fields))
 ' 2>/dev/null)"
 
-IFS=$'\t' read -r CWD MODEL_NAME CTX_USED IN_TOK OUT_TOK COST EFFORT <<< "$PARSED"
+IFS=$'\x1f' read -r CWD MODEL_NAME CTX_USED IN_TOK OUT_TOK COST EFFORT TREND <<< "$PARSED"
 [ -z "$CWD" ] && CWD="$PWD"
 
 # ── Segment: prompt + dir ────────────────────────────────────────────────────
@@ -162,6 +184,9 @@ SEG_TOKENS=""
 if [ "${AI_TOOLKIT_STATUSLINE_NO_TOKENS:-0}" != "1" ] && [ -n "$IN_TOK" ] && \
    { [ "$IN_TOK" != "0" ] || [ "$OUT_TOK" != "0" ]; }; then
     SEG_TOKENS="  ${C_BOLD_GREEN}\xe2\x86\x91${IN_TOK}${C_RESET} ${C_RED}\xe2\x86\x93${OUT_TOK}${C_RESET}"
+    if [ -n "$TREND" ]; then
+        SEG_TOKENS+=" ${C_DIM}trend:${C_RESET}${TREND}"
+    fi
     if [ "${AI_TOOLKIT_STATUSLINE_SHOW_COST:-0}" = "1" ] && [ -n "$COST" ]; then
         SEG_TOKENS+=" ${C_BOLD_GREEN}\$${COST}${C_RESET}"
     fi

package/app/hooks/filter-tool-output.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# Claude PostToolUse adapter for the native tool-output filter.
+
+HOOK_SOURCE="${BASH_SOURCE[0]}"
+HOOK_DIR="${HOOK_SOURCE%/*}"
+[[ "$HOOK_DIR" == "$HOOK_SOURCE" ]] && HOOK_DIR="."
+# shellcheck source=_profile-check.sh
+source "$HOOK_DIR/_profile-check.sh"
+
+OWNER_MARKER="ai-toolkit-output-filter-policy-v1"
+GLOBAL_POLICY="$HOME/.softspark/ai-toolkit/hooks/output-filter-policy.json"
+PROJECTS_REGISTRY="$HOME/.softspark/ai-toolkit/projects.json"
+
+is_regular_file() {
+    [[ -f "$1" && -r "$1" && ! -L "$1" ]]
+}
+
+# A project policy is trusted only for projects the user registered via
+# `ai-toolkit install --local`. The owner marker alone is a public constant,
+# so a cloned repo must never be able to self-enable filtering with it.
+is_registered_project() {
+    is_regular_file "$PROJECTS_REGISTRY" &&
+        grep -qF "\"$1\"" "$PROJECTS_REGISTRY" 2>/dev/null
+}
+
+if [[ "${AI_TOOLKIT_OUTPUT_FILTER_DISABLE:-}" == "1" ]]; then
+    exit 0
+fi
+
+if [[ -n "${AI_TOOLKIT_OUTPUT_FILTER_POLICY:-}" ]]; then
+    POLICY_PATH="$AI_TOOLKIT_OUTPUT_FILTER_POLICY"
+    if ! is_regular_file "$POLICY_PATH"; then
+        exit 0
+    fi
+else
+    PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+    PROJECT_POLICY="$PROJECT_ROOT/.claude/ai-toolkit-output-filter.json"
+    PROJECT_OWNER="$PROJECT_ROOT/.claude/.ai-toolkit-output-filter.owner"
+    if [[ -L "$PROJECT_ROOT" || -L "$PROJECT_ROOT/.claude" ]]; then
+        exit 0
+    fi
+    if is_registered_project "$PROJECT_ROOT" &&
+       is_regular_file "$PROJECT_OWNER" &&
+       [[ "$(<"$PROJECT_OWNER")" == "$OWNER_MARKER" ]]; then
+        if ! is_regular_file "$PROJECT_POLICY"; then
+            exit 0
+        fi
+        POLICY_PATH="$PROJECT_POLICY"
+    else
+        POLICY_PATH="$GLOBAL_POLICY"
+    fi
+fi
+
+if ! is_regular_file "$POLICY_PATH"; then
+    exit 0
+fi
+POLICY_CONTENT="$(<"$POLICY_PATH")" || exit 0
+if [[ ${#POLICY_CONTENT} -gt 65536 ]]; then
+    exit 0
+fi
+MODE_OFF_PATTERN='"mode"[[:space:]]*:[[:space:]]*"off"'
+MODE_ACTIVE_PATTERN='"mode"[[:space:]]*:[[:space:]]*"(observe|safe)"'
+if [[ "$POLICY_CONTENT" =~ $MODE_OFF_PATTERN ]]; then
+    exit 0
+fi
+if [[ ! "$POLICY_CONTENT" =~ $MODE_ACTIVE_PATTERN ]]; then
+    exit 0
+fi
+
+RUNTIME_PATH="${AI_TOOLKIT_OUTPUT_FILTER_HOOK_RUNTIME:-${AI_TOOLKIT_OUTPUT_FILTER_CLI:-$HOME/.softspark/ai-toolkit/scripts/output_filter_hook.py}}"
+if ! is_regular_file "$RUNTIME_PATH"; then
+    exit 0
+fi
+python3 -S "$RUNTIME_PATH" hook --policy "$POLICY_PATH" 2>/dev/null || true
+
+exit 0

package/app/hooks/governance-capture.sh

@@ -11,12 +11,12 @@ source "$(dirname "$0")/_profile-check.sh"
 LOG_DIR="$HOME/.softspark/ai-toolkit"
 LOG_FILE="$LOG_DIR/governance.log"
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-SESSION="${CLAUDE_SESSION_ID:-unknown}"
 
 # shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"
+SESSION=$(hook_session_id)
 TOOL_NAME=$(hook_tool_name)
 
 if [ -z "$TOOL_NAME" ]; then

package/app/hooks/guard-path.sh

@@ -14,8 +14,8 @@ REAL_HOME="$HOME"
 
 # Verify jq is available — required for JSON parsing
 if ! command -v jq >/dev/null 2>&1; then
-    echo "WARNING: guard-path.sh requires jq but it is not installed. Path validation skipped." >&2
-    exit 0
+    echo "BLOCKED: guard-path.sh requires jq but it is not installed. Path validation cannot run safely." >&2
+    exit 2
 fi
 
 # Collect ALL path values from tool input into a single list (one per line).

package/app/hooks/post-tool-use.sh

@@ -12,18 +12,20 @@ source "$(dirname "$0")/_locate-toolkit.sh"
 # shellcheck source=_hook-io.sh
 source "$(dirname "$0")/_hook-io.sh"
 
-# Read from stdin (Claude Code passes JSON with .tool_name, .tool_input)
+# Read from stdin (Claude Code passes JSON with .tool_name, .tool_input).
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 TOOL_NAME=$(hook_tool_name)
 [ -z "$TOOL_NAME" ] && TOOL_NAME="unknown"
 FILE_PATH=$(hook_file_path)
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
+SESSION_ID=$(hook_session_id)
+SESSION_ARGS=(--session-id "$SESSION_ID")
 
 # Append edit to session state (used by revert-guard, test-cohesion, quality-gate).
 if [ -n "$FILE_PATH" ] && [ -n "$TOOLKIT_DIR" ] && command -v python3 >/dev/null 2>&1; then
     python3 "$TOOLKIT_DIR/scripts/session_state.py" append \
         --tool "$TOOL_NAME" --path "$FILE_PATH" \
-        ${SESSION_ID:+--session-id "$SESSION_ID"} >/dev/null 2>&1 || true
+        "${SESSION_ARGS[@]}" >/dev/null 2>&1 || true
 fi
 
 if [ -z "$FILE_PATH" ]; then

package/app/hooks/pre-compact-save.sh

@@ -7,19 +7,20 @@
 
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
 
 SAVE_DIR="$HOME/.softspark/ai-toolkit/compactions"
 mkdir -p "$SAVE_DIR"
 
 # Read from stdin (Claude Code passes JSON with .session_id)
+# shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 TIMESTAMP=$(date -u +"%Y-%m-%d_%H-%M-%S")
-SESSION=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
-[ -z "$SESSION" ] && SESSION="$$"
+SESSION=$(hook_session_id)
 SAVE_FILE="$SAVE_DIR/${TIMESTAMP}_${SESSION}.txt"
 
 # Gather context
-SESSION="${CLAUDE_SESSION_ID:-unknown}"
 WORKDIR="$(pwd)"
 BRANCH=""
 if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then

package/app/hooks/quality-gate.sh

@@ -9,6 +9,16 @@
 source "$(dirname "$0")/_profile-check.sh"
 # shellcheck source=_locate-toolkit.sh
 source "$(dirname "$0")/_locate-toolkit.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+
+INPUT=""
+if [ ! -t 0 ]; then
+    # shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
+    INPUT=$(cat)
+fi
+SESSION_ID=$(hook_session_id)
+SESSION_ARGS=(--session-id "$SESSION_ID")
 
 run_required() {
     local label="$1"
@@ -44,7 +54,8 @@ cohesion_for_session_edits() {
     command -v python3 >/dev/null 2>&1 || return 0
 
     local edits
-    edits=$(python3 "$TOOLKIT_DIR/scripts/session_state.py" list 2>/dev/null)
+    edits=$(python3 "$TOOLKIT_DIR/scripts/session_state.py" list \
+        "${SESSION_ARGS[@]}" 2>/dev/null)
     [ -z "$edits" ] && return 0
 
     # shellcheck disable=SC2206  # word-splitting is intentional, paths have no spaces

package/app/hooks/revert-guard.sh

@@ -25,6 +25,8 @@ source "$(dirname "$0")/_hook-io.sh"
 # shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
 INPUT=$(cat)
 COMMAND=$(hook_command)
+SESSION_ID=$(hook_session_id)
+SESSION_ARGS=(--session-id "$SESSION_ID")
 
 [ -z "$COMMAND" ] && exit 0
 [ "${CLAUDE_REVERT_OK:-0}" = "1" ] && exit 0
@@ -54,7 +56,7 @@ EOF
 
 # git reset --hard / git clean -fd: clobber-style, scope = all session edits.
 if printf '%s' "$COMMAND" | grep -Eq 'reset[[:space:]]+(-+[A-Za-z-]+[[:space:]]+)*--hard|clean[[:space:]]+-[A-Za-z]*[df]'; then
-    edited=$(python3 "$TOOLKIT_DIR/scripts/session_state.py" list 2>/dev/null | head -10)
+    edited=$(python3 "$TOOLKIT_DIR/scripts/session_state.py" list "${SESSION_ARGS[@]}" 2>/dev/null | head -10)
     if [ -n "$edited" ]; then
         _block "destructive 'git reset --hard' / 'git clean' with session edits in tree" "$edited"
     fi
@@ -73,7 +75,8 @@ if printf '%s' "$COMMAND" | grep -Eq '(checkout|restore)([[:space:]].*)?[[:space
             /*) abs="$f" ;;
             *)  abs="$PWD/$f" ;;
         esac
-        if python3 "$TOOLKIT_DIR/scripts/session_state.py" was-edited "$abs" >/dev/null 2>&1; then
+        if python3 "$TOOLKIT_DIR/scripts/session_state.py" was-edited "$abs" \
+            "${SESSION_ARGS[@]}" >/dev/null 2>&1; then
             blocked="$blocked $f"
         fi
     done

package/app/hooks/save-session.sh

@@ -8,15 +8,17 @@
 source "$(dirname "$0")/_profile-check.sh"
 # shellcheck source=_session-paths.sh
 source "$(dirname "$0")/_session-paths.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.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)
+SESSION_ID=$(hook_session_id)
 LAST_MSG=$(echo "$INPUT" | jq -r '.last_assistant_message // "No summary available"' 2>/dev/null | head -5)
 
 SESSION_FILE="$SESSION_CONTEXT_FILE"
 
-if [ -n "$SESSION_ID" ]; then
+if [ "$SESSION_ID" != "default" ]; then
     mkdir -p "$SESSION_DIR"
 
     # Gather git state for richer context

package/app/hooks/session-end.sh

@@ -3,12 +3,45 @@
 #
 # Fires on: SessionEnd
 # Matcher: all
-# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+# The handoff snapshot is skipped for the minimal profile. Owned recovery
+# cleanup still runs for every profile.
 
-# shellcheck source=_profile-check.sh
-source "$(dirname "$0")/_profile-check.sh"
 # shellcheck source=_session-paths.sh
 source "$(dirname "$0")/_session-paths.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+
+# Cleanup must run before _profile-check.sh can exit for the minimal profile.
+INPUT=""
+if [ ! -t 0 ]; then
+    # shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
+    INPUT=$(cat)
+fi
+SESSION_ID=$(hook_session_id)
+RECOVERY_ROOT="$SESSION_DIR/output-filter"
+OUTPUT_FILTER_CLI="${AI_TOOLKIT_OUTPUT_FILTER_CLI:-$HOME/.softspark/ai-toolkit/scripts/output_filter_cli.py}"
+if [ "$SESSION_ID" != "default" ] &&
+   [ -d "$RECOVERY_ROOT" ] &&
+   [ ! -L "$RECOVERY_ROOT" ] &&
+   [ -f "$OUTPUT_FILTER_CLI" ] &&
+   [ ! -L "$OUTPUT_FILTER_CLI" ] &&
+   command -v python3 >/dev/null 2>&1; then
+    python3 -S "$OUTPUT_FILTER_CLI" clean \
+        --base-directory "$SESSION_DIR" \
+        --session-id "$SESSION_ID" >/dev/null 2>&1 || true
+fi
+
+SESSION_STATE_CLI="${AI_TOOLKIT_SESSION_STATE_CLI:-$HOME/.softspark/ai-toolkit/scripts/session_state.py}"
+if [ "$SESSION_ID" != "default" ] &&
+   [ -f "$SESSION_STATE_CLI" ] &&
+   [ ! -L "$SESSION_STATE_CLI" ] &&
+   command -v python3 >/dev/null 2>&1; then
+    python3 -S "$SESSION_STATE_CLI" clean \
+        --session-id "$SESSION_ID" >/dev/null 2>&1 || true
+fi
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
 
 SESSION_FILE="$SESSION_CONTEXT_FILE"
 HANDOFF_FILE="$SESSION_END_FILE"
@@ -35,4 +68,3 @@ else
 fi
 
 exit 0
-

package/app/hooks/session-start.sh

@@ -8,6 +8,8 @@
 source "$(dirname "$0")/_locate-toolkit.sh"
 # shellcheck source=_session-paths.sh
 source "$(dirname "$0")/_session-paths.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
 
 emit_context() {
     [ "${AI_TOOLKIT_HOOK_QUIET:-0}" = "1" ] && return 0
@@ -20,14 +22,18 @@ emit_context "MANDATORY: Before answering ANY technical question, apply ALL rule
 emit_context "REMINDER: When writing features or fixing bugs, ensure tests cover the changes. When modifying API, config, or setup, update relevant documentation. Propose these steps to the user — do not silently skip them."
 
 # 1a. Reset per-session edit state (used by revert-guard, test-cohesion, quality-gate)
-SESSION_ID_INPUT=""
+INPUT=""
 if [ ! -t 0 ]; then
-    STDIN_PAYLOAD="$(cat)"
-    SESSION_ID_INPUT="$(printf '%s' "$STDIN_PAYLOAD" | jq -r '.session_id // empty' 2>/dev/null)"
+    # shellcheck disable=SC2034  # INPUT is consumed via sourced _hook-io.sh
+    INPUT="$(cat)"
 fi
-if [ -n "$TOOLKIT_DIR" ] && command -v python3 >/dev/null 2>&1; then
+SESSION_ID_INPUT=$(hook_session_id)
+SESSION_SOURCE=$(hook_json '.source // empty')
+if [ "$SESSION_SOURCE" != "compact" ] &&
+   [ -n "$TOOLKIT_DIR" ] &&
+   command -v python3 >/dev/null 2>&1; then
     python3 "$TOOLKIT_DIR/scripts/session_state.py" reset \
-        ${SESSION_ID_INPUT:+--session-id "$SESSION_ID_INPUT"} >/dev/null 2>&1 || true
+        --session-id "$SESSION_ID_INPUT" >/dev/null 2>&1 || true
 fi
 
 # 1b. GC stale per-session search-required flags (older than 60 min)

package/app/hooks.json

@@ -158,6 +158,16 @@
                         "command": "\"$HOME/.softspark/ai-toolkit/hooks/search-tracker.sh\""
                     }
                 ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "Bash",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/filter-tool-output.sh\""
+                    }
+                ]
             }
         ],
         "Stop": [

package/app/output-filter-policy.json

@@ -0,0 +1,15 @@
+{
+  "mode": "off",
+  "profiles": [
+    "repeat-lines",
+    "tap-success"
+  ],
+  "maxInputBytes": 8388608,
+  "minSavingsBytes": 1024,
+  "minSavingsRatio": 0.15,
+  "recovery": {
+    "mode": "ephemeral",
+    "ttlMinutes": 60,
+    "maxSessionBytes": 33554432
+  }
+}