clementine-agent 1.18.210 → 1.18.211

package/dist/agent/clarification-gate.d.ts

@@ -58,10 +58,59 @@ export interface BlockedActionClassifier {
  * state machine; providers own only small classifiers and resume instructions.
  */
 export declare function registerBlockedActionClassifier(classifier: BlockedActionClassifier): () => void;
+export interface PreconditionEnv {
+    /** Working directory the agent will use for this tool call. */
+    cwd: string;
+    /** Active project path if the router resolved one. */
+    activeProjectPath?: string;
+    /** filesystem.existsSync injection point for testability. */
+    existsSync?: (path: string) => boolean;
+}
+export interface PreconditionMatch {
+    /** The command or tool action that would have run (for owner display). */
+    attemptedCommand: string;
+    /** The reason the precondition failed (for owner display). */
+    reason: string;
+    /** Optional project path inferred from the input (e.g. `cd /path && netlify deploy`). */
+    projectPath?: string;
+}
+export interface PreconditionClassifier {
+    id: string;
+    category: BlockedActionCategory;
+    provider: string;
+    providerLabel: string;
+    targetNoun: string;
+    targetPlaceholder: string;
+    blockerSummary: string;
+    /** Tool names this classifier inspects. e.g. ['Bash'] or
+     *  ['mcp__clementine-tools__project_deploy']. Wildcard `'*'` not supported —
+     *  classifiers should be narrow on purpose. */
+    toolNames: readonly string[];
+    /** Returns a PreconditionMatch when the call should be blocked, or null
+     *  to let it proceed. Errors thrown here are caught and treated as a pass
+     *  (fail-open) — the post-hoc classifier still catches the failure. */
+    matchesPreconditions(input: Record<string, unknown>, env: PreconditionEnv): PreconditionMatch | null;
+    createInstructions: string[];
+    existingInstructions: string[];
+}
+/** Extension point for pre-call classifiers. Mirrors registerBlockedActionClassifier. */
+export declare function registerPreconditionClassifier(classifier: PreconditionClassifier): () => void;
 export declare function buildBlockedActionDecisionFromRunSummary(summary: RunSummary, originalRequest: string, nowMs?: number): PendingAgentDecision | null;
 export declare function parseAgentDecisionReply(decision: PendingAgentDecision, message: string): AgentDecisionReply;
 export declare function buildAgentDecisionContinuationPrompt(decision: PendingAgentDecision, reply: Extract<AgentDecisionReply, {
     kind: 'answer';
 }>): string;
 export declare const buildRepairDecisionFromRunSummary: typeof buildBlockedActionDecisionFromRunSummary;
+/**
+ * Run all registered precondition classifiers against an attempted tool
+ * call. Returns the first PendingAgentDecision that matches, or null if
+ * the call should proceed. Errors inside individual classifiers are
+ * swallowed (fail-open) — the post-hoc classifier remains as the safety
+ * net for any case the pre-call rule mishandles.
+ */
+export declare function evaluatePreconditionsForToolCall(toolName: string, input: Record<string, unknown>, env: PreconditionEnv, opts?: {
+    originalRequest?: string;
+    runId?: string;
+    nowMs?: number;
+}): PendingAgentDecision | null;
 //# sourceMappingURL=clarification-gate.d.ts.map

package/dist/agent/clarification-gate.js

@@ -11,6 +11,16 @@ export function registerBlockedActionClassifier(classifier) {
             customClassifiers.splice(index, 1);
     };
 }
