la-machina-engine 0.17.0 → 0.19.0

package/dist/index.cjs

@@ -3986,6 +3986,29 @@ var RunContext = class {
     });
     this.episodes?.logTurn(this.turnCount, "user", text2);
   }
+  /**
+   * Plan 051 — seed a prior chat turn into the run's message stack
+   * before the current task. Writes a normal `user` / `assistant`
+   * transcript entry so resume + inspect + compaction see the same
+   * conversation the model saw, but intentionally:
+   *   - does NOT increment `turnCount` (a turn is a model response
+   *     this run produced, not historical context)
+   *   - does NOT log to `episodes` (avoid cross-run memory noise)
+   *
+   * Caller is responsible for validating role + content shape; this
+   * helper just persists what it's given.
+   */
+  async seedInitialMessage(role, text2) {
+    const content = [{ type: "text", text: text2 }];
+    this.messages.push({ role, content });
+    await this.writeEntry({
+      type: role,
+      uuid: this.nextUuid(),
+      parentUuid: this.lastUuid,
+      ts: this.now(),
+      message: { role, content }
+    });
+  }
   async addAssistantMessage(content) {
     this.messages.push({ role: "assistant", content });
     await this.writeEntry({
@@ -8041,196 +8064,6 @@ function extractDescription(content) {
   return headingText;
 }
 
-// src/prompts/sections/base.ts
-init_cjs_shims();
-function getBaseSection() {
-  return `# System
-
-You are an AI assistant running inside la-machina-engine. You complete tasks by using the tools available to you. Your output goes to a programmatic caller (not a human terminal), so focus on correctness and completeness.
-
-IMPORTANT: Assist with authorized security testing, defensive security, CTF challenges, and educational contexts. Refuse requests for destructive techniques, DoS attacks, mass targeting, supply chain compromise, or detection evasion for malicious purposes.
-IMPORTANT: You must NEVER generate or guess URLs for the user unless you are confident they are correct. You may use URLs provided in the task or discovered via tools.`;
-}
-
-// src/prompts/sections/doingTasks.ts
-init_cjs_shims();
-function getDoingTasksSection() {
-  return `# Doing tasks
-
-- The caller will request you to perform tasks \u2014 solving bugs, adding features, refactoring, analyzing data, research, and more.
-- You are highly capable and often allow callers to complete ambitious tasks that would otherwise be too complex or take too long. You should defer to the caller's judgement about whether a task is too large to attempt.
-- If you notice the request is based on a misconception, or spot a bug adjacent to what was asked about, say so. You're a collaborator, not just an executor \u2014 callers benefit from your judgment, not just your compliance.
-- In general, do not propose changes to code you haven't read. If asked about or to modify a file, read it first. Understand existing code before suggesting modifications.
-- Do not create files unless they're absolutely necessary for achieving your goal. Generally prefer editing an existing file to creating a new one, as this prevents file bloat and builds on existing work more effectively.
-- Avoid giving time estimates or predictions for how long tasks will take. Focus on what needs to be done, not how long it might take.
-- If an approach fails, diagnose why before switching tactics \u2014 read the error, check your assumptions, try a focused fix. Don't retry the identical action blindly, but don't abandon a viable approach after a single failure either. Escalate only when you're genuinely stuck after investigation, not as a first response to friction.
-- Be careful not to introduce security vulnerabilities such as command injection, XSS, SQL injection, and other OWASP top 10 vulnerabilities. If you notice that you wrote insecure code, immediately fix it. Prioritize writing safe, secure, and correct code.
-- Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability. Don't add docstrings, comments, or type annotations to code you didn't change. Only add comments where the logic isn't self-evident.
-- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use feature flags or backwards-compatibility shims when you can just change the code.
-- Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is what the task actually requires \u2014 no speculative abstractions, but no half-finished implementations either. Three similar lines of code is better than a premature abstraction.
-- Default to writing no comments. Only add one when the WHY is non-obvious: a hidden constraint, a subtle invariant, a workaround for a specific bug, behavior that would surprise a reader. If removing the comment wouldn't confuse a future reader, don't write it.
-- Don't explain WHAT the code does, since well-named identifiers already do that. Don't reference the current task, fix, or callers ("used by X", "added for the Y flow", "handles the case from issue #123"), since those belong in the commit message and rot as the codebase evolves.
-- Don't remove existing comments unless you're removing the code they describe or you know they're wrong. A comment that looks pointless to you may encode a constraint or a lesson from a past bug that isn't visible in the current diff.
-- Before reporting a task complete, verify it actually works: run the test, execute the script, check the output. Minimum complexity means no gold-plating, not skipping the finish line. If you can't verify (no test exists, can't run the code), say so explicitly rather than claiming success.
-- Report outcomes faithfully: if tests fail, say so with the relevant output; if you did not run a verification step, say that rather than implying it succeeded. Never claim "all tests pass" when output shows failures, never suppress or simplify failing checks to manufacture a green result, and never characterize incomplete or broken work as done. Equally, when a check did pass or a task is complete, state it plainly \u2014 do not hedge confirmed results with unnecessary disclaimers, downgrade finished work to "partial," or re-verify things you already checked. The goal is an accurate report, not a defensive one.`;
-}
-
-// src/prompts/sections/actions.ts
-init_cjs_shims();
-function getActionsSection() {
-  return `# Executing actions with care
-
-Carefully consider the reversibility and blast radius of actions. Generally you can freely take local, reversible actions like editing files or running tests. But for actions that are hard to reverse, affect shared systems beyond your local environment, or could otherwise be risky or destructive, check with the caller before proceeding. The cost of pausing to confirm is low, while the cost of an unwanted action (lost work, unintended messages sent, deleted branches) can be very high. For actions like these, consider the context, the action, and caller instructions, and by default transparently communicate the action and ask for confirmation before proceeding. This default can be changed by caller instructions \u2014 if explicitly asked to operate more autonomously, then you may proceed without confirmation, but still attend to the risks and consequences when taking actions.
-
-Examples of the kind of risky actions that warrant confirmation:
-- Destructive operations: deleting files/branches, dropping database tables, killing processes, rm -rf, overwriting uncommitted changes
-- Hard-to-reverse operations: force-pushing (can overwrite upstream), git reset --hard, amending published commits, removing or downgrading packages/dependencies, modifying CI/CD pipelines
-- Actions visible to others or that affect shared state: pushing code, creating/closing/commenting on PRs or issues, sending messages (Slack, email, GitHub), posting to external services, modifying shared infrastructure or permissions
-- Uploading content to third-party web tools (diagram renderers, pastebins, gists) publishes it \u2014 consider whether it could be sensitive before sending, since it may be cached or indexed even if later deleted.
-
-When you encounter an obstacle, do not use destructive actions as a shortcut to simply make it go away. For instance, try to identify root causes and fix underlying issues rather than bypassing safety checks (e.g. --no-verify). If you discover unexpected state like unfamiliar files, branches, or configuration, investigate before deleting or overwriting, as it may represent in-progress work. For example, typically resolve merge conflicts rather than discarding changes; similarly, if a lock file exists, investigate what process holds it rather than deleting it. In short: only take risky actions carefully, and when in doubt, ask before acting. Follow both the spirit and letter of these instructions \u2014 measure twice, cut once.`;
-}
-
-// src/prompts/sections/usingTools.ts
-init_cjs_shims();
-function getUsingToolsSection(options) {
-  const has = (name) => options.registeredToolNames.has(name);
-  const items = [];
-  items.push(
-    `Do NOT use Bash to run commands when a relevant dedicated tool is provided. Using dedicated tools produces clearer, more reviewable output. This is CRITICAL:`
-  );
-  if (has("Read")) items.push(`  - To read files use Read instead of cat, head, tail, or sed`);
-  if (has("Edit")) items.push(`  - To edit files use Edit instead of sed or awk`);
-  if (has("Write"))
-    items.push(`  - To create files use Write instead of cat with heredoc or echo redirection`);
-  if (has("Glob")) items.push(`  - To search for files use Glob instead of find or ls`);
-  if (has("Grep")) items.push(`  - To search the content of files, use Grep instead of grep or rg`);
-  items.push(
-    `  - Reserve using Bash exclusively for system commands and terminal operations that require shell execution. If you are unsure and there is a relevant dedicated tool, default to using the dedicated tool and only fallback on Bash if it is absolutely necessary.`
-  );
-  items.push(
-    `You can call multiple tools in a single response. If you intend to call multiple tools and there are no dependencies between them, make all independent tool calls in parallel. Maximize use of parallel tool calls where possible to increase efficiency. However, if some tool calls depend on previous calls to inform dependent values, do NOT call these tools in parallel and instead call them sequentially.`
-  );
-  if (has("Agent")) {
-    items.push(
-      `Use the Agent tool with specialized agents when the task at hand matches the agent's description. Subagents are valuable for parallelizing independent queries or for protecting the main context window from excessive results, but should not be used excessively when not needed. Importantly, avoid duplicating work that subagents are already doing \u2014 if you delegate research to a subagent, do not also perform the same searches yourself.`
-    );
-    if (has("Glob") || has("Grep")) {
-      items.push(
-        `For simple, directed codebase searches (e.g. for a specific file/class/function) use Glob or Grep directly.`
-      );
-    }
-  }
-  if (has("SkillPage")) {
-    items.push(
-      `Skills are surfaced in the system prompt. Use the SkillPage tool to load specific pages from multi-page skills when you need detailed instructions.`
-    );
-  }
-  return `# Using your tools
-
-${items.map((i) => ` - ${i}`).join("\n")}`;
-}
-
-// src/prompts/sections/toneAndStyle.ts
-init_cjs_shims();
-function getToneAndStyleSection() {
-  return `# Tone and style
-
-- Only use emojis if the caller explicitly requests it. Avoid using emojis in all output unless asked.
-- Your responses should be concise and direct. Lead with the answer or action, not the reasoning.
-- When referencing specific functions or pieces of code include the pattern file_path:line_number.
-- When referencing GitHub issues or pull requests, use the owner/repo#123 format.
-- Do not use a colon before tool calls. Your tool calls may not be shown directly in the output, so text like "Let me read the file:" followed by a read tool call should just be "Let me read the file." with a period.
-
-# Output efficiency
-
-Go straight to the point. Try the simplest approach first without going in circles. Do not overdo it. Be extra concise.
-
-Keep your text output brief and direct. Lead with the answer or action, not the reasoning. Skip filler words, preamble, and unnecessary transitions. Do not restate the task \u2014 just do it. When explaining, include only what is necessary.
-
-Focus text output on:
-- Decisions that need input
-- High-level status updates at natural milestones
-- Errors or blockers that change the plan
-
-If you can say it in one sentence, don't use three. Prefer short, direct sentences over long explanations.`;
-}
-
-// src/prompts/sections/environment.ts
-init_cjs_shims();
-async function getEnvironmentSection(options) {
-  let platform = "unknown";
-  let osRelease = "";
-  try {
-    const os = await import("os");
-    platform = os.platform();
-    osRelease = os.release();
-  } catch {
-    platform = typeof navigator !== "undefined" ? "worker" : "unknown";
-  }
-  const shell = (typeof process !== "undefined" ? process.env?.SHELL : void 0) ?? (platform === "win32" ? "cmd.exe" : "/bin/sh");
-  const osVersion = `${platform}${osRelease ? " " + osRelease : ""}`;
-  const cwd = options.cwd ?? (typeof process !== "undefined" && process.cwd ? process.cwd() : "/");
-  const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
-  const lines = [
-    "# Environment",
-    "",
-    `- Platform: ${platform}`,
-    `- Shell: ${shell}`,
-    `- OS Version: ${osVersion}`,
-    `- Working directory: ${cwd}`,
-    `- Model: ${options.modelId} (provider: ${options.provider})`,
-    `- Current date: ${date}`
-  ];
-  if (canSpawnProcesses()) {
-    const git = await getGitContext(cwd);
-    if (git) {
-      lines.push("");
-      lines.push("## Git");
-      if (git.branch) lines.push(`- Branch: ${git.branch}`);
-      if (git.isRepo) lines.push(`- Is git repo: true`);
-      if (git.status) lines.push(`- Status:
-${git.status}`);
-      if (git.recentCommits) lines.push(`- Recent commits:
-${git.recentCommits}`);
-    }
-  }
-  return lines.join("\n");
-}
-async function getGitContext(cwd) {
-  try {
-    const { execSync } = await import("child_process");
-    const opts = {
-      cwd,
-      stdio: ["ignore", "pipe", "ignore"],
-      timeout: 5e3
-    };
-    try {
-      execSync("git rev-parse --is-inside-work-tree", opts);
-    } catch {
-      return null;
-    }
-    const branch = tryExec(execSync, "git branch --show-current", opts);
-    const status = tryExec(execSync, "git status --short", opts, 2e3);
-    const recentCommits = tryExec(execSync, "git log --oneline -5", opts, 2e3);
-    const ctx = { isRepo: true };
-    if (branch) ctx.branch = branch;
-    if (status) ctx.status = status;
-    if (recentCommits) ctx.recentCommits = recentCommits;
-    return ctx;
-  } catch {
-    return null;
-  }
-}
-function tryExec(execSync, cmd, opts, maxChars = 1e3) {
-  try {
-    const out = execSync(cmd, opts).toString("utf-8").trim();
-    return out.length > maxChars ? out.slice(0, maxChars) + "\n...(truncated)" : out;
-  } catch {
-    return "";
-  }
-}
-
 // src/prompts/sections/mcp.ts
 init_cjs_shims();
 function getMcpSection(options) {
@@ -8316,14 +8149,21 @@ function getApiServicesSection(opts) {
       lines.push("");
     }
   } else {
-    lines.push(
-      "Configured external HTTP APIs. Use `ApiCall` to invoke, but first call `DescribeService(service)` to fetch that service's endpoint catalog. Auth is injected automatically."
-    );
+    const hasDescribe = opts.hasDescribeService !== false;
+    if (hasDescribe) {
+      lines.push(
+        "Configured external HTTP APIs. Use `ApiCall` to invoke, but first call `DescribeService(service)` to fetch that service's endpoint catalog. Auth is injected automatically."
+      );
+    } else {
+      lines.push(
+        "Configured external HTTP APIs. Use `ApiCall` to invoke. Auth is injected automatically."
+      );
+    }
     lines.push("");
     appendStrictApiToolRules(
       lines,
       /* hasLazy */
-      true
+      hasDescribe
     );
     for (const svc of withEndpoints) {
       const count = svc.endpoints.length;
@@ -8378,33 +8218,20 @@ function resolveEffectiveMode(services, requested, threshold) {
 // src/prompts/systemPrompt.ts
 async function buildSystemPrompt(options) {
   const sections = [];
+  const visibleToolNames = options.visibleToolNames ?? /* @__PURE__ */ new Set();
   if (options.coordinatorMode) {
-  } else if (options.staticBase !== void 0 && options.staticBase.length > 0) {
+  } else if (options.staticBase !== void 0 && options.staticBase.trim().length > 0) {
     sections.push(options.staticBase);
-  } else {
-    sections.push(getBaseSection());
-    sections.push(getDoingTasksSection());
-    sections.push(getActionsSection());
-    if (options.registeredToolNames !== void 0 && options.registeredToolNames.size > 0) {
-      sections.push(getUsingToolsSection({ registeredToolNames: options.registeredToolNames }));
-    }
-    sections.push(getToneAndStyleSection());
-  }
-  sections.push(
-    await getEnvironmentSection({
-      modelId: options.modelId ?? "unknown",
-      provider: options.provider ?? "unknown",
-      cwd: options.cwd
-    })
-  );
+  }
   if (options.mcpTools !== void 0 && options.mcpTools.length > 0) {
     const mcpSection = getMcpSection({ mcpTools: options.mcpTools });
     if (mcpSection !== null) sections.push(mcpSection);
   }
-  if (options.apiServices !== void 0 && options.apiServices.length > 0) {
+  if (options.apiServices !== void 0 && options.apiServices.length > 0 && visibleToolNames.has("ApiCall")) {
     const apiSection = getApiServicesSection({
       services: options.apiServices,
       mode: options.apiCatalogMode ?? "lazy",
+      hasDescribeService: visibleToolNames.has("DescribeService"),
       ...options.apiLazyTokenThreshold !== void 0 ? { lazyTokenThreshold: options.apiLazyTokenThreshold } : {}
     });
     if (apiSection !== null) sections.push(apiSection);
@@ -8425,7 +8252,7 @@ ${rules}`);
 ${lessons}`);
   }
   const effectiveSkillList = options.skillList !== void 0 ? options.skillList : options.skillsAutoload ? await collectSkills(options.storage, options.skillsDir ?? "skills") : void 0;
-  if (effectiveSkillList !== void 0 && effectiveSkillList.length > 0) {
+  if (effectiveSkillList !== void 0 && effectiveSkillList.length > 0 && visibleToolNames.has("SkillPage")) {
     const lines = ["# Skills"];
     for (const skill of effectiveSkillList) {
       lines.push(`- ${skill.name}: ${skill.description}`);
@@ -10847,6 +10674,18 @@ function scrubRunOptions(opts) {
   if (opts.tools !== void 0) out.tools = [...opts.tools];
   if (opts.toolChoice !== void 0) out.toolChoice = opts.toolChoice;
   if (opts.tokenBudget !== void 0) out.tokenBudget = opts.tokenBudget;
+  if (opts.systemPromptBase !== void 0 && opts.systemPromptBase.length > 0) {
+    out.systemPromptBase = {
+      present: true,
+      chars: opts.systemPromptBase.length
+    };
+  }
+  if (opts.systemPromptAppend !== void 0 && opts.systemPromptAppend.length > 0) {
+    out.systemPromptAppend = {
+      present: true,
+      chars: opts.systemPromptAppend.length
+    };
+  }
   if (opts.knowledge !== void 0) {
     const k = {};
     if (opts.knowledge.folders !== void 0) k.folders = [...opts.knowledge.folders];
@@ -10879,6 +10718,24 @@ function scrubRunOptions(opts) {
   }
   if (opts.compaction !== void 0) out.compaction = opts.compaction;
   if (opts.context !== void 0) out.context = { ...opts.context };
+  if (opts.initialMessages !== void 0 && Array.isArray(opts.initialMessages)) {
+    const roles = [];
+    let totalChars = 0;
+    for (const m of opts.initialMessages) {
+      if (m === null || typeof m !== "object") continue;
+      const role = m.role;
+      const content = m.content;
+      if (role !== "user" && role !== "assistant") continue;
+      if (typeof content !== "string") continue;
+      roles.push(role);
+      totalChars += content.length;
+    }
+    out.initialMessages = {
+      count: roles.length,
+      roles,
+      totalChars
+    };
+  }
   return out;
 }
 function serializeOutputSchema(schema) {
@@ -10954,6 +10811,14 @@ function rebuildMessagesFromEntries(entries) {
   return messages;
 }
 
+// src/engine/types.ts
+init_cjs_shims();
+var INITIAL_MESSAGES_LIMITS = {
+  maxMessages: 100,
+  maxTotalChars: 32e3,
+  maxCharsPerMessage: 8e3
+};
+
 // src/engine/response.ts
 init_cjs_shims();
 function toResponse(result, extra) {
@@ -11344,60 +11209,36 @@ var Engine = class {
     const memory = createSmartMemory({ storage, config: this.config.memory });
     const agents = await this.resolveAgents(storage);
     const mcpTools = await this.mcpManager.getTools();
-    const toolNameSet = this.collectToolNames(mcpTools);
     const coordinatorBase = isCoordinatorMode(this.config) ? getCoordinatorBasePrompt() : void 0;
     const skillSource = this.resolveSkillSource(options.skills, storage);
     const skillList = skillSource !== void 0 ? await skillSource.list() : void 0;
     const apiConfig = this.resolveApiConfig(options.api);
     const offloadConfig = this.resolveOffloadConfig(options.compaction?.toolResultOffload);
     const knowledgeRuntime = this.resolveKnowledgeRuntime(options.knowledge, storage);
-    let systemPrompt = await buildSystemPrompt({
-      ...coordinatorBase !== void 0 ? { base: coordinatorBase } : {},
-      ...options.systemPromptBase !== void 0 ? { staticBase: options.systemPromptBase } : {},
-      ...options.systemPromptAppend !== void 0 && options.systemPromptAppend.length > 0 ? { platformAppend: options.systemPromptAppend } : {},
-      memory,
-      storage,
-      // When an override was supplied, skip the legacy disk-scan path.
-      skillsAutoload: options.skills !== void 0 ? false : this.config.skills.autoload,
-      ...this.config.skills.path !== void 0 ? { skillsDir: this.config.skills.path } : {},
-      ...skillList !== void 0 ? { skillList } : {},
-      modelId: this.config.model.modelId,
-      provider: this.config.model.provider,
-      registeredToolNames: toolNameSet,
-      mcpTools,
-      coordinatorMode: isCoordinatorMode(this.config),
-      // Plan 047 — render API services catalog (lazy by default).
-      ...apiConfig !== void 0 && apiConfig.services.length > 0 ? {
-        apiServices: apiConfig.services,
-        apiCatalogMode: apiConfig.mode ?? "lazy",
-        ...apiConfig.lazyTokenThreshold !== void 0 ? { apiLazyTokenThreshold: apiConfig.lazyTokenThreshold } : {}
-      } : {}
-    });
-    if (options.outputFormat === "json") {
-      systemPrompt += "\n\n" + buildSchemaPrompt(options.outputSchema);
-    }
     const gate = this.resolveGate();
     const inspect = this.buildInspectWriter(storage.workspace, logPath);
-    const registry = buildToolRegistry({
-      config: this.config,
+    const { systemPrompt: assembledPrompt, registry } = await this.buildPromptAndRegistry({
+      runOptions: options,
+      coordinatorBase,
       storage,
       client,
-      parentLogPath: logPath,
-      parentAgentId: null,
+      logPath,
       subagentRegistry,
-      system: systemPrompt,
       agents,
       mcpTools,
       memory,
       inspect,
-      ...this.config.hooks.propagateGateToSubagents === true && gate !== void 0 ? { subagentGate: gate } : {},
-      ...skillSource !== void 0 ? { skillSource } : {},
-      ...apiConfig !== void 0 ? { apiConfig } : {},
-      ...offloadConfig !== void 0 ? { toolResultOffload: offloadConfig } : {},
-      ...knowledgeRuntime !== void 0 ? { knowledge: knowledgeRuntime } : {},
-      ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
+      gate,
+      skillSource,
+      skillList,
+      apiConfig,
+      offloadConfig,
+      knowledgeRuntime
     });
-    applyRunToolFilter(registry, options);
+    let systemPrompt = assembledPrompt;
+    if (options.outputFormat === "json") {
+      systemPrompt += "\n\n" + buildSchemaPrompt(options.outputSchema);
+    }
     await inspect.writeStartSnapshot({
       systemPrompt,
       tools: this.snapshotTools(registry, mcpTools),
@@ -11456,6 +11297,23 @@ var Engine = class {
     const runTimeout = this.startRunTimeout();
     try {
       await writer.setStatus("running");
+      if (options.initialMessages !== void 0) {
+        const validation = validateInitialMessages(options.initialMessages);
+        if (!validation.ok) {
+          await writer.setStatus("failed");
+          return {
+            runId,
+            status: "failed",
+            data: null,
+            meta: { nodeId: options.nodeId, durationMs: Date.now() - startTime },
+            errors: [{ code: "ERR_INVALID_INITIAL_MESSAGES", message: validation.message }],
+            timestamp: Date.now()
+          };
+        }
+        for (const m of validation.messages) {
+          await ctx.seedInitialMessage(m.role, m.content);
+        }
+      }
       await dispatchHooks(this.config.hooks.preRun, {
         runId,
         nodeId: options.nodeId,
@@ -11549,68 +11407,55 @@ var Engine = class {
     const memory = createSmartMemory({ storage, config: this.config.memory });
     const agents = await this.resolveAgents(storage);
     const mcpTools = await this.mcpManager.getTools();
-    const toolNameSet = this.collectToolNames(mcpTools);
     const coordinatorBase = isCoordinatorMode(this.config) ? getCoordinatorBasePrompt() : void 0;
     const skillSource = this.resolveSkillSource(options.skills, storage);
     const skillList = skillSource !== void 0 ? await skillSource.list() : void 0;
     const apiConfig = this.resolveApiConfig(options.api);
     const offloadConfig = this.resolveOffloadConfig(options.compaction?.toolResultOffload);
     const knowledgeRuntime = this.resolveKnowledgeRuntime(options.knowledge, storage);
-    let systemPrompt = await buildSystemPrompt({
-      ...coordinatorBase !== void 0 ? { base: coordinatorBase } : {},
-      ...options.systemPromptBase !== void 0 ? { staticBase: options.systemPromptBase } : {},
-      ...options.systemPromptAppend !== void 0 && options.systemPromptAppend.length > 0 ? { platformAppend: options.systemPromptAppend } : {},
-      memory,
-      storage,
-      // When an override was supplied, skip the legacy disk-scan path.
-      skillsAutoload: options.skills !== void 0 ? false : this.config.skills.autoload,
-      ...this.config.skills.path !== void 0 ? { skillsDir: this.config.skills.path } : {},
-      ...skillList !== void 0 ? { skillList } : {},
-      modelId: this.config.model.modelId,
-      provider: this.config.model.provider,
-      registeredToolNames: toolNameSet,
-      mcpTools,
-      coordinatorMode: isCoordinatorMode(this.config),
-      // Plan 047 — render API services catalog (lazy by default).
-      ...apiConfig !== void 0 && apiConfig.services.length > 0 ? {
-        apiServices: apiConfig.services,
-        apiCatalogMode: apiConfig.mode ?? "lazy",
-        ...apiConfig.lazyTokenThreshold !== void 0 ? { apiLazyTokenThreshold: apiConfig.lazyTokenThreshold } : {}
-      } : {}
-    });
-    if (options.outputFormat === "json") {
-      systemPrompt += "\n\n" + buildSchemaPrompt(options.outputSchema);
-    }
     const gate = this.resolveGate();
     const inspect = this.buildInspectWriter(storage.workspace, logPath);
-    const registry = buildToolRegistry({
-      config: this.config,
+    const { systemPrompt: assembledPrompt, registry } = await this.buildPromptAndRegistry({
+      runOptions: options,
+      coordinatorBase,
       storage,
       client,
-      parentLogPath: logPath,
-      parentAgentId: null,
+      logPath,
       subagentRegistry,
-      system: systemPrompt,
       agents,
       mcpTools,
       memory,
       inspect,
-      ...this.config.hooks.propagateGateToSubagents === true && gate !== void 0 ? { subagentGate: gate } : {},
-      ...skillSource !== void 0 ? { skillSource } : {},
-      ...apiConfig !== void 0 ? { apiConfig } : {},
-      ...offloadConfig !== void 0 ? { toolResultOffload: offloadConfig } : {},
-      ...knowledgeRuntime !== void 0 ? { knowledge: knowledgeRuntime } : {},
-      ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
+      gate,
+      skillSource,
+      skillList,
+      apiConfig,
+      offloadConfig,
+      knowledgeRuntime
     });
+    let systemPrompt = assembledPrompt;
+    if (options.outputFormat === "json") {
+      systemPrompt += "\n\n" + buildSchemaPrompt(options.outputSchema);
+    }
     await inspect.writeStartSnapshot({
       systemPrompt,
       tools: this.snapshotTools(registry, mcpTools),
+      // Plan 052 review fix — surface the resume-time effective
+      // policy in `run-options.json` so post-hoc debuggers see
+      // exactly what gating drove the resume's prompt + tool
+      // surface. Otherwise resume's inspect bundle looked like a
+      // fresh run with no restrictions, masking the silent-widening
+      // failure mode documented on `ResumeOptions.tools`.
       runOptions: scrubRunOptions({
         runId: snapshot.runId,
         nodeId: snapshot.nodeId,
         task: "[resumed run \u2014 original task in transcript]",
         ...options.outputFormat !== void 0 ? { outputFormat: options.outputFormat } : {},
-        ...options.outputSchema !== void 0 ? { outputSchema: options.outputSchema } : {}
+        ...options.outputSchema !== void 0 ? { outputSchema: options.outputSchema } : {},
+        ...options.tools !== void 0 ? { tools: options.tools } : {},
+        ...options.toolChoice !== void 0 ? { toolChoice: options.toolChoice } : {},
+        ...options.systemPromptBase !== void 0 ? { systemPromptBase: options.systemPromptBase } : {},
+        ...options.systemPromptAppend !== void 0 ? { systemPromptAppend: options.systemPromptAppend } : {}
       }),
       modelConfig: scrubModelConfig(
         {
@@ -12259,72 +12104,97 @@ ${inputJson}
     });
   }
   /**
-   * Collect the names of all tools that will be registered — used to
-   * populate the system prompt's tool-specific instructions BEFORE
-   * building the registry itself (the prompt goes into the registry's
-   * Agent tool as the child system prompt, so the prompt must exist
-   * first).
+   * Plan 052 — two-pass system-prompt + tool-registry build.
+   *
+   * The prompt's API / skill / MCP sections describe only the tools
+   * the model will actually see, so we must know the post-filter
+   * tool set before assembling the prompt. The registry, however,
+   * is what produces that set, AND its `Agent` tool needs the
+   * final system prompt baked in for subagent dispatch.
+   *
+   * The chicken-and-egg is resolved by building twice:
+   *
+   *   Pass 1 — placeholder prompt → registry → applyRunToolFilter
+   *            → snapshot of visible tool names + visible MCP tools.
+   *   Pass 2 — final prompt assembled from those visible surfaces
+   *            → rebuild registry → applyRunToolFilter again.
+   *
+   * `applyRunToolFilter` is deterministic given options, so the
+   * second filter pass is identical to the first; the second
+   * registry is the authoritative one returned to the caller.
+   *
+   * Pass 1's prompt is intentionally minimal (placeholder string)
+   * because the only thing we use the first registry for is its
+   * post-filter tool list. The transient prompt never reaches the
+   * model.
    */
-  collectToolNames(mcpTools) {
-    const names = /* @__PURE__ */ new Set();
-    const builtins = [
-      // Bash is no longer registered by the engine (Plan 020) — but
-      // we keep it in the prompt-generation list so any caller that
-      // adds it via `tools.custom` (or its capabilityStub equivalent)
-      // gets a consistent prompt mention.
-      "Bash",
-      "Read",
-      "Write",
-      "Edit",
-      "Glob",
-      "Grep",
-      "WebFetch",
-      "WebSearch",
-      "Agent",
-      "SkillPage",
-      "Sleep",
-      "NotebookEdit",
-      "TaskCreate",
-      "TaskGet",
-      "TaskList",
-      "TaskUpdate",
-      "Memorize",
-      "Recall",
-      "ToolSearch"
-    ];
-    const enabled = new Set(this.config.tools.enabled);
-    const disabled = new Set(this.config.tools.disabled);
-    const wantAll = enabled.has("*");
-    for (const name of builtins) {
-      if (disabled.has(name)) continue;
-      if (wantAll || enabled.has(name)) names.add(name);
-    }
-    if ((this.config.api?.services.length ?? 0) > 0) {
-      if (!disabled.has("ApiCall") && (wantAll || enabled.has("ApiCall"))) {
-        names.add("ApiCall");
-      }
-    }
-    if (this.config.compaction.toolResultOffload?.enabled === true) {
-      if (!disabled.has("FetchData") && (wantAll || enabled.has("FetchData"))) {
-        names.add("FetchData");
-      }
-    }
-    if (this.config.knowledge?.enabled === true) {
-      if (!disabled.has("SearchKnowledge") && (wantAll || enabled.has("SearchKnowledge"))) {
-        names.add("SearchKnowledge");
-      }
-      if (!disabled.has("ReadKnowledge") && (wantAll || enabled.has("ReadKnowledge"))) {
-        names.add("ReadKnowledge");
-      }
-    }
-    for (const tool of this.config.tools.custom) {
-      names.add(tool.name);
-    }
-    for (const tool of mcpTools) {
-      if (disabled.has(tool.name)) continue;
-      if (wantAll || enabled.has(tool.name)) names.add(tool.name);
-    }
-    return names;
+  async buildPromptAndRegistry(args) {
+    const {
+      runOptions,
+      coordinatorBase,
+      storage,
+      client,
+      logPath,
+      subagentRegistry,
+      agents,
+      mcpTools,
+      memory,
+      inspect,
+      gate,
+      skillSource,
+      skillList,
+      apiConfig,
+      offloadConfig,
+      knowledgeRuntime
+    } = args;
+    const baseRegistryArgs = {
+      config: this.config,
+      storage,
+      client,
+      parentLogPath: logPath,
+      parentAgentId: null,
+      subagentRegistry,
+      agents,
+      mcpTools,
+      memory,
+      inspect,
+      ...this.config.hooks.propagateGateToSubagents === true && gate !== void 0 ? { subagentGate: gate } : {},
+      ...skillSource !== void 0 ? { skillSource } : {},
+      ...apiConfig !== void 0 ? { apiConfig } : {},
+      ...offloadConfig !== void 0 ? { toolResultOffload: offloadConfig } : {},
+      ...knowledgeRuntime !== void 0 ? { knowledge: knowledgeRuntime } : {},
+      ...this.internals.fetch !== void 0 ? { fetch: this.internals.fetch } : {}
+    };
+    const tempRegistry = buildToolRegistry({ ...baseRegistryArgs, system: "" });
+    applyRunToolFilter(tempRegistry, runOptions);
+    const visibleToolNames = new Set(tempRegistry.list().map((t) => t.name));
+    const visibleMcpTools = mcpTools.filter((t) => visibleToolNames.has(t.name));
+    const systemPrompt = await buildSystemPrompt({
+      ...coordinatorBase !== void 0 ? { base: coordinatorBase } : {},
+      ...runOptions.systemPromptBase !== void 0 ? { staticBase: runOptions.systemPromptBase } : {},
+      ...runOptions.systemPromptAppend !== void 0 && runOptions.systemPromptAppend.length > 0 ? { platformAppend: runOptions.systemPromptAppend } : {},
+      memory,
+      storage,
+      // When an override was supplied, skip the legacy disk-scan path.
+      skillsAutoload: skillSource !== void 0 ? false : this.config.skills.autoload,
+      ...this.config.skills.path !== void 0 ? { skillsDir: this.config.skills.path } : {},
+      ...skillList !== void 0 ? { skillList } : {},
+      // Plan 052 — pass the FINAL post-filter visible tool surface
+      // so prompt sections gate correctly.
+      visibleToolNames,
+      mcpTools: visibleMcpTools,
+      coordinatorMode: isCoordinatorMode(this.config),
+      // Plan 047 — render API services catalog (lazy by default).
+      // Gating on `ApiCall` visibility lives inside buildSystemPrompt.
+      ...apiConfig !== void 0 && apiConfig.services.length > 0 ? {
+        apiServices: apiConfig.services,
+        apiCatalogMode: apiConfig.mode ?? "lazy",
+        ...apiConfig.lazyTokenThreshold !== void 0 ? { apiLazyTokenThreshold: apiConfig.lazyTokenThreshold } : {}
+      } : {}
+    });
+    const registry = buildToolRegistry({ ...baseRegistryArgs, system: systemPrompt });
+    applyRunToolFilter(registry, runOptions);
+    return { systemPrompt, registry };
   }
   /**
    * Resolve the subagent catalogue the Agent tool will dispatch against.
@@ -12962,6 +12832,60 @@ function buildToolRegistry(options) {
   }
   return registry;
 }
+function validateInitialMessages(raw) {
+  if (!Array.isArray(raw)) {
+    return { ok: false, message: "initialMessages must be an array" };
+  }
+  const { maxMessages, maxTotalChars, maxCharsPerMessage } = INITIAL_MESSAGES_LIMITS;
+  if (raw.length > maxMessages) {
+    return {
+      ok: false,
+      message: `initialMessages exceeds max of ${String(maxMessages)} messages (got ${String(raw.length)})`
+    };
+  }
+  const out = [];
+  let totalChars = 0;
+  for (let i = 0; i < raw.length; i++) {
+    const m = raw[i];
+    if (m === null || typeof m !== "object") {
+      return { ok: false, message: `initialMessages[${String(i)}] must be an object` };
+    }
+    if (m.role !== "user" && m.role !== "assistant") {
+      return {
+        ok: false,
+        message: `initialMessages[${String(i)}].role must be 'user' or 'assistant'`
+      };
+    }
+    if (typeof m.content !== "string") {
+      return {
+        ok: false,
+        message: `initialMessages[${String(i)}].content must be a string`
+      };
+    }
+    const trimmed = m.content.trim();
+    if (trimmed.length === 0) {
+      return {
+        ok: false,
+        message: `initialMessages[${String(i)}].content must not be empty`
+      };
+    }
+    if (trimmed.length > maxCharsPerMessage) {
+      return {
+        ok: false,
+        message: `initialMessages[${String(i)}].content exceeds ${String(maxCharsPerMessage)} chars`
+      };
+    }
+    totalChars += trimmed.length;
+    if (totalChars > maxTotalChars) {
+      return {
+        ok: false,
+        message: `initialMessages total content exceeds ${String(maxTotalChars)} chars`
+      };
+    }
+    out.push({ role: m.role, content: trimmed });
+  }
+  return { ok: true, messages: out };
+}
 
 // src/index.ts
 init_contract();