@kontourai/flow-agents 0.1.1

package/context/deferred/parallelization.md

@@ -0,0 +1,35 @@
+# Parallelization with tool-worker
+
+You have access to `tool-worker` — an autonomous coding subagent with full `@builtin` tool access (read, write, shell, code, grep, glob). Use it to parallelize implementation work.
+
+## When to Delegate to tool-worker
+
+- **Independent file changes** — multiple files that don't depend on each other can be written in parallel
+- **Long-running tasks** — implementation that would take many turns can run in the background while you handle other work
+- **Code Generation phase** (aidlc) — fan out unit implementations to parallel tool-worker instances
+- **Test writing** — delegate test creation while you continue with implementation
+- **Repetitive changes** — applying the same pattern across multiple files/modules
+
+## When NOT to Delegate
+
+- Tasks requiring user interaction or clarification
+- Changes with tight dependencies on each other (file A must exist before file B)
+- Exploratory work where the approach isn't clear yet
+
+## How to Delegate
+
+Provide tool-worker with a self-contained prompt including:
+
+Every worker delegation must target the exact `tool-worker` role. Omitting the role creates a generic unnamed worker that cannot load the Flow Agents worker contract.
+1. **Clear scope** — exactly which files to create/modify
+2. **Acceptance criteria** — what "done" looks like
+3. **Context** — relevant code patterns, conventions, types/interfaces it needs to follow
+4. **Working directory** — if different from current
+
+tool-worker manages its own TODO files in `.flow-agents/<slug>/` and tracks `modified_files` to detect conflicts with other parallel workers. It will end its turn immediately if instructions are insufficient rather than guessing.
+
+## Conflict Avoidance
+
+- tool-worker checks `.flow-agents/` for in-progress work from other instances
+- If file overlap is detected, it flags the conflict and may use `git worktree` isolation
+- When spawning multiple tool-worker instances, ensure their file scopes don't overlap

package/context/deferred/worktree-isolation.md

@@ -0,0 +1,24 @@
+# Git Worktree Isolation
+
+When working on tasks that overlap with in-progress work from other sessions, use git worktrees to avoid conflicts.
+
+## When to Use Worktrees
+
+- Check existing TODO lists for incomplete work
+- Compare your target files against `modified_files` in active TODOs
+- If files overlap with another TODO's active changes, create a worktree
+- If no overlap exists, work directly in the main tree
+
+## Worktree Workflow
+
+1. Create: `git worktree add ../worktree/kiro-<todo-id>-<feature> -b feat/<feature>`
+2. Do all implementation work in the worktree path
+3. On completion, attempt `git merge` back to the working branch
+4. If merge conflicts arise, surface them to the user for resolution
+5. Only clean up the worktree after a successful merge
+
+## TODO Awareness
+
+- Incomplete TODOs = active work — expect broken builds or partial implementations in those areas
+- Always check for overlap before starting work
+- If your task relates to an existing TODO, ask the user whether to continue it or start fresh

package/context/development-workflow.md

@@ -0,0 +1,50 @@
+# Development Workflow
+
+Standard workflow for all dev agent tasks. Steps are sequential — do not skip.
+
+## 0. Research & Reuse (mandatory)
+
+Before writing new code, search for existing solutions:
+- Codebase: grep/code search for similar logic already implemented
+- Package registries: npm, PyPI, crates.io for proven libraries
+- GitHub: public repos, code search for patterns and approaches
+
+Prefer adopting proven solutions over writing net-new. Use the `search-first` skill for structured research when the decision isn't obvious.
+
+## 1. Plan
+
+Use `plan-work` skill or `tool-planner` agent. Produce a plan artifact that covers:
+- Files to create/modify with specific changes
+- Dependencies and risks
+- Phased execution (waves for parallelization)
+
+## 2. TDD
+
+Write tests first, then implement, then refactor:
+- **RED** — write failing tests that define expected behavior
+- **GREEN** — write minimum code to pass
+- **IMPROVE** — refactor without changing behavior
+
+Target 80%+ coverage. Use `tdd-workflow` skill for structured TDD.
+
+## 3. Code Review
+
+Use `review-work` for automated critique. It delegates to `tool-code-reviewer` for quality, standards, and architecture fit, and to `tool-security-reviewer` when security triggers are present.
+- Address all CRITICAL and HIGH severity issues before proceeding
+- LOW/INFO items are advisory — fix if trivial, otherwise note and move on
+
+## 4. Verify
+
+Use `verify-work` skill for functional verification and evidence:
+- Build succeeds
+- Type checking passes
+- Linter clean
+- All tests pass
+- No security vulnerabilities introduced
+
+## 5. Commit
+
+Follow Conventional Commits per AGENTS.md:
+- Format: `<type>(<scope>): <description>`
+- Lowercase, imperative, no period, under 72 chars
+- Append `!` for breaking changes

