@agentprojectcontext/apx 1.66.0 → 1.68.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.66.0",
+  "version": "1.68.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"
@@ -15,7 +15,8 @@
   "bin": {
     "apx": "./src/interfaces/cli/index.js",
     "apx-daemon": "./src/host/daemon/index.js",
-    "apx-mcp": "./src/interfaces/mcp-server/index.js"
+    "apx-mcp": "./src/interfaces/mcp-server/index.js",
+    "apx-acp": "./src/interfaces/acp/index.js"
   },
   "files": [
     "src/",

package/skills/apx/SKILL.md

@@ -57,6 +57,9 @@ apx memory <agent-slug> --append "<fact>"
 # Observe activity
 apx messages tail
 apx messages chat --channel <name> -n 20
+
+# Protocol bridges (spawned by clients, not run interactively)
+apx acp                         # Agent Client Protocol server on stdio (Zed, JetBrains, ...)
 ```
 
 ---

package/src/core/agent/index.js

@@ -22,6 +22,8 @@ export {
   probeAllProviders,
   fallbackModels,
   isFallbackEnabled,
+  routingConfig,
+  selectModelByRules,
   DEFAULT_FALLBACK_ORDER,
   DEFAULT_FALLBACK_MODELS,
 } from "./model-router.js";

package/src/core/agent/judge.js

@@ -0,0 +1,174 @@
+// Goal-completion judge loop (OpenHands Critic / iterative-refinement
+// pattern). After a completion-contract run declares done, an LLM judge scores
+// how likely the ORIGINAL goal is actually met (0..1). Below the threshold,
+// the agent gets a follow-up verification note and continues — bounded by
+// max_iterations so a harsh judge can't spin forever. Opt-in and scoped to
+// completion-contract surfaces (coding turns), where "done" is checkable.
+import { callEngine } from "../engines/index.js";
+
+export function judgeConfig(globalConfig) {
+  const raw = globalConfig?.super_agent?.judge || {};
+  const threshold = Number(raw.success_threshold);
+  const iters = parseInt(raw.max_iterations, 10);
+  return {
+    enabled: raw.enabled === true,
+    success_threshold:
+      Number.isFinite(threshold) && threshold > 0 && threshold <= 1 ? threshold : 0.6,
+    max_iterations: Number.isFinite(iters) && iters > 0 ? Math.min(iters, 5) : 2,
+    model: typeof raw.model === "string" ? raw.model : "",
+  };
+}
+
+const JUDGE_SYSTEM =
+  "You are a strict completion judge for an autonomous agent. You read the " +
+  "user's original request and the agent's final report plus action trace, and " +
+  "estimate the probability that the request is FULLY satisfied. Judge only " +
+  "what the evidence supports: claims without a matching action in the trace " +
+  "count against completion. Answer with STRICT JSON only.";
+
+function judgePrompt({ goal, finalText, traceSummary }) {
+  return [
+    "ORIGINAL REQUEST:",
+    goal,
+    "",
+    "AGENT'S FINAL REPORT:",
+    finalText || "(empty)",
+    "",
+    "ACTION TRACE (tool, outcome preview):",
+    traceSummary || "(no tools ran)",
+    "",
+    'Reply with STRICT JSON, nothing else: {"score": <0..1 probability the request is fully satisfied>, "reasoning": "<one dense sentence>", "missing": ["<unmet requirement>", ...]}',
+  ].join("\n");
+}
+
+export function summarizeTraceForJudge(trace, { maxItems = 20 } = {}) {
+  if (!Array.isArray(trace) || trace.length === 0) return "";
+  return trace
+    .slice(-maxItems)
+    .map((t) => {
+      const r = t?.result;
+      const preview =
+        typeof r === "string"
+          ? r
+          : r && typeof r === "object"
+            ? (r.error ? `error: ${r.error}` : JSON.stringify(r))
+            : String(r);
+      return `- ${t.tool}: ${String(preview).slice(0, 160)}`;
+    })
+    .join("\n");
+}
+
+export function parseVerdict(text) {
+  const raw = String(text || "");
+  const start = raw.indexOf("{");
+  if (start === -1) return null;
+  // Walk to the matching close brace so trailing prose can't break the parse.
+  let depth = 0;
+  let end = -1;
+  for (let i = start; i < raw.length; i++) {
+    if (raw[i] === "{") depth++;
+    else if (raw[i] === "}") {
+      depth--;
+      if (depth === 0) { end = i; break; }
+    }
+  }
+  if (end === -1) return null;
+  try {
+    const obj = JSON.parse(raw.slice(start, end + 1));
+    const score = Number(obj.score);
+    if (!Number.isFinite(score)) return null;
+    return {
+      score: Math.max(0, Math.min(1, score)),
+      reasoning: typeof obj.reasoning === "string" ? obj.reasoning : "",
+      missing: Array.isArray(obj.missing) ? obj.missing.filter((m) => typeof m === "string") : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Score a finished run against its goal. Returns {score, reasoning, missing}
+ * or null when the judge is unusable (engine down, unparseable reply) — the
+ * caller treats null as "accept the result", never as a failure.
+ */
+export async function judgeCompletion({ goal, result, globalConfig, callEngineFn = callEngine }) {
+  const cfg = judgeConfig(globalConfig);
+  const modelId = cfg.model || globalConfig?.super_agent?.model || "";
+  if (!modelId) return null;
+  try {
+    const r = await callEngineFn({
+      modelId,
+      system: JUDGE_SYSTEM,
+      messages: [
+        {
+          role: "user",
+          content: judgePrompt({
+            goal,
+            finalText: result?.text || "",
+            traceSummary: summarizeTraceForJudge(result?.trace),
+          }),
+        },
+      ],
+      config: globalConfig,
+      maxTokens: 500,
+      temperature: 0,
+    });
+    return parseVerdict(r?.text);
+  } catch {
+    return null;
+  }
+}
+
+// In-band note, adapted from OpenHands CriticBase.get_followup_prompt: shapes
+// behavior, never words. The model must re-verify against the ORIGINAL
+// request, not against the judge's phrasing.
+export function buildJudgeFollowup(verdict, iteration) {
+  const pct = Math.round((verdict?.score ?? 0) * 100);
+  const missing = (verdict?.missing || []).slice(0, 5);
+  return [
+    `[Internal verification note — this is NOT from the user. An automated completion check scored this turn ${pct}% likely complete (verification round ${iteration}).`,
+    verdict?.reasoning ? `Judge's reasoning: ${verdict.reasoning}` : "",
+    missing.length ? `Possibly unmet: ${missing.map((m) => `"${m}"`).join(", ")}.` : "",
+    "Re-read the user's ORIGINAL request, verify each requirement against what you actually did (check the tool results, don't assume), complete whatever is genuinely missing, then finish. If everything IS already complete, finish with a summary stating precisely why each requirement is met.]",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+/**
+ * Refinement driver, dependency-injected so surfaces and tests supply their
+ * own judge/runner. `judgeFn(result)` → verdict|null; `runFollowup(followupPrompt,
+ * result)` → next run result. Merges usage and traces across rounds and
+ * attaches the verdict trail as `result.judge`.
+ */
+export async function applyJudgeLoop({ initialResult, cfg, judgeFn, runFollowup, onEvent = null }) {
+  let result = initialResult;
+  const trail = [];
+  for (let i = 1; i <= cfg.max_iterations; i++) {
+    const verdict = await judgeFn(result);
+    if (verdict) {
+      trail.push({ iteration: i, ...verdict });
+      if (typeof onEvent === "function") {
+        await onEvent({
+          type: "judge_verdict",
+          iteration: i,
+          score: verdict.score,
+          reasoning: verdict.reasoning,
+          passed: verdict.score >= cfg.success_threshold,
+        });
+      }
+    }
+    if (!verdict || verdict.score >= cfg.success_threshold) break;
+    const next = await runFollowup(buildJudgeFollowup(verdict, i), result);
+    result = {
+      ...next,
+      usage: {
+        input_tokens: (result.usage?.input_tokens || 0) + (next.usage?.input_tokens || 0),
+        output_tokens: (result.usage?.output_tokens || 0) + (next.usage?.output_tokens || 0),
+      },
+      trace: [...(result.trace || []), ...(next.trace || [])],
+    };
+  }
+  return trail.length ? { ...result, judge: trail } : result;
+}

package/src/core/agent/model-router.js

@@ -133,10 +133,91 @@ export function isFallbackEnabled(globalConfig) {
   return fb.enabled !== false;
 }
 
+// ---------------------------------------------------------------------------
+// Content-based routing (OpenHands RouterLLM pattern). Static engine routing
+// picks ONE model per deployment; these rules inspect the actual turn —
+// images, prompt/context size, channel, keywords — and prefer a different
+// model for it. The preferred model still goes through the same health check
+// and falls back down the regular chain when unavailable, so a routing rule
+// can never strand a turn on a dead provider.
+// ---------------------------------------------------------------------------
+
+export function routingConfig(globalConfig) {
+  const raw = globalConfig?.super_agent?.routing || {};
+  return {
+    enabled: raw.enabled === true,
+    rules: Array.isArray(raw.rules) ? raw.rules : [],
+  };
+}
+
+// Multimodal content shows up as parts arrays on message content (engine
+// adapters and the Telegram photo flow use type "image"/"image_url").
+function contentHasImage(content) {
+  if (!Array.isArray(content)) return false;
+  return content.some(
+    (p) => p && (p.type === "image" || p.type === "image_url" || p.type === "input_image")
+  );
+}
+
+/**
+ * Evaluate `super_agent.routing.rules` in order against the turn's features;
+ * first full match wins. Each rule: `{ model: "<provider>:<model>", when: {
+ * has_image?, min_prompt_chars?, max_prompt_chars?, min_context_chars?,
+ * channels?: [], keywords?: [] } }`. All conditions in `when` must hold
+ * (AND); an empty `when` matches every turn. Returns `{model, ruleIndex}` or
+ * null (no rules, disabled, or nothing matched).
+ */
+export function selectModelByRules(
+  { prompt = "", previousMessages = [], channel = "", channelMeta = {} } = {},
+  globalConfig
+) {
+  const cfg = routingConfig(globalConfig);
+  if (!cfg.enabled || cfg.rules.length === 0) return null;
+
+  const promptText = typeof prompt === "string" ? prompt : "";
+  const messages = Array.isArray(previousMessages) ? previousMessages : [];
+  const hasImage =
+    channelMeta?.has_image === true ||
+    contentHasImage(prompt) ||
+    messages.some((m) => contentHasImage(m?.content));
+  let contextChars = 0;
+  for (const m of messages) {
+    const c = m?.content;
+    if (typeof c === "string") contextChars += c.length;
+    else if (c != null) {
+      try { contextChars += JSON.stringify(c).length; } catch { /* unserializable — skip */ }
+    }
+  }
+
+  for (let i = 0; i < cfg.rules.length; i++) {
+    const rule = cfg.rules[i] || {};
+    const model = rule.model;
+    if (typeof model !== "string" || !model.includes(":")) continue;
+    const when = rule.when || {};
+
+    if (when.has_image === true && !hasImage) continue;
+    if (when.has_image === false && hasImage) continue;
+    if (Number.isFinite(when.min_prompt_chars) && promptText.length < when.min_prompt_chars) continue;
+    if (Number.isFinite(when.max_prompt_chars) && promptText.length > when.max_prompt_chars) continue;
+    if (Number.isFinite(when.min_context_chars) && contextChars < when.min_context_chars) continue;
+    if (Array.isArray(when.channels) && when.channels.length > 0 && !when.channels.includes(channel)) continue;
+    if (Array.isArray(when.keywords) && when.keywords.length > 0) {
+      const low = promptText.toLowerCase();
+      const hit = when.keywords.some(
+        (k) => typeof k === "string" && k.trim().length >= 2 && low.includes(k.toLowerCase())
+      );
+      if (!hit) continue;
+    }
+
+    return { model, ruleIndex: i };
+  }
+  return null;
+}
+
 /**
  * Pick first healthy model following configured provider order.
  */
-export async function resolveActiveModel(globalConfig, { overrideModel = null, timeoutMs } = {}) {
+export async function resolveActiveModel(globalConfig, { overrideModel = null, preferredModel = null, timeoutMs } = {}) {
   if (overrideModel) {
     const { provider } = parseModelId(overrideModel);
     return {
@@ -152,12 +233,20 @@ export async function resolveActiveModel(globalConfig, { overrideModel = null, t
   const fb = sa.model_fallback || {};
   const healthMs = timeoutMs ?? fb.health_timeout_ms ?? 800;
   const tried = [];
+  // Content routing (selectModelByRules) prefers a model for THIS turn. It
+  // leads the chain but is not forced: unhealthy → regular chain takes over.
+  const preferred =
+    typeof preferredModel === "string" && preferredModel.includes(":") ? preferredModel : null;
 
   if (isFallbackEnabled(globalConfig)) {
-    // Build the full chain: primary first, then the fallback list, deduped.
-    // Each entry is a fully-qualified "<provider>:<model>" string.
+    // Build the full chain: preferred (content-routed) first, then primary,
+    // then the fallback list, deduped. Each entry is a fully-qualified
+    // "<provider>:<model>" string.
     const chain = [];
-    if (typeof sa.model === "string" && sa.model.includes(":")) chain.push(sa.model);
+    if (preferred) chain.push(preferred);
+    if (typeof sa.model === "string" && sa.model.includes(":") && !chain.includes(sa.model)) {
+      chain.push(sa.model);
+    }
     for (const m of fallbackModels(globalConfig)) {
       if (!chain.includes(m)) chain.push(m);
     }
@@ -185,11 +274,24 @@ export async function resolveActiveModel(globalConfig, { overrideModel = null, t
         return {
           modelId,
           provider,
-          fromFallback: !isPrimary,
+          fromFallback: !isPrimary && modelId !== preferred,
+          ...(modelId === preferred ? { routedBy: "content_rules" } : {}),
           tried,
         };
       }
     }
+  } else if (preferred) {
+    // No fallback router: honor the routing rule directly (same trust level
+    // as the primary model, which is also unchecked in this branch).
+    const { provider } = parseModelId(preferred);
+    return {
+      modelId: preferred,
+      provider,
+      fromFallback: false,
+      forced: true,
+      routedBy: "content_rules",
+      tried: [{ provider, modelId: preferred, healthy: true, reason: "content_rules" }],
+    };
   }
 
   if (sa.model) {

package/src/core/agent/prompts/modes/code-build.md

@@ -1 +1 @@
-MODE: build. Make the changes directly using your file and shell tools (read_file, write_file, edit_file, run_shell, …). Do not ask for confirmation and do not stop after one step — keep calling tools until the entire task is done, then briefly summarize what you changed and why. Prefer surgical edits over rewrites. When the user asks for a reusable script, snippet, or 'artifact' (something they want to keep and run later), put it under `artifacts/<name>` inside the project — it then shows up in the Artifacts tab. Don't drop reusable scripts at the project root. If a parameter you need is missing (API key, app id, target URL, …), call `ask_questions` ONCE with all your questions and stop — control returns to the user. Do not call ask_questions again in the same turn; you'll just get the same blank state back. Each question can be a string (free-text answer) OR an object {question, options:[{label, description}], multiSelect} for choices. Prefer 2–4 mutually-exclusive options when a question has a natural shortlist (yes/no, which-of-these, …); leave options empty for open-ended answers (API keys, names, free-form ideas). If the previous assistant turn already asked these same questions and the current user message is the compiled answers, DO NOT call ask_questions again — process the answers and proceed with the task.
+MODE: build. Make the changes directly using your file and shell tools (read_file, write_file, edit_file, run_shell, …). Do not ask for confirmation and do not stop after one step — keep calling tools until the entire task is done, then briefly summarize what you changed and why. Prefer surgical edits over rewrites. When the user asks for a reusable script, snippet, or 'artifact' (something they want to keep and run later), put it under `artifacts/<name>` inside the project — it then shows up in the Artifacts tab. Don't drop reusable scripts at the project root. When an artifact is something visual the user should SEE (an HTML page, a single-file React component, a dashboard), preview it with `run_shell`: `apx artifact preview <name>` serves it on an ephemeral local URL with live-reload, and `apx artifact share <name>` also returns a temporary public URL to share — give the user the printed link. If a parameter you need is missing (API key, app id, target URL, …), call `ask_questions` ONCE with all your questions and stop — control returns to the user. Do not call ask_questions again in the same turn; you'll just get the same blank state back. Each question can be a string (free-text answer) OR an object {question, options:[{label, description}], multiSelect} for choices. Prefer 2–4 mutually-exclusive options when a question has a natural shortlist (yes/no, which-of-these, …); leave options empty for open-ended answers (API keys, names, free-form ideas). If the previous assistant turn already asked these same questions and the current user message is the compiled answers, DO NOT call ask_questions again — process the answers and proceed with the task.

package/src/core/agent/run-agent.js

@@ -8,6 +8,19 @@ import { MAX_TOOL_ITERS, ACK_ONLY_TOOLS, MAX_CONSECUTIVE_ACKS, TURN_ENDING_TOOLS
 import { pseudoToolSystem, shouldRetryWithPseudoTools } from "./tools/pseudo-tools.js";
 import { filterToolSchemas } from "./tools-overlap.js";
 import { isRetryableEngineError, shortRetryReason } from "./retry.js";
+import {
+  securityRiskConfig,
+  withSecurityRiskField,
+  popSecurityRisk,
+  shouldConfirmRisk,
+} from "./security.js";
+import { buildConfirmDescription } from "../confirmation/index.js";
+import { PERMISSION_MODES } from "../constants/permissions.js";
+import {
+  stuckDetectionConfig,
+  createStuckDetector,
+  stuckNudgeSignal,
+} from "./stuck-detector.js";
 
 async function emitProgress(onEvent, event) {
   if (typeof onEvent !== "function") return;
@@ -120,6 +133,9 @@ export async function runAgent({
   prompt,
   previousMessages = [],
   overrideModel = null,
+  // Content-routed model for this turn (selectModelByRules). Unlike
+  // overrideModel it is health-checked and falls back down the chain.
+  preferredModel = null,
   toolSchemas,
   makeToolHandlers,
   toolHandlerCtx,
@@ -144,7 +160,7 @@ export async function runAgent({
   // never end the turn by narrating the next step. Language-agnostic by design.
   completionContract = false,
 }) {
-  const routing = await resolveActiveModel(globalConfig, { overrideModel });
+  const routing = await resolveActiveModel(globalConfig, { overrideModel, preferredModel });
   // Mutable: lazy-retry can rotate to a different model mid-loop on 429/413/5xx.
   let activeModel = routing.modelId;
 
@@ -161,12 +177,13 @@ export async function runAgent({
     return true;
   });
 
-  if (routing.fromFallback) {
+  if (routing.fromFallback || routing.routedBy) {
     await emitProgress(onEvent, {
       type: "model_routed",
       model: activeModel,
       provider: routing.provider,
-      from_fallback: true,
+      from_fallback: routing.fromFallback === true,
+      ...(routing.routedBy ? { routed_by: routing.routedBy } : {}),
       tried: routing.tried,
     });
   }
@@ -194,6 +211,30 @@ export async function runAgent({
     effectiveSchemas = [...effectiveSchemas, FINISH_TOOL_SCHEMA];
   }
 
+  // Inline security-risk analysis: every eligible tool schema gains a required
+  // `security_risk` enum the model fills as part of the call itself (no second
+  // LLM pass). The loop extracts the grade below and the ConfirmRisky policy
+  // decides whether the call pauses for human approval.
+  const riskCfg = securityRiskConfig(globalConfig);
+  const permissionMode = globalConfig?.super_agent?.permission_mode || "";
+  const riskGateOn = riskCfg.enabled;
+  // In `total` (full trust) the risk gate acts ONLY as a safety floor: HIGH-risk
+  // actions still confirm, everything below runs free. That's the value the
+  // permission mode alone can't give — it gates by tool identity, this gates by
+  // the model's own judgment of THIS action's severity. In automatico/permiso
+  // the configured confirm_at applies.
+  const effectiveRiskCfg =
+    permissionMode === PERMISSION_MODES.TOTAL
+      ? { ...riskCfg, confirm_at: "HIGH", confirm_unknown: false }
+      : riskCfg;
+  if (riskGateOn) {
+    effectiveSchemas = withSecurityRiskField(effectiveSchemas);
+    // Handshake with createPermissionGuard: outside `total`, the analyzer owns
+    // dangerous-call gating so the static dangerous-flag branch stands down.
+    // (In `total` the guard returns early anyway, so this is a no-op there.)
+    if (toolHandlerCtx) toolHandlerCtx.securityRiskActive = true;
+  }
+
   const rawHandlers = makeToolHandlers(toolHandlerCtx);
   const handlers = suppressed.size > 0
     ? new Proxy(rawHandlers, {
@@ -224,7 +265,11 @@ export async function runAgent({
       if (n && !seen.has(n)) { additions.push(sc); seen.add(n); }
     }
     toolSession.pending = [];
-    if (additions.length > 0) effectiveSchemas = effectiveSchemas.concat(additions);
+    if (additions.length > 0) {
+      effectiveSchemas = effectiveSchemas.concat(
+        riskGateOn ? withSecurityRiskField(additions) : additions
+      );
+    }
   };
 
   const conversation = [...previousMessages, { role: "user", content: prompt }];
@@ -281,6 +326,23 @@ export async function runAgent({
     }
   };
 
+  // Stuck detection: catches the loops the side-effect dedupe can't — a
+  // read-only call repeated with identical results, or the same call erroring
+  // over and over. First trigger = in-band nudge; second = force the tool-free
+  // wrap-up so the turn closes with a model-authored status instead of burning
+  // the rest of the budget.
+  const stuckCfg = stuckDetectionConfig(globalConfig);
+  const stuckDetector = createStuckDetector(stuckCfg);
+  let stuckNudged = false;
+  let forceWrapUp = false;
+  const safeSig = (v) => {
+    try {
+      return JSON.stringify(v) ?? "";
+    } catch {
+      return "<unserializable>";
+    }
+  };
+
   // Engine call wrapped with lazy retry: on 413/429/5xx/rate-limit/etc, try
   // the next model in `retryChain` instead of bubbling. Stops when the chain
   // is exhausted; non-retryable errors (auth, bad payload) throw immediately.
@@ -316,8 +378,12 @@ export async function runAgent({
     // STRUCTURE (no tools this step) + an in-band directive turn (WRAPUP_SIGNAL);
     // the wording is entirely the model's. Coding surfaces keep their finish-tool flow, so
     // this never applies under completionContract.
+    // forceWrapUp (stuck abort) overrides the contract: a stuck model under
+    // toolChoice:"required" would only repeat itself, so we withhold tools and
+    // make it close the turn in prose either way.
     const isFinalWrapUp =
-      !useContract && effectiveSchemas.length > 0 && iter === maxIters - 1;
+      effectiveSchemas.length > 0 &&
+      ((!useContract && iter === maxIters - 1) || forceWrapUp);
     await emitProgress(onEvent, {
       type: isFinalWrapUp ? "final_wrapup" : "model_start",
       iteration: iter + 1,
@@ -426,6 +492,9 @@ export async function runAgent({
         try { args = JSON.parse(args); } catch { args = {}; }
       }
       args = args || {};
+      // Pop the model's own risk grade BEFORE the handler sees the args — the
+      // field belongs to the loop, not to any tool's contract.
+      const securityRisk = riskGateOn ? popSecurityRisk(args) : null;
 
       // Completion contract: `finish` declares the task done. Capture its
       // summary as the final text and stop processing the rest of this turn.
@@ -438,7 +507,13 @@ export async function runAgent({
       const traceId = `${iter + 1}:${trace.length + 1}`;
       await emitProgress(onEvent, {
         type: "tool_start",
-        trace: { id: traceId, tool: name, args, pending: true },
+        trace: {
+          id: traceId,
+          tool: name,
+          args,
+          pending: true,
+          ...(securityRisk ? { security_risk: securityRisk } : {}),
+        },
         iteration: iter + 1,
       });
       // Dedupe identical side-effecting calls within this turn.
@@ -456,19 +531,65 @@ export async function runAgent({
           iteration: iter + 1,
         });
       } else {
-        try {
-          const handler = handlers[name];
-          toolResult = handler ? await handler(args) : { error: `unknown tool: ${name}` };
-        } catch (e) {
-          toolResult = { error: e.message };
+        // ConfirmRisky gate: pause on the model's own grade before executing.
+        // A decline becomes a normal error observation — the model sees the
+        // rejection and can re-plan, mirroring OpenHands' rejection flow.
+        let riskDenied = null;
+        if (riskGateOn && shouldConfirmRisk(securityRisk, effectiveRiskCfg)) {
+          const description = buildConfirmDescription(name, args);
+          const requestConfirmation = toolHandlerCtx?.requestConfirmation;
+          if (typeof requestConfirmation !== "function") {
+            riskDenied = `Action requires user confirmation (security risk ${securityRisk}): ${description}`;
+          } else {
+            await emitProgress(onEvent, {
+              type: "security_confirmation",
+              trace: { id: traceId, tool: name, risk: securityRisk },
+              iteration: iter + 1,
+            });
+            let approved = false;
+            try {
+              approved = await requestConfirmation(name, args, `[risk: ${securityRisk}] ${description}`);
+            } catch {
+              approved = false;
+            }
+            if (approved && toolHandlerCtx) toolHandlerCtx.securityGateCleared = true;
+            if (!approved) {
+              riskDenied = `User did not confirm (security risk ${securityRisk}): ${description}`;
+            }
+          }
+        }
+        if (riskDenied) {
+          toolResult = { error: riskDenied };
+        } else {
+          try {
+            const handler = handlers[name];
+            toolResult = handler ? await handler(args) : { error: `unknown tool: ${name}` };
+          } catch (e) {
+            toolResult = { error: e.message };
+          } finally {
+            if (toolHandlerCtx) toolHandlerCtx.securityGateCleared = false;
+          }
         }
         if (sig) sideEffectExecuted.set(sig, summarizeForTrace(toolResult));
       }
 
-      const traceItem = { id: traceId, tool: name, args, result: summarizeForTrace(toolResult) };
+      const traceItem = {
+        id: traceId,
+        tool: name,
+        args,
+        result: summarizeForTrace(toolResult),
+        ...(securityRisk ? { security_risk: securityRisk } : {}),
+      };
       trace.push(traceItem);
       await emitProgress(onEvent, { type: "tool_result", trace: traceItem, iteration: iter + 1 });
 
+      stuckDetector.record({
+        tool: name,
+        argsSig: safeSig(args),
+        resultSig: safeSig(traceItem.result),
+        isError: !!(toolResult && typeof toolResult === "object" && toolResult.error),
+      });
+
       // Groq (and strict OpenAI) require tool_call_id to be present and
       // match the id of the tool_call in the previous assistant message.
       // Real engines populate it; the pseudo-tool parser also assigns one
@@ -529,6 +650,22 @@ export async function runAgent({
     } else {
       ackOnlyStreak = 0;
     }
+
+    // Stuck escalation: first detection nudges (in-band note, detector reset so
+    // only FRESH repetitions count again); a second detection means the nudge
+    // didn't land — stop spending budget and force the wrap-up close.
+    const stuck = stuckDetector.check();
+    if (stuck) {
+      if (!stuckNudged) {
+        stuckNudged = true;
+        stuckDetector.reset();
+        await emitProgress(onEvent, { type: "stuck_detected", ...stuck, iteration: iter + 1 });
+        conversation.push({ role: "user", content: stuckNudgeSignal(stuck) });
+      } else {
+        await emitProgress(onEvent, { type: "stuck_abort", ...stuck, iteration: iter + 1 });
+        forceWrapUp = true;
+      }
+    }
   }
 
   return {