Method buildInitialMessages

src/agent/loop.ts:367–634

Build the initial system message with full context.

(
    userPrompt: string,
    mode: ToolExecutionMode['mode'],
    modelId: string,
    /** Sub-agent role name. Affects system prompt selection. */
    role?: string,
    /** Tools actually available to this run; if provided, drives the "Available tools:"
     *  line so a restricted sub-agent doesn't think it has tools the registry filters out. */
    allowedTools?: string[],
  )

      // messages.session_id carries a FK to sessions.id, so the sub-agent's FIRST
      // recordTurn would fail with "FOREIGN KEY constraint failed", killing every
      // delegation instantly. Create the parent row up front (idempotent).
      getSessionStore().ensureSession(opts.sessionId, this.cwd, modelUsed);

      // Role-specific tool restriction (allow-list). Built-in policy:
      //   - vision role: only vision_analyze + read-only browser/file/web tools
      //   - subagent role: everything except `task` (no recursion) — handled by mode=subagent
      const roleConfig = (this.config as any).roles?.[role] as { allowedTools?: string[] } | undefined;
      let allowedTools = roleConfig?.allowedTools;
      if (!allowedTools && role === 'vision') {
        // Sensible default for vision role: it should ANALYZE images, not refactor code.
        // Keep it focused — read-only inspection + the vision tool.
        allowedTools = [
          'vision_analyze',
          'read_file', 'ls', 'glob', 'grep',
          'browser_navigate', 'browser_screenshot', 'browser_get_text',
          'browser_console', 'browser_wait_for', 'browser_close',
          'web_fetch',
        ];
      } else if (!allowedTools && role === 'scout') {
        // Scout role: read-only reconnaissance for the `gather` tool. Collects data/
        // context for the parent to decide on — must NEVER mutate. Restricted to
        // read-only inspection tools (any missing one just degrades gracefully).
        allowedTools = [
          'read_file', 'ls', 'glob', 'grep', 'semantic_search',
          'project_overview', 'explain_codebase', 'data_flow', 'analyze_impact', 'find_dead_code',
          'git_status', 'git_diff', 'git_log',
          'db_schema', 'db_query', 'openapi_digest', 'backend_routemap',
          'web_search', 'web_fetch', 'media_probe',
          'project_recall', 'recall',
        ];
      }

      // Build a fresh message stack — sub-agent has NO prior context. The system
      // prompt is selected per-role; built-ins (subagent, vision) have crafted defaults.
      // Custom roles can override via config.roles.<name>.systemPrompt.
      //
      // CRITICAL: we pass `allowedTools` so the system prompt lists ONLY the tools the
      // sub-agent can actually call. Small/quantized models will hallucinate they don't
      // have web_search if it isn't named in prose — see Sub-Agent persona fix.
      const initialMessages = await this.buildInitialMessages(prompt, 'subagent', dispatchModel.model, role, allowedTools);

      for await (const event of this.run(initialMessages, opts.sessionId, {
        mode: { mode: 'subagent', allowedTools },
        signal: opts.signal,
        // run() reads `maxIterationsOverride` (not `maxIterations`) to cap the child's
        // budget — passing the wrong key silently left every sub-agent on the parent's
        // full iteration budget. Pass BOTH so the cap actually applies.
        maxIterationsOverride: opts.maxIterations,
        maxIterations: opts.maxIterations,
        modelOverride: { provider: dispatchModel.provider, model: dispatchModel.model },
        // A sub-agent runs unattended: it has no interactive user to answer a
        // permission prompt. Without an askUser, any tool that prompts would call
        // `ctx.askUser` === undefined and crash the whole delegation. Supply a
        // conservative auto-decline so a gated tool degrades to a tool-level refusal
        // (which the child can adapt to) instead of killing the run.
        askUser: async () => 'no',
      } as any)) {
        if (event.type === 'tool_call_start') toolCallsRun += 1;