docs(core): clarify subagent session input

packages/core/src/plugin/runtime.ts

@@ -23,7 +23,7 @@ export interface Interface {
     | "synthetic"
     | "wait"
   >
-  readonly job: Pick<Job.Interface, "start" | "wait" | "block" | "background" | "cancel">
+  readonly job: Pick<Job.Interface, "get" | "start" | "wait" | "block" | "background" | "cancel">
   readonly location: {
     readonly agent: {
       readonly list: (
@@ -69,6 +69,7 @@ export const layerWithCell = (cell: Cell) =>
         wait: (sessionID) => require(cell, (runtime) => runtime.session.wait(sessionID)),
       },
       job: {
+        get: (id) => require(cell, (runtime) => runtime.job.get(id)),
         start: (input) => require(cell, (runtime) => runtime.job.start(input)),
         wait: (input) => require(cell, (runtime) => runtime.job.wait(input)),
         block: (input) => require(cell, (runtime) => runtime.job.block(input)),

packages/core/src/tool/plugin/subagent.ts

@@ -23,6 +23,10 @@ export const Input = Schema.Struct({
   agent: Schema.String.annotate({ description: "The type of specialized agent to use for this task" }),
   description: Schema.String.annotate({ description: "A short 3-5 word label for the task, displayed to the user" }),
   prompt: Schema.String.annotate({ description: "The task for the subagent to perform" }),
+  sessionID: Schema.optionalKey(SessionSchema.ID).annotate({
+    description:
+      "Continue a specific previous subagent conversation by passing its sessionID. Calls without a sessionID start a new conversation.",
+  }),
   background: Schema.optionalKey(Schema.Boolean).annotate({
     description:
       "Run the subagent in the background and return immediately. You will be notified when it completes. DO NOT sleep, poll, or proactively check on its progress.",
@@ -36,7 +40,8 @@ export const Output = Schema.Struct({
 })
 export const description = [
   "Spawns an agent in a child session to work on the specified task.",
-  "Include all relevant context and instructions in the prompt because the child starts with fresh context.",
+  "The output includes a sessionID you can pass back later to continue that specific conversation with the subagent.",
+  "New child sessions start with fresh context, so include all relevant context and instructions when you don't pass a sessionID.",
   "Foreground (default) runs the subagent to completion and returns its final response.",
   "Background mode (background=true) launches it asynchronously and returns immediately; you are notified when it finishes.",
   "Use background only for independent work that can run while you continue elsewhere.",
@@ -77,7 +82,7 @@ export const Plugin = {
     ) {
       yield* runtime.session.synthetic({
         sessionID: parentID,
-        text: `<subagent id="${childID}" state="${state}" description="${description}">\n${text}\n</subagent>`,
+        text: `<subagent sessionID="${childID}" state="${state}" description="${description}">\n${text}\n</subagent>`,
         description,
         metadata: { source: "subagent", childID, agent, state },
       })
@@ -164,22 +169,51 @@ export const Plugin = {
                   })
                   .pipe(Effect.mapError((error) => new ToolFailure({ message: `Subagent denied: ${agent.id}`, error })))
 
+                if (input.sessionID !== undefined && input.background === true)
+                  return yield* new ToolFailure({
+                    message: "Continuing a subagent in the background is not implemented yet",
+                  })
+
+                const existing =
+                  input.sessionID === undefined
+                    ? undefined
+                    : yield* runtime.session.get(input.sessionID).pipe(
+                        Effect.mapError(
+                          (error) =>
+                            new ToolFailure({ message: `Subagent session not found: ${input.sessionID}`, error }),
+                        ),
+                      )
+                if (existing !== undefined && existing.parentID !== context.sessionID)
+                  return yield* new ToolFailure({
+                    message: `Session ${existing.id} is not a child of the current session`,
+                  })
+                if (existing !== undefined && existing.agent !== agent.id)
+                  return yield* new ToolFailure({
+                    message: `Session ${existing.id} belongs to agent ${existing.agent ?? "unknown"}, not ${agent.id}`,
+                  })
+                if (existing !== undefined && (yield* runtime.job.get(existing.id))?.status === "running")
+                  return yield* new ToolFailure({
+                    message: "Continuing a running subagent is not implemented yet",
+                  })
+
                 // Model selection is policy/config/session state, not an LLM-facing tool argument.
                 const model = agent.model ?? parent.model
-                const child = yield* runtime.session
-                  .create({
-                    parentID: context.sessionID,
-                    title: input.description,
-                    agent: Agent.ID.make(input.agent),
-                    model,
-                    // TODO(opencode kkdvxn): derive restricted subagent permissions from the parent
-                    // session (V1 deriveSubagentSessionPermission). MVP uses the agent's own permissions.
-                  })
-                  .pipe(
-                    Effect.mapError(
-                      (error) => new ToolFailure({ message: `Parent session not found: ${context.sessionID}`, error }),
-                    ),
-                  )
+                const child =
+                  existing ??
+                  (yield* runtime.session
+                    .create({
+                      parentID: context.sessionID,
+                      title: input.description,
+                      agent: Agent.ID.make(input.agent),
+                      model,
+                      // TODO(opencode kkdvxn): derive restricted subagent permissions from the parent
+                      // session (V1 deriveSubagentSessionPermission). MVP uses the agent's own permissions.
+                    })
+                    .pipe(
+                      Effect.mapError(
+                        (error) => new ToolFailure({ message: `Parent session not found: ${context.sessionID}`, error }),
+                      ),
+                    ))
 
                 const background = input.background === true
                 yield* context.progress({
@@ -190,7 +224,10 @@ export const Plugin = {
                   // The child session owns its agent/model (set at create); prompt only admits input.
                   yield* runtime.session.prompt({
                     sessionID: child.id,
-                    text: ["You are a subagent spawned by another session.", input.prompt].join("\n"),
+                    text:
+                      existing === undefined
+                        ? ["You are a subagent spawned by another session.", input.prompt].join("\n")
+                        : input.prompt,
                     resume: false,
                   })
                   yield* runtime.session.resume(child.id)
@@ -238,7 +275,10 @@ export const Plugin = {
               }).pipe(
                 Effect.map((output) => ({
                   output,
-                  content: output.output,
+                  content:
+                    output.status === "completed"
+                      ? `<subagent sessionID="${output.sessionID}" state="completed">\n${output.output}\n</subagent>`
+                      : output.output,
                   metadata: { sessionID: output.sessionID, status: output.status },
                 })),
               ),

packages/core/test/tool-subagent.test.ts

@@ -240,7 +240,7 @@ describe("SubagentTool", () => {
           expect(settled).toMatchObject({
             status: "completed",
             metadata: { status: "completed" },
-            content: [{ type: "text", text: childText }],
+            content: [{ type: "text", text: expect.stringContaining(childText) }],
           })
           expect(settled.metadata).toEqual({
             sessionID: outputSessionID(settled.metadata),
@@ -283,9 +283,15 @@ describe("SubagentTool", () => {
           expect(settled).toMatchObject({
             status: "completed",
             metadata: { status: "completed" },
-            content: [{ type: "text", text: childText }],
+            content: [{ type: "text", text: expect.stringContaining(childText) }],
           })
           const child = yield* sessions.get(outputSessionID(settled.metadata))
+          expect(settled.content).toEqual([
+            {
+              type: "text",
+              text: `<subagent sessionID="${child.id}" state="completed">\n${childText}\n</subagent>`,
+            },
+          ])
           expect(settled.metadata).toEqual({ sessionID: child.id, status: "completed" })
           expect(progress[0]?.metadata).toEqual({ sessionID: child.id, status: "running" })
           expect(child).toMatchObject({
@@ -315,6 +321,144 @@ describe("SubagentTool", () => {
     ),
   )
 
+  it.live("continues an existing child session", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (dir) => Effect.promise(() => dir[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((dir) =>
+        Effect.gen(function* () {
+          const location = Location.Ref.make({ directory: AbsolutePath.make(dir.path) })
+          const sessions = yield* Session.Service
+          const parent = yield* sessions.create({ location, model: parentModel })
+          yield* withSubagent(parent.location)
+          const locations = yield* LocationServiceMap.Service
+          const registry = yield* Tool.Service.pipe(Effect.provide(locations.get(parent.location)))
+          yield* waitForTool(registry, SubagentTool.name)
+
+          const first = yield* executeTool(registry, {
+            sessionID: parent.id,
+            ...toolIdentity,
+            call: {
+              type: "tool-call",
+              id: "call-subagent-first",
+              name: SubagentTool.name,
+              input: { agent: "reviewer", description: "review", prompt: "review this" },
+            },
+          })
+          const childID = outputSessionID(first.metadata)
+          const second = yield* executeTool(registry, {
+            sessionID: parent.id,
+            ...toolIdentity,
+            call: {
+              type: "tool-call",
+              id: "call-subagent-second",
+              name: SubagentTool.name,
+              input: {
+                agent: "reviewer",
+                description: "follow up",
+                prompt: "continue this",
+                sessionID: childID,
+              },
+            },
+          })
+
+          expect(outputSessionID(second.metadata)).toBe(childID)
+          expect((yield* sessions.list({ parentID: parent.id })).data).toHaveLength(1)
+          expect((yield* sessions.get(childID)).title).toBe("review")
+          expect(
+            (yield* sessions.pending(childID)).flatMap((message) =>
+              message.type === "user" ? [message.data.text] : [],
+            ),
+          ).toEqual(["You are a subagent spawned by another session.\nreview this", "continue this"])
+          expect(second.content).toEqual([
+            {
+              type: "text",
+              text: `<subagent sessionID="${childID}" state="completed">\n${childText}\n</subagent>`,
+            },
+          ])
+        }),
+      ),
+    ),
+  )
+
+  it.live("rejects background continuation", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (dir) => Effect.promise(() => dir[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((dir) =>
+        Effect.gen(function* () {
+          const location = Location.Ref.make({ directory: AbsolutePath.make(dir.path) })
+          const sessions = yield* Session.Service
+          const parent = yield* sessions.create({ location })
+          const child = yield* sessions.create({
+            parentID: parent.id,
+            title: "review",
+            agent: Agent.ID.make("reviewer"),
+          })
+          yield* withSubagent(parent.location)
+          const locations = yield* LocationServiceMap.Service
+          const registry = yield* Tool.Service.pipe(Effect.provide(locations.get(parent.location)))
+          yield* waitForTool(registry, SubagentTool.name)
+
+          expect(
+            yield* executeTool(registry, {
+              sessionID: parent.id,
+              ...toolIdentity,
+              call: {
+                type: "tool-call",
+                id: "call-background-continuation",
+                name: SubagentTool.name,
+                input: {
+                  agent: "reviewer",
+                  description: "follow up",
+                  prompt: "continue this",
+                  sessionID: child.id,
+                  background: true,
+                },
+              },
+            }),
+          ).toEqual({
+            status: "error",
+            error: {
+              type: "tool.execution",
+              message: "Continuing a subagent in the background is not implemented yet",
+            },
+          })
+
+          const jobs = yield* Job.Service
+          yield* jobs.start({ id: child.id, type: "subagent", run: Effect.never })
+          yield* jobs.background(child.id)
+          expect(
+            yield* executeTool(registry, {
+              sessionID: parent.id,
+              ...toolIdentity,
+              call: {
+                type: "tool-call",
+                id: "call-running-continuation",
+                name: SubagentTool.name,
+                input: {
+                  agent: "reviewer",
+                  description: "follow up",
+                  prompt: "continue this",
+                  sessionID: child.id,
+                },
+              },
+            }),
+          ).toEqual({
+            status: "error",
+            error: {
+              type: "tool.execution",
+              message: "Continuing a running subagent is not implemented yet",
+            },
+          })
+          yield* jobs.cancel(child.id)
+        }),
+      ),
+    ),
+  )
+
   it.live("returns child runner failures as tool errors", () =>
     Effect.acquireRelease(
       Effect.promise(() => tmpdir()),
@@ -393,7 +537,7 @@ describe("SubagentTool", () => {
           expect(settled.content).toEqual([{ type: "text", text: expect.stringContaining(`id: ${childID}`) }])
 
           const admission = Array.from(yield* Fiber.join(admitted))[0]
-          expect(admission?.data.input.data.text).toContain(`<subagent id="${childID}" state="completed"`)
+          expect(admission?.data.input.data.text).toContain(`<subagent sessionID="${childID}" state="completed"`)
           expect(admission?.data.input.data).toMatchObject({
             description: "background review",
             metadata: {
@@ -407,7 +551,7 @@ describe("SubagentTool", () => {
           yield* SessionPending.promote(database.db, bus, parent.id, "steer")
           const synthetic = (yield* sessions.context(parent.id)).filter((message) => message.type === "synthetic")
           expect(synthetic).toHaveLength(1)
-          expect(synthetic[0]?.text).toContain(`<subagent id="${childID}" state="completed"`)
+          expect(synthetic[0]?.text).toContain(`<subagent sessionID="${childID}" state="completed"`)
           expect(synthetic[0]?.text).toContain(childText)
         }),
       ),