+const customPreconditionClassifiers = [];
+/** Extension point for pre-call classifiers. Mirrors registerBlockedActionClassifier. */
+export function registerPreconditionClassifier(classifier) {
+    customPreconditionClassifiers.unshift(classifier);
+    return () => {
+        const index = customPreconditionClassifiers.indexOf(classifier);
+        if (index >= 0)
+            customPreconditionClassifiers.splice(index, 1);
+    };
+}
 function firstString(...values) {
     for (const value of values) {
         if (typeof value === 'string' && value.trim())
@@ -268,4 +278,125 @@ export function buildAgentDecisionContinuationPrompt(decision, reply) {
 // Backward-compatible alias for the router/tests while callers migrate to the
 // provider-neutral name.
 export const buildRepairDecisionFromRunSummary = buildBlockedActionDecisionFromRunSummary;
+// ─── Pre-call decision construction ────────────────────────────────────
+function preconditionClassifiers() {
+    return [...customPreconditionClassifiers, ...BUILTIN_PRECONDITION_CLASSIFIERS];
+}
+/**
+ * Run all registered precondition classifiers against an attempted tool
+ * call. Returns the first PendingAgentDecision that matches, or null if
+ * the call should proceed. Errors inside individual classifiers are
+ * swallowed (fail-open) — the post-hoc classifier remains as the safety
+ * net for any case the pre-call rule mishandles.
+ */
+export function evaluatePreconditionsForToolCall(toolName, input, env, opts = {}) {
+    const nowMs = opts.nowMs ?? Date.now();
+    for (const classifier of preconditionClassifiers()) {
+        if (!classifier.toolNames.includes(toolName))
+            continue;
+        let match = null;
+        try {
+            match = classifier.matchesPreconditions(input, env);
+        }
+        catch {
+            // Fail-open — the post-hoc classifier will catch a failure.
+            continue;
+        }
+        if (!match)
+            continue;
+        const decision = {
+            id: makeDecisionId('blocked_external_action'),
+            kind: 'blocked_external_action',
+            createdAt: nowMs,
+            expiresAt: nowMs + 30 * 60_000,
+            runIds: opts.runId ? [opts.runId] : [],
+            originalRequest: opts.originalRequest ?? '',
+            question: '',
+            context: {
+                category: classifier.category,
+                classifierId: classifier.id,
+                provider: classifier.provider,
+                providerLabel: classifier.providerLabel,
+                blockerSummary: classifier.blockerSummary,
+                failedCommand: compactCommand(match.attemptedCommand),
+                error: compactValue(match.reason, 500),
+                targetNoun: classifier.targetNoun,
+                targetPlaceholder: classifier.targetPlaceholder,
+                createInstructions: classifier.createInstructions,
+                existingInstructions: classifier.existingInstructions,
+                ...(match.projectPath ? { projectPath: match.projectPath } : {}),
+            },
+        };
+        decision.question = formatDecisionPrompt(decision);
+        return decision;
+    }
+    return null;
+}
+// ─── Built-in precondition classifiers ─────────────────────────────────
+import { existsSync as nodeExistsSync } from 'node:fs';
+import { join as pathJoin } from 'node:path';
+/**
+ * Netlify deploy precondition: deny `netlify deploy` (or our project_deploy
+ * tool when its provider is netlify) when the project has no record of a
+ * linked site. Mirrors the post-hoc netlify_missing_deployment_target
+ * classifier but fires BEFORE the tool runs.
+ *
+ * Detection signals (any one is sufficient to allow):
+ *   - `.netlify/state.json` exists in the project dir (netlify CLI's own
+ *     link record)
+ *   - `.clementine/deploy.json` exists in the project dir (Clementine's
+ *     deploy config)
+ *
+ * If neither exists AND the project dir is identifiable, we deny pre-call
+ * and ask the owner. If the project dir is not identifiable (e.g. the
+ * agent invoked `netlify deploy` without a `cd` prefix), we fail-open
+ * and let the post-hoc classifier handle it.
+ */
+const netlifyMissingLinkPrecondition = {
+    id: 'netlify_missing_deployment_target',
+    category: 'deployment_target_missing',
+    provider: 'netlify',
+    providerLabel: 'Netlify',
+    targetNoun: 'deployment target',
+    targetPlaceholder: 'target-slug-or-id',
+    blockerSummary: 'This project does not have a Netlify deployment target linked yet. Deploying will fail until one is configured.',
+    toolNames: ['Bash'],
+    matchesPreconditions(input, env) {
+        const command = firstString(input.command);
+        if (!command)
+            return null;
+        if (!/\bnetlify\s+deploy\b/i.test(command))
+            return null;
+        const projectPath = extractProjectPathFromCommand(command) ?? env.activeProjectPath;
+        if (!projectPath)
+            return null; // can't check — fail open
+        const exists = env.existsSync ?? nodeExistsSync;
+        const netlifyLinked = exists(pathJoin(projectPath, '.netlify', 'state.json'));
+        const clementineDeployConfig = exists(pathJoin(projectPath, '.clementine', 'deploy.json'));
+        if (netlifyLinked || clementineDeployConfig)
+            return null;
+        return {
+            attemptedCommand: compactCommand(command),
+            reason: 'No `.netlify/state.json` or `.clementine/deploy.json` found in the project. Netlify CLI will fail with "Project not found. Please rerun \'netlify link\'".',
+            projectPath,
+        };
+    },
+    createInstructions: [
+        'Create or link a new Netlify deployment target for this project, then deploy and verify the live URL.',
+        'Do not restart project discovery or reread full generated artifacts unless a small targeted read is necessary.',
+        'If provider auth, browser login, or an interactive naming choice is required and cannot be completed safely, stop and ask one concrete question.',
+        'If a Clementine deploy config is appropriate, write `.clementine/deploy.json` with the provider kind, target identifier, deploy directory, and verify URL.',
+        'Prefer `project_deploy` once deploy config exists; otherwise run the equivalent provider deploy command and verify the live URL before claiming success.',
+    ],
+    existingInstructions: [
+        'Use or link the existing Netlify target: {target}',
+        'Do not restart project discovery or reread full generated artifacts unless a small targeted read is necessary.',
+        'Write or update `.clementine/deploy.json` for the existing target before deploying when that config is supported.',
+        'Prefer `project_deploy` once deploy config exists; otherwise run the equivalent provider deploy command and verify the live URL before claiming success.',
+        'If the provider rejects the target or auth is missing, stop and ask one concrete question with the exact CLI/API error.',
+    ],
+};
+const BUILTIN_PRECONDITION_CLASSIFIERS = [
+    netlifyMissingLinkPrecondition,
+];
 //# sourceMappingURL=clarification-gate.js.map

package/dist/agent/precondition-guard.d.ts

@@ -0,0 +1,61 @@
+/**
+ * precondition-guard — SDK PreToolUse hooks that evaluate the registered
+ * precondition classifiers before each tool call. When a classifier
+ * matches, the hook returns `permissionDecision: 'deny'` with a reason,
+ * captures the PendingAgentDecision in module-scoped state for the run,
+ * and runAgent surfaces it to the router via RunAgentResult.
+ *
+ * Why this exists
+ * ───────────────
+ * `clarification-gate.ts` already handles owner-decision routing for
+ * blocked external actions, but its existing BlockedActionClassifier API
+ * is post-hoc: the tool already ran and failed, so we parse the error,
+ * inferred the blocker, then asked the owner. That leaves partial state
+ * behind (a half-deploy, a created-but-unconfigured target, an emitted
+ * webhook that can't be undone).
+ *
+ * The orchestrator-first north star prefers pre-emptive gates. The SDK
+ * exposes PreToolUse hooks that run BEFORE every tool call regardless
+ * of permissionMode. We use them to short-circuit known-bad calls
+ * before they fire. The same PendingAgentDecision shape flows through
+ * the router, so the owner experience is identical — only the failure
+ * surface is narrower.
+ *
+ * Why PreToolUse over canUseTool
+ * ──────────────────────────────
+ * `canUseTool` is permission-prompt scoped and may be skipped under
+ * `bypassPermissions` mode. `PreToolUse` hooks fire universally. The
+ * SDK's own doc string on PermissionDeniedMessage confirms:
+ *
+ *   "PreToolUse hook denies bypass canUseTool and are not covered here."
+ *
+ * That means PreToolUse decisions run FIRST, even when canUseTool is
+ * absent or short-circuited. PreToolUse is also already wired into the
+ * runAgent hooks pipeline (`tool-output-guard`, `dedup`,
+ * `idempotency`), so this fits the established pattern.
+ */
+import type { HookCallbackMatcher, HookEvent } from '@anthropic-ai/claude-agent-sdk';
+import { type PendingAgentDecision } from './clarification-gate.js';
+export interface PreconditionGuardOptions {
+    /** Working directory the agent is running in. Used by classifiers to
+     *  resolve relative project paths. */
+    cwd: string;
+    /** Active project path if the router resolved one. Optional. */
+    activeProjectPath?: string;
+    /** The original owner request that started this run. Used to populate
+     *  PendingAgentDecision.originalRequest when a precondition fires.
+     *  Optional — the router can fill it in later if needed. */
+    originalRequest?: string;
+    /** Stable run UUID. Stored on the decision so post-resume continues
+     *  to reference the same run. */
+    runId: string;
+}
+export interface PreconditionGuardHandles {
+    /** SDK hook map. Merge into the runAgent hooks pipeline. */
+    hooks: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    /** Read out the captured decision after the SDK stream ends. Null when
+     *  no precondition fired during the run. */
+    getCapturedDecision(): PendingAgentDecision | null;
+}
+export declare function buildPreconditionGuardHooks(opts: PreconditionGuardOptions): PreconditionGuardHandles;
+//# sourceMappingURL=precondition-guard.d.ts.map

package/dist/agent/precondition-guard.js

@@ -0,0 +1,88 @@
+/**
+ * precondition-guard — SDK PreToolUse hooks that evaluate the registered
+ * precondition classifiers before each tool call. When a classifier
+ * matches, the hook returns `permissionDecision: 'deny'` with a reason,
+ * captures the PendingAgentDecision in module-scoped state for the run,
+ * and runAgent surfaces it to the router via RunAgentResult.
+ *
+ * Why this exists
+ * ───────────────
+ * `clarification-gate.ts` already handles owner-decision routing for
+ * blocked external actions, but its existing BlockedActionClassifier API
+ * is post-hoc: the tool already ran and failed, so we parse the error,
+ * inferred the blocker, then asked the owner. That leaves partial state
+ * behind (a half-deploy, a created-but-unconfigured target, an emitted
+ * webhook that can't be undone).
+ *
+ * The orchestrator-first north star prefers pre-emptive gates. The SDK
+ * exposes PreToolUse hooks that run BEFORE every tool call regardless
+ * of permissionMode. We use them to short-circuit known-bad calls
+ * before they fire. The same PendingAgentDecision shape flows through
+ * the router, so the owner experience is identical — only the failure
+ * surface is narrower.
+ *
+ * Why PreToolUse over canUseTool
+ * ──────────────────────────────
+ * `canUseTool` is permission-prompt scoped and may be skipped under
+ * `bypassPermissions` mode. `PreToolUse` hooks fire universally. The
+ * SDK's own doc string on PermissionDeniedMessage confirms:
+ *
+ *   "PreToolUse hook denies bypass canUseTool and are not covered here."
+ *
+ * That means PreToolUse decisions run FIRST, even when canUseTool is
+ * absent or short-circuited. PreToolUse is also already wired into the
+ * runAgent hooks pipeline (`tool-output-guard`, `dedup`,
+ * `idempotency`), so this fits the established pattern.
+ */
+import pino from 'pino';
+import { evaluatePreconditionsForToolCall, } from './clarification-gate.js';
+const logger = pino({ name: 'clementine.precondition-guard' });
+export function buildPreconditionGuardHooks(opts) {
+    let capturedDecision = null;
+    const env = {
+        cwd: opts.cwd,
+        ...(opts.activeProjectPath ? { activeProjectPath: opts.activeProjectPath } : {}),
+    };
+    const preToolUse = async (input, _toolUseID) => {
+        if (input.hook_event_name !== 'PreToolUse') {
+            return {};
+        }
+        const evt = input;
+        const toolName = String(evt.tool_name ?? 'unknown');
+        const toolInput = (evt.tool_input ?? {});
+        // Already captured a decision earlier in this run — let everything
+        // after pass through. The first deny interrupts the loop; subsequent
+        // tool calls (if any) shouldn't be re-evaluated.
+        if (capturedDecision)
+            return {};
+        const decision = evaluatePreconditionsForToolCall(toolName, toolInput, env, {
+            ...(opts.originalRequest ? { originalRequest: opts.originalRequest } : {}),
+            runId: opts.runId,
+        });
+        if (!decision)
+            return {};
+        capturedDecision = decision;
+        logger.info({
+            toolName,
+            classifierId: decision.context.classifierId,
+            provider: decision.context.provider,
+            runId: opts.runId,
+        }, 'precondition-guard: denied tool call pre-flight; surfacing PendingAgentDecision');
+        return {
+            hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: 'deny',
+                permissionDecisionReason: decision.question,
+            },
+        };
+    };
+    return {
+        hooks: {
+            PreToolUse: [{ hooks: [preToolUse] }],
+        },
+        getCapturedDecision() {
+            return capturedDecision;
+        },
+    };
+}
+//# sourceMappingURL=precondition-guard.js.map

package/dist/agent/run-agent.d.ts

@@ -37,6 +37,7 @@ export declare function invalidateMcpStatusEntry(name: string): {
     updatedAt: string;
 };
 import { type ToolOutputGuardConfig } from './tool-output-guard.js';
+import type { PendingAgentDecision } from './clarification-gate.js';
 import type { AgentProfile } from '../types.js';
 import type { AgentManager } from './agent-manager.js';
 import type { MemoryStore } from '../memory/store.js';
@@ -158,6 +159,13 @@ export interface RunAgentResult {
     allowedToolsApplied?: string[];
     builtinToolsApplied?: string[];
     mcpServersApplied?: string[];
+    /** A precondition classifier fired during this run, blocking a tool
+     *  call before it executed. The router surfaces this to the owner via
+     *  the pendingAgentDecision flow (clarification-gate.ts). Distinct
+     *  from the post-hoc path that runs on RunSummary.failedSideEffects —
+     *  this path means the tool NEVER ran, no partial state was left
+     *  behind. */
+    pendingAgentDecision?: PendingAgentDecision;
 }
 /**
  * Run a single agent invocation via the canonical SDK pattern.

package/dist/agent/run-agent.js

@@ -100,6 +100,7 @@ import { buildDedupHook } from './tool-call-dedup.js';
 import { buildSideEffectIdempotencyHook } from './side-effect-idempotency.js';
 import { buildChatStopHook } from './chat-stop-hook.js';
 import { buildRunStateHooks } from './run-state.js';
+import { buildPreconditionGuardHooks } from './precondition-guard.js';
 import { buildAgentMap } from './agent-definitions.js';
 import { buildExecutionToolPolicy, } from './execution-policy.js';
 const MCP_SERVER_SCRIPT = path.join(PKG_DIR, 'dist', 'tools', 'mcp-server.js');
@@ -523,9 +524,34 @@ export async function runAgent(prompt, opts) {
             },
         })
         : null;
+    // ── Pre-emptive blocked-action gate (Commit 3 / 1.18.211) ──────────
+    // Evaluates registered precondition classifiers before each tool call
+    // via a PreToolUse hook. When a classifier matches (e.g. `netlify
+    // deploy` with no `.netlify/state.json` and no `.clementine/deploy.json`),
+    // the tool is denied with the decision question as the reason and the
+    // PendingAgentDecision is captured for surfacing via RunAgentResult.
+    // The router stashes it on the session and asks the owner instead of
+    // letting the tool fire and leave partial state behind. The existing
+    // post-hoc BlockedActionClassifier path (clarification-gate.ts) is
+    // unchanged and remains as the safety net for failures the pre-call
+    // rule didn't anticipate.
+    const preconditionGuard = buildPreconditionGuardHooks({
+        runId,
+        cwd: opts.cwd ?? BASE_DIR,
+        // The chat path already wires `activeProject?.path` into opts.cwd
+        // (router.ts), so cwd doubles as the active-project hint for the
+        // classifier. Falling back inside the classifier keeps the public
+        // RunAgentOptions surface unchanged.
+        activeProjectPath: opts.cwd ?? BASE_DIR,
+        originalRequest: prompt,
+    });
     // Merge hook maps from the modules. SDK accepts arrays of
     // HookCallbackMatcher per event; we concatenate.
     const mergedHooks = { ...guard.hooks };
+    for (const [evt, matchers] of Object.entries(preconditionGuard.hooks)) {
+        const existing = mergedHooks[evt] ?? [];
+        mergedHooks[evt] = [...existing, ...matchers];
+    }
     for (const [evt, matchers] of Object.entries(idempotency.hooks)) {
         const existing = mergedHooks[evt] ?? [];
         mergedHooks[evt] = [...existing, ...matchers];
@@ -929,6 +955,7 @@ export async function runAgent(prompt, opts) {
     catch (err) {
         logger.debug({ err }, 'runAgent: subagent backfill failed (non-fatal)');
     }
+    const pendingAgentDecision = preconditionGuard.getCapturedDecision();
     return {
         text: finalText,
         totalCostUsd,
@@ -942,6 +969,7 @@ export async function runAgent(prompt, opts) {
         allowedToolsApplied: sdkAllowedTools,
         builtinToolsApplied: toolPolicy.builtinTools,
         mcpServersApplied: Object.keys(mcpServers),
+        ...(pendingAgentDecision ? { pendingAgentDecision } : {}),
     };
 }
 //# sourceMappingURL=run-agent.js.map

package/dist/gateway/router.js

@@ -2894,6 +2894,35 @@ export class Gateway {
                     }
                     clearTimeout(chatTimer);
                     clearTimeout(hardWallTimer);
+                    // ── Pre-emptive blocked-action decision (Commit 3 / 1.18.211) ──
+                    // The precondition guard inside runAgent denied a tool call
+                    // before it fired (e.g. `netlify deploy` without a linked site).
+                    // Stash the decision on the session so the next owner message
+                    // is parsed as a decision reply, mirror the question into the
+                    // transcript, and respond with the question text. No partial
+                    // state was left behind because the tool never ran.
+                    const preCallDecision = runAgentResult.pendingAgentDecision;
+                    if (preCallDecision && !isBuilderSession) {
+                        const state = this.getSession(sessionKey);
+                        state.pendingAgentDecision = preCallDecision;
+                        const decisionResponse = preCallDecision.question;
+                        try {
+                            this.assistant.injectContext(effectiveSessionKey, originalText, decisionResponse, {
+                                pending: false,
+                                model: 'chat',
+                                countExchange: true,
+                            });
+                        }
+                        catch (err) {
+                            logger.debug({ err }, 'chat: pre-call decision transcript mirror failed (non-fatal)');
+                        }
+                        logger.info({
+                            sessionKey: effectiveSessionKey,
+                            classifierId: preCallDecision.context.classifierId,
+                            provider: preCallDecision.context.provider,
+                        }, 'chat: precondition-guard fired pre-call; routed to PendingAgentDecision');
+                        return decisionResponse;
+                    }
                     // Mirror transcript so memory + recall continue working — but
                     // skip for builder sessions since their turns are spec-drafting,
                     // not real conversation worth recalling later.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.210",
+  "version": "1.18.211",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",