@kontourai/flow-agents 0.1.2 → 0.3.0

package/integrations/strands-ts/src/hooks.ts

@@ -0,0 +1,312 @@
+/**
+ * hooks.ts — FlowAgentsHooks: the main hook provider for Strands Agents TypeScript SDK.
+ *
+ * Design: duck-typed against the Strands TS registry/event shapes so the module
+ * compiles and tests WITHOUT strands-agents installed. strands-agents is listed
+ * as an optional peerDependency in package.json.
+ *
+ * When strands-agents IS installed, FlowAgentsHooks is a valid HookProvider
+ * because it implements registerHooks(registry) which calls:
+ *   registry.addCallback(EventClass, callback)
+ *
+ * Usage (with strands-agents installed):
+ *
+ *   import { Agent, BeforeInvocationEvent, AfterInvocationEvent,
+ *            BeforeToolCallEvent, AfterToolCallEvent } from "@strands-agents/sdk";
+ *   import { FlowAgentsHooks } from "@kontourai/flow-agents-strands";
+ *
+ *   const hooks = new FlowAgentsHooks({ workspace: "." });
+ *   const agent = new Agent({ hooks: [hooks] });
+ *   // or: agent.addHook(BeforeInvocationEvent, cb);
+ *
+ * Usage (without strands-agents, e.g. tests):
+ *
+ *   import { FlowAgentsHooks } from "@kontourai/flow-agents-strands";
+ *   const hooks = new FlowAgentsHooks();
+ *   // All methods callable; registerHooks() is a no-op without the SDK.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { TelemetrySink } from "./telemetry.js";
+import { PolicyGate } from "./policy.js";
+
+// ---------------------------------------------------------------------------
+// Duck-typed Strands registry/event interfaces
+// These match the Strands TS SDK surface structurally; we do NOT import the
+// actual SDK so the module compiles without it being installed.
+// ---------------------------------------------------------------------------
+
+/** Minimal duck-type for a Strands-TS event class constructor. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type EventClass = new (...args: any[]) => unknown;
+
+/** Minimal duck-type for a Strands-TS HookRegistry. */
+export interface HookRegistry {
+  addCallback(eventClass: EventClass, callback: (event: StrandsEvent) => void): void;
+}
+
+/** Minimal duck-type for Strands events we handle. */
+export interface StrandsEvent {
+  // BeforeToolCallEvent fields
+  toolName?: string;
+  toolInput?: Record<string, unknown>;
+  // TS variant: cancellable via cancel property
+  cancel?: string;
+  // AfterToolCallEvent
+  retry?: boolean;
+  result?: unknown;
+  // Common optional fields
+  [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Kit flow discovery (Issue #32, Decision Q3: option (a))
+//
+// activateStrandsLocal (src/runtime-adapters.ts) writes kit flow files to
+// .flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json.
+// steeringContext() reads those files and surfaces their id + description
+// so the agent is aware of available workflow guidance without the hooks
+// needing to know anything about the catalog layout.
+// ---------------------------------------------------------------------------
+
+interface KitFlowEntry {
+  kitId: string;
+  assetId: string;
+  description: string;
+}
+
+function findRepoRoot(start: string): string {
+  let current = path.resolve(start);
+  for (let i = 0; i < 40; i++) {
+    if (
+      fs.existsSync(path.join(current, ".git")) ||
+      fs.existsSync(path.join(current, "AGENTS.md"))
+    ) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return path.resolve(start);
+}
+
+function readKitFlows(flowAgentsDir: string): KitFlowEntry[] {
+  const flowsDir = path.join(flowAgentsDir, "runtime", "strands", "flows");
+  if (!fs.existsSync(flowsDir)) return [];
+  const results: KitFlowEntry[] = [];
+
+  function walkDir(dir: string): void {
+    for (const name of fs.readdirSync(dir).sort()) {
+      const full = path.join(dir, name);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) {
+        walkDir(full);
+      } else if (name.endsWith(".flow.json")) {
+        try {
+          const payload = JSON.parse(fs.readFileSync(full, "utf8")) as Record<string, unknown>;
+          const stemName = name.replace(/\.flow\.json$/, "");
+          const assetId = typeof payload.id === "string" ? payload.id : stemName;
+          const description = typeof payload.description === "string" ? payload.description : "";
+          // kit_id is the directory component between flows/ and the file
+          const rel = path.relative(flowsDir, full);
+          const relParts = rel.split(path.sep);
+          const kitId = relParts.length >= 2 ? relParts[0] : "";
+          results.push({ kitId, assetId, description });
+        } catch {
+          // Malformed file — skip silently (fail-open)
+        }
+      }
+    }
+  }
+
+  walkDir(flowsDir);
+  return results;
+}
+
+function buildKitFlowsHint(flows: KitFlowEntry[]): string {
+  if (flows.length === 0) return "";
+  const lines = ["KIT FLOWS: the following kit flows are activated for this workspace:"];
+  for (const flow of flows) {
+    const desc = flow.description ? ` — ${flow.description.slice(0, 120)}` : "";
+    lines.push(`  • ${flow.assetId}${desc}`);
+  }
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// FlowAgentsHooks options
+// ---------------------------------------------------------------------------
+
+export interface FlowAgentsHooksOptions {
+  /** JSONL telemetry sink path or directory. Default: <workspace>/.telemetry/full.jsonl */
+  sinkPath?: string;
+  /** Root of the workspace (reads .flow-agents/ and .telemetry/). Default: process.cwd() */
+  workspace?: string;
+  /** Agent identifier embedded in telemetry. Default: "strands-agent" */
+  agentName?: string;
+  /** Runtime label in telemetry. Default: "strands-ts" */
+  runtime?: string;
+  /**
+   * Root of the @kontourai/flow-agents package for native engine import.
+   * Defaults to auto-discovery (see policy.ts).
+   */
+  engineRoot?: string;
+}
+
+// ---------------------------------------------------------------------------
+// FlowAgentsHooks
+// ---------------------------------------------------------------------------
+
+export class FlowAgentsHooks {
+  private readonly sink: TelemetrySink;
+  private readonly policyGate: PolicyGate;
+  private readonly _workspace: string;
+  private _sessionStartMs: number | null = null;
+
+  constructor(options: FlowAgentsHooksOptions = {}) {
+    this._workspace = findRepoRoot(options.workspace ?? process.cwd());
+
+    this.sink = new TelemetrySink({
+      sinkPath: options.sinkPath,
+      workspace: options.workspace,
+      agentName: options.agentName ?? "strands-agent",
+      runtime: options.runtime ?? "strands-ts",
+    });
+
+    this.policyGate = new PolicyGate({
+      engineRoot: options.engineRoot,
+    });
+  }
+
+  // --------------------------------------------------------------------------
+  // Steering context — available without strands-agents installed (Issue #32 AC2)
+  // --------------------------------------------------------------------------
+
+  /**
+   * Return workflow-steering context text for the current workspace.
+   *
+   * Includes activated kit flows discovered from the strands-local runtime
+   * path (.flow-agents/runtime/strands/flows/) written by
+   * `flow-kit activate --adapter strands-local`.
+   *
+   * Callers should prepend this to the Agent's system prompt:
+   *
+   *   const hooks = new FlowAgentsHooks({ workspace: "." });
+   *   const agent = new Agent({ systemPrompt: basePrompt + hooks.steeringContext() });
+   */
+  steeringContext(): string {
+    const flowAgentsDir = path.join(this._workspace, ".flow-agents");
+    const flows = readKitFlows(flowAgentsDir);
+    const kitFlowsHint = buildKitFlowsHint(flows);
+    if (!kitFlowsHint) return "";
+    return "\n\n---\n" + kitFlowsHint + "\n---";
+  }
+
+  // --------------------------------------------------------------------------
+  // HookProvider protocol — registerHooks(registry)
+  // This is the sole method required by the Strands HookProvider protocol.
+  // --------------------------------------------------------------------------
+
+  /**
+   * Register Flow Agents callbacks with a Strands HookRegistry.
+   *
+   * Requires strands-agents to be installed. If the SDK is absent,
+   * this method throws ImportError with instructions.
+   */
+  registerHooks(registry: HookRegistry): void {
+    // Lazily import Strands event classes. If the SDK is not installed,
+    // a helpful error is thrown.
+    let BeforeInvocationEvent: EventClass;
+    let AfterInvocationEvent: EventClass;
+    let BeforeToolCallEvent: EventClass;
+    let AfterToolCallEvent: EventClass;
+
+    try {
+      // Dynamic import is used so the module compiles without the SDK installed.
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const sdk = require("strands-agents") as {
+        BeforeInvocationEvent: EventClass;
+        AfterInvocationEvent: EventClass;
+        BeforeToolCallEvent: EventClass;
+        AfterToolCallEvent: EventClass;
+      };
+      BeforeInvocationEvent = sdk.BeforeInvocationEvent;
+      AfterInvocationEvent = sdk.AfterInvocationEvent;
+      BeforeToolCallEvent = sdk.BeforeToolCallEvent;
+      AfterToolCallEvent = sdk.AfterToolCallEvent;
+    } catch (err) {
+      throw new Error(
+        "strands-agents is required to register hooks. " +
+          "Install it with: npm install @strands-agents/sdk\n" +
+          `Original error: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+
+    registry.addCallback(BeforeInvocationEvent, (event) => this.onBeforeInvocation(event));
+    registry.addCallback(AfterInvocationEvent, (event) => this.onAfterInvocation(event));
+    registry.addCallback(BeforeToolCallEvent, (event) => this.onBeforeToolCall(event));
+    registry.addCallback(AfterToolCallEvent, (event) => this.onAfterToolCall(event));
+  }
+
+  // --------------------------------------------------------------------------
+  // Callbacks — public for direct wiring in tests / without SDK
+  // --------------------------------------------------------------------------
+
+  /** BeforeInvocationEvent → userPromptSubmit / turn.user */
+  onBeforeInvocation(_event: StrandsEvent): void {
+    if (this._sessionStartMs === null) {
+      this._sessionStartMs = Date.now();
+    }
+    this.sink.emitUserPromptSubmit();
+  }
+
+  /** AfterInvocationEvent → stop / session.end */
+  onAfterInvocation(_event: StrandsEvent): void {
+    const durationMs =
+      this._sessionStartMs !== null ? Date.now() - this._sessionStartMs : 0;
+    this.sink.emitSessionEnd(durationMs);
+  }
+
+  /**
+   * BeforeToolCallEvent → preToolUse / tool.invoke + config-protection policy gate.
+   *
+   * If the policy gate blocks the call, sets event.cancel to the block reason
+   * (Strands TS variant: event.cancel = "reason").
+   */
+  onBeforeToolCall(event: StrandsEvent): void {
+    const toolName = (event.toolName as string | undefined) ?? "";
+    const toolInput = (event.toolInput as Record<string, unknown> | undefined) ?? {};
+
+    // Emit telemetry first (fail-open: policy check follows)
+    this.sink.emitToolInvoke(toolName, toolInput);
+
+    // Policy gate — native engine call (no subprocess)
+    const blockReason = this.policyGate.checkToolCall(toolName, toolInput);
+    if (blockReason) {
+      try {
+        event.cancel = blockReason;
+      } catch {
+        // Some event mock or future SDK change; ignore and continue
+      }
+    }
+  }
+
+  /** AfterToolCallEvent → postToolUse / tool.result */
+  onAfterToolCall(event: StrandsEvent): void {
+    const toolName = (event.toolName as string | undefined) ?? "";
+    const result = event.result;
+    this.sink.emitToolResult(toolName, result);
+  }
+
+  // --------------------------------------------------------------------------
+  // Session start — emit agentSpawn when wiring is complete
+  // --------------------------------------------------------------------------
+
+  /** Call once after constructing / wiring to emit the agentSpawn event. */
+  emitSessionStart(): void {
+    this._sessionStartMs = Date.now();
+    this.sink.emitSessionStart();
+  }
+}

package/integrations/strands-ts/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @kontourai/flow-agents-strands
+ *
+ * Native-import TypeScript adapter for AWS Strands Agents.
+ *
+ * Wires Flow Agents policy engine directly into Strands hook callbacks without
+ * spawning a subprocess. This is the first native-import consumer of the Flow
+ * Agents policy engine contract.
+ */
+
+export { FlowAgentsHooks } from "./hooks.js";
+export type {
+  FlowAgentsHooksOptions,
+  HookRegistry,
+  StrandsEvent,
+} from "./hooks.js";
+
+export { TelemetrySink, STRANDS_TO_CANONICAL, normalizeToolName, SCHEMA_VERSION } from "./telemetry.js";
+export type { TelemetrySinkOptions, TelemetryEvent } from "./telemetry.js";
+
+export { PolicyGate, PROTECTED_FILES } from "./policy.js";
+export type { PolicyGateOptions } from "./policy.js";

package/integrations/strands-ts/src/policy.ts

@@ -0,0 +1,345 @@
+/**
+ * policy.ts — Native-import policy gate for BeforeToolCallEvent.
+ *
+ * Primary binding: NATIVE import of scripts/hooks/config-protection.js via
+ * its module.exports.run(raw, opts) API — no subprocess.  This is the key
+ * differentiator from the Python adapter which uses a subprocess binding.
+ *
+ * The run() API contract (from run-hook.js §8.2, Form 2):
+ *   run(rawJsonString, { truncated, maxStdin }) → string | { exitCode, stderr?, stdout? }
+ *
+ * Exit code / return value semantics:
+ *   exitCode 0   → allow (return null)
+ *   exitCode 2   → block (return block reason string from stderr/stdout)
+ *   other/error  → fail-open (return null)
+ *
+ * Engine location resolution (in priority order):
+ *   1. Constructor option `engineRoot` (explicit root dir — if provided but invalid,
+ *      stops here and returns null; does NOT fall through to auto-discovery).
+ *   2. FLOW_AGENTS_ENGINE_ROOT env var.
+ *   3. Relative to this file: ../../../scripts/hooks/ (repo checkout layout).
+ *   4. Walk up from cwd: node_modules/@kontourai/flow-agents/scripts/hooks/.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ---------------------------------------------------------------------------
+// Protected files set — mirrors PROTECTED_FILES in config-protection.js
+// Used as fallback when native engine is unavailable.
+// ---------------------------------------------------------------------------
+
+export const PROTECTED_FILES: ReadonlySet<string> = new Set([
+  // ESLint
+  ".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",
+  // Prettier
+  ".prettierrc",
+  ".prettierrc.js",
+  ".prettierrc.cjs",
+  ".prettierrc.json",
+  ".prettierrc.yml",
+  ".prettierrc.yaml",
+  "prettier.config.js",
+  "prettier.config.cjs",
+  "prettier.config.mjs",
+  // Biome
+  "biome.json",
+  "biome.jsonc",
+  // Ruff
+  ".ruff.toml",
+  "ruff.toml",
+  // Others
+  ".shellcheckrc",
+  ".stylelintrc",
+  ".stylelintrc.json",
+  ".stylelintrc.yml",
+  ".markdownlint.json",
+  ".markdownlint.yaml",
+  ".markdownlintrc",
+]);
+
+// Write-like tool names — only gate write-like tools; reads are always allowed.
+const WRITE_TOOLS: ReadonlySet<string> = new Set([
+  "edit",
+  "write",
+  "fs_write",
+  "apply_patch",
+  "create_file",
+  "str_replace_editor",
+]);
+
+const BLOCK_REASON_TEMPLATE = (basename: string): string =>
+  `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 policy gate temporarily.";
+
+// ---------------------------------------------------------------------------
+// Engine location resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the hooksDir (directory containing config-protection.js etc).
+ *
+ * When engineRootOverride is provided:
+ *   - If the override is a valid repo root (contains scripts/hooks/run-hook.js):
+ *     return that hooksDir.
+ *   - If the override is a valid hooks dir itself (contains run-hook.js directly):
+ *     return that dir.
+ *   - Otherwise: return null. Do NOT fall through to auto-discovery.
+ *     This ensures an explicit but invalid override surfaces clearly.
+ *
+ * When engineRootOverride is absent:
+ *   Auto-discover via env var → file-relative → cwd walk.
+ */
+function resolveHooksDir(engineRootOverride?: string): string | null {
+  // 1. Explicit override provided — do not fall through to auto-discovery
+  if (engineRootOverride !== undefined) {
+    const asRepoRoot = path.join(engineRootOverride, "scripts", "hooks");
+    if (fs.existsSync(path.join(asRepoRoot, "run-hook.js"))) {
+      return asRepoRoot;
+    }
+    // Allow engineRoot to point directly at scripts/hooks/
+    if (fs.existsSync(path.join(engineRootOverride, "run-hook.js"))) {
+      return engineRootOverride;
+    }
+    return null; // explicit override specified but invalid
+  }
+
+  // 2. Env var
+  const envRoot = process.env.FLOW_AGENTS_ENGINE_ROOT;
+  if (envRoot) {
+    const candidate = path.join(envRoot, "scripts", "hooks");
+    if (fs.existsSync(path.join(candidate, "run-hook.js"))) return candidate;
+    if (fs.existsSync(path.join(envRoot, "run-hook.js"))) return envRoot;
+  }
+
+  // 3. Relative to this file (repo checkout layout)
+  // __dirname is dist/src/ at runtime, src/ when run as source
+  // scripts/hooks/ is relative to the repo root, not this file
+  for (const relPath of [
+    path.resolve(__dirname, "../../../scripts/hooks"),     // src/ layout (3 up)
+    path.resolve(__dirname, "../../../../scripts/hooks"),  // dist/src/ layout (4 up)
+  ]) {
+    if (fs.existsSync(path.join(relPath, "run-hook.js"))) {
+      return relPath;
+    }
+  }
+
+  // 4. Walk up from cwd looking for npm-installed package
+  let current = process.cwd();
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(
+      current,
+      "node_modules",
+      "@kontourai",
+      "flow-agents",
+      "scripts",
+      "hooks"
+    );
+    if (fs.existsSync(path.join(candidate, "run-hook.js"))) {
+      return candidate;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Native engine call (Form 2 — module.exports.run())
+// ---------------------------------------------------------------------------
+
+interface HookRunOutput {
+  exitCode?: number;
+  stderr?: string;
+  stdout?: string;
+}
+
+type HookRunResult = string | HookRunOutput;
+
+interface HookModule {
+  run(raw: string, options: { truncated: boolean; maxStdin: number }): HookRunResult;
+}
+
+function loadHookModule(hooksDir: string, scriptName: string): HookModule | null {
+  const scriptPath = path.join(hooksDir, scriptName);
+  if (!fs.existsSync(scriptPath)) return null;
+
+  try {
+    // Use createRequire for CJS modules from ESM context
+    const require = createRequire(import.meta.url);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const mod = require(scriptPath) as any;
+    if (mod && typeof mod.run === "function") {
+      return mod as HookModule;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function interpretRunResult(result: HookRunResult): { exitCode: number; blockReason: string | null } {
+  if (typeof result === "string") {
+    // String return = stdout pass-through → allow
+    return { exitCode: 0, blockReason: null };
+  }
+  if (result && typeof result === "object") {
+    const exitCode = typeof result.exitCode === "number" ? result.exitCode : 0;
+    if (exitCode === 2) {
+      const reason =
+        result.stderr?.trim() ||
+        result.stdout?.trim() ||
+        "BLOCKED: config-protection policy blocked this action.";
+      return { exitCode: 2, blockReason: reason };
+    }
+    return { exitCode, blockReason: null };
+  }
+  return { exitCode: 0, blockReason: null };
+}
+
+// ---------------------------------------------------------------------------
+// Pure-TS fallback — mirrors the JS config-protection.js logic
+// ---------------------------------------------------------------------------
+
+function tsConfigProtection(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+  protectedFiles: ReadonlySet<string> = PROTECTED_FILES
+): string | null {
+  if (!WRITE_TOOLS.has(toolName.toLowerCase())) return null;
+
+  const filePath =
+    (toolInput.path as string | undefined) ||
+    (toolInput.file_path as string | undefined) ||
+    "";
+  if (!filePath) return null;
+
+  const basename = path.basename(filePath);
+  if (protectedFiles.has(basename)) {
+    return BLOCK_REASON_TEMPLATE(basename);
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// PolicyGate
+// ---------------------------------------------------------------------------
+
+export interface PolicyGateOptions {
+  /**
+   * Root directory of the @kontourai/flow-agents package (the directory
+   * containing scripts/hooks/run-hook.js). Defaults to auto-discovery.
+   *
+   * If provided but invalid (engine not found there), the gate uses pure-TS
+   * fallback and does NOT attempt auto-discovery.
+   */
+  engineRoot?: string;
+  /**
+   * Custom set of protected file basenames. When provided, the native engine
+   * is bypassed and pure-TS evaluation is used (intended for tests only).
+   */
+  customProtectedFiles?: ReadonlySet<string>;
+  /**
+   * If true, suppress the one-time console.warn when falling back to TS evaluation.
+   */
+  suppressFallbackWarning?: boolean;
+}
+
+export class PolicyGate {
+  private readonly configProtectionModule: HookModule | null;
+  private readonly customProtectedFiles: ReadonlySet<string> | undefined;
+  private readonly suppressFallbackWarning: boolean;
+  private _warnedFallback = false;
+
+  constructor(options: PolicyGateOptions = {}) {
+    this.customProtectedFiles = options.customProtectedFiles;
+    this.suppressFallbackWarning = options.suppressFallbackWarning ?? false;
+
+    const hooksDir = resolveHooksDir(options.engineRoot);
+    if (hooksDir) {
+      this.configProtectionModule = loadHookModule(hooksDir, "config-protection.js");
+    } else {
+      this.configProtectionModule = null;
+    }
+  }
+
+  get engineAvailable(): boolean {
+    return this.configProtectionModule !== null;
+  }
+
+  private warnFallback(): void {
+    if (this._warnedFallback || this.suppressFallbackWarning) return;
+    this._warnedFallback = true;
+    console.warn(
+      "[flow-agents-strands] Warning: The Flow Agents policy engine (config-protection.js) " +
+        "could not be loaded via native import. Policy gates are degrading to the built-in " +
+        "TypeScript fallback (fail-open for unknown cases). " +
+        "Set FLOW_AGENTS_ENGINE_ROOT to the @kontourai/flow-agents root directory to " +
+        "use the canonical engine. See README.md §Limitations."
+    );
+  }
+
+  /**
+   * Check whether a tool call is allowed by config-protection policy.
+   *
+   * Returns null if allowed, or a block-reason string if blocked.
+   * Always fail-open on errors.
+   */
+  checkToolCall(
+    toolName: string,
+    toolInput: Record<string, unknown>
+  ): string | null {
+    // Tool-name pre-filter: reads are always allowed
+    if (!WRITE_TOOLS.has(toolName.toLowerCase())) return null;
+
+    // Custom protected set → pure-TS evaluation only
+    if (this.customProtectedFiles !== undefined) {
+      return tsConfigProtection(toolName, toolInput, this.customProtectedFiles);
+    }
+
+    // Native engine call (the key differentiator vs Python subprocess adapter)
+    if (this.configProtectionModule !== null) {
+      const payload = JSON.stringify({
+        hook_event_name: "PreToolUse",
+        tool_name: toolName,
+        tool_input: toolInput,
+      });
+
+      try {
+        const result = this.configProtectionModule.run(payload, {
+          truncated: false,
+          maxStdin: 1024 * 1024,
+        });
+        const { blockReason } = interpretRunResult(result);
+        return blockReason;
+      } catch {
+        // fail-open on native call errors
+        return null;
+      }
+    }
+
+    // Fallback: pure-TS evaluation
+    this.warnFallback();
+    return tsConfigProtection(toolName, toolInput);
+  }
+}