@@ -218,6 +218,10 @@ export const Info = Schema.Struct({
         description:
           "Maximum subagent nesting depth (the root session is depth 1; clamped to 1..10). Default 5. Set 2 to restore the previous spawn behavior (the root spawns, subagents do not) — additionally the workflow tool is removed at the limit (security fix) and custom agents that previously nested without limit are bounded; 1 is the kill switch that removes the task and workflow tools entirely.",
       }),
+      subagent_tree_limit: Schema.optional(PositiveInt).annotate({
+        description:
+          "In-memory lifetime cap on subagents started per session tree, a per-process safety ceiling against runaway delegation (clamped to 1..10000). Default 200. Resumes and workflow dispatches do not count against it; the counter is not persisted, so it resets each process run.",
+      }),
       policies: Schema.optional(Schema.mutable(Schema.Array(ConfigExperimental.Policy))).annotate({
         description: "Policy statements applied to supported resources, such as provider access",
       }),
 
@@ -21,13 +21,23 @@ export const DEFAULT_MAX_TASK_DEPTH = 5
 export const HARD_MAX_DEPTH = 10
 
 /**
- * In-memory lifetime cap on subagents started per session tree (keyed by root
- * session). A safety ceiling against runaway delegation within one process
- * run, not an accounting counter; resumes do not count, workflow dispatches
- * keep their own `DEFAULT_AGENT_LIMIT`.
+ * Default in-memory lifetime cap on subagents started per session tree (keyed
+ * by root session). A safety ceiling against runaway delegation within one
+ * process run, not an accounting counter; resumes do not count, workflow
+ * dispatches keep their own `DEFAULT_AGENT_LIMIT`. Overridable via
+ * `experimental.subagent_tree_limit` — see `treeLimit(cfg)`.
  */
 export const SUBAGENT_TREE_LIMIT = 200
 
