@@ -36,6 +36,7 @@ import { Snapshot } from "@/snapshot"
 import { ProjectV2 } from "@opencode-ai/core/project"
 import { WorkspaceV2 } from "@opencode-ai/core/workspace"
 import { SessionID, MessageID, PartID } from "./schema"
+import { SubagentLimits } from "./subagent-limits"
 
 import type { Provider } from "@/provider/provider"
 import { Permission } from "@/permission"
@@ -498,6 +499,23 @@ export interface Interface {
   readonly diff: (sessionID: SessionID) => Effect.Effect<Snapshot.FileDiff[]>
   readonly messages: (input: { sessionID: SessionID; limit?: number }) => Effect.Effect<SessionV1.WithParts[], NotFound>
   readonly children: (parentID: SessionID) => Effect.Effect<Info[]>
+  /**
+   * The parent chain of a session, ordered self → root: `depth = chain.length`,
+   * `rootID = chain.at(-1)!.id`. A parent row that vanished mid-chain ends the
+   * walk there (orphans count as roots — the safest reading). Fails with
+   * SubagentLineageError once the walk exceeds LINEAGE_ITERATION_CAP (corrupt
+   * or cyclic parent data); callers treat that like "depth ≥ limit" instead of
+   * hanging.
+   */
+  readonly lineage: (
+    sessionID: SessionID,
+  ) => Effect.Effect<Info[], SubagentLimits.SubagentLineageError | NotFound>
+  /**
+   * Every transitive child of a session (the session itself excluded),
+   * collected by iterative BFS over `children`. Cycle-safe via a seen-set and
+   * truncated at a 10 000-node safety cap.
+   */
+  readonly descendants: (sessionID: SessionID) => Effect.Effect<Info[]>
   readonly remove: (sessionID: SessionID) => Effect.Effect<void, NotFound>
   readonly updateMessage: <T extends SessionV1.Info>(msg: T) => Effect.Effect<T>
   readonly removeMessage: (input: { sessionID: SessionID; messageID: MessageID }) => Effect.Effect<MessageID>
@@ -559,6 +577,23 @@ export const layer: Layer.Layer<
       metadata?: typeof Metadata.Type
       permission?: PermissionV1.Ruleset
     }) {
+      // Config-free hard cap on session nesting (design-final §4.1, line 4):
+      // no code path — today's or a future one — may create a session deeper
+      // than HARD_MAX_DEPTH. Every guarded spawn path fails earlier with a
+      // typed error at the (clamped, ≤10) configured limit, so tripping this
+      // is an invariant violation and surfaces as a defect carrying the typed
+      // error; the public create() contract stays Effect<Info>.
+      if (input.parentID !== undefined) {
+        const chain = yield* lineage(input.parentID).pipe(
+          // An unknown parent is an orphan and orphans count as roots.
+          Effect.catchTag("NotFoundError", () => Effect.succeed<Info[]>([])),
+          Effect.catchTag("SubagentLineageError", (error) => Effect.die(error)),
+        )
+        if (chain.length + 1 > SubagentLimits.HARD_MAX_DEPTH)
+          yield* Effect.die(
+            SubagentLimits.depthError({ depth: chain.length + 1, limit: SubagentLimits.HARD_MAX_DEPTH }),
+          )
+      }
       const ctx = yield* InstanceState.context
       const result: Info = {
         id: SessionID.descending(input.id),
@@ -654,6 +689,40 @@ export const layer: Layer.Layer<
       return rows.map(fromRow)
     })
 
