omniconductor 0.3.0

package/core/docs-templates/specs/_example.md

@@ -0,0 +1,121 @@
+---
+area: <your-area>            # e.g., auth, billing, email
+owner: <you-or-team>
+status: draft|active|archived
+last_synced: YYYY-MM-DD
+api_routes:                  # list of API route paths owned by this area
+  - /api/<your-area>/<route>
+pages:                       # list of pages owned by this area
+  - /<your-area>
+components:                  # list of components owned by this area
+  - <YourComponent>
+services:                    # list of services owned by this area
+  - <yourAreaService>
+hooks:                       # list of hooks owned by this area
+  - useYourArea
+db_tables:                   # list of DB tables owned by this area
+  - <table_name>
+---
+
+# Spec — `<your-area>` (PLACEHOLDER — copy + rename per area)
+
+> **What this is**: single source-of-truth for everything in the `<your-area>` domain. Updated EVERY time code in this area changes (spec-as-you-go ABSOLUTE rule).
+
+> **Status (P0 placeholder)**: copy this file, rename to your area, replace contents. P1 will provide a richer example.
+
+---
+
+## Overview
+
+One paragraph: what is this area, what problem does it solve, what are the boundaries.
+
+---
+
+## User-facing flows
+
+For each user flow:
+
+### Flow: <flow name>
+
+1. User does X.
+2. System responds Y.
+3. User sees Z.
+
+**Edge cases**:
+- What happens on error.
+- What happens on empty state.
+- What happens on permission denied.
+
+---
+
+## API
+
+For each route:
+
+### `<METHOD> /api/<your-area>/<route>`
+
+- **Auth**: required / optional / none.
+- **Body**: schema.
+- **Response**: schema (Result pattern: `{ data: T; error: null } | { data: null; error: string }`).
+- **Errors**: list of error codes + meanings.
+
+---
+
+## UI
+
+For each page or major component:
+
+### Page: `/<your-area>`
+
+- **Layout**: brief description.
+- **Components used**: list.
+- **State**: what state the page manages.
+- **Permissions**: who can access.
+
+---
+
+## Services
+
+For each service function:
+
+### `<yourAreaService>.<method>()`
+
+- **Input**: parameters.
+- **Output**: Result-pattern return.
+- **Side effects**: DB writes, external API calls, etc.
+
+---
+
+## DB Schema
+
+For each table:
+
+### `<table_name>`
+
+| Column | Type | Notes |
+|---|---|---|
+| id | uuid | PK |
+| ... | ... | ... |
+
+**Indexes**:
+- ...
+
+**RLS policies**:
+- ...
+
+---
+
+## Known constraints / gotchas
+
+- Limits, quotas, rate limits.
+- Browser-specific behavior.
+- Things future contributors must know.
+
+---
+
+## Recent changes
+
+- YYYY-MM-DD: <what changed and why>.
+- YYYY-MM-DD: ...
+
+(Append-only; oldest at bottom; archive once it grows past 20 entries.)

package/core/hooks/README.md

