@specship/specship-win32-arm64 0.25.0 → 0.28.0

package/bin/specship.cmd

@@ -1 +1,31 @@
-@"%~dp0..\node.exe" --liftoff-only "%~dp0..\lib\dist\bin\specship.js" %*
+@echo off
+setlocal
+set "NODE="
+for /f "delims=" %%i in ('where node 2^>nul') do if not defined NODE set "NODE=%%i"
+if not defined NODE (
+  echo specship: Node.js is required ^(^>^= 22.5.0, ^< 25.0.0^) but no 'node' was found on PATH.>&2
+  echo specship: install it from https://nodejs.org>&2
+  exit /b 1
+)
+set "NODEVER="
+rem Query the version through PATH (`node`, not "%NODE%") so a Program Files
+rem path with spaces doesn't hit cmd's nested-quote parsing — `where node`
+rem already proved PATH resolves to this same executable.
+for /f "delims=" %%v in ('node -v 2^>nul') do set "NODEVER=%%v"
+set "NMAJ="
+set "NMIN="
+for /f "tokens=1,2 delims=v." %%a in ("%NODEVER%") do (
+  set "NMAJ=%%a"
+  set "NMIN=%%b"
+)
+if not defined NMAJ goto :badnode
+if %NMAJ% LSS 22 goto :badnode
+if %NMAJ% GEQ 25 goto :badnode
+if %NMAJ% EQU 22 if %NMIN% LSS 5 goto :badnode
+rem --liftoff-only: avoid the V8 turboshaft WASM Zone OOM (issues #293/#298).
+"%NODE%" --liftoff-only "%~dp0..\lib\dist\bin\specship.js" %*
+exit /b %ERRORLEVEL%
+:badnode
+echo specship: Node.js ^>^= 22.5.0 and ^< 25.0.0 is required (found %NODEVER% at %NODE%).>&2
+echo specship: install a supported version from https://nodejs.org>&2
+exit /b 1

package/lib/dist/activation/cheatsheet.d.ts

@@ -27,7 +27,23 @@ export declare const CHEATSHEET_TEXT: string;
  * out via `SPECSHIP_NO_CHEATSHEET` (REQ-CHEAT-004.A1). An unset or empty
  * variable prints normally (REQ-CHEAT-004.A2).
  */
-export declare function buildCheatsheetPayload(env?: NodeJS.ProcessEnv): {
+export declare function buildCheatsheetPayload(env?: NodeJS.ProcessEnv, extras?: CheatsheetExtras): {
     systemMessage: string;
 } | null;
+/** Optional learned-state extras the CLI resolves before rendering. */
+export interface CheatsheetExtras {
+    /** Raw content of .specship/conventions.md (null/empty → no section). */
+    conventions?: string | null;
+    /** Count of open reflection proposals (0/undefined → no line). */
+    openProposals?: number;
+}
+/** Max convention bullets injected per session (REQ-ALEARN-002.A2). */
+export declare const CONVENTIONS_BUDGET_LINES = 8;
+/**
+ * Render the confirmed conventions as a budget-bounded cheatsheet section
+ * (REQ-ALEARN-002). Rules are the `## <title>` lines of the SpecShip-written
+ * marker blocks plus their first body line; over budget, the rest collapse
+ * into a "+N more" pointer. No blocks → empty string (nothing injected).
+ */
+export declare function renderConventionsSection(content: string, budget: number): string;
 //# sourceMappingURL=cheatsheet.d.ts.map

package/lib/dist/activation/cheatsheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cheatsheet.d.ts","sourceRoot":"","sources":["../../src/activation/cheatsheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAqBhB,CAAC;AAEb;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAGlC"}
+{"version":3,"file":"cheatsheet.d.ts","sourceRoot":"","sources":["../../src/activation/cheatsheet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAqBhB,CAAC;AAEb;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,MAAM,GAAE,gBAAqB,GAC5B;IAAE,aAAa,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAkBlC;AAED,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAE1C;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAmBhF"}

package/lib/dist/activation/cheatsheet.js

@@ -15,8 +15,9 @@
  * and the `SPECSHIP_NO_CHEATSHEET` opt-out below, not by this module.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CHEATSHEET_TEXT = void 0;
+exports.CONVENTIONS_BUDGET_LINES = exports.CHEATSHEET_TEXT = void 0;
 exports.buildCheatsheetPayload = buildCheatsheetPayload;
+exports.renderConventionsSection = renderConventionsSection;
 /**
  * The cheat-sheet rendered to the user. Names only user-facing commands, tools,
  * and env vars — no internal file paths, symbol names, or benchmark figures
@@ -52,9 +53,52 @@ exports.CHEATSHEET_TEXT = [
  * out via `SPECSHIP_NO_CHEATSHEET` (REQ-CHEAT-004.A1). An unset or empty
  * variable prints normally (REQ-CHEAT-004.A2).
  */
-function buildCheatsheetPayload(env = process.env) {
+function buildCheatsheetPayload(env = process.env, extras = {}) {
     if (env.SPECSHIP_NO_CHEATSHEET)
         return null;
-    return { systemMessage: exports.CHEATSHEET_TEXT };
+    const parts = [exports.CHEATSHEET_TEXT];
+    // Learned project conventions (REQ-ALEARN-002): absent/empty file → output
+    // is byte-identical to the base cheatsheet (A1).
+    if (extras.conventions) {
+        const section = renderConventionsSection(extras.conventions, exports.CONVENTIONS_BUDGET_LINES);
+        if (section)
+            parts.push('', section);
+    }
+    // Open learned proposals awaiting review (REQ-ALEARN-004.A2): one line,
+    // only when the count is positive.
+    if (extras.openProposals && extras.openProposals > 0) {
+        parts.push('', `🧠 ${extras.openProposals} learned proposal(s) awaiting review — run \`specship reflect\` to review them.`);
+    }
+    return { systemMessage: parts.join('\n') };
+}
+/** Max convention bullets injected per session (REQ-ALEARN-002.A2). */
+exports.CONVENTIONS_BUDGET_LINES = 8;
+/**
+ * Render the confirmed conventions as a budget-bounded cheatsheet section
+ * (REQ-ALEARN-002). Rules are the `## <title>` lines of the SpecShip-written
+ * marker blocks plus their first body line; over budget, the rest collapse
+ * into a "+N more" pointer. No blocks → empty string (nothing injected).
+ */
+function renderConventionsSection(content, budget) {
+    const rules = [];
+    const re = /<!-- SPECSHIP_LEARNING:[^>]+ -->\n## ([^\n]+)\n+([^\n<]*)/g;
+    let m;
+    while ((m = re.exec(content)) !== null) {
+        const title = (m[1] ?? '').replace(/^Convention:\s*/i, '').trim();
+        const body = (m[2] ?? '').trim();
+        // The body line is the rule; the title is a summary of it. Prefer the
+        // body (the user's own words), fall back to the title.
+        rules.push(body || title);
+    }
+    if (rules.length === 0)
+        return '';
+    const shown = rules.slice(0, budget);
+    const lines = ['Project conventions (learned — .specship/conventions.md):'];
+    for (const r of shown)
+        lines.push(`• ${r.length > 100 ? r.slice(0, 97) + '…' : r}`);
+    if (rules.length > shown.length) {
+        lines.push(`  +${rules.length - shown.length} more — see .specship/conventions.md`);
+    }
+    return lines.join('\n');
 }
 //# sourceMappingURL=cheatsheet.js.map

package/lib/dist/activation/cheatsheet.js.map

@@ -1 +1 @@
-{"version":3,"file":"cheatsheet.js","sourceRoot":"","sources":["../../src/activation/cheatsheet.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;AAsCH,wDAKC;AAzCD;;;;;GAKG;AACU,QAAA,eAAe,GAAG;IAC7B,2EAA2E;IAC3E,EAAE;IACF,kCAAkC;IAClC,+EAA+E;IAC/E,sFAAsF;IACtF,+EAA+E;IAC/E,qFAAqF;IACrF,EAAE;IACF,+BAA+B;IAC/B,mFAAmF;IACnF,mFAAmF;IACnF,8EAA8E;IAC9E,EAAE;IACF,+EAA+E;IAC/E,kFAAkF;IAClF,kFAAkF;IAClF,sDAAsD;IACtD,uFAAuF;IACvF,EAAE;IACF,oFAAoF;CACrF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAEb;;;;;;GAMG;AACH,SAAgB,sBAAsB,CACpC,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,GAAG,CAAC,sBAAsB;QAAE,OAAO,IAAI,CAAC;IAC5C,OAAO,EAAE,aAAa,EAAE,uBAAe,EAAE,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"cheatsheet.js","sourceRoot":"","sources":["../../src/activation/cheatsheet.ts"],"names":[],"mappings":"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"}

package/lib/dist/activation/hook-output.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared helpers for hook commands (`steer-nudge`, `spec-nudge`,
+ * `search-intercept`) that read a hook payload from stdin and emit a
+ * `hookSpecificOutput.additionalContext` line.
+ *
+ * The `hook_event_name` field is echoed back from the payload rather than
+ * hard-coded so the same CLI command serves Claude Code's event names
+ * (`UserPromptSubmit`, `PreToolUse`) AND Gemini CLI's (`BeforeAgent`,
+ * `BeforeTool`) — the installer wires them to the same binaries and the
+ * payload tells the command which host called it (REQ-GEMINI-010).
+ */
+export interface HookPayload {
+    prompt: string;
+    cwd: string | null;
+    sessionId: string | null;
+    transcriptPath: string | null;
+    hookEventName: string | null;
+}
+export declare function parseHookPayload(raw: string): HookPayload;
+/**
+ * Build a `hookSpecificOutput.additionalContext` JSON line. `eventName` is
+ * echoed from the payload when present (so Gemini's `BeforeAgent` /
+ * `BeforeTool` names round-trip) and falls back to `fallbackEventName` only
+ * when the payload carries none.
+ */
+export declare function buildHookAdditionalContext(additionalContext: string, eventName: string | null, fallbackEventName: string): string;
+/**
+ * A blocking decision for a host whose before-tool hook reads a TOP-LEVEL
+ * `decision` (Gemini CLI 0.28.0 `BeforeToolHookOutput.isBlockingDecision`
+ * checks `this.decision === 'block' || 'deny'`; nested under
+ * `hookSpecificOutput` it is ignored). Only emitted for hosts whose traits
+ * report `supportsBeforeToolDeny`.
+ */
+export declare function buildHookDenyDecision(reason: string): string;
+/**
+ * Host-shaped traits derived from a hook payload — the one place that peeks
+ * at `hook_event_name` to decide whether we're serving Claude Code or Gemini
+ * CLI. Shared code (`search-intercept`, `bin/specship`) consumes the traits
+ * and never event-name-sniffs itself, keeping it host-agnostic per the
+ * project's agent-agnostic rule.
+ *
+ *   - `specshipToolMarkers` — substrings naming a specship tool_use record.
+ *     Claude exposes our server as `mcp__specship__<tool>`; Gemini shows
+ *     the model the bare tool name (`specship_explore`), qualifying it as
+ *     `specship__<tool>` only on a name collision.
+ *   - `transcriptFormat` — Claude writes JSONL (one record per line); Gemini's
+ *     `ChatRecordingService` writes one pretty-printed JSON doc with
+ *     `messages[].toolCalls[].name`.
+ *   - `supportsBeforeToolDeny` — whether the host reads a top-level
+ *     `{decision:'deny'}` on its BeforeTool-equivalent. Gemini 0.28.0+
+ *     `BeforeToolHookOutput.isBlockingDecision` does; Claude's PreToolUse
+ *     uses a different shape so we never emit deny for Claude.
+ */
+export interface HostTraits {
+    specshipToolMarkers: string[];
+    transcriptFormat: 'jsonl' | 'single-json';
+    supportsBeforeToolDeny: boolean;
+    /**
+     * Prefix the host puts in front of a SpecShip tool name when the model
+     * calls it (AGENTADAPT-DOC, REQ-AGENTADAPT-001): agent-facing text renders
+     * `${toolPrefix}specship_explore` so each host sees its own tool name.
+     */
+    toolPrefix: string;
+    /** Event names to answer with when the payload names none (REQ-AGENTADAPT-002). */
+    fallbackPromptEvent: string;
+    fallbackToolEvent: string;
+    /** The host's own built-in search tools a strict interceptor may redirect. */
+    denyEligibleTools: readonly string[];
+    /** The host's shell tool, whose `command` the interceptor classifies. */
+    shellTool: string | null;
+}
+/**
+ * Claude Code — also the legacy default for payloads that name no event, so
+ * every pre-adapter install keeps its exact behaviour (REQ-AGENTADAPT-002.A2).
+ */
+export declare const CLAUDE_CODE_TRAITS: HostTraits;
+/** Gemini CLI (verified against 0.28.0). */
+export declare const GEMINI_CLI_TRAITS: HostTraits;
+export declare function deriveHostTraits(payload: HookPayload): HostTraits;
+//# sourceMappingURL=hook-output.d.ts.map

package/lib/dist/activation/hook-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-output.d.ts","sourceRoot":"","sources":["../../src/activation/hook-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CA4BzD;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,iBAAiB,EAAE,MAAM,EACzB,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,iBAAiB,EAAE,MAAM,GACxB,MAAM,CAMR;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,UAAU;IACzB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,gBAAgB,EAAE,OAAO,GAAG,aAAa,CAAC;IAC1C,sBAAsB,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,mFAAmF;IACnF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,yEAAyE;IACzE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,UAShC,CAAC;AAEF,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,EAAE,UAS/B,CAAC;AAIF,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,CAKjE"}

package/lib/dist/activation/hook-output.js

@@ -0,0 +1,103 @@
+"use strict";
+/**
+ * Shared helpers for hook commands (`steer-nudge`, `spec-nudge`,
+ * `search-intercept`) that read a hook payload from stdin and emit a
+ * `hookSpecificOutput.additionalContext` line.
+ *
+ * The `hook_event_name` field is echoed back from the payload rather than
+ * hard-coded so the same CLI command serves Claude Code's event names
+ * (`UserPromptSubmit`, `PreToolUse`) AND Gemini CLI's (`BeforeAgent`,
+ * `BeforeTool`) — the installer wires them to the same binaries and the
+ * payload tells the command which host called it (REQ-GEMINI-010).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GEMINI_CLI_TRAITS = exports.CLAUDE_CODE_TRAITS = void 0;
+exports.parseHookPayload = parseHookPayload;
+exports.buildHookAdditionalContext = buildHookAdditionalContext;
+exports.buildHookDenyDecision = buildHookDenyDecision;
+exports.deriveHostTraits = deriveHostTraits;
+function parseHookPayload(raw) {
+    const empty = {
+        prompt: '',
+        cwd: null,
+        sessionId: null,
+        transcriptPath: null,
+        hookEventName: null,
+    };
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return empty;
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        // Not JSON — treat the raw text as the prompt body.
+        return { ...empty, prompt: trimmed };
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return empty;
+    const p = parsed;
+    const str = (v) => typeof v === 'string' && v.length > 0 ? v : null;
+    return {
+        prompt: typeof p.prompt === 'string' ? p.prompt : '',
+        cwd: str(p.cwd),
+        sessionId: str(p.session_id),
+        transcriptPath: str(p.transcript_path),
+        hookEventName: str(p.hook_event_name),
+    };
+}
+/**
+ * Build a `hookSpecificOutput.additionalContext` JSON line. `eventName` is
+ * echoed from the payload when present (so Gemini's `BeforeAgent` /
+ * `BeforeTool` names round-trip) and falls back to `fallbackEventName` only
+ * when the payload carries none.
+ */
+function buildHookAdditionalContext(additionalContext, eventName, fallbackEventName) {
+    const hookEventName = eventName ?? fallbackEventName;
+    return (JSON.stringify({ hookSpecificOutput: { hookEventName, additionalContext } }) +
+        '\n');
+}
+/**
+ * A blocking decision for a host whose before-tool hook reads a TOP-LEVEL
+ * `decision` (Gemini CLI 0.28.0 `BeforeToolHookOutput.isBlockingDecision`
+ * checks `this.decision === 'block' || 'deny'`; nested under
+ * `hookSpecificOutput` it is ignored). Only emitted for hosts whose traits
+ * report `supportsBeforeToolDeny`.
+ */
+function buildHookDenyDecision(reason) {
+    return JSON.stringify({ decision: 'deny', reason }) + '\n';
+}
+/**
+ * Claude Code — also the legacy default for payloads that name no event, so
+ * every pre-adapter install keeps its exact behaviour (REQ-AGENTADAPT-002.A2).
+ */
+exports.CLAUDE_CODE_TRAITS = {
+    specshipToolMarkers: ['"name":"mcp__specship__'],
+    transcriptFormat: 'jsonl',
+    supportsBeforeToolDeny: false,
+    toolPrefix: 'mcp__specship__',
+    fallbackPromptEvent: 'UserPromptSubmit',
+    fallbackToolEvent: 'PreToolUse',
+    denyEligibleTools: [],
+    shellTool: null,
+};
+/** Gemini CLI (verified against 0.28.0). */
+exports.GEMINI_CLI_TRAITS = {
+    specshipToolMarkers: ['"name":"specship_', '"name": "specship_'],
+    transcriptFormat: 'single-json',
+    supportsBeforeToolDeny: true,
+    toolPrefix: '',
+    fallbackPromptEvent: 'BeforeAgent',
+    fallbackToolEvent: 'BeforeTool',
+    denyEligibleTools: ['grep_search', 'glob'],
+    shellTool: 'run_shell_command',
+};
+const GEMINI_EVENTS = new Set(['BeforeAgent', 'BeforeTool', 'AfterTool']);
+function deriveHostTraits(payload) {
+    if (payload.hookEventName && GEMINI_EVENTS.has(payload.hookEventName)) {
+        return exports.GEMINI_CLI_TRAITS;
+    }
+    return exports.CLAUDE_CODE_TRAITS;
+}
+//# sourceMappingURL=hook-output.js.map

package/lib/dist/activation/hook-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-output.js","sourceRoot":"","sources":["../../src/activation/hook-output.ts"],"names":[],"mappings":"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"}

package/lib/dist/activation/search-intercept.d.ts

@@ -1,23 +1,31 @@
 /**
- * Point-of-use search interceptor (STEER-HOOK-DOC, REQ-STEER-004/005).
+ * Point-of-use search interceptor (STEER-HOOK-DOC, REQ-STEER-004/005,
+ * REQ-GEMINI-011).
  *
  * The prompt-level nudge (steering.ts) fires once, at prompt submit, and its
  * pull decays across a long turn — the observed failure is a search-shaped
  * tool call made many tool-calls after the nudge. This module is the decision
- * logic for the `PreToolUse` hook the installer writes on search tools
- * (`specship search-intercept`): deliver the same guidance at the moment of
- * the wrong choice.
+ * logic for the hook the installer writes on each host's search tools
+ * (Claude: PreToolUse on Grep/Glob; Gemini: BeforeTool on grep_search / glob /
+ * run_shell_command): deliver the same guidance at the moment of the wrong
+ * choice.
  *
- * Two properties are non-negotiable:
+ * Two modes exist:
  *
- *   - ADVISORY (REQ-STEER-004): the emitted text is `additionalContext`,
- *     never a permission decision. A search the index cannot answer is a
- *     legitimate search; a wrong denial costs the agent a turn — the very
- *     failure this feature exists to reduce.
- *   - SELF-SILENCING (REQ-STEER-005): at most one line per session, and only
- *     when the session has made zero specship tool calls. Firing on every
- *     search would make the hook noise, and noise is what taught the agent to
- *     ignore the prompt-level nudge.
+ *   - ADVISORY (default, both hosts, REQ-STEER-004/005): emit a one-line
+ *     `additionalContext` redirect. At most once per session, silent once the
+ *     session has used specship. The search still runs.
+ *   - STRICT (Gemini-only opt-in, REQ-GEMINI-011): for a built-in search tool
+ *     (`grep_search`, `glob`) in an indexed project, emit a top-level
+ *     `{decision:'deny'}` with a reason naming `specship_explore`. A
+ *     search-shaped `run_shell_command` NEVER denies — Gemini's hook runs
+ *     after the user's shell confirmation, so denying it would make the user
+ *     approve a command and then see it blocked. Parse-failure / unindexed
+ *     project / already-using-specship → ALLOW.
+ *
+ * Shared code stays agent-agnostic: this file never sniffs `hook_event_name`
+ * or tool-name prefixes. The caller (bin/specship) hands in host traits
+ * derived in the hook I/O adapter (`activation/hook-output.ts`).
  */
 /**
  * The one redirect line. Explicitly advisory ("your search still runs") so
@@ -26,10 +34,19 @@
 export declare const SEARCH_INTERCEPT_TEXT: string;
 /** Per-session tracking file, kept inside the project's own `.specship/`. */
 export declare function interceptStatePath(projectRoot: string): string;
+/**
+ * Classify a shell command string for intercept purposes. We ONLY look at the
+ * first pipeline segment: `npm test | grep FAIL` uses grep as a FILTER on
+ * another command's output and must not be nudged, while `rg "renderScene"
+ * src/` is the lookup we care about. Read-shaped programs (`cat`, `head`,
+ * `tail`, `sed -n`, …) are never classified `search` — reading a config or
+ * log is legitimate.
+ */
+export declare function classifyShellCommand(cmd: string): 'search' | 'other';
 export interface SearchInterceptInput {
     /** Project the intercepted call belongs to (the hook payload's `cwd`). */
     cwd: string;
-    /** Claude Code session id from the hook payload; null → untrackable, stay silent. */
+    /** Host session id from the hook payload; null → untrackable, stay silent. */
     sessionId: string | null;
     /** Session transcript path from the hook payload, when present. */
     transcriptPath: string | null;
@@ -37,23 +54,37 @@ export interface SearchInterceptInput {
     homedir?: string;
     /** Injectable clock for tests. */
     now?: Date;
+    /** Transcript substrings signaling specship tool_use. Default: Claude form. */
+    specshipToolMarkers?: string[];
+    /** Transcript file format. Default: Claude JSONL. */
+    transcriptFormat?: 'jsonl' | 'single-json';
+    /** Strict mode (host supports a BeforeTool deny AND user opted in). */
+    strict?: boolean;
+    /** Whether the intercepted tool is a built-in search eligible for deny. */
+    denyEligible?: boolean;
+    /** When the intercepted tool is a shell runner, the raw command string. */
+    shellCommand?: string | null;
+    /** Search pattern/needle to echo in the deny reason, when known. */
+    searchPattern?: string | null;
 }
+export type SearchInterceptResult = {
+    additionalContext: string;
+} | {
+    decision: 'deny';
+    reason: string;
+} | null;
 /**
- * Decide whether to emit the redirect line for one intercepted search call.
- *
- * Silence gates, in order (all REQ-STEER-004.A3 / REQ-STEER-005):
- *   1. `SPECSHIP_NO_STEERING=1` (env > project > install settings) — same
- *      opt-out as the prompt nudge.
- *   2. No `.specship/` directory at cwd — uninitialized projects get zero
- *      noise.
- *   3. No session id — nothing to key the once-per-session guarantee on, so
- *      silence beats repeat-firing.
- *   4. The session is already recorded — it fired before, or was seen using
- *      specship.
- *   5. The transcript shows specship use — the agent doesn't need redirecting;
- *      record the session so later calls skip the scan.
+ * Decide what to emit for one intercepted search call.
  *
- * Otherwise: record the session and return the line (fires exactly once).
+ * Order:
+ *   1. `SPECSHIP_NO_STEERING=1` → ALLOW (silent).
+ *   2. No `.specship/` at cwd → ALLOW.
+ *   3. Shell runner: classify; `other` → ALLOW; `search` → advisory path
+ *      only (never deny, REQ-GEMINI-011.A3).
+ *   4. Strict + denyEligible: parse transcript; `used` or `parse-failure` or
+ *      no transcript path → ALLOW; `not-used` → DENY with reason.
+ *   5. Otherwise advisory: once-per-session, silent in sessions already using
+ *      specship (REQ-STEER-005).
  */
-export declare function buildSearchIntercept(input: SearchInterceptInput): string | null;
+export declare function buildSearchIntercept(input: SearchInterceptInput): SearchInterceptResult;
 //# sourceMappingURL=search-intercept.d.ts.map

package/lib/dist/activation/search-intercept.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-intercept.d.ts","sourceRoot":"","sources":["../../src/activation/search-intercept.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAIX,CAAC;AAExB,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AA8ED,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mEAAmE;IACnE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,GAAG,IAAI,CAwB/E"}
+{"version":3,"file":"search-intercept.d.ts","sourceRoot":"","sources":["../../src/activation/search-intercept.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAOH;;;GAGG;AACH,eAAO,MAAM,qBAAqB,QAIX,CAAC;AAExB,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE9D;AA0GD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAUpE;AAqBD,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,mEAAmE;IACnE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,GAAG,CAAC,EAAE,IAAI,CAAC;IAEX,+EAA+E;IAC/E,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,OAAO,GAAG,aAAa,CAAC;IAC3C,uEAAuE;IACvE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oEAAoE;IACpE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,iBAAiB,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpC,IAAI,CAAC;AAYT;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CA4DvF"}