package/context/scripts/context-budget/budget-scan.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+# budget-scan.sh — Scan Flow Agents bundles for token overhead estimation
+# Usage: bash budget-scan.sh [--verbose]
+set -euo pipefail
+
+BUNDLE_DIR="${FLOW_AGENTS_BUNDLE_DIR:-${HOME}/.flow-agents}"
+VERBOSE=false
+[[ "${1:-}" == "--verbose" ]] && VERBOSE=true
+
+# Handle missing bundle dir gracefully
+if [[ ! -d "$BUNDLE_DIR" ]]; then
+  echo '{"packages":[],"issues":[],"totals":{"context":0,"skills":0,"agents":0,"total":0}}'
+  exit 0
+fi
+
+# Collect all bundle directories (top-level + local/)
+_pkg_dirs=()
+for d in "${BUNDLE_DIR}"/*/; do
+  [[ ! -d "$d" ]] && continue
+  base=$(basename "$d")
+  if [[ "$base" == "local" ]]; then
+    for ld in "${d}"*/; do
+      [[ -d "$ld" ]] && _pkg_dirs+=("$ld")
+    done
+  else
+    _pkg_dirs+=("$d")
+  fi
+done
+
+estimate_tokens() {
+  local file="$1"
+  [[ ! -f "$file" ]] && echo 0 && return
+  local words chars
+  words=$(wc -w < "$file" 2>/dev/null | tr -d ' ')
+  chars=$(wc -c < "$file" 2>/dev/null | tr -d ' ')
+  case "$file" in
+    *.sh|*.json) echo $(( chars / 4 )) ;;
+    *) echo $(( (words * 13 + 9) / 10 )) ;;
+  esac
+}
+
+count_lines() {
+  local file="$1"
+  [[ ! -f "$file" ]] && echo 0 && return
+  wc -l < "$file" 2>/dev/null | tr -d ' '
+}
+
+skill_desc_words() {
+  local file="$1"
+  [[ ! -f "$file" ]] && echo 0 && return
+  sed -n '/^---$/,/^---$/p' "$file" | grep -i 'description' | head -1 | wc -w | tr -d ' '
+}
+
+count_mcp_servers() {
+  local file="$1"
+  jq '[.mcpServers // {} | keys | length] | add // 0' "$file" 2>/dev/null || echo 0
+}
+
+count_tools() {
+  local file="$1"
+  jq '[.tools // [] | length] | add // 0' "$file" 2>/dev/null || echo 0
+}
+
+prompt_lines() {
+  local file="$1"
+  case "$file" in
+    *.json)
+      jq -r '.systemPrompt // .prompt // .developer_instructions // ""' "$file" 2>/dev/null | wc -l | tr -d ' '
+      ;;
+    *.toml)
+      # Codex agent TOML stores instructions as escaped newlines in one string.
+      awk -F' = ' '/^(developer_instructions|instructions|prompt) = / {print $2}' "$file" \
+        | sed 's/^"//; s/"$//' \
+        | perl -pe 's/\\n/\n/g' \
+        | wc -l | tr -d ' '
+      ;;
+    *)
+      echo 0
+      ;;
+  esac
+}
+
+packages_json='[]'
+issues_json='[]'
+
+for pkg_dir in "${_pkg_dirs[@]}"; do
+  [[ ! -d "$pkg_dir" ]] && continue
+  pkg_name=$(basename "$pkg_dir")
+
+  context_tokens=0
+  skill_tokens=0
+  agent_tokens=0
+  files_json='[]'
+
+  # Scan context files
+  while IFS= read -r -d '' f; do
+    tokens=$(estimate_tokens "$f")
+    lines=$(count_lines "$f")
+    context_tokens=$((context_tokens + tokens))
+    rel="${f#"$pkg_dir"}"
+    if $VERBOSE; then
+      files_json=$(echo "$files_json" | jq -c --arg p "$rel" --argjson t "$tokens" --argjson l "$lines" '. + [{path:$p,tokens:$t,lines:$l,type:"context"}]')
+    fi
+    if [[ "$lines" -gt 100 ]]; then
+      issues_json=$(echo "$issues_json" | jq -c --arg p "${pkg_name}/${rel}" --argjson l "$lines" '. + [{type:"context_bloat",path:$p,lines:$l,suggestion:"Consider moving to context/deferred/ or splitting"}]')
+    fi
+  done < <(find "${pkg_dir}context" -name '*.md' -print0 2>/dev/null || true)
+
+  # Scan skills
+  while IFS= read -r -d '' f; do
+    tokens=$(estimate_tokens "$f")
+    desc_words=$(skill_desc_words "$f")
+    skill_tokens=$((skill_tokens + tokens))
+    rel="${f#"$pkg_dir"}"
+    if $VERBOSE; then
+      files_json=$(echo "$files_json" | jq -c --arg p "$rel" --argjson t "$tokens" --argjson dw "$desc_words" '. + [{path:$p,tokens:$t,desc_words:$dw,type:"skill"}]')
+    fi
+    if [[ "$desc_words" -gt 30 ]]; then
+      issues_json=$(echo "$issues_json" | jq -c --arg p "${pkg_name}/${rel}" --argjson w "$desc_words" '. + [{type:"bloated_skill_desc",path:$p,words:$w,suggestion:"Trim description to under 30 words"}]')
+    fi
+  done < <(find "${pkg_dir}skills" -name 'SKILL.md' -print0 2>/dev/null || true)
+
+  # Scan agent specs
+  while IFS= read -r -d '' f; do
+    tokens=$(estimate_tokens "$f")
+    pl=$(prompt_lines "$f")
+    mcp=$(count_mcp_servers "$f")
+    tools=$(count_tools "$f")
+    agent_tokens=$((agent_tokens + tokens))
+    rel="${f#"$pkg_dir"}"
+    if $VERBOSE; then
+      files_json=$(echo "$files_json" | jq -c --arg p "$rel" --argjson t "$tokens" --argjson pl "$pl" --argjson mcp "$mcp" --argjson tools "$tools" '. + [{path:$p,tokens:$t,prompt_lines:$pl,mcp_servers:$mcp,tools:$tools,type:"agent"}]')
+    fi
+    if [[ "$pl" -gt 200 ]]; then
+      issues_json=$(echo "$issues_json" | jq -c --arg p "${pkg_name}/${rel}" --argjson l "$pl" '. + [{type:"heavy_agent_spec",path:$p,prompt_lines:$l,suggestion:"Reduce systemPrompt or move to context file"}]')
+    fi
+    if [[ "$mcp" -gt 10 ]] || [[ "$tools" -gt 50 ]]; then
+      issues_json=$(echo "$issues_json" | jq -c --arg p "${pkg_name}/${rel}" --argjson m "$mcp" --argjson t "$tools" '. + [{type:"mcp_oversubscription",path:$p,mcp_servers:$m,tools:$t,suggestion:"Reduce MCP servers or tools per agent"}]')
+    fi
+  done < <(find "${pkg_dir}agents" \( -name '*agent-spec.json' -o -name '*.json' -o -name '*.toml' \) -print0 2>/dev/null || true)
+
+  total=$((context_tokens + skill_tokens + agent_tokens))
+  pkg_entry=$(jq -nc \
+    --arg name "$pkg_name" \
+    --argjson context "$context_tokens" \
+    --argjson skills "$skill_tokens" \
+    --argjson agents "$agent_tokens" \
+    --argjson total "$total" \
+    --argjson files "$files_json" \
+    '{name:$name,tokens:{context:$context,skills:$skills,agents:$agents,total:$total},files:$files}')
+  packages_json=$(echo "$packages_json" | jq -c --argjson p "$pkg_entry" '. + [$p]')
+done
+
+total_context=$(echo "$packages_json" | jq '[.[].tokens.context] | add // 0')
+total_skills=$(echo "$packages_json" | jq '[.[].tokens.skills] | add // 0')
+total_agents=$(echo "$packages_json" | jq '[.[].tokens.agents] | add // 0')
+total_all=$(echo "$packages_json" | jq '[.[].tokens.total] | add // 0')
+
+jq -nc \
+  --argjson packages "$packages_json" \
+  --argjson issues "$issues_json" \
+  --argjson tc "$total_context" \
+  --argjson ts "$total_skills" \
+  --argjson ta "$total_agents" \
+  --argjson tt "$total_all" \
+  '{packages:$packages,issues:$issues,totals:{context:$tc,skills:$ts,agents:$ta,total:$tt}}'

