feat: add max steps for supervisor and sub-agents

We want a way to limit the number of steps allow
agents in the app can take. This is primarily useful
for sub-agents, but it applies to the supervisor as
well.

The user can define a single maxSteps value or
optionally define a maxSteps value for each sub-agent.

Author: nwthomas

packages/opencode/src/agent/agent.ts

@@ -16,6 +16,7 @@ export namespace Agent {
       builtIn: z.boolean(),
       topP: z.number().optional(),
       temperature: z.number().optional(),
+      maxSteps: z.number().int().positive().optional(),
       permission: z.object({
         edit: Config.Permission,
         bash: z.record(z.string(), Config.Permission),
@@ -39,6 +40,8 @@ export namespace Agent {
   const state = Instance.state(async () => {
     const cfg = await Config.get()
     const defaultTools = cfg.tools ?? {}
+    const DEFAULT_MAX_STEPS = 25
+    const globalMaxSteps = cfg.experimental?.maxSteps ?? DEFAULT_MAX_STEPS
     const defaultPermission: Info["permission"] = {
       edit: "allow",
       bash: {
@@ -108,6 +111,7 @@ export namespace Agent {
         permission: agentPermission,
         mode: "subagent",
         builtIn: true,
+        maxSteps: globalMaxSteps,
       },
       build: {
         name: "build",
@@ -116,6 +120,7 @@ export namespace Agent {
         permission: agentPermission,
         mode: "primary",
         builtIn: true,
+        maxSteps: globalMaxSteps,
       },
       plan: {
         name: "plan",
@@ -126,6 +131,7 @@ export namespace Agent {
         },
         mode: "primary",
         builtIn: true,
+        maxSteps: globalMaxSteps,
       },
     }
     for (const [key, value] of Object.entries(cfg.agent ?? {})) {
@@ -142,8 +148,9 @@ export namespace Agent {
           options: {},
           tools: {},
           builtIn: false,
+          maxSteps: globalMaxSteps,
         }
-      const { name, model, prompt, tools, description, temperature, top_p, mode, permission, ...extra } = value
+      const { name, model, prompt, tools, description, temperature, top_p, mode, permission, maxSteps, ...extra } = value
       item.options = {
         ...item.options,
         ...extra,
@@ -163,6 +170,7 @@ export namespace Agent {
       if (temperature != undefined) item.temperature = temperature
       if (top_p != undefined) item.topP = top_p
       if (mode) item.mode = mode
+      if (maxSteps != undefined) item.maxSteps = maxSteps
       // just here for consistency & to prevent it from being added as an option
       if (name) item.name = name
 

packages/opencode/src/config/config.ts

@@ -355,6 +355,12 @@ export namespace Config {
       disable: z.boolean().optional(),
       description: z.string().optional().describe("Description of when to use the agent"),
       mode: z.union([z.literal("subagent"), z.literal("primary"), z.literal("all")]).optional(),
+      maxSteps: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Maximum number of steps this agent can take before stopping gracefully"),
       permission: z
         .object({
           edit: Permission.optional(),
@@ -602,6 +608,14 @@ export namespace Config {
             })
             .optional(),
           chatMaxRetries: z.number().optional().describe("Number of retries for chat completions on failure"),
+          maxSteps: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe(
+              "Maximum number of steps (iterations) agents can take before stopping gracefully. Steps accumulate across parent and child sessions. Default: 25",
+            ),
           disable_paste_summary: z.boolean().optional(),
         })
         .optional(),

packages/opencode/src/session/prompt.ts

@@ -109,6 +109,7 @@ export namespace SessionPrompt {
     noReply: z.boolean().optional(),
     system: z.string().optional(),
     tools: z.record(z.string(), z.boolean()).optional(),
+    currentSteps: z.number().int().nonnegative().optional(),
     parts: z.array(
       z.discriminatedUnion("type", [
         MessageV2.TextPart.omit({
@@ -178,6 +179,10 @@ export namespace SessionPrompt {
 
     using abort = lock(input.sessionID)
 
+    const currentSteps = input.currentSteps ?? 0
+    const maxSteps = agent.maxSteps ?? Infinity
+    const stepRef = { current: 0 }
+
     const system = await resolveSystemPrompt({
       providerID: model.providerID,
       modelID: model.info.id,
@@ -201,6 +206,8 @@ export namespace SessionPrompt {
       providerID: model.providerID,
       tools: input.tools,
       processor,
+      currentSteps,
+      stepRef,
     })
 
     const params = await Plugin.trigger(
@@ -235,6 +242,34 @@ export namespace SessionPrompt {
         (messages) => insertReminders({ messages, agent }),
       )
       step++
+      stepRef.current = step
+
+      // Check if we've exceeded maxSteps
+      if (currentSteps + step > maxSteps) {
+        const userMsgID = msgs.findLast((m) => m.info.role === "user")?.info.id!
+        const assistantMsg = await processor.next(userMsgID)
+
+        // Create a graceful stop message
+        await Session.updatePart({
+          id: Identifier.ascending("part"),
+          messageID: assistantMsg.id,
+          sessionID: assistantMsg.sessionID,
+          type: "text",
+          text: `Maximum steps (${maxSteps}) reached. The agent has completed ${currentSteps + step} iterations across all main and sub-agent sessions. Consider increasing the maxSteps limit in your configuration if more steps are needed.`,
+          time: {
+            start: Date.now(),
+            end: Date.now(),
+          },
+        })
+
+        assistantMsg.time.completed = Date.now()
+        await Session.updateMessage(assistantMsg)
+        await processor.end()
+
+        const parts = await MessageV2.parts(assistantMsg.id)
+        return { info: assistantMsg, parts }
+      }
+
       await processor.next(msgs.findLast((m) => m.info.role === "user")?.info.id!)
       if (step === 1) {
         state().track(
@@ -510,6 +545,8 @@ export namespace SessionPrompt {
     providerID: string
     tools?: Record<string, boolean>
     processor: Processor
+    currentSteps: number
+    stepRef: { current: number }
   }) {
     const tools: Record<string, AITool> = {}
     const enabledTools = pipe(
@@ -544,6 +581,7 @@ export namespace SessionPrompt {
             extra: {
               modelID: input.modelID,
               providerID: input.providerID,
+              currentSteps: input.currentSteps + input.stepRef.current,
             },
             agent: input.agent.name,
             metadata: async (val) => {

packages/opencode/src/tool/task.ts

@@ -73,6 +73,7 @@ export const TaskTool = Tool.define("task", async () => {
           providerID: model.providerID,
         },
         agent: agent.name,
+        currentSteps: (ctx.extra as any)?.currentSteps ?? 0,
         tools: {
           todowrite: false,
           todoread: false,