feat(tool): allow human-readable slugs as task_id

Accept a human-readable slug as the task tool's task_id: it is resolved to a
deterministic session ID derived from the root session, so passing the same
slug resumes the named task and a new slug creates one. Full "ses_..." IDs
still resume directly. Adds Session.create({ id }) and Session.root().

Ported from anomalyco#32122 (adapted for the Effect layer).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: randomvariable

packages/opencode/src/session/session.ts

@@ -269,6 +269,7 @@ export const CreateInput = Schema.optional(
     metadata: Schema.optional(Metadata),
     permission: Schema.optional(PermissionV1.Ruleset),
     workspaceID: Schema.optional(WorkspaceV2.ID),
+    id: Schema.optional(SessionID),
   }),
 )
 export type CreateInput = Types.DeepMutable<Schema.Schema.Type<typeof CreateInput>>
@@ -426,7 +427,9 @@ export interface Interface {
     metadata?: typeof Metadata.Type
     permission?: PermissionV1.Ruleset
     workspaceID?: WorkspaceV2.ID
+    id?: SessionID
   }) => Effect.Effect<Info>
+  readonly root: (sessionID: SessionID) => Effect.Effect<SessionID, NotFound>
   readonly fork: (input: { sessionID: SessionID; messageID?: MessageID }) => Effect.Effect<Info, NotFound>
   readonly touch: (sessionID: SessionID) => Effect.Effect<void>
   readonly get: (id: SessionID) => Effect.Effect<Info, NotFound>
@@ -677,10 +680,12 @@ export const layer: Layer.Layer<
       metadata?: typeof Metadata.Type
       permission?: PermissionV1.Ruleset
       workspaceID?: WorkspaceV2.ID
+      id?: SessionID
     }) {
       const ctx = yield* InstanceState.context
       const workspace = yield* InstanceState.workspaceID
       return yield* createNext({
+        id: input?.id,
         parentID: input?.parentID,
         directory: ctx.directory,
         path: sessionPath(ctx.worktree, ctx.directory),
@@ -693,6 +698,15 @@ export const layer: Layer.Layer<
       })
     })
 
+    const root = Effect.fn("Session.root")(function* (sessionID: SessionID) {
+      let current = sessionID
+      while (true) {
+        const s = yield* get(current)
+        if (!s.parentID) return current
+        current = s.parentID
+      }
+    })
+
     const fork = Effect.fn("Session.fork")(function* (input: { sessionID: SessionID; messageID?: MessageID }) {
       const ctx = yield* InstanceState.context
       const original = yield* get(input.sessionID)
@@ -912,6 +926,7 @@ export const layer: Layer.Layer<
       list,
       listGlobal,
       create,
+      root,
       fork,
       touch,
       get,

packages/opencode/src/tool/task.ts

@@ -16,6 +16,16 @@ import { Effect, Exit, Schema, Scope } from "effect"
 import { EffectBridge } from "@/effect/bridge"
 import { RuntimeFlags } from "@/effect/runtime-flags"
 import { Database } from "@opencode-ai/core/database/database"
+import { createHash } from "crypto"
+
+function isSlug(taskId: string): boolean {
+  return !taskId.startsWith("ses_")
+}
+
+function deriveSlugSessionID(slug: string, rootID: SessionID): SessionID {
+  const hash = createHash("sha256").update(rootID).digest("hex").slice(0, 4)
+  return SessionID.descending(`ses_${hash}_${slug}`)
+}
 
 export interface TaskPromptOps {
   cancel(sessionID: SessionID): Effect.Effect<void>
@@ -52,7 +62,7 @@ const BaseParameterFields = {
   }),
   task_id: Schema.optional(Schema.String).annotate({
     description:
-      "This should only be set if you mean to resume a previous task (you can pass a prior task_id and the task will continue the same subagent session as before instead of creating a fresh one)",
+      'A human-readable slug (e.g. "explore-auth") to create or resume a named task session within this root session. If the slug has not been used yet, a new task is created with that identifier. If it already exists, the existing session is resumed. Also accepts full "ses_..." session IDs to resume a specific session directly.',
   }),
   command: Schema.optional(Schema.String).annotate({ description: "The command that triggered this task" }),
 }
@@ -153,8 +163,13 @@ export const TaskTool = Tool.define(
         return yield* Effect.fail(new Error(`Unknown agent type: ${params.subagent_type} is not a valid agent type`))
       }
 
+      const slugTaskId = params.task_id && isSlug(params.task_id) ? params.task_id : undefined
+      const derivedID = slugTaskId ? deriveSlugSessionID(slugTaskId, yield* sessions.root(ctx.sessionID)) : undefined
+
       const session = params.task_id
-        ? yield* sessions.get(SessionID.make(params.task_id)).pipe(Effect.catchCause(() => Effect.succeed(undefined)))
+        ? yield* sessions
+            .get(derivedID ?? SessionID.make(params.task_id))
+            .pipe(Effect.catchCause(() => Effect.succeed(undefined)))
         : undefined
       const parent = yield* sessions.get(ctx.sessionID)
       const childPermission = deriveSubagentSessionPermission({
@@ -177,6 +192,7 @@ export const TaskTool = Tool.define(
       const nextSession =
         session ??
         (yield* sessions.create({
+          id: derivedID,
           parentID: ctx.sessionID,
           title: params.description + ` (@${next.name} subagent)`,
           agent: next.name,

packages/opencode/src/tool/task.txt

@@ -18,7 +18,7 @@ Model selection:
 Usage notes:
 1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
 2. Once you have delegated work to an agent, do not duplicate that work yourself. Continue with non-overlapping tasks, or wait for the result. For background tasks, you will be notified automatically when the result is ready.
-3. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result. The output includes a task_id you can reuse later to continue the same subagent session.
+3. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result. The output includes a task_id you can reuse later to continue the same subagent session. You can also pass a human-readable slug (e.g. "explore-auth") as task_id to create or resume a named task within the current root session — if the slug has not been used yet, a new task is created; if it already exists, the existing session is resumed.
 4. Each agent invocation starts with a fresh context unless you provide task_id to resume the same subagent session (which continues with its previous messages and tool outputs). When starting fresh, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
 5. The agent's outputs should generally be trusted
 6. Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent. Tell it how to verify its work if possible (e.g., relevant test commands).