package/context/scripts/detect-tools.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+# Detect optional CLI tools. Output is injected into agent context at spawn.
+

package/context/scripts/discover-agents.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+# Spawn hook: discover agent cards from the repo, installed bundle, or legacy root file.
+echo "=== Agent Card Discovery ==="
+FOUND=0
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+shopt -s nullglob
+cards=(
+  "$ROOT_DIR"/agent-cards/*.json
+  "$HOME"/.flow-agents/agent-cards/*.json
+  "$HOME"/.flow-agents/agent-card.json
+)
+for card in "${cards[@]}"; do
+  [ -f "$card" ] || continue
+  FOUND=$((FOUND + 1))
+  name=$(node -e "const d=require(process.argv[1]); process.stdout.write(d.name||'?')" "$card" 2>/dev/null)
+  agent=$(node -e "const d=require(process.argv[1]); process.stdout.write(d.agent||'?')" "$card" 2>/dev/null)
+  desc=$(node -e "const d=require(process.argv[1]); process.stdout.write(d.description||'')" "$card" 2>/dev/null)
+  echo ""
+  echo "📋 $name (agent: $agent)"
+  echo "   $desc"
+done
+if [ "$FOUND" -eq 0 ]; then
+  echo "No agent cards found."
+else
+  echo ""
+  echo "Discovered $FOUND orchestrator(s)."
+fi

package/context/scripts/git-status.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Spawn hook: git status + worktree context for parallel safety
+
+if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+  echo "📁 Not a git repository — skipping git context"
+  exit 0
+fi
+
+# Basic status
+echo "=== Git Status ==="
+git status --short
+
+# Branch/worktree context
+echo ""
+echo "=== Branch ==="
+git branch --show-current
+
+# Detect if we're in a worktree (not the main working tree)
+TOPLEVEL=$(git rev-parse --show-toplevel)
+COMMON=$(git rev-parse --git-common-dir)
+GIT_DIR=$(git rev-parse --git-dir)
+
+if [ "$GIT_DIR" != "$COMMON" ]; then
+  echo "⚠️  Running inside a git worktree: $TOPLEVEL"
+  echo "   Main repo: $(cd "$COMMON/.." && pwd)"
+fi
+
+# List active worktrees for conflict awareness
+WORKTREE_COUNT=$(git worktree list | wc -l | tr -d ' ')
+if [ "$WORKTREE_COUNT" -gt 1 ]; then
+  echo ""
+  echo "=== Active Worktrees ($WORKTREE_COUNT) ==="
+  git worktree list
+  echo ""
+  echo "⚠️  Multiple worktrees active — check .flow-agents/ for in-progress tasks before modifying shared files"
+fi
+
+# List existing TODOs for awareness
+TODO_DIR=".flow-agents"
+if [ -d "$TODO_DIR" ]; then
+  TODO_COUNT=$(find "$TODO_DIR" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$TODO_COUNT" -gt 0 ]; then
+    echo ""
+    echo "=== Active TODOs ($TODO_COUNT) ==="
+    while IFS= read -r f; do
+      [ -f "$f" ] && echo "  - $(basename "$f" .md): $(head -1 "$f")"
+    done < <(find "$TODO_DIR" -mindepth 2 -maxdepth 2 -name "*.md" 2>/dev/null | sort)
+  fi
+fi

package/context/scripts/hooks/config-protection.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Config Protection Hook
+ *
+ * Blocks modifications to linter/formatter config files.
+ * Steers the agent to fix source code instead of weakening configs.
+ *
+ * Exit codes: 0 = allow, 2 = block
+ */
+
+'use strict';
+
+const path = require('path');
+
+const MAX_STDIN = 1024 * 1024;
+
+const PROTECTED_FILES = new Set([
+  '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.eslintrc.yml', '.eslintrc.yaml',
+  'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs', 'eslint.config.ts', 'eslint.config.mts', 'eslint.config.cts',
+  '.prettierrc', '.prettierrc.js', '.prettierrc.cjs', '.prettierrc.json', '.prettierrc.yml', '.prettierrc.yaml',
+  'prettier.config.js', 'prettier.config.cjs', 'prettier.config.mjs',
+  'biome.json', 'biome.jsonc',
+  '.ruff.toml', 'ruff.toml',
+  '.shellcheckrc', '.stylelintrc', '.stylelintrc.json', '.stylelintrc.yml',
+  '.markdownlint.json', '.markdownlint.yaml', '.markdownlintrc',
+]);
+
+function run(inputOrRaw, options = {}) {
+  if (options.truncated) {
+    return {
+      exitCode: 2,
+      stderr: `BLOCKED: Hook input exceeded ${options.maxStdin || MAX_STDIN} bytes. ` +
+        'Refusing to bypass config-protection on a truncated payload.',
+    };
+  }
+
+  let input;
+  try {
+    input = typeof inputOrRaw === 'string' ? JSON.parse(inputOrRaw) : inputOrRaw;
+  } catch { return { exitCode: 0 }; }
+
+  const filePath = input?.tool_input?.path || input?.tool_input?.file_path || '';
+  if (!filePath) return { exitCode: 0 };
+
+  const basename = path.basename(filePath);
+  if (PROTECTED_FILES.has(basename)) {
+    return {
+      exitCode: 2,
+      stderr: `BLOCKED: Modifying ${basename} is not allowed. ` +
+        'Fix the source code to satisfy linter/formatter rules instead of ' +
+        'weakening the config. If this is a legitimate config change, ' +
+        'disable the config-protection hook temporarily.',
+    };
+  }
+
+  return { exitCode: 0 };
+}
+
+module.exports = { run };
+
+// Stdin fallback for spawnSync execution
+if (require.main === module) {
+  let raw = '';
+  let truncated = /^(1|true|yes)$/i.test(String(process.env.SA_HOOK_INPUT_TRUNCATED || ''));
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (raw.length < MAX_STDIN) {
+      const remaining = MAX_STDIN - raw.length;
+      raw += chunk.substring(0, remaining);
+      if (chunk.length > remaining) truncated = true;
+    } else { truncated = true; }
+  });
+  process.stdin.on('end', () => {
+    const result = run(raw, { truncated, maxStdin: Number(process.env.SA_HOOK_INPUT_MAX_BYTES) || MAX_STDIN });
+    if (result.stderr) process.stderr.write(result.stderr + '\n');
+    if (result.exitCode === 2) process.exit(2);
+    process.stdout.write(raw);
+  });
+}

