Method runSubagent

src/agent/loop.ts:276–364

* Run a sub-agent inline. Used by the `task` tool. * * Architecture: sub-agent gets a fresh AgentLoop with the same router/registry/perms * but a new session id and an isolated message history. Tools run in 'subagent' mode * (task and present_plan filtered). We drain the event stream and

(
    prompt: string,
    opts: {
      maxIterations: number;
      signal?: AbortSignal;
      sessionId: string;
      modelOverride?: string;
      /** Role name — drives model selection, system prompt, tool restriction. Default 'subagent'. */
      role?: string;
    },
  )

    (this.config as any).safety = { ...(this.config as any).safety, autoSnapshot: enabled };
  }

  /**
   * Queue a mid-task steering note (from `/btw …`). Picked up at the top of the next
   * run-loop iteration and injected into the conversation. Safe to call while a run
   * is in flight; no-ops on an empty/whitespace note.
   */
  pushSteer(note: string): void {
    if (typeof note === 'string' && note.trim().length > 0) {
      this.steerQueue.push(note.trim());
    }
  }

  /** True when there are steering notes waiting to be injected. */
  hasPendingSteer(): boolean {
    return this.steerQueue.length > 0;
  }

  /**
   * Run a sub-agent inline. Used by the `task` tool.
   *
   * Architecture: sub-agent gets a fresh AgentLoop with the same router/registry/perms
   * but a new session id and an isolated message history. Tools run in 'subagent' mode
   * (task and present_plan filtered). We drain the event stream and collect just the
   * final text + tool-call count.
   *
   * The sub-agent's events ARE persisted to the session store under its sub-session id —
   * so `qx sessions` will list it as a child, debuggable independently. We do NOT
   * pipe sub-agent UI events to the parent's UI; the parent just sees the eventual
   * tool result.
   */
  async runSubagent(
    prompt: string,
    opts: {
      maxIterations: number;
      signal?: AbortSignal;
      sessionId: string;
      modelOverride?: string;
      /** Role name — drives model selection, system prompt, tool restriction. Default 'subagent'. */
      role?: string;
    },
  ): Promise<{ finalText: string; toolCallsRun: number; ok: boolean; error?: string; modelUsed?: string }> {
    let finalText = '';
    let toolCallsRun = 0;
    let errMsg: string | undefined;
    let ok = true;
    let modelUsed: string | undefined;
    try {
      const role = opts.role ?? 'subagent';
      // Resolve which model this sub-agent should use, applying the precedence rules:
      // explicit (opts.modelOverride) > session override > config.roles.<role> > config.roles.subagent > parent default.
      const resolved = resolveRole(role, this.config, opts.modelOverride);

      // ── Token-efficiency auto-offload (opt-in, offload.enabled) ──
      // A scout dispatch is read-only recon whose output only the PARENT consumes — the
      // safe set for a cheap model. Only lift the model when nothing more specific chose
      // one (source parent-default): explicit per-call overrides, session overrides and
      // config roles always win. Follow-up: extend to other read-only roles once the
      // policy has mileage. Non-scout roles are untouched by design (see offload-policy.ts).