+/**
+ * Config-free upper bound for `experimental.subagent_tree_limit`. The cap stays
+ * a per-process safety ceiling, so even a power user's override is clamped to a
+ * sane order of magnitude (guards against typos/overflow turning the ceiling
+ * into "effectively unlimited"). Well above the 200 default; the lower clamp
+ * bound is 1 (at least one spawn must remain possible).
+ */
+export const HARD_MAX_TREE_LIMIT = 10_000
+
 /**
  * Iteration cap for the `Session.lineage` parent-chain walk. Legitimate chains
  * are at most HARD_MAX_DEPTH long; exceeding this means corrupt or cyclic
@@ -51,6 +61,23 @@ export function maxDepth(cfg: ConfigV1.Info): number {
   return Math.min(Math.max(Math.trunc(raw), 1), HARD_MAX_DEPTH)
 }
 
+/**
+ * Resolves the effective subagent tree lifetime cap — the single source of
+ * truth for the spawn gate (design-final §2.5, Phase-2 Issue 2). Precedence:
+ * the `__testHooks.treeLimit` seam wins (mirrors `__testHooks.agentLimit` in
+ * workflow.ts), then `experimental.subagent_tree_limit` (clamped to
+ * 1..HARD_MAX_TREE_LIMIT, truncated), else the SUBAGENT_TREE_LIMIT default.
+ * The in-memory per-process counter is unchanged — this only sets the ceiling.
+ */
+export function treeLimit(cfg: ConfigV1.Info): number {
+  if (typeof __testHooks.treeLimit === "number") return __testHooks.treeLimit
+  // The config key ships with the default-opening track; the cast keeps this
+  // helper typed against ConfigV1.Info before and after the schema gains it.
+  const raw = (cfg.experimental as { subagent_tree_limit?: number } | undefined)?.subagent_tree_limit
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return SUBAGENT_TREE_LIMIT
+  return Math.min(Math.max(Math.trunc(raw), 1), HARD_MAX_TREE_LIMIT)
+}
+
 /**
  * Appended to the task tool description on levels 2..max−1 so subagents know
  * their remaining delegation budget instead of discovering it by failed calls.
@@ -145,8 +172,8 @@ export const lineageError = (input: { sessionID: SessionID }) =>
 
 /**
  * Test seam for the tree lifetime cap (mirrors `__testHooks.agentLimit` in
- * workflow.ts): when set, the task tool gates on this value instead of
- * SUBAGENT_TREE_LIMIT. Inert in production.
+ * workflow.ts): when set, `treeLimit(cfg)` returns this value instead of the
+ * config-derived/default ceiling. Inert in production.
  */
 export const __testHooks = {
   treeLimit: undefined as number | undefined,
 
@@ -189,7 +189,7 @@ export const TaskTool = Tool.define(
           // Tree lifetime cap (design-final §2.2): gates NEW spawns only —
           // the resume/extend path never reaches this branch. Counted against
           // the tree's root so every level shares one ceiling.
-          const treeLimit = SubagentLimits.__testHooks.treeLimit ?? SubagentLimits.SUBAGENT_TREE_LIMIT
+          const treeLimit = SubagentLimits.treeLimit(cfg)
           const started = treeSpawnCounts.get(rootID) ?? 0
           if (started >= treeLimit) {
             return yield* Effect.fail(SubagentLimits.treeLimitError({ started, limit: treeLimit }))
 
@@ -1329,6 +1329,20 @@ test("config parser accepts experimental.subagent_max_depth and rejects non-posi
   expect(() => ConfigParse.schema(ConfigV1.Info, { experimental: { subagent_max_depth: 0 } }, "test")).toThrow()
 })
 
+// Phase-2 Issue 2: the tree lifetime cap is now configurable. Same contract as
+// subagent_max_depth — the value must round-trip the parser and non-positive
+// values are rejected by PositiveInt (clamping to 1..10000 happens at read time
+// via SubagentLimits.treeLimit).
+test("config parser accepts experimental.subagent_tree_limit and rejects non-positive values", () => {
+  const config = ConfigParse.schema(ConfigV1.Info, { experimental: { subagent_tree_limit: 200 } }, "test")
+  expect(config.experimental?.subagent_tree_limit).toBe(200)
+
+  const custom = ConfigParse.schema(ConfigV1.Info, { experimental: { subagent_tree_limit: 50 } }, "test")
+  expect(custom.experimental?.subagent_tree_limit).toBe(50)
+
+  expect(() => ConfigParse.schema(ConfigV1.Info, { experimental: { subagent_tree_limit: 0 } }, "test")).toThrow()
+})
+
 test("config parser preserves permission order while rejecting unknown top-level keys", () => {
   const config = ConfigParse.schema(
     ConfigV1.Info,
 
@@ -8,15 +8,52 @@ import { SubagentLimits } from "@/session/subagent-limits"
 const cfg = (value?: number) =>
   ({ experimental: value === undefined ? {} : { subagent_max_depth: value } }) as unknown as ConfigV1.Info
 
+// Same cast for the Phase-2 `subagent_tree_limit` knob (Issue 2).
+const treeCfg = (value?: number) =>
+  ({ experimental: value === undefined ? {} : { subagent_tree_limit: value } }) as unknown as ConfigV1.Info
+
 describe("constants", () => {
   test("limits match the design", () => {
     expect(SubagentLimits.DEFAULT_MAX_TASK_DEPTH).toBe(5)
     expect(SubagentLimits.HARD_MAX_DEPTH).toBe(10)
     expect(SubagentLimits.SUBAGENT_TREE_LIMIT).toBe(200)
+    expect(SubagentLimits.HARD_MAX_TREE_LIMIT).toBe(10_000)
     expect(SubagentLimits.LINEAGE_ITERATION_CAP).toBe(32)
   })
 })
 
+describe("treeLimit", () => {
+  test("defaults to 200 when unset", () => {
+    expect(SubagentLimits.treeLimit(treeCfg())).toBe(200)
+    expect(SubagentLimits.treeLimit({} as ConfigV1.Info)).toBe(200)
+  })
+
+  test("clamps to [1, HARD_MAX_TREE_LIMIT]", () => {
+    expect(SubagentLimits.treeLimit(treeCfg(0))).toBe(1)
+    expect(SubagentLimits.treeLimit(treeCfg(-5))).toBe(1)
+    expect(SubagentLimits.treeLimit(treeCfg(1))).toBe(1)
+    expect(SubagentLimits.treeLimit(treeCfg(50))).toBe(50)
+    expect(SubagentLimits.treeLimit(treeCfg(200))).toBe(200)
+    expect(SubagentLimits.treeLimit(treeCfg(999_999))).toBe(10_000)
+  })
+
+  test("truncates fractional values", () => {
+    expect(SubagentLimits.treeLimit(treeCfg(50.9))).toBe(50)
+  })
+
+  test("ignores non-finite values (falls back to default)", () => {
+    expect(SubagentLimits.treeLimit(treeCfg(Number.NaN))).toBe(200)
+    expect(SubagentLimits.treeLimit(treeCfg(Number.POSITIVE_INFINITY))).toBe(200)
+  })
+
+  test("__testHooks.treeLimit overrides config when set", () => {
+    SubagentLimits.__testHooks.treeLimit = 3
+    expect(SubagentLimits.treeLimit(treeCfg(200))).toBe(3)
+    SubagentLimits.__testHooks.treeLimit = undefined
+    expect(SubagentLimits.treeLimit(treeCfg(200))).toBe(200)
+  })
+})
+
 describe("maxDepth", () => {
   test("defaults to 5 when unset", () => {
     expect(SubagentLimits.maxDepth(cfg())).toBe(5)
 
@@ -152,7 +152,7 @@ By default, nesting is allowed up to **depth 5**. Sessions at depth 1 through 4
 | Limit                      | Default                                                                                            | On violation                                                                                                                       |
 | -------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
 | Maximum nesting depth      | `5` (root session = depth 1), configurable via `experimental.subagent_max_depth`, clamped to 1–10  | The `task` and `workflow` tools are removed at the last level; any remaining spawn attempt fails with a typed `SubagentDepthError` |
-| Subagents per session tree | `200` started subagents per tree, counted **per OpenCode process** (the counter resets on restart) | Further spawns fail with `SubagentTreeLimitError`                                                                                  |
+| Subagents per session tree | `200` started subagents per tree, configurable via `experimental.subagent_tree_limit` (clamped to 1–10000), counted **per OpenCode process** (the counter resets on restart) | Further spawns fail with `SubagentTreeLimitError`                                                                                  |
 | `task_id` resume           | Only tasks the session started itself (direct children)                                            | Other session IDs fail with `SubagentResumeError`; unknown IDs still start a fresh session                                         |
 | Permission prompts         | Raised anywhere in the tree, answered on the **root session** of the tree                          | — see [permissions in nested trees](#permissions-in-nested-trees)                                                                  |
 
@@ -179,6 +179,23 @@ Values are clamped to the range 1–10.
 
 ---
 
+### Configure the tree limit
+
+Set the per-tree lifetime cap with `experimental.subagent_tree_limit`:
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "experimental": {
+    "subagent_tree_limit": 200
+  }
+}
+```
+
+The default is `200`. This is an in-memory safety ceiling counted per OpenCode process: resumed subagents and workflow dispatches do not count against it, and the counter resets on restart. Values are clamped to the range 1–10000; reaching the cap fails further spawns with `SubagentTreeLimitError`.
+
+---
+
 ### Permissions in nested trees
 
 - Whether an agent below the depth limit can spawn is governed by its regular [task permissions](#task-permissions). The default wildcard `"*": "allow"` is enough — an exact `task` rule is no longer required.
 
@@ -880,6 +880,21 @@ Use `experimental.subagent_max_depth` to control how deep subagents can [nest](/
 
 The default is `5`. Setting it to `2` restores the previous spawn behavior (the main session spawns subagents, subagents do not); additionally, the `workflow` tool is removed at the limit (a security fix), and custom agents that previously nested without limit are now bounded. Setting it to `1` is the kill switch: the `task` and `workflow` tools are removed everywhere, including from the main session.
 
+#### Subagent tree limit
+
+Use `experimental.subagent_tree_limit` to control how many subagents a single session tree may start over its lifetime. The cap is an in-memory, per-process safety ceiling against runaway delegation; values are clamped to 1–10000.
+
+```json title="opencode.json"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "experimental": {
+    "subagent_tree_limit": 200
+  }
+}
+```
+
+The default is `200`. Resumed subagents and workflow dispatches do not count against it, and the counter is not persisted — it resets on each OpenCode process restart. Reaching the limit fails further spawns with a typed `SubagentTreeLimitError`.
+
 ---
 
 ## Variables