@@ -0,0 +1,62 @@
+# `core/hooks/` — Universal hook templates
+
+CONDUCTOR's universal hook spec. Templates here are compiled into native shell scripts by adapters that natively support hooks (Claude Code as of v0.2). Adapters without native hook support transform these into rule-text reminders embedded in the tool's primary rule file.
+
+## The templates
+
+| Template | Trigger | Action | Compile target |
+|---|---|---|---|
+| `pretool-agent-routing.sh.template` | Agent / sub-agent dispatch about to fire | Validate routing (no `general-purpose`, explicit model) | Claude `.claude/hooks/pretool-agent-routing.sh` |
+| `pretool-commit-current-work-check.sh.template` | PreToolUse on Bash `git commit` | Soft `ask` warn — surfaces a reason at commit time when 3+ source files are staged but `CURRENT_WORK.md` is not part of the commit; non-blocking, orchestrator approves to proceed. Override env disables: `CONDUCTOR_SKIP_CURRENT_WORK_HOOK=1`. | Claude `.claude/hooks/pretool-commit-current-work-check.sh` |
+| `pretool-commit-test-coverage-check.sh.template` | PreToolUse on Bash `git commit` | Soft `ask` warn (quality-gates Q3) — surfaces a reason when a newly-added feature-shaped source file has no new test (path with `test`/`spec`/`__tests__`/`e2e`) in the same commit; non-blocking, orchestrator approves to proceed. Override env disables: `CONDUCTOR_SKIP_TEST_COVERAGE_HOOK=1`. | Claude `.claude/hooks/pretool-commit-test-coverage-check.sh` |
+| `pretool-large-file-read-guard.sh.template` | PreToolUse on the Read tool | **Block** a Read of files ≥ `${CONDUCTOR_LARGE_FILE_LINE_THRESHOLD}` (default 500) lines when no `offset`/`limit` is supplied; recommends range-read or Grep (token-economy / anti-pattern `large-file-read-no-range`). Fail-open. Override env disables: `CONDUCTOR_ALLOW_LARGE_READ=1`. | Claude `.claude/hooks/pretool-large-file-read-guard.sh` |
+| `stop-session-log-check.sh.template` | Session stop event | Block stop if recent commits exist + CURRENT_WORK.md or specs are stale | Claude `.claude/hooks/stop-session-log-check.sh` |
+| `stop-r6-review-check.sh.template` | Session stop event | Remind to run pre-merge review on open PR | Claude `.claude/hooks/stop-r6-review-check.sh` |
+| `stop-cache-hit-baseline-check.sh.template` | Session stop event | Non-blocking diagnostic — reads the latest session JSONL, computes cache hit rate, reminds when below baseline (token-economy). Fail-open. Override env disables: `CONDUCTOR_SKIP_CACHE_CHECK=1`. | Claude `.claude/hooks/stop-cache-hit-baseline-check.sh` |
+| `stop-trajectory-log.sh.template` | Session stop event | Non-blocking — reads `transcript_path` + `session_id` from the Stop hook's **stdin** (exact provenance; no `~/.claude/projects` dir-scan) and **upserts** one pointer record per session (session id, transcript path, git HEAD, cwd) into `.conductor/trajectories/index.jsonl` for the Reflector (recipes/self-improvement.md). Same stdin approach as the non-Claude portable logger `core/reflector/trajectory-log.sh`. **Opt-in gated: no-ops unless `.conductor/reflect/` exists** (created only by the self-improvement recipe). Anchors to the project root; fail-open. Override: `CONDUCTOR_SKIP_TRAJLOG=1`. | Claude `.claude/hooks/stop-trajectory-log.sh` |
+
+The two `pretool-commit-*` templates are **soft `ask` warns**: they emit
+`{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":...}}`,
+which surfaces the reason and routes to the permission flow — the orchestrator approves and
+proceeds (or justifies). This is non-blocking and does NOT auto-approve (unlike
+`permissionDecision: allow`, which would silently bypass the permission prompt). It mirrors
+`pretool-agent-routing.sh.template`'s `deny`+reason shape (here `ask`+reason). They also fail
+soft — any internal error exits 0. Each honors a per-commit override env var (above) for the
+rare intentional exception.
+
+## Frontmatter convention
+
+Templates use a comment-block frontmatter (because shell scripts don't read YAML at runtime — the adapter parses the comment block):
+
+```bash
+#!/usr/bin/env bash
+#
+# CONDUCTOR universal hook template
+# hook_id: <id>
+# trigger: <pretool | stop>
+# action: <description>
+# compile_targets: claude
+# fallback: rule-text-reminder
+```
+
+## Per-tool compilation
+
+| Adapter | Compile behavior |
+|---|---|
+| Claude | `transform.sh` substitutes placeholders (paths, branch names, cool-down windows), writes to `.claude/hooks/<hook>.sh`, runs `chmod +x`. |
+| Cursor / Copilot / Gemini / Codex / Windsurf | Hook compiles to a rule-text reminder added to the appropriate rule file. The reminder includes the trigger condition, the action, and the rationale. |
+
+## Placeholders
+
+Templates use `${PLACEHOLDER}` syntax for values that the adapter substitutes at compile time:
+
+| Placeholder | Replaced with |
+|---|---|
+| `${CONDUCTOR_PROJECT_DIR}` | Absolute path to the target project |
+| `${CONDUCTOR_PROTECTED_BRANCHES}` | Pipe-separated list (e.g., `main\|release\|develop`) |
+| `${CONDUCTOR_COOLDOWN_SECONDS}` | Cool-down between reminders (typical: 1800 = 30 min) |
+| `${CONDUCTOR_STALE_MINUTES}` | Staleness threshold (typical: 30) |
+| `${CONDUCTOR_SOURCE_GLOB}` | Alternation of source extensions (e.g., `ts\|tsx`) |
+| `${CONDUCTOR_CURRENT_WORK_PATH}` | Session-log path (default `docs/CURRENT_WORK.md`) |
+
+Placeholders that the adapter does not know how to fill are passed through unchanged (with a warning) so the user can edit them post-install.

package/core/hooks/pretool-agent-routing.sh.template

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+#
+# CONDUCTOR universal hook template
+# hook_id: pretool-agent-routing
+# trigger: pretool
+# action: Validate sub-agent dispatch — block forbidden subagent_type, require explicit model.
+# compile_targets: claude
+# fallback: rule-text-reminder
+#
+# Generated by adapters/<tool>/transform.sh.
+# Tool-native semantics:
+#   - Claude Code: PreToolUse hook reads the tool-call payload from stdin (JSON)
+#     and validates Agent tool calls.
+#   - Other tools: this template is converted to rule-text by their adapter.
+#
+# Validations:
+#   V1. Agent tool MUST NOT use a forbidden subagent_type (e.g., "general-purpose"
+#       which defaults to a generic model and ignores project rules).
+#       Route to one of the 6 universal roles + project-specific roles instead.
+#   V2. Agent tool calls MUST include an explicit `model` parameter. The
+#       orchestrator is responsible for sizing tasks per
+#       universal-rules/meta-discipline.md section 6.
+#
+# Exit code meaning in PreToolUse hooks (Claude Code):
+#   0 with no JSON output                 → allow
+#   0 with {"permissionDecision":"deny"}  → block with reason (shown to LLM)
+#   non-zero                              → allow (fail-open)
+
+set -u
+
+# ${CONDUCTOR_PROJECT_DIR} — absolute path to project root (filled by transform.sh).
+# ${CONDUCTOR_FORBIDDEN_SUBAGENT_TYPES} — pipe-separated list (default: general-purpose).
+
+# Read payload from stdin into env var so python can parse it safely.
+export PAYLOAD_RAW="$(/bin/cat 2>/dev/null || true)"
+[ -n "${PAYLOAD_RAW:-}" ] || exit 0
+
+if ! command -v /usr/bin/python3 >/dev/null 2>&1; then
+  exit 0
+fi
+
+PARSED=$(/usr/bin/python3 -c "
+import json, os, sys
+try:
+    d = json.loads(os.environ.get('PAYLOAD_RAW', '{}'))
+    if d.get('tool_name', '') != 'Agent':
+        sys.exit(0)
+    inp = d.get('tool_input', {}) or {}
+    print('SUB=' + inp.get('subagent_type', ''))
+    print('MODEL=' + inp.get('model', ''))
+except Exception:
+    sys.exit(0)
+" 2>/dev/null)
+
+[ -z "$PARSED" ] && exit 0
+
+while IFS='=' read -r key val; do
+  case "$key" in
+    SUB) SUB="$val" ;;
+    MODEL) MODEL="$val" ;;
+  esac
+done <<< "$PARSED"
+
+REASONS=""
+
+# V1 — block forbidden subagent_type.
+# Default forbidden list: general-purpose. Override at compile time.
+FORBIDDEN_RE="${CONDUCTOR_FORBIDDEN_SUBAGENT_TYPES:-general-purpose}"
+if [ -n "${SUB:-}" ] && echo "${SUB}" | /usr/bin/grep -qE "^(${FORBIDDEN_RE})$"; then
+  REASONS="[ROUTING VIOLATION] subagent_type='${SUB}' is FORBIDDEN. Route to one of the registered roles in core/roles/ (planner, builder, reviewer, helper, designer, scribe) or a project-specific role. If no role fits, do the work in the orchestrator thread."
+fi
+
+# V2 — require explicit model parameter.
+if [ -z "${MODEL:-}" ]; then
+  MSG="[ROUTING VIOLATION] Agent tool call is missing the 'model' parameter. Orchestrator must classify the task and pass model='opus' | 'sonnet' | 'haiku' explicitly per universal-rules/meta-discipline.md section 6."
+  if [ -n "$REASONS" ]; then
+    REASONS="$REASONS $MSG"
+  else
+    REASONS="$MSG"
+  fi
+fi
+
+[ -z "$REASONS" ] && exit 0
+
+REASONS_JSON=$(REASONS="$REASONS" /usr/bin/python3 -c "
+import json, os
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'PreToolUse',
+        'permissionDecision': 'deny',
+        'permissionDecisionReason': os.environ.get('REASONS', ''),
+    }
+}))
+")
+
+echo "$REASONS_JSON"
+exit 0

