[FEATURE]:Option to always start sessions in the configured default agent mode #27370

I looked into the code and found the root cause: when restoring a session, restoreSessionStateFromMessages() reads the last user message's agent and writes it into session state. Then resolveModeState() sees a non-empty storedModeId and returns early, skipping default_agent entirely.

I think restoring the last-used agent is actually good idea — if you were mid-task in Build mode, coming back to Build makes sense. But it does ignore users who have explicitly configured default_agent and expect it to always be respected.

I'm thinking through the best way to handle this and will share a concrete proposal soon.

@kitlangton Hi, here's my concrete proposal.

Root cause: restoreSessionStateFromMessages() writes the last-used agent into session state, then resolveModeState() sees a non-empty storedModeId and returns early — default_agent is never consulted.

Relevant code path in acp/agent.ts:

// restoreSessionStateFromMessages() — runs before resolveModeState()
if (lastUser.agent) {
  this.sessionManager.setMode(sessionId, lastUser.agent)  // writes "build" into state
}

// resolveModeState() — sees storedModeId and exits early
const storedModeId = this.sessionManager.get(sessionId).modeId
if (storedModeId && availableModes.some((mode) => mode.id === storedModeId)) {
  return { availableModes, currentModeId: storedModeId }  // default_agent never reached
}

Reproduction steps:

1. Set "default_agent": "plan" in opencode.json

2. Open opencode — session correctly starts in Plan mode

3. Press Tab to switch to Build mode, send any message

4. Close opencode, then reopen and resume the same session
5. Session opens in Build mode instead of Plan — default_agent is ignored

Proposed fix

I looked at two approaches:

Option A — add always_use_default_agent: false opt-out field

Default behavior when default_agent is set becomes: always use default_agent when opening any session (new or resumed). The reasoning: anyone who takes the time to configure default_agent has a strong intent to use that agent — silently overriding it on resume is surprising. Users who prefer the old restore behavior can explicitly opt out:

{ "default_agent": "plan" }                                          // always opens in Plan
{ "default_agent": "plan", "always_use_default_agent": false }       // new sessions use Plan, resumed sessions restore last-used

Changes needed:

• config.ts: add always_use_default_agent: Schema.optional(Schema.Boolean)
• acp/runtime.ts: expose the default-agent startup policy from directory-scoped config, since acp/agent.ts currently only receives ACP config and cannot directly tell whether this option is set
• acp/agent.ts: in resolveModeState(), skip the storedModeId early-return when default_agent is set and always_use_default_agent !== false
• customize-opencode.md: document the new field

Option B — change default_agent from string to object

{ "default_agent": { "name": "plan", "always": true } }

More extensible for future per-default-agent options (e.g. { "name": "plan", "always": false, "model": "...", "tools": [...] }), but requires handling a union type (string | object) everywhere default_agent is read — agent.ts, acp/agent.ts, acp/runtime.ts, docs, and tests. Note that per-agent config is already covered by the existing agent field, so the extensibility gain is limited.

I prefer Option A: minimal API surface change, fully backward-compatible, and the semantics are clear — if you configure a default_agent, you almost certainly want it respected on every open. The opt-out exists for the rare case where you don't.

Happy to implement whichever direction you prefer.

Hi @21pounder,

Is there anything I can help with regarding this task, or are we currently waiting for comments from @kitlangton?

Please let me know if there is anything I can do to move this forward.

Regards,

@ezzems still waiting, it's a big change u know.

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.