package/context/scripts/hooks/desktop-notify.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# desktop-notify.sh — macOS desktop notification on agent session stop
+# Usage: echo '<hook_event_json>' | bash desktop-notify.sh stop <agent_name>
+# Non-blocking: wraps osascript in background subshell
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TELEMETRY_DIR="$(cd "${SCRIPT_DIR}/../telemetry" && pwd)"
+source "${TELEMETRY_DIR}/lib/config.sh"
+
+main() {
+  # Feature gate
+  [[ "$TELEMETRY_NOTIFICATIONS" != "true" ]] && return 0
+
+  # Profile gate
+  case "$TELEMETRY_NOTIFICATION_PROFILE" in
+    standard|strict) ;;
+    *) return 0 ;;
+  esac
+
+  local hook_type="${1:-stop}" agent_name="${2:-agent}"
+  local stdin_json="$3"
+
+  # Extract summary from last_assistant_message
+  local summary
+  summary=$(echo "$stdin_json" | jq -r '.last_assistant_message // ""' 2>/dev/null)
+  # Take first non-empty line
+  summary=$(echo "$summary" | grep -m1 '.' || echo "Session complete")
+  # Truncate to 100 chars
+  [[ ${#summary} -gt 100 ]] && summary="${summary:0:100}..."
+
+  # Send notification (async, non-blocking)
+  osascript -e "display notification \"${summary//\"/\\\"}\" with title \"Kiro — ${agent_name}\"" &>/dev/null &
+}
+
+_stdin=$(cat)
+echo "$_stdin"
+(main "$@" "$_stdin") </dev/null &>/dev/null &
+disown 2>/dev/null
+exit 0

package/context/scripts/hooks/governance-audit.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# governance-audit.sh — Governance detection hook for preToolUse/postToolUse
+# Usage: echo '<hook_event_json>' | bash governance-audit.sh <hookType> <agentName>
+set -o pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TELEMETRY_DIR="$(cd "${SCRIPT_DIR}/../telemetry" && pwd)"
+
+source "${TELEMETRY_DIR}/lib/config.sh"
+source "${SCRIPT_DIR}/lib/patterns.sh"
+source "${SCRIPT_DIR}/lib/audit-transport.sh"
+
+# Max input size to inspect (bytes) — truncate beyond this
+MAX_INSPECT_SIZE=50000
+
+_build_event() {
+  local finding_type="$1" severity="$2" tool_name="$3" hook_phase="$4" details="$5"
+  local session_id agent_name="$6"
+  session_id=$(ls -t "${TELEMETRY_SESSION_DIR}"/*.session 2>/dev/null | head -n1 | xargs -I{} jq -r '.session_id' {} 2>/dev/null || echo "no-session")
+  local event_id timestamp_ms
+  event_id="gov-$(date +%s)-$(head -c4 /dev/urandom 2>/dev/null | od -An -tx1 | tr -d ' \n' || echo $$)"
+  timestamp_ms=$(date +%s)000
+
+  jq -nc \
+    --arg sv "0.3.0" \
+    --arg ts "$timestamp_ms" \
+    --arg sid "$session_id" \
+    --arg eid "$event_id" \
+    --arg et "governance.${finding_type}" \
+    --arg an "$agent_name" \
+    --arg ft "$finding_type" \
+    --arg sev "$severity" \
+    --arg tn "$tool_name" \
+    --arg hp "$hook_phase" \
+    --argjson det "$details" \
+    '{
+      schema_version: $sv,
+      timestamp: $ts,
+      session_id: $sid,
+      event_id: $eid,
+      event_type: $et,
+      agent: {name: $an, runtime: "kiro-cli"},
+      governance: {finding_type: $ft, severity: $sev, tool_name: $tn, hook_phase: $hp, details: $det}
+    }'
+}
+
+main() {
+  [[ "$TELEMETRY_GOVERNANCE" != "true" ]] && return 0
+
+  local hook_type="${1:-preToolUse}" agent_name="${2:-unknown}"
+  local stdin_json="$3"
+  local hook_phase
+  case "$hook_type" in
+    preToolUse) hook_phase="pre" ;;
+    postToolUse) hook_phase="post" ;;
+    *) return 0 ;;
+  esac
+
+  local tool_name text
+  tool_name=$(echo "$stdin_json" | jq -r '.tool_name // ""' 2>/dev/null)
+
+  # Combine tool_input and tool_response for scanning
+  local tool_input tool_response
+  tool_input=$(echo "$stdin_json" | jq -r '.tool_input // "" | if type == "object" then tostring else . end' 2>/dev/null)
+  tool_response=$(echo "$stdin_json" | jq -r '.tool_response // "" | if type == "object" then tostring else . end' 2>/dev/null)
+  text="${tool_input}${tool_response}"
+
+  # Truncation check
+  if [[ ${#text} -gt $MAX_INSPECT_SIZE ]]; then
+    local trunc_event
+    trunc_event=$(_build_event "audit_input_truncated" "warning" "$tool_name" "$hook_phase" \
+      "{\"original_size\":${#text},\"max_size\":${MAX_INSPECT_SIZE}}" "$agent_name")
+    audit_emit "$trunc_event"
+    text="${text:0:$MAX_INSPECT_SIZE}"
+  fi
+
+  # Secret detection
+  local secrets
+  secrets=$(_detect_secrets "$text")
+  if [[ -n "$secrets" ]]; then
+    local types_json location
+    types_json=$(echo "$secrets" | jq -Rsc 'split("\n") | map(select(. != ""))')
+    [[ "$hook_phase" == "pre" ]] && location="input" || location="output"
+    local evt
+    evt=$(_build_event "secret_detected" "critical" "$tool_name" "$hook_phase" \
+      "{\"secret_types\":${types_json},\"location\":\"${location}\"}" "$agent_name")
+    audit_emit "$evt"
+  fi
+
+  # AWS policy violations
+  local violations
+  violations=$(_detect_aws_violations "$text")
+  if [[ -n "$violations" ]]; then
+    local vtypes_json
+    vtypes_json=$(echo "$violations" | jq -Rsc 'split("\n") | map(select(. != ""))')
+    local evt
+    evt=$(_build_event "aws_policy_violation" "critical" "$tool_name" "$hook_phase" \
+      "{\"violation_types\":${vtypes_json}}" "$agent_name")
+    audit_emit "$evt"
+  fi
+
+  # Destructive operations (primarily preToolUse on bash commands)
+  if _detect_destructive_ops "$text"; then
+    local evt
+    evt=$(_build_event "destructive_operation" "high" "$tool_name" "$hook_phase" \
+      '{"location":"command"}' "$agent_name")
+    audit_emit "$evt"
+  fi
+
+  # Sensitive file access (preToolUse on file writes)
+  local file_path
+  file_path=$(echo "$stdin_json" | jq -r '.tool_input.path // .tool_input.file_path // ""' 2>/dev/null)
+  if [[ -n "$file_path" ]] && _detect_sensitive_paths "$file_path"; then
+    local evt
+    evt=$(_build_event "sensitive_file_access" "warning" "$tool_name" "$hook_phase" \
+      "{\"path\":\"${file_path}\"}" "$agent_name")
+    audit_emit "$evt"
+  fi
+
+  # Elevated privilege
+  if _detect_elevated_privilege "$text"; then
+    local evt
+    evt=$(_build_event "elevated_privilege" "medium" "$tool_name" "$hook_phase" \
+      '{"location":"command"}' "$agent_name")
+    audit_emit "$evt"
+  fi
+
+  audit_maybe_rotate
+}
+
+_stdin=$(cat)
+echo "$_stdin"
+(main "$@" "$_stdin") </dev/null &>/dev/null &
+disown 2>/dev/null
+exit 0

package/context/scripts/hooks/lib/audit-transport.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# audit-transport.sh — Audit-specific JSONL transport (separate from telemetry channels)
+
+audit_emit() {
+  local event_json="$1"
+  [[ -z "$event_json" ]] && return
+  local audit_file="${TELEMETRY_DATA_DIR}/audit.jsonl"
+  echo "$event_json" >> "$audit_file" 2>/dev/null
+}
+
+audit_maybe_rotate() {
+  local audit_file="${TELEMETRY_DATA_DIR}/audit.jsonl"
+  [[ ! -f "$audit_file" ]] && return
+
+  local file_size_bytes=0
+  if stat -c %s "$audit_file" >/dev/null 2>&1; then
+    file_size_bytes=$(stat -c %s "$audit_file")
+  else
+    file_size_bytes=$(stat -f %z "$audit_file" 2>/dev/null || echo "0")
+  fi
+
+  local max_bytes=$(( TELEMETRY_GOVERNANCE_AUDIT_MAX_SIZE_MB * 1024 * 1024 ))
+  [[ "$file_size_bytes" -lt "$max_bytes" ]] && return
+
+  local base="${audit_file%.*}"
+  local ext="${audit_file##*.}"
+
+  # Remove oldest
+  local oldest="${base}.$((TELEMETRY_GOVERNANCE_AUDIT_MAX_FILES - 1)).${ext}"
+  [[ -f "$oldest" ]] && rm -f "$oldest"
+
+  # Shift existing
+  for ((i = TELEMETRY_GOVERNANCE_AUDIT_MAX_FILES - 2; i >= 1; i--)); do
+    local cur="${base}.${i}.${ext}"
+    local nxt="${base}.$((i + 1)).${ext}"
+    [[ -f "$cur" ]] && mv "$cur" "$nxt"
+  done
+
+  mv "$audit_file" "${base}.1.${ext}"
+}