package/core/hooks/pretool-commit-current-work-check.sh.template

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+#
+# CONDUCTOR universal hook template
+# hook_id: pretool-commit-current-work-check
+# trigger: pretool
+# action: Soft-warn at commit time when 3+ source files are staged but
+#         ${CONDUCTOR_CURRENT_WORK_PATH} is not part of the same commit.
+# compile_targets: claude
+# fallback: rule-text-reminder
+#
+# Generated by adapters/<tool>/transform.sh.
+#
+# Commit-time companion to stop-session-log-check.sh.template. Soft warn, never blocks.
+#
+# Enforces:
+#   - operations.md O2 (CURRENT_WORK.md must update when work happens) — caught at
+#     commit time instead of (only) at session stop.
+#
+# Behavior:
+#   1. Parse PreToolUse stdin payload (same method as pretool-agent-routing).
+#   2. If tool_name != Bash → allow (silent exit 0).
+#   3. If the command is not a `git commit` → allow (silent exit 0).
+#   4. Count staged source files matching ${CONDUCTOR_SOURCE_GLOB}.
+#   5. If 3+ staged source files AND ${CONDUCTOR_CURRENT_WORK_PATH} is NOT staged
+#      → emit a soft confirmation (permissionDecision: ask + permissionDecisionReason).
+#   6. Override env / any error → allow (silent exit 0).
+#
+# Override (skip this check for a commit):
+#   CONDUCTOR_SKIP_CURRENT_WORK_HOOK=1
+#
+# Exit code meaning in PreToolUse hooks (Claude Code):
+#   0 with no JSON output                                    → allow (silent)
+#   0 with {"permissionDecision":"ask","permissionDecisionReason":...}
+#       → surface the reason and route to the permission flow; the orchestrator
+#         approves and proceeds (or justifies). Does NOT block and does NOT
+#         auto-approve. This is the documented non-blocking soft-warn and matches
+#         pretool-agent-routing.sh.template's deny+reason shape (here: ask+reason).
+#   0 with {"permissionDecision":"deny"}                     → block with reason
+#   non-zero                                                 → allow (fail-open)
+
+set -u
+
+# Placeholders filled by adapters/<tool>/transform.sh:
+#   ${CONDUCTOR_SOURCE_GLOB}        — alternation of source extensions (default ts|tsx)
+#   ${CONDUCTOR_CURRENT_WORK_PATH}  — session-log path (default docs/CURRENT_WORK.md)
+
+# Honor opt-out before any work.
+[ "${CONDUCTOR_SKIP_CURRENT_WORK_HOOK:-}" = "1" ] && exit 0
+
+SRC_GLOB="${CONDUCTOR_SOURCE_GLOB:-ts|tsx}"
+CURRENT_WORK="${CONDUCTOR_CURRENT_WORK_PATH:-docs/CURRENT_WORK.md}"
+
+command -v /usr/bin/python3 >/dev/null 2>&1 || exit 0
+
+# Read payload from stdin into env var so python can parse it safely.
+export PAYLOAD_RAW="$(/bin/cat 2>/dev/null || true)"
+[ -n "${PAYLOAD_RAW:-}" ] || exit 0
+
+# Extract the Bash command (same extraction shape the existing hooks use).
+CMD=$(/usr/bin/python3 -c "
+import json, os, sys
+try:
+    d = json.loads(os.environ.get('PAYLOAD_RAW', '{}'))
+    if d.get('tool_name', '') != 'Bash':
+        sys.exit(0)
+    inp = d.get('tool_input', {}) or {}
+    sys.stdout.write(inp.get('command', '') or '')
+except Exception:
+    sys.exit(0)
+" 2>/dev/null)
+
+# Only act on git commit commands.
+case "$CMD" in
+  *"git commit"*) : ;;
+  *) exit 0 ;;
+esac
+
+# Count staged source files (additions, modifications, etc.).
+STAGED_SRC=$(git diff --cached --name-only 2>/dev/null | /usr/bin/grep -cE "\.(${SRC_GLOB})$" || true)
+case "$STAGED_SRC" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+
+[ "$STAGED_SRC" -ge 3 ] || exit 0
+
+# Is the session log itself part of this commit?
+if git diff --cached --name-only 2>/dev/null | /usr/bin/grep -qF "$CURRENT_WORK"; then
+  exit 0
+fi
+
+REASON="[current-work-check] ${STAGED_SRC} source file(s) are staged but ${CURRENT_WORK} is not in this commit. Per operations.md O2, append the planned change to ${CURRENT_WORK} before committing so the session log stays in sync. (Skip once: set CONDUCTOR_SKIP_CURRENT_WORK_HOOK=1.)"
+
+REASON="$REASON" /usr/bin/python3 -c "
+import json, os
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'PreToolUse',
+        'permissionDecision': 'ask',
+        'permissionDecisionReason': os.environ.get('REASON', ''),
+    }
+}))
+"
+exit 0