+    const lineage: Interface["lineage"] = Effect.fn("Session.lineage")(function* (sessionID: SessionID) {
+      const chain = [yield* get(sessionID)]
+      while (chain.at(-1)!.parentID !== undefined) {
+        if (chain.length >= SubagentLimits.LINEAGE_ITERATION_CAP)
+          return yield* Effect.fail(SubagentLimits.lineageError({ sessionID }))
+        const parent = yield* get(chain.at(-1)!.parentID!).pipe(Effect.option)
+        // A vanished parent ends the chain: orphans count as roots.
+        if (Option.isNone(parent)) return chain
+        chain.push(parent.value)
+      }
+      return chain
+    })
+
+    // Safety cap for the descendants traversal; legitimate trees stay far
+    // below it (HARD_MAX_DEPTH levels × the per-tree spawn cap).
+    const DESCENDANTS_CAP = 10_000
+
+    const descendants: Interface["descendants"] = Effect.fn("Session.descendants")(function* (sessionID: SessionID) {
+      const seen = new Set<SessionID>([sessionID])
+      const result: Info[] = []
+      const queue = [sessionID]
+      while (queue.length > 0) {
+        const kids = yield* children(queue.shift()!)
+        for (const kid of kids) {
+          if (seen.has(kid.id)) continue
+          seen.add(kid.id)
+          result.push(kid)
+          if (result.length >= DESCENDANTS_CAP) return result
+          queue.push(kid.id)
+        }
+      }
+      return result
+    })
+
     const remove: Interface["remove"] = Effect.fnUntraced(function* (sessionID: SessionID) {
       const session = yield* get(sessionID)
       try {
@@ -961,6 +1030,8 @@ export const layer: Layer.Layer<
       diff,
       messages,
       children,
+      lineage,
+      descendants,
       remove,
       updateMessage,
       removeMessage,
 
@@ -0,0 +1,155 @@
+import { Schema } from "effect"
+import { ConfigV1 } from "@opencode-ai/core/v1/config/config"
+import { SessionID } from "./schema"
+
+/**
+ * Shared constants and typed errors for nested subagent spawning
+ * (design-final.md §2). Depth is a purely derived value: the root ("CEO")
+ * session is depth 1 and every task/subtask/workflow dispatch adds one level.
+ * This is a plain module on purpose — NOT an Effect service — so the session
+ * layer, tools and the workflow dispatcher can consume it without wiring.
+ */
+
+/** Default maximum nesting depth (root session = 1; levels 1..4 may spawn). */
+export const DEFAULT_MAX_TASK_DEPTH = 5
+
+/**
+ * Config-free upper bound enforced as an invariant in `Session.createNext`:
+ * no code path — including plugins or future dispatchers — can create a
+ * session deeper than this. Also the clamp ceiling for `maxDepth`.
+ */
+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`.
+ */
+export const SUBAGENT_TREE_LIMIT = 200
+
+/**
+ * Iteration cap for the `Session.lineage` parent-chain walk. Legitimate chains
+ * are at most HARD_MAX_DEPTH long; exceeding this means corrupt or cyclic
+ * parent data and fails with SubagentLineageError instead of hanging.
+ */
+export const LINEAGE_ITERATION_CAP = 32
+
+/**
+ * Resolves the effective maximum nesting depth from config — the single source
+ * of truth for `experimental.subagent_max_depth` (clamped to 1..HARD_MAX_DEPTH,
+ * default DEFAULT_MAX_TASK_DEPTH). Semantics (design-final §2.5): `5` is the
+ * target behavior, `2` reproduces the pre-nesting behavior (root spawns,
+ * subagents do not) and `1` is the kill switch (even the root loses the task
+ * tool). NEVER document `1` as the legacy behavior — that is an off-by-one.
+ */
+export function maxDepth(cfg: ConfigV1.Info): number {
+  // 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_max_depth?: number } | undefined)?.subagent_max_depth
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return DEFAULT_MAX_TASK_DEPTH
+  return Math.min(Math.max(Math.trunc(raw), 1), HARD_MAX_DEPTH)
+}
+
+/**
+ * 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.
+ */
+export function depthHint(depth: number, max: number): string {
+  return `You are a sub-agent at delegation depth ${depth} of ${max}. You may delegate to deeper sub-agents; prefer doing small tasks yourself.`
+}
+
+/**
+ * Raised when a session at the maximum nesting depth attempts to spawn another
+ * subagent (or, as the config-free hard cap in `Session.createNext`, when a
+ * child would exceed HARD_MAX_DEPTH). Tests match on the tag; the message is
+ * model-directed and pinned once in subagent-limits.test.ts.
+ */
+export class SubagentDepthError extends Schema.TaggedErrorClass<SubagentDepthError>()("SubagentDepthError", {
+  message: Schema.String,
+  depth: Schema.Finite,
+  limit: Schema.Finite,
+}) {}
+
+export const depthError = (input: { depth: number; limit: number }) =>
+  new SubagentDepthError({
+    ...input,
+    message: `Subagent nesting limit reached: this session is already at the maximum nesting depth (${input.depth} of ${input.limit}; the root session is depth 1). Do the remaining work yourself in this session and report the results in your final message instead of delegating.`,
+  })
+
+/**
+ * Raised when a session tree has started its lifetime cap of subagents
+ * (SUBAGENT_TREE_LIMIT, overridable via `__testHooks.treeLimit`).
+ */
+export class SubagentTreeLimitError extends Schema.TaggedErrorClass<SubagentTreeLimitError>()(
+  "SubagentTreeLimitError",
+  {
+    message: Schema.String,
+    started: Schema.Finite,
+    limit: Schema.Finite,
+  },
+) {}
+
+export const treeLimitError = (input: { started: number; limit: number }) =>
+  new SubagentTreeLimitError({
+    ...input,
+    message: `Subagent limit reached: this session tree has already started ${input.started} of ${input.limit} subagents (the cap guards against runaway delegation). Finish the remaining work directly in this session.`,
+  })
+
+/**
+ * Raised when `task_id` names an existing session that is NOT a direct child
+ * of the caller — resuming ancestors or foreign sessions is refused instead of
+ * silently adopted (closes the verified resume deadlock).
+ */
+export class SubagentResumeError extends Schema.TaggedErrorClass<SubagentResumeError>()("SubagentResumeError", {
+  message: Schema.String,
+  taskID: Schema.String,
+}) {}
+
+export const resumeError = (input: { taskID: string }) =>
+  new SubagentResumeError({
+    ...input,
+    message: `Cannot resume task ${input.taskID}: it is not a subagent of this session. task_id can only resume tasks this session started itself.`,
+  })
+
+/**
+ * Raised by the spawn gate when the shared turn-budget pool is exhausted —
+ * running subagents may finish, new ones are refused (soft cap).
+ */
+export class SubagentBudgetError extends Schema.TaggedErrorClass<SubagentBudgetError>()("SubagentBudgetError", {
+  message: Schema.String,
+}) {}
+
+export const budgetError = () =>
+  new SubagentBudgetError({
+    message:
+      "Turn budget exhausted: cannot start another subagent. Finish the remaining work directly within this session.",
+  })
+
+/**
+ * Raised when the parent-chain walk exceeds LINEAGE_ITERATION_CAP (corrupt or
+ * cyclic session parents). Callers treat this like "depth ≥ limit": spawning
+ * is refused and the task/workflow tools are filtered.
+ */
+export class SubagentLineageError extends Schema.TaggedErrorClass<SubagentLineageError>()("SubagentLineageError", {
+  message: Schema.String,
+  sessionID: SessionID,
+}) {}
+
+export const lineageError = (input: { sessionID: SessionID }) =>
+  new SubagentLineageError({
+    ...input,
+    message:
+      "Session ancestry could not be resolved (possible cycle in session parents); refusing to spawn subagents from this session.",
+  })
+
+/**
+ * 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.
+ */
+export const __testHooks = {
+  treeLimit: undefined as number | undefined,
+}
+
+export * as SubagentLimits from "./subagent-limits"