@agentprojectcontext/apx 1.31.2 → 1.32.2

package/src/core/agent/constants.js

@@ -1,3 +1,8 @@
 export const MAX_TOOL_ITERS = 6;
 export const ACK_ONLY_TOOLS = new Set(["send_telegram"]);
 export const MAX_CONSECUTIVE_ACKS = 2;
+// Tools whose semantics REQUIRE handing control back to the user. After the
+// tool runs we break the loop — even under completionContract — because the
+// task literally cannot advance without a human reply. Without this, models
+// under forced toolChoice spam the same question across iterations.
+export const TURN_ENDING_TOOLS = new Set(["ask_questions"]);

package/src/core/agent/index.js

@@ -20,9 +20,7 @@ export {
   resolveActiveModel,
   checkProviderHealth,
   probeAllProviders,
-  fallbackOrder,
   fallbackModels,
-  modelForProvider,
   isFallbackEnabled,
   DEFAULT_FALLBACK_ORDER,
   DEFAULT_FALLBACK_MODELS,

package/src/core/{agent-memory.js → agent/memory.js}

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { projectStorageRoot } from "./config.js";
-import { getOrCreateApxId } from "./scaffold.js";
+import { projectStorageRoot } from "../config/index.js";
+import { getOrCreateApxId } from "../apc/scaffold.js";
 
 const EMPTY_MEMORY = (slug) =>
   `# Memory — ${slug}\n\n` +

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

@@ -128,42 +128,6 @@ export function fallbackModels(globalConfig) {
     .filter((m) => typeof m === "string" && m.includes(":"));
 }
 
-/**
- * @deprecated use fallbackModels(). Kept for tests / external callers that
- * still ask "what provider to try after Ollama?". Derives the answer from the
- * resolved model chain.
- */
-export function fallbackOrder(globalConfig) {
-  const models = fallbackModels(globalConfig);
-  const providers = [];
-  for (const m of models) {
-    try {
-      const p = parseModelId(m).provider;
-      if (!providers.includes(p)) providers.push(p);
-    } catch { /* skip malformed entries */ }
-  }
-  return providers.length ? providers : [...DEFAULT_FALLBACK_ORDER];
-}
-
-/**
- * @deprecated use fallbackModels(). Looks up a single provider's model in
- * the resolved chain. Returns "" if the provider isn't in the fallback list.
- */
-export function modelForProvider(globalConfig, provider) {
-  const p = String(provider).toLowerCase();
-  const sa = globalConfig?.super_agent || {};
-  const models = fallbackModels(globalConfig);
-  const match = models.find((m) => {
-    try { return parseModelId(m).provider === p; } catch { return false; }
-  });
-  if (match) return match;
-  // Ollama gets a special fallback to the primary model (legacy behavior).
-  if (p === "ollama" && typeof sa.model === "string" && /^ollama:/i.test(sa.model)) {
-    return sa.model;
-  }
-  return DEFAULT_FALLBACK_MODELS[p] || "";
-}
-
 export function isFallbackEnabled(globalConfig) {
   const fb = globalConfig?.super_agent?.model_fallback || {};
   return fb.enabled !== false;
@@ -243,15 +207,29 @@ export async function resolveActiveModel(globalConfig, { overrideModel = null, t
 }
 
 export async function probeAllProviders(globalConfig, timeoutMs) {
-  const order = fallbackOrder(globalConfig);
+  const models = fallbackModels(globalConfig);
+  // Build a deduped list of {provider, model} in chain order. Fall back to
+  // DEFAULT_FALLBACK_ORDER + DEFAULT_FALLBACK_MODELS when nothing is configured.
+  const entries = [];
+  const seen = new Set();
+  for (const m of models) {
+    let provider;
+    try { provider = parseModelId(m).provider; } catch { continue; }
+    if (seen.has(provider)) continue;
+    seen.add(provider);
+    entries.push({ provider, model: m });
+  }
+  if (entries.length === 0) {
+    for (const provider of DEFAULT_FALLBACK_ORDER) {
+      const m = DEFAULT_FALLBACK_MODELS[provider];
+      entries.push({ provider, model: m || "(not set)" });
+    }
+  }
+
   const out = [];
-  for (const provider of order) {
+  for (const { provider, model } of entries) {
     const health = await checkProviderHealth(provider, globalConfig, timeoutMs);
-    out.push({
-      provider,
-      model: modelForProvider(globalConfig, provider) || "(not set)",
-      ...health,
-    });
+    out.push({ provider, model, ...health });
   }
   return out;
 }

package/src/core/agent/prompt-builder.js

@@ -7,13 +7,20 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { readIdentity } from "../identity.js";
+import { readIdentity } from "../identity/index.js";
 import { readSelfMemoryForPrompt } from "./self-memory.js";
+import { buildSkillsHintBlock } from "./skills/catalog.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PROMPTS_DIR = path.join(__dirname, "prompts");
 const BASE_PROMPT_PATH = path.join(PROMPTS_DIR, "super-agent-base.md");
 
+// Action discipline + chit-chat rules — same file used by project agents
+// (buildAgentSystem in agent-system.js), loaded once here for the super-agent.
+const ACTION_DISCIPLINE = fs
+  .readFileSync(path.join(PROMPTS_DIR, "action-discipline.md"), "utf8")
+  .trimEnd();
+
 const promptCache = new Map();
 
 /** @deprecated use super-agent-base.md */
@@ -24,15 +31,15 @@ const LEGACY_PROMPT_PATH = path.join(PROMPTS_DIR, "super-agent-default.md");
 // turn is channel "deck" + voice mode, not its own channel.
 const CHANNEL_PROMPT_FILES = {
   telegram: "channels/telegram.md",
-  terminal: "channels/terminal.md",
   cli: "channels/cli.md",
   routine: "channels/routine.md",
   api: "channels/api.md",
   web: "channels/web.md",                 // web big chat (long-form, full tools)
   web_sidebar: "channels/web_sidebar.md", // web quick chat (short, lightweight)
+  web_code: "channels/web_code.md",       // web Code module (rich coding session)
   deck: "channels/deck.md",               // cockpit dashboard
   desktop: "channels/desktop.md",         // PC floating module (was "overlay")
-  code: "channels/code.md",               // web Code module (rich coding session)
+  code: "channels/code.md",               // `apx code` — terminal coding session
 };
 
 // Voice mode: spoken-reply rules layered on any surface when the turn will be
@@ -135,7 +142,7 @@ export function buildIdentityBlock(identity, userLang = "en") {
 }
 
 // "Who you're talking to" block. Agent-agnostic: built once from the resolved
-// sender (see core/telegram-identity.js) and injected into BOTH the super-agent
+// sender (see core/identity/telegram.js) and injected into BOTH the super-agent
 // prompt and any routed project-agent prompt, so identification doesn't depend
 // on which agent answers. Returns "" when there's no sender info.
 export function buildRelationshipBlock(sender) {
@@ -173,8 +180,8 @@ export function buildRelationshipBlock(sender) {
   return lines.join("\n");
 }
 
-// Roby's own notebook (~/.apx/memory.md), bounded for the prompt. Returns ""
-// when empty so the block is dropped entirely.
+// The super-agent's own notebook (~/.apx/memory.md), bounded for the prompt.
+// Returns "" when empty so the block is dropped entirely.
 export function buildSelfMemoryBlock() {
   const slice = readSelfMemoryForPrompt();
   if (!slice) return "";
@@ -193,59 +200,6 @@ export function isSuperAgentEnabled(cfg) {
   return sa.enabled !== false;
 }
 
-function buildPermissionBlock(sa) {
-  const permissionMode = sa.permission_mode || "automatico";
-  const allowedTools = Array.isArray(sa.allowed_tools) ? sa.allowed_tools : [];
-  return [
-    "# Permission mode",
-    `mode: ${permissionMode}`,
-    `allowed_tools: ${allowedTools.join(", ") || "(none)"}`,
-    "When a tool schema has confirmed, set confirmed=true only after explicit user confirmation for that exact action.",
-  ].join("\n");
-}
-
-// Skill descriptions are authored for Claude Code's skill matcher, so many end
-// with verbose "Trigger on: …" / "Activate when …" lists and multi-sentence
-// usage notes. Inside Roby's prompt those tails are pure noise (he matches
-// semantically, not by trigger string). Keep the first sentence only, drop the
-// trigger/activation tail, and cap length — this is the single biggest
-// signal-per-token win in the prompt (~1k tokens recovered per turn).
-function condenseSkillDescription(desc) {
-  if (!desc) return "(no description)";
-  const full = String(desc).replace(/\s+/g, " ").trim();
-  const MARKER =
-    /\s*(?:Trigger(?:s)? on|Triggers|TRIGGER|Activate (?:on|when|only)|Use this skill (?:whenever|when)|Use (?:it )?when|Triggers include|SKIP|Also (?:use|triggers))\b/i;
-  // Prefer the gist before any trigger/activation marker; but if a skill leads
-  // straight into "Activate ONLY when…" (no gist first), that head is empty —
-  // fall back to the first sentence of the full text so we keep real info.
-  let d = full.split(MARKER)[0].trim();
-  if (d.length < 15) d = full;
-  // First sentence only, then cap length.
-  const firstStop = d.search(/\.(\s|$)/);
-  if (firstStop > 0) d = d.slice(0, firstStop + 1);
-  d = d.trim();
-  if (d.length > 160) d = d.slice(0, 157).trimEnd() + "…";
-  return d || "(no description)";
-}
-
-function buildSkillsCatalog(listSkills) {
-  let list = [];
-  try {
-    list = listSkills();
-  } catch {
-    /* empty */
-  }
-  if (!list.length) return "";
-  return [
-    "# Available skills (load on demand)",
-    "Catalog (slug + one-line gist). Bodies are NOT loaded. When the user needs",
-    "knowledge or syntax matching one (match semantically, any language), call",
-    "load_skill({slug}).",
-    "",
-    ...list.map((s) => `- **${s.slug}**: ${condenseSkillDescription(s.description)}`),
-  ].join("\n");
-}
-
 export function buildSuperAgentSystem({
   globalConfig,
   projects,
@@ -263,12 +217,12 @@ export function buildSuperAgentSystem({
   // at the end of the system prompt (where format directives belong),
   // not mixed in with situational context.
   systemSuffix = "",
-  // Pre-rendered output of the Memory Broker (Pieza 4): a [MEMORIA RELEVANTE]
+  // Pre-rendered output of the Memory Broker (Pieza 4): a [RELEVANT MEMORY]
   // block built from the RAG retriever + recent memory.md entries. When
   // provided it REPLACES the always-on self-memory slice (it already includes
   // the latest notebook entries). "" falls back to the plain notebook slice.
   memoryBlock = "",
-  // Pre-rendered "# Hilos activos en otros canales" block (recency-based
+  // Pre-rendered "# Active threads on other channels" block (recency-based
   // cross-channel awareness; see core/memory/active-threads.js). "" → omitted.
   activeThreadsBlock = "",
   // Compact "# Tools adicionales (activación on-demand)" block: instructions +
@@ -304,14 +258,14 @@ export function buildSuperAgentSystem({
     memoryBlock || buildSelfMemoryBlock(),
     activeThreadsBlock,
     relationshipBlock,
-    buildPermissionBlock(sa),
     extraContext,
     "# Registered projects (just the index — call tools for details)",
     projectIndex || "(no projects registered)",
     buildProjectAgentsBlock(channelMeta?.projectPath),
-    buildSkillsCatalog(listSkills),
+    buildSkillsHintBlock(listSkills),
     lazyToolsBlock,
     voiceModeBlock,
+    ACTION_DISCIPLINE,
     systemSuffix,
   ]
     .filter(Boolean)

package/src/core/agent/prompts/action-discipline.md

@@ -0,0 +1,17 @@
+## Action Discipline (mandatory)
+- NEVER acknowledge an action without executing it in the same turn. If you are going to do something, call the tool FIRST, then report the result.
+- NEVER use empty acknowledgments like "Ok", "Got it", "Sure", "Understood", "On it", "Give me a moment", "I'll do that now" as standalone responses when a tool call is expected. These are invalid responses.
+- Action first, report after. Produce the tool call in the same response as your acknowledgment.
+- If you cannot execute the action (missing permission, unclear params, tool not available), explain WHY — do not promise and disappear.
+- If the user asks you to do multiple things, do them all in the same turn using sequential tool calls if needed.
+
+## One reply per turn — no repeated greetings (mandatory)
+- A single turn can produce SEVERAL text segments: a short narration you write BEFORE calling a tool, and the final answer that comes AFTER the tool runs. On some surfaces each segment is shown separately.
+- Greet AT MOST ONCE per turn. If you already said "hola"/"hi" in an early segment, do NOT greet again in the final answer — start it with the actual content.
+- NEVER repeat the same sentence, greeting, or summary across segments of the same turn. Each segment is shown in full.
+- On simple requests, SKIP the intro entirely: go straight to the work, then give the result once. Only add a short intro when the work will clearly take more than a single quick tool call, and keep it to a few words ("un momento…", "reviso eso…").
+
+## Chit-chat & greetings (only path out of a forced tool turn)
+- If the user is just greeting, chatting, or thanking you with NO actionable request ("hola", "hi", "buenas", "gracias", "👍", "ok"), you must STILL satisfy the tool-choice contract: call `finish` with a brief friendly reply in the user's language. Do NOT call any other tool just because tools are available — `finish` is the correct tool for chit-chat.
+- A greeting that piggybacks a real request ("hola, listame las rutinas") is NOT chit-chat — handle the request normally with the right tool.
+- When in doubt between chit-chat and a vague request, ask ONE short clarifying question via `finish` — never invent a topic or run an unrelated tool to "be useful".

package/src/core/agent/prompts/channels/code.md

@@ -1,20 +1,16 @@
 # Channel context
-Channel: **code** (the Code module in the web admin panel) — a rich, OpenCode-style coding session scoped to a single project. The user sees every tool call, argument, file edit, and result rendered in the UI, plus a live "changes" diff and a token/context panel.
+Channel: **code** (`apx code`, the interactive APX coding session in the terminal) — the same OpenCode-style coding surface as the web Code module, just rendered in the terminal. You can read, search, edit files and run shell commands.
 
-Working project: **{{projectName}}** (id {{projectId}})
-Path: `{{projectPath}}`
-All file and shell tools resolve relative to that project path — operate inside it unless told otherwise.
+- CWD: {{cwd}}
+- References to "this directory", "this project", "here", "current folder" mean the CWD above — use it as the path argument; do not ask for a path
 
-{{modeGuidance}}
-
-Working style — KEEP GOING UNTIL THE TASK IS DONE:
+Working style — KEEP GOING UNTIL THE TASK IS DONE (build mode):
 - You are an autonomous coding agent. Once the user gives a task, complete the WHOLE thing in this turn: chain as many tool calls as needed (read → edit → run → verify), do not stop after one or two steps.
-- NEVER stop to ask "do you want me to…?" / "¿confirmás…?" / "should I continue?". You already have permission on this surface — just do it. Only ask a question if the task is truly ambiguous and you genuinely cannot proceed.
+- NEVER stop to ask "do you want me to…?" / "should I continue?" / "is that OK?". You already have permission on this surface — just do it. Only ask if the task is truly ambiguous and you genuinely cannot proceed.
 - NEVER announce an action and then end your turn ("now I'll edit the file." → stop). If you say you will do something, immediately call the tool and actually do it in the same turn.
-- After each tool result, decide the next concrete step and take it. Keep iterating until the user's request is fully satisfied; only then write your final summary.
+- After each tool result, decide the next concrete step and take it. Keep iterating until the request is fully satisfied; only then write your final summary.
 - If something fails, read the error, fix it, and retry — don't hand the problem back to the user.
 
 Formatting:
-- Markdown with code fences is expected. Narrate what you're doing naturally; don't re-paste full tool output the user can already see in the UI.
-- Lead with the result. Keep prose tight — this is a working surface, not a chat.
-- When you edit files, prefer small, surgical `edit_file` changes over rewriting whole files, and explain the intent of each change briefly.
+- Markdown OK; keep readable; use code diffs when editing.
+- Lead with the result; keep prose tight. Don't re-paste full tool output the user can already see.

package/src/core/agent/prompts/channels/desktop.md

@@ -16,8 +16,9 @@ Formatting:
   done and a tiny confirmation, not an explanation.
 - No markdown tables, no code fences, no bulleted lists unless the user
   explicitly asks. Plain prose only — these get read aloud verbatim.
-- No URLs / file paths spelled out — refer to them by name ("abrí Voces en
-  la admin web" rather than "http://localhost:7430/m/voice").
+- No URLs / file paths spelled out — refer to them by name (e.g. "open
+  Voices in the web admin" rather than "http://localhost:7430/m/voice").
+  Use the user's language when phrasing it.
 - If a Voice mode block is present below, its rules win over anything here.
 - Bias hard toward DOING the action and reporting the result in one breath,
   rather than asking back. Confirm-after, not confirm-before, for
@@ -27,8 +28,9 @@ Don't repeat yourself (this matters — your messages are shown AND spoken):
 - Greet AT MOST once per conversation. If you already said hi, never greet
   again — jump straight to the answer.
 - When you call a tool, any line BEFORE it must be a 2–4 word filler only
-  ("Dame un segundo…", "Ya lo busco…"). NEVER state the answer, the list, or
-  the result before the tool has run — you don't have it yet.
+  (e.g. "one moment…", "checking that…", in the user's language). NEVER
+  state the answer, the list, or the result before the tool has run — you
+  don't have it yet.
 - After the tool returns, give the result ONCE. Do not re-announce it, do not
   re-greet, do not restate the filler. One clean reply.
 - Never say the same thing twice across a single turn.

package/src/core/agent/prompts/channels/routine.md

@@ -1,9 +1,18 @@
 # Channel context
 Channel: **routine** (autonomous scheduled run — not an interactive chat).
 
-Routine: `{{routineName}}`
+Routine name: `{{routineName}}`
+Routine ID: `{{routineId}}`
+Schedule: `{{routineSchedule}}`
+Last run: {{routineLastRun}}
+Routine memory: `{{routineMemoryPath}}`
 Project path: {{projectPath}}
 
+## Routine memory (durable notes for this routine)
+{{routineMemory}}
+
 Formatting:
 - Execute the task fully; no conversational filler
 - This is not Telegram — do not optimize for chat brevity unless the routine prompt says so
+- "Last run" is when this routine fired previously — use it to know what's already been done; never repeat the same work blindly
+- "Routine memory" above is everything this specific routine has decided to remember across runs. Treat as known facts. The file exists at the path shown — read it in full with `read_file` if the slice looks truncated.

package/src/core/agent/prompts/channels/telegram.md

@@ -7,3 +7,8 @@ Formatting:
 - Previous turns are conversational context only; re-call tools for facts
 
 What the user sees here: ONLY your final text reply. They do NOT see your tool calls, args, or intermediate results — those never reach Telegram. So if a request needs real work (running something, searching, editing, a multi-step task), the channel sends a short "on it" heads-up for you; you still must report what you actually did in plain words at the end. Never assume they saw what you ran.
+
+Segments policy: when you write any prose BEFORE calling a tool (an intro like "voy a revisar…") it lands as its OWN Telegram message — separate from the final answer that comes AFTER the tool runs. So:
+- Greet at most ONCE per turn. If you already said "Hola" in the intro segment, do NOT greet again in the final answer. Start the final answer with the actual content.
+- Prefer to skip the intro entirely on simple requests — go straight to the work, then answer. Only add an intro when the work will take noticeably longer than a single tool call.
+- Never repeat the same sentence across segments — each message is shown in full to the user.

package/src/core/agent/prompts/channels/web_code.md

@@ -0,0 +1,20 @@
+# Channel context
+Channel: **web_code** (the Code module in the web admin panel at `/m/code`) — a rich, OpenCode-style coding session scoped to a single project. The user sees every tool call, argument, file edit, and result rendered in the UI, plus a live "changes" diff and a token/context panel.
+
+Working project: **{{projectName}}** (id {{projectId}})
+Path: `{{projectPath}}`
+All file and shell tools resolve relative to that project path — operate inside it unless told otherwise.
+
+{{modeGuidance}}
+
+Working style — KEEP GOING UNTIL THE TASK IS DONE:
+- You are an autonomous coding agent. Once the user gives a task, complete the WHOLE thing in this turn: chain as many tool calls as needed (read → edit → run → verify), do not stop after one or two steps.
+- NEVER stop to ask "do you want me to…?" / "should I continue?" / "is that OK?". You already have permission on this surface — just do it. Only ask a question if the task is truly ambiguous and you genuinely cannot proceed.
+- NEVER announce an action and then end your turn ("now I'll edit the file." → stop). If you say you will do something, immediately call the tool and actually do it in the same turn.
+- After each tool result, decide the next concrete step and take it. Keep iterating until the user's request is fully satisfied; only then write your final summary.
+- If something fails, read the error, fix it, and retry — don't hand the problem back to the user.
+
+Formatting:
+- Markdown with code fences is expected. Narrate what you're doing naturally; don't re-paste full tool output the user can already see in the UI.
+- Lead with the result. Keep prose tight — this is a working surface, not a chat.
+- When you edit files, prefer small, surgical `edit_file` changes over rewriting whole files, and explain the intent of each change briefly.

package/src/core/agent/prompts/modes/voice.md

@@ -1,4 +1,4 @@
 # Voice mode (your reply will be SPOKEN by a TTS engine)
 - Two short sentences max. No markdown, no bullet lists, no code fences, no URLs — it gets read aloud.
-- Lead with the outcome ("Listo, anoté la tarea"), then at most one detail.
-- Spell things out for the ear: say "punto" not ".", avoid long ids/paths — summarize them ("el proyecto apx").
+- Lead with the outcome (e.g. "Done, the task is noted"), then at most one detail. Phrase it in the user's language.
+- Spell things out for the ear: say "dot" instead of ".", avoid long ids/paths — summarize them (e.g. "the apx project").

package/src/core/agent/prompts/super-agent-base.md

@@ -19,8 +19,8 @@ You also ship **apx-\* skills** with the exact syntax for multi-step APX operati
 
 # Memory & history
 You have durable memory across all channels — never deny it. Two sources:
-- **Sessions & chat logs**: when asked what you worked on, about a "previous/last session", or "what we talked about", call `search_sessions` (defaults to your own apx sessions — pass `engine` only when the user names claude/codex, `all:true` only when they want every engine; pass `id` to open a transcript) and/or `search_messages`. Answer didactically in prose ("la última vez hicimos X e Y"), not as a raw list of titles. If your sessions are thin, say so and offer to look across engines — never conclude you "have no history".
-- **Your notebook (self-memory)**: `~/.apx/memory.md`, a bounded slice injected above (as "# Your notebook" or folded into "# Memoria relevante"). At the end of any turn where something durable happened (a decision, a completed task, an agreed fact), save the gist with `remember` so your other channels know it too. Keep notes to one self-contained sentence. Use `create_task` for one-off TODOs and project-agent memory for project-scoped facts. When a "# Memoria relevante" block is present, treat its bullets as known facts; if a fresh chat opens and something there is still open, bring it up naturally ("ayer estuvimos con X, ¿seguimos?") — weave in only what's relevant, don't dump the block.
+- **Sessions & chat logs**: when asked what you worked on, about a "previous/last session", or "what we talked about", call `search_sessions` (defaults to your own apx sessions — pass `engine` only when the user names claude/codex, `all:true` only when they want every engine; pass `id` to open a transcript) and/or `search_messages`. Answer didactically in prose (in the user's language — e.g. "last time we worked on X and Y"), not as a raw list of titles. If your sessions are thin, say so and offer to look across engines — never conclude you "have no history".
+- **Your notebook (self-memory)**: `~/.apx/memory.md`, a bounded slice injected above (as "# Your notebook" or folded into "# Relevant memory"). At the end of any turn where something durable happened (a decision, a completed task, an agreed fact), save the gist with `remember` so your other channels know it too. Keep notes to one self-contained sentence. Use `create_task` for one-off TODOs and project-agent memory for project-scoped facts. When a "# Relevant memory" block is present, treat its bullets as known facts; if a fresh chat opens and something there is still open, bring it up naturally in the user's language (e.g. "yesterday we were on X — shall we continue?") — weave in only what's relevant, don't dump the block.
 
 # How you operate
 - APC projects live anywhere on disk; the default workspace is APX home, not a user repo. Registered projects appear below as a tiny index — call tools for details.

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

@@ -2,16 +2,10 @@ import { callEngine } from "../engines/index.js";
 import {
   extractPseudoToolCalls,
   cleanTextOfPseudoToolCalls,
-} from "./tool-call-parser.js";
+} from "./tools/tool-call-parser.js";
 import { resolveActiveModel, fallbackModels } from "./model-router.js";
-import { MAX_TOOL_ITERS, ACK_ONLY_TOOLS, MAX_CONSECUTIVE_ACKS } from "./constants.js";
-import {
-  isShortConfirmation,
-  lastAssistantAskedForConfirmation,
-  isGhostResponse,
-  looksLikeActionRequest,
-} from "./ghost-guard.js";
-import { pseudoToolSystem, shouldRetryWithPseudoTools } from "./pseudo-tools.js";
+import { MAX_TOOL_ITERS, ACK_ONLY_TOOLS, MAX_CONSECUTIVE_ACKS, TURN_ENDING_TOOLS } from "./constants.js";
+import { pseudoToolSystem, shouldRetryWithPseudoTools } from "./tools/pseudo-tools.js";
 import { filterToolSchemas } from "./tools-overlap.js";
 import { isRetryableEngineError, shortRetryReason } from "./retry.js";
 
@@ -39,6 +33,19 @@ function fallbackFinalText(trace, error) {
   return lines.join("\n");
 }
 
+// A leading greeting clause: "¡Hola Manu!", "Hola,", "Hi there!", "Buenas tardes…".
+// Intentionally narrow — only the opening salutation up to its first terminator —
+// so we never eat real content.
+const LEADING_GREETING_RE =
+  /^\s*[¡!]*\s*(hola+|holis?|buenas|buen[oa]s?\s+(d[ií]as|tardes|noches)|hey|hi|hello)\b[^.!?¡\n]*[.!?¡]*[\s,]*/i;
+
+/** If `text` opens with a greeting, return it with that greeting removed; else null. */
+function stripLeadingGreeting(text) {
+  const m = String(text).match(LEADING_GREETING_RE);
+  if (!m) return null;
+  return String(text).slice(m[0].length).replace(/^\s+/, "");
+}
+
 function previewTraceResult(result) {
   if (result === null || result === undefined) return "ok";
   if (typeof result === "string") return result.slice(0, 180);
@@ -160,11 +167,7 @@ export async function runAgent({
     effectiveSchemas = [...effectiveSchemas, FINISH_TOOL_SCHEMA];
   }
 
-  const rawHandlers = makeToolHandlers({
-    ...toolHandlerCtx,
-    implicitConfirmation:
-      isShortConfirmation(prompt) && lastAssistantAskedForConfirmation(previousMessages),
-  });
+  const rawHandlers = makeToolHandlers(toolHandlerCtx);
   const handlers = suppressed.size > 0
     ? new Proxy(rawHandlers, {
         get(target, name) {
@@ -201,6 +204,22 @@ export async function runAgent({
   const trace = [];
   let totalUsage = { input_tokens: 0, output_tokens: 0 };
   let lastText = "";
+
+  // Collapse repeated greetings within a single turn. A turn can produce several
+  // text segments (pre-tool narration + final answer) and weaker models greet in
+  // each one, so the user sees "¡Hola Manu!" twice. Keep the first greeting,
+  // strip any later one. Belt-and-suspenders over the action-discipline prompt
+  // rule (which strong models follow but gemini-flash et al. often ignore).
+  let greetedThisTurn = false;
+  const dedupeGreeting = (text) => {
+    if (!text) return text;
+    if (greetedThisTurn) {
+      const stripped = stripLeadingGreeting(text);
+      return stripped == null ? text : stripped;
+    }
+    if (LEADING_GREETING_RE.test(text)) greetedThisTurn = true;
+    return text;
+  };
   let usePseudoTools = false;
   let ackOnlyStreak = 0;
   // Side-effect dedupe. Weaker models (Gemini especially) sometimes
@@ -258,16 +277,9 @@ export async function runAgent({
     // Merge any tools activated via discover_tools on the previous iteration.
     drainPendingTools();
     await emitProgress(onEvent, { type: "model_start", iteration: iter + 1, model: activeModel });
-    // Force a tool call on iter 0 ONLY when the user message looks like a real
-    // action request ("listame…", "mandá…", "buscá…"). For chit-chat ("hola",
-    // "qué tal") forcing a tool makes weaker models (llama-3.3 via Groq,
-    // qwen3-32b) emit a malformed tool_calls payload — Groq then rejects the
-    // whole turn with 400 "Failed to call a function". Better: let the model
-    // choose between text and tool when the prompt is conversational.
     const forceTool =
       effectiveSchemas.length > 0 &&
       (useContract ||
-        (iter === 0 && looksLikeActionRequest(prompt)) ||
         (ackOnlyStreak > 0 && ackOnlyStreak <= MAX_CONSECUTIVE_ACKS));
     let result;
     try {
@@ -320,22 +332,11 @@ export async function runAgent({
     }
 
     if (!toolCalls || toolCalls.length === 0) {
-      if (iter === 0 && isGhostResponse(lastText) && looksLikeActionRequest(prompt)) {
-        await emitProgress(onEvent, { type: "ghost_response_detected", text: lastText });
-        conversation.push({ role: "assistant", content: lastText });
-        conversation.push({
-          role: "user",
-          content:
-            "Remember: you must execute the action, not just confirm it. " +
-            "Call the tool now — action first, report after.",
-        });
-        continue;
-      }
       lastText = cleanTextOfPseudoToolCalls(lastText) || lastText;
       break;
     }
 
-    const visibleText = cleanTextOfPseudoToolCalls(lastText).trim();
+    const visibleText = dedupeGreeting(cleanTextOfPseudoToolCalls(lastText).trim());
     if (visibleText) {
       await emitProgress(onEvent, { type: "assistant_text", text: visibleText, iteration: iter + 1 });
     }
@@ -347,6 +348,7 @@ export async function runAgent({
     });
 
     let finishSummary = null;
+    let turnEndingQuestions = null;
     for (const tc of toolCalls) {
       const fn = tc.function || tc;
       const name = fn.name;
@@ -409,18 +411,45 @@ export async function runAgent({
         tool_name: name,
         content: JSON.stringify(toolResult),
       });
+
+      // Capture turn-ending intents (e.g. ask_questions). The loop cannot
+      // legitimately advance without a user reply; under completionContract
+      // forcing another tool call just produces ask_questions spam.
+      if (TURN_ENDING_TOOLS.has(name) && !turnEndingQuestions) {
+        // Questions may be plain strings (legacy) or {question, options, ...}.
+        // For the assistant_text fallback we only need the prompt strings.
+        const qs = Array.isArray(args.questions)
+          ? args.questions
+              .map((q) => (typeof q === "string" ? q : q && typeof q.question === "string" ? q.question : null))
+              .filter(Boolean)
+          : [];
+        turnEndingQuestions = qs;
+      }
     }
 
     // Task declared complete via the contract — emit the summary as the final
     // assistant text and exit the loop.
     if (finishSummary !== null) {
       if (finishSummary) {
-        lastText = finishSummary;
-        await emitProgress(onEvent, { type: "assistant_text", text: finishSummary, iteration: iter + 1 });
+        lastText = dedupeGreeting(finishSummary) || "";
+        if (lastText) await emitProgress(onEvent, { type: "assistant_text", text: lastText, iteration: iter + 1 });
       }
       break;
     }
 
+    // ask_questions (or future turn-ending tools): the task is genuinely
+    // blocked on user input. Exit the loop — completionContract or not,
+    // asking again gets us nowhere. We deliberately do NOT emit a synthetic
+    // assistant_text and we leave lastText empty so persistence and one-shot
+    // API callers don't end up with a duplicate bullet list next to the
+    // rendering surfaces' own UI (web AskQuestionsCard, terminal renderer,
+    // telegram inline keyboard). The structured questions live on the tool
+    // trace — that's the canonical source.
+    if (turnEndingQuestions) {
+      if (!lastText) lastText = "";
+      break;
+    }
+
     const allAckOnly = toolCalls.every((tc) => {
       const n = (tc.function?.name) || tc.name;
       return ACK_ONLY_TOOLS.has(n);
@@ -434,7 +463,8 @@ export async function runAgent({
   }
 
   return {
-    text: lastText,
+    // Strip a final greeting if an earlier segment in this turn already greeted.
+    text: dedupeGreeting(lastText),
     usage: totalUsage,
     name: agentName,
     trace,

package/src/core/agent/runtime-bridge.js

@@ -0,0 +1,42 @@
+// Prompt-shaped hint injected into external runtimes when APX delegates work
+// to them (Claude Code, Codex, OpenCode, Aider, Cursor Agent, Gemini CLI,
+// Qwen Code). Tells the runtime two things only:
+//
+//   1. "You're being orchestrated by APX as the super-agent (or as agent X
+//      via APX delegation)" — equivalent to a one-shot a2a hand-off.
+//   2. The session id APX created on disk so the runtime can echo it back
+//      via `apx session close <id> --result "..."` if its shell allows it.
+//
+// We intentionally do NOT re-explain APC: every runtime that can read this
+// hint already has the apc-context skill (or equivalent rule) installed in
+// its own config, and that rule covers the project context. Repeating it
+// here just bloats the prompt. The bridge is APX-specific glue.
+//
+// (Was `buildApfHint` in host/daemon/apc-runtime-context.js. "APF" was the
+// old internal name; renamed for clarity. Lifecycle helpers
+// — createRuntimeSession / closeRuntimeSession — live in
+// core/stores/runtime-sessions.js.)
+
+const RUNTIME_BRIDGE_HINT = `
+# APX runtime delegation
+
+You are being run by APX. The APX super-agent (or the named agent below) handed this turn to you as a one-shot delegation — think of it as an a2a (agent-to-agent) call where you are the callee. APX is the parent process; the project's apc-context already explains the codebase.
+
+- Project: {{name}}
+- Delegating agent: {{agent}}
+- APX session id: {{session_id}}
+
+When you finish, if you can shell out, leave a short trace for APX:
+  apx session close {{session_id}} --result "<one-line summary>"
+`.trim();
+
+export function buildRuntimeBridgeHint({ projectName, projectPath, agentSlug, sessionId }) {
+  return RUNTIME_BRIDGE_HINT
+    .replace(/\{\{name\}\}/g, projectName)
+    .replace(/\{\{path\}\}/g, projectPath)
+    .replace(/\{\{agent\}\}/g, agentSlug)
+    .replace(/\{\{session_id\}\}/g, sessionId);
+}
+
+// Back-compat alias — callers can migrate at their own pace.
+export const buildApfHint = buildRuntimeBridgeHint;