package/core/hooks/pretool-commit-test-coverage-check.sh.template

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+#
+# CONDUCTOR universal hook template
+# hook_id: pretool-commit-test-coverage-check
+# trigger: pretool
+# action: Soft-warn at commit time when a new feature-shaped source file is added
+#         with no accompanying test file in the same commit.
+# compile_targets: claude
+# fallback: rule-text-reminder
+#
+# Generated by adapters/<tool>/transform.sh.
+#
+# Script form of quality-gates Q3. Soft warn, never blocks.
+#
+# Enforces:
+#   - quality-gates.md Q3 (test coverage sync) — a new feature/route/page/endpoint/
+#     service should land with its test in the same commit.
+#
+# Behavior:
+#   1. Parse PreToolUse stdin payload (same method as pretool-agent-routing).
+#   2. If tool_name != Bash → allow. If command is not `git commit` → allow.
+#   3. From `git diff --cached --name-only --diff-filter=A`, collect newly-ADDED
+#      source files matching ${CONDUCTOR_SOURCE_GLOB}.
+#   4. Heuristic (kept generic on purpose): treat an added source file as
+#      "feature-shaped" if its path contains one of: route, page, endpoint,
+#      service, api, handler, controller, feature  (case-insensitive). Pure type
+#      files / barrels / configs rarely contain those tokens, so they don't trip it.
+#   5. If a feature-shaped added file exists AND no NEW test file is staged
+#      (path containing test, spec, __tests__, or e2e) → emit a soft confirmation
+#      (permissionDecision: ask + permissionDecisionReason) citing Q3.
+#   6. Override env / any error → allow (silent exit 0).
+#
+# Override (skip this check for a commit):
+#   CONDUCTOR_SKIP_TEST_COVERAGE_HOOK=1
+#
+# Exit code meaning in PreToolUse hooks (Claude Code):
+#   0 with no JSON output                                    → allow (silent)
+#   0 with {"permissionDecision":"ask","permissionDecisionReason":...}
+#       → surface the reason and route to the permission flow; the orchestrator
+#         approves and proceeds (or justifies). Does NOT block and does NOT
+#         auto-approve. This is the documented non-blocking soft-warn and matches
+#         pretool-agent-routing.sh.template's deny+reason shape (here: ask+reason).
+#   non-zero                                                 → allow (fail-open)
+
+set -u
+
+# Placeholders filled by adapters/<tool>/transform.sh:
+#   ${CONDUCTOR_SOURCE_GLOB}  — alternation of source extensions (default ts|tsx)
+
+# Honor opt-out before any work.
+[ "${CONDUCTOR_SKIP_TEST_COVERAGE_HOOK:-}" = "1" ] && exit 0
+
+SRC_GLOB="${CONDUCTOR_SOURCE_GLOB:-ts|tsx}"
+
+command -v /usr/bin/python3 >/dev/null 2>&1 || exit 0
+
+export PAYLOAD_RAW="$(/bin/cat 2>/dev/null || true)"
+[ -n "${PAYLOAD_RAW:-}" ] || exit 0
+
+CMD=$(/usr/bin/python3 -c "
+import json, os, sys
+try:
+    d = json.loads(os.environ.get('PAYLOAD_RAW', '{}'))
+    if d.get('tool_name', '') != 'Bash':
+        sys.exit(0)
+    inp = d.get('tool_input', {}) or {}
+    sys.stdout.write(inp.get('command', '') or '')
+except Exception:
+    sys.exit(0)
+" 2>/dev/null)
+
+case "$CMD" in
+  *"git commit"*) : ;;
+  *) exit 0 ;;
+esac
+
+# Newly-added source files in this commit (added files only).
+ADDED_SRC=$(git diff --cached --name-only --diff-filter=A 2>/dev/null | /usr/bin/grep -E "\.(${SRC_GLOB})$" || true)
+[ -n "$ADDED_SRC" ] || exit 0
+
+# Feature-shaped heuristic: path segment hints at a feature/route/page/endpoint/service.
+# Kept deliberately generic so it works across stacks; excludes test files themselves.
+# The substring match is intentionally loose (e.g. `pageant.ts` can trip `page`) — acceptable
+# because this is a soft `ask` warn the orchestrator can wave through, not a hard block.
+FEATURE_RE='(route|page|endpoint|service|api|handler|controller|feature)'
+TEST_RE='(test|spec|__tests__|e2e)'
+
+FEATURE_NEW=$(printf '%s\n' "$ADDED_SRC" \
+  | /usr/bin/grep -ivE "$TEST_RE" \
+  | /usr/bin/grep -icE "$FEATURE_RE" || true)
+case "$FEATURE_NEW" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+[ "$FEATURE_NEW" -ge 1 ] || exit 0
+
+# Any NEW test file staged in this commit (added; covers the common case of a new feature).
+NEW_TESTS=$(git diff --cached --name-only --diff-filter=A 2>/dev/null | /usr/bin/grep -icE "$TEST_RE" || true)
+case "$NEW_TESTS" in
+  ''|*[!0-9]*) NEW_TESTS=0 ;;
+esac
+
+[ "$NEW_TESTS" -ge 1 ] && exit 0
+
+REASON="[test-coverage-check] A new feature-shaped source file is staged but no new test file (path with test/spec/__tests__/e2e) is in this commit. Per quality-gates.md Q3, add or update the covering test in the same commit. (Skip once: set CONDUCTOR_SKIP_TEST_COVERAGE_HOOK=1.)"
+
+REASON="$REASON" /usr/bin/python3 -c "
+import json, os
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'PreToolUse',
+        'permissionDecision': 'ask',
+        'permissionDecisionReason': os.environ.get('REASON', ''),
+    }
+}))
+"
+exit 0

package/core/hooks/pretool-large-file-read-guard.sh.template

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+#
+# CONDUCTOR universal hook template
+# hook_id: pretool-large-file-read-guard
+# trigger: pretool
+# action: Block Read of files >= ${CONDUCTOR_LARGE_FILE_LINE_THRESHOLD}
+#         lines unless offset/limit is supplied (or override env set).
+# compile_targets: claude
+# fallback: rule-text-reminder
+#
+# Generated by adapters/<tool>/transform.sh.
+#
+# Enforces:
+#   - meta-discipline.md token-economy section: range reads mandatory for
+#     files exceeding the line threshold.
+#
+# Behavior:
+#   1. Parse PreToolUse stdin payload.
+#   2. If tool_name != Read → allow (silent exit 0).
+#   3. Resolve file_path; if missing or unreadable → allow (let Read tool error).
+#   4. wc -l file. If lines < threshold → allow.
+#   5. If offset OR limit present → allow.
+#   6. If override env set → allow.
+#   7. Else → deny with diagnostic message recommending offset/limit or Grep.
+#
+# Override (rare, e.g. small JSON config that happens to be wide):
+#   ${CONDUCTOR_LARGE_READ_OVERRIDE_ENV}=1
+#
+# Exit code meaning in PreToolUse hooks (Claude Code):
+#   0 with no JSON output                 → allow
+#   0 with {"permissionDecision":"deny"}  → block with reason (shown to LLM)
+#   non-zero                              → allow (fail-open)
+
+set -u
+
+# Placeholders filled by adapters/<tool>/transform.sh:
+#   ${CONDUCTOR_LARGE_FILE_LINE_THRESHOLD}  — line threshold (default 500)
+#   ${CONDUCTOR_LARGE_READ_OVERRIDE_ENV}    — env var to bypass (default CONDUCTOR_ALLOW_LARGE_READ)
+
+THRESHOLD="${CONDUCTOR_LARGE_FILE_LINE_THRESHOLD:-500}"
+OVERRIDE_ENV_NAME="${CONDUCTOR_LARGE_READ_OVERRIDE_ENV:-CONDUCTOR_ALLOW_LARGE_READ}"
+
+# Honor opt-out before any work.
+OVERRIDE_VAL="$(/usr/bin/printenv "$OVERRIDE_ENV_NAME" 2>/dev/null || true)"
+[ "$OVERRIDE_VAL" = "1" ] && exit 0
+
+command -v python3 >/dev/null 2>&1 || exit 0
+
+PAYLOAD_RAW="$(/bin/cat 2>/dev/null || true)"
+[ -n "$PAYLOAD_RAW" ] || exit 0
+
+# Single python pass extracts tool_name + file_path + offset/limit presence.
+# Output format: TOOL=<name>\nPATH=<file>\nHAS_OFFSET=<0|1>\nHAS_LIMIT=<0|1>
+PARSED=$(PAYLOAD_RAW="$PAYLOAD_RAW" python3 -c "
+import json, os, sys
+try:
+    d = json.loads(os.environ.get('PAYLOAD_RAW', '{}'))
+except Exception:
+    sys.exit(0)
+if d.get('tool_name', '') != 'Read':
+    sys.exit(0)
+inp = d.get('tool_input', {}) or {}
+fp = inp.get('file_path', '') or ''
+has_off = '1' if (inp.get('offset') is not None) else '0'
+has_lim = '1' if (inp.get('limit') is not None) else '0'
+print('TOOL=Read')
+print('PATH=' + fp)
+print('HAS_OFFSET=' + has_off)
+print('HAS_LIMIT=' + has_lim)
+" 2>/dev/null)
+
+[ -n "$PARSED" ] || exit 0
+
+FILE_PATH=""
+HAS_OFFSET="0"
+HAS_LIMIT="0"
+while IFS='=' read -r key val; do
+  case "$key" in
+    PATH) FILE_PATH="$val" ;;
+    HAS_OFFSET) HAS_OFFSET="$val" ;;
+    HAS_LIMIT) HAS_LIMIT="$val" ;;
+  esac
+done <<EOF
+$PARSED
+EOF
+
+# Allow if range read.
+if [ "$HAS_OFFSET" = "1" ] || [ "$HAS_LIMIT" = "1" ]; then
+  exit 0
+fi
+
+# File must exist + be readable for size check; else let Read tool handle errors.
+[ -n "$FILE_PATH" ] || exit 0
+[ -r "$FILE_PATH" ] || exit 0
+[ -f "$FILE_PATH" ] || exit 0
+
+LINES=$(/usr/bin/wc -l < "$FILE_PATH" 2>/dev/null | /usr/bin/tr -d ' ')
+case "$LINES" in
+  ''|*[!0-9]*) exit 0 ;;
+esac
+
+[ "$LINES" -lt "$THRESHOLD" ] && exit 0
+
+# Build deny payload.
+REASON="[large-file-read-guard] File '${FILE_PATH}' has ${LINES} lines (threshold ${THRESHOLD}). Pass offset/limit (e.g. limit:100, offset:0) to range-read, or use Grep to find the specific symbol/section first. Override (rare, e.g. wide JSON config): set ${OVERRIDE_ENV_NAME}=1 in environment."
+
+REASON="$REASON" python3 -c "
+import json, os
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'PreToolUse',
+        'permissionDecision': 'deny',
+        'permissionDecisionReason': os.environ.get('REASON', ''),
+    }
+}))
+"
+exit 0