bonecode 1.0.0

package/src/engine/tool/tool/skill.ts

@@ -0,0 +1,75 @@
+import path from "path"
+import { pathToFileURL } from "url"
+import { Effect, Schema } from "effect"
+import * as Stream from "effect/Stream"
+import { Ripgrep } from "../file/ripgrep"
+import { Skill } from "../skill"
+import * as Tool from "./tool"
+import DESCRIPTION from "./skill.txt"
+
+export const Parameters = Schema.Struct({
+  name: Schema.String.annotate({ description: "The name of the skill from available_skills" }),
+})
+
+export const SkillTool = Tool.define(
+  "skill",
+  Effect.gen(function* () {
+    const skill = yield* Skill.Service
+    const rg = yield* Ripgrep.Service
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+        Effect.gen(function* () {
+          const info = yield* skill.get(params.name)
+          if (!info) {
+            const all = yield* skill.all()
+            const available = all.map((item) => item.name).join(", ")
+            throw new Error(`Skill "${params.name}" not found. Available skills: ${available || "none"}`)
+          }
+
+          yield* ctx.ask({
+            permission: "skill",
+            patterns: [params.name],
+            always: [params.name],
+            metadata: {},
+          })
+
+          const dir = path.dirname(info.location)
+          const base = pathToFileURL(dir).href
+          const limit = 10
+          const files = yield* rg.files({ cwd: dir, follow: false, hidden: true, signal: ctx.abort }).pipe(
+            Stream.filter((file) => !file.includes("SKILL.md")),
+            Stream.map((file) => path.resolve(dir, file)),
+            Stream.take(limit),
+            Stream.runCollect,
+            Effect.map((chunk) => [...chunk].map((file) => `<file>${file}</file>`).join("\n")),
+          )
+
+          return {
+            title: `Loaded skill: ${info.name}`,
+            output: [
+              `<skill_content name="${info.name}">`,
+              `# Skill: ${info.name}`,
+              "",
+              info.content.trim(),
+              "",
+              `Base directory for this skill: ${base}`,
+              "Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory.",
+              "Note: file list is sampled.",
+              "",
+              "<skill_files>",
+              files,
+              "</skill_files>",
+              "</skill_content>",
+            ].join("\n"),
+            metadata: {
+              name: info.name,
+              dir,
+            },
+          }
+        }).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/engine/tool/tool/skill.txt

@@ -0,0 +1,5 @@
+Load a specialized skill when the task at hand matches one of the skills listed in the system prompt.
+
+Use this tool to inject the skill's instructions and resources into current conversation. The output may contain detailed workflow guidance as well as references to scripts, files, etc in the same directory as the skill.
+
+The skill name must match one of the skills listed in your system prompt.

package/src/engine/tool/tool/task.ts

@@ -0,0 +1,337 @@
+import * as Tool from "./tool"
+import DESCRIPTION from "./task.txt"
+import { ToolJsonSchema } from "./json-schema"
+import { BackgroundJob } from "@/background/job"
+import { Bus } from "@/bus"
+import { Session } from "@/session/session"
+import { SessionID, MessageID } from "../session/schema"
+import { MessageV2 } from "../session/message-v2"
+import { Agent } from "../agent/agent"
+import { deriveSubagentSessionPermission } from "../agent/subagent-permissions"
+import type { SessionPrompt } from "../session/prompt"
+import { SessionStatus } from "@/session/status"
+import { Config } from "@/config/config"
+import { TuiEvent } from "@/cli/cmd/tui/event"
+import { Cause, Effect, Exit, Option, Schema, Scope } from "effect"
+import { EffectBridge } from "@/effect/bridge"
+import { RuntimeFlags } from "@/effect/runtime-flags"
+
+export interface TaskPromptOps {
+  cancel(sessionID: SessionID): Effect.Effect<void>
+  resolvePromptParts(template: string): Effect.Effect<SessionPrompt.PromptInput["parts"]>
+  prompt(input: SessionPrompt.PromptInput): Effect.Effect<MessageV2.WithParts>
+  loop(input: SessionPrompt.LoopInput): Effect.Effect<MessageV2.WithParts>
+}
+
+const id = "task"
+
+const BaseParameters = Schema.Struct({
+  description: Schema.String.annotate({ description: "A short (3-5 words) description of the task" }),
+  prompt: Schema.String.annotate({ description: "The task for the agent to perform" }),
+  subagent_type: Schema.String.annotate({ description: "The type of specialized agent to use for this task" }),
+  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)",
+  }),
+  command: Schema.optional(Schema.String).annotate({ description: "The command that triggered this task" }),
+})
+
+export const Parameters = Schema.Struct({
+  description: Schema.String.annotate({ description: "A short (3-5 words) description of the task" }),
+  prompt: Schema.String.annotate({ description: "The task for the agent to perform" }),
+  subagent_type: Schema.String.annotate({ description: "The type of specialized agent to use for this task" }),
+  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)",
+  }),
+  command: Schema.optional(Schema.String).annotate({ description: "The command that triggered this task" }),
+  background: Schema.optional(Schema.Boolean).annotate({
+    description: "When true, launch the subagent in the background and return immediately",
+  }),
+})
+
+function output(sessionID: SessionID, text: string) {
+  return [
+    `task_id: ${sessionID} (for resuming to continue this task if needed)`,
+    "",
+    "<task_result>",
+    text,
+    "</task_result>",
+  ].join("\n")
+}
+
+function backgroundOutput(sessionID: SessionID) {
+  return [
+    `task_id: ${sessionID} (for polling this task with task_status)`,
+    "state: running",
+    "",
+    "<task_result>",
+    "Background task started. Continue your current work and call task_status when you need the result.",
+    "</task_result>",
+  ].join("\n")
+}
+
+function backgroundMessage(input: {
+  sessionID: SessionID
+  description: string
+  state: "completed" | "error"
+  text: string
+}) {
+  const tag = input.state === "completed" ? "task_result" : "task_error"
+  const title =
+    input.state === "completed"
+      ? `Background task completed: ${input.description}`
+      : `Background task failed: ${input.description}`
+  return [title, `task_id: ${input.sessionID}`, `state: ${input.state}`, "", `<${tag}>`, input.text, `</${tag}>`].join(
+    "\n",
+  )
+}
+
+function errorText(error: unknown) {
+  if (error instanceof Error) return error.message
+  return String(error)
+}
+
+export const TaskTool = Tool.define(
+  id,
+  Effect.gen(function* () {
+    const agent = yield* Agent.Service
+    const background = yield* BackgroundJob.Service
+    const bus = yield* Bus.Service
+    const config = yield* Config.Service
+    const sessions = yield* Session.Service
+    const scope = yield* Scope.Scope
+    const status = yield* SessionStatus.Service
+    const flags = yield* RuntimeFlags.Service
+
+    const run = Effect.fn("TaskTool.execute")(function* (
+      params: Schema.Schema.Type<typeof Parameters>,
+      ctx: Tool.Context,
+    ) {
+      const cfg = yield* config.get()
+      const runInBackground = params.background === true
+      if (runInBackground && !flags.experimentalBackgroundSubagents) {
+        return yield* Effect.fail(
+          new Error("Background subagents require OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true"),
+        )
+      }
+
+      if (!ctx.extra?.bypassAgentCheck) {
+        yield* ctx.ask({
+          permission: id,
+          patterns: [params.subagent_type],
+          always: ["*"],
+          metadata: {
+            description: params.description,
+            subagent_type: params.subagent_type,
+          },
+        })
+      }
+
+      const next = yield* agent.get(params.subagent_type)
+      if (!next) {
+        return yield* Effect.fail(new Error(`Unknown agent type: ${params.subagent_type} is not a valid agent type`))
+      }
+
+      const taskID = params.task_id
+      const session = taskID
+        ? yield* sessions.get(SessionID.make(taskID)).pipe(Effect.catchCause(() => Effect.succeed(undefined)))
+        : undefined
+      const parent = yield* sessions.get(ctx.sessionID)
+      const parentAgent = parent.agent
+        ? yield* agent.get(parent.agent).pipe(Effect.catchCause(() => Effect.succeed(undefined)))
+        : undefined
+      const nextSession =
+        session ??
+        (yield* sessions.create({
+          parentID: ctx.sessionID,
+          title: params.description + ` (@${next.name} subagent)`,
+          permission: [
+            ...deriveSubagentSessionPermission({
+              parentSessionPermission: parent.permission ?? [],
+              parentAgent,
+              subagent: next,
+            }),
+            ...(cfg.experimental?.primary_tools?.map((item) => ({
+              pattern: "*",
+              action: "allow" as const,
+              permission: item,
+            })) ?? []),
+          ],
+        }))
+
+      const msg = yield* MessageV2.get({ sessionID: ctx.sessionID, messageID: ctx.messageID }).pipe(Effect.orDie)
+      if (msg.info.role !== "assistant") return yield* Effect.fail(new Error("Not an assistant message"))
+
+      const model = next.model ?? {
+        modelID: msg.info.modelID,
+        providerID: msg.info.providerID,
+      }
+      const metadata = {
+        parentSessionId: ctx.sessionID,
+        sessionId: nextSession.id,
+        model,
+        ...(runInBackground ? { background: true } : {}),
+      }
+
+      yield* ctx.metadata({
+        title: params.description,
+        metadata,
+      })
+
+      const ops = ctx.extra?.promptOps as TaskPromptOps
+      if (!ops) return yield* Effect.fail(new Error("TaskTool requires promptOps in ctx.extra"))
+      const runCancel = yield* EffectBridge.make()
+
+      const runTask = Effect.fn("TaskTool.runTask")(function* () {
+        const parts = yield* ops.resolvePromptParts(params.prompt)
+        const result = yield* ops.prompt({
+          messageID: MessageID.ascending(),
+          sessionID: nextSession.id,
+          model: {
+            modelID: model.modelID,
+            providerID: model.providerID,
+          },
+          agent: next.name,
+          tools: {
+            ...(next.permission.some((rule) => rule.permission === "todowrite") ? {} : { todowrite: false }),
+            ...(next.permission.some((rule) => rule.permission === id) ? {} : { task: false }),
+            ...Object.fromEntries((cfg.experimental?.primary_tools ?? []).map((item) => [item, false])),
+          },
+          parts,
+        })
+        return result.parts.findLast((item) => item.type === "text")?.text ?? ""
+      })
+
+      const resumeWhenIdle: (input: { userID: MessageID; state: "completed" | "error" }) => Effect.Effect<void> =
+        Effect.fn("TaskTool.resumeWhenIdle")(function* (input: { userID: MessageID; state: "completed" | "error" }) {
+          const latest = yield* sessions
+            .findMessage(ctx.sessionID, (item) => item.info.role === "user")
+            .pipe(Effect.orDie)
+          if (Option.isNone(latest)) return
+          if (latest.value.info.id !== input.userID) return
+          if ((yield* status.get(ctx.sessionID)).type !== "idle") {
+            yield* Effect.sleep("300 millis")
+            return yield* resumeWhenIdle(input)
+          }
+          yield* bus.publish(TuiEvent.ToastShow, {
+            title: input.state === "completed" ? "Background task complete" : "Background task failed",
+            message:
+              input.state === "completed"
+                ? `Background task "${params.description}" finished. Resuming the main thread.`
+                : `Background task "${params.description}" failed. Resuming the main thread.`,
+            variant: input.state === "completed" ? "success" : "error",
+            duration: 5000,
+          })
+          yield* ops
+            .loop({ sessionID: ctx.sessionID })
+            .pipe(Effect.ignore, Effect.forkIn(scope, { startImmediately: true }))
+        })
+
+      const continueIfIdle = Effect.fn("TaskTool.continueIfIdle")(function* (input: {
+        userID: MessageID
+        state: "completed" | "error"
+      }) {
+        yield* resumeWhenIdle(input).pipe(Effect.ignore, Effect.forkIn(scope, { startImmediately: true }))
+      })
+
+      const inject = Effect.fn("TaskTool.injectBackgroundResult")(function* (
+        state: "completed" | "error",
+        text: string,
+      ) {
+        const currentParent = yield* sessions.get(ctx.sessionID)
+        const message = yield* ops.prompt({
+          sessionID: ctx.sessionID,
+          noReply: true,
+          agent: currentParent.agent ?? ctx.agent,
+          parts: [
+            {
+              type: "text",
+              synthetic: true,
+              text: backgroundMessage({
+                sessionID: nextSession.id,
+                description: params.description,
+                state,
+                text,
+              }),
+            },
+          ],
+        })
+        yield* continueIfIdle({ userID: message.info.id, state })
+      })
+
+      const existing = yield* background.get(nextSession.id)
+      if (existing?.status === "running") {
+        return yield* Effect.fail(
+          new Error(`Task ${nextSession.id} is already running. Use task_status to check progress.`),
+        )
+      }
+
+      if (runInBackground) {
+        const info = yield* background.start({
+          id: nextSession.id,
+          type: id,
+          title: params.description,
+          metadata,
+          run: runTask().pipe(
+            Effect.tap((text) => inject("completed", text).pipe(Effect.ignore)),
+            Effect.catchCause((cause) =>
+              (Cause.hasInterruptsOnly(cause)
+                ? Effect.void
+                : inject("error", errorText(Cause.squash(cause))).pipe(Effect.ignore)
+              ).pipe(Effect.andThen(Effect.failCause(cause))),
+            ),
+          ),
+        })
+
+        return {
+          title: params.description,
+          metadata: {
+            ...metadata,
+            jobId: info.id,
+          },
+          output: backgroundOutput(nextSession.id),
+        }
+      }
+
+      const cancel = ops.cancel(nextSession.id)
+
+      function onAbort() {
+        runCancel.fork(cancel)
+      }
+
+      return yield* Effect.acquireUseRelease(
+        Effect.sync(() => {
+          ctx.abort.addEventListener("abort", onAbort)
+        }),
+        () =>
+          Effect.gen(function* () {
+            const text = yield* runTask()
+            return {
+              title: params.description,
+              metadata,
+              output: output(nextSession.id, text),
+            }
+          }),
+        (_, exit) =>
+          Effect.gen(function* () {
+            if (Exit.hasInterrupts(exit)) yield* cancel
+          }).pipe(
+            Effect.ensuring(
+              Effect.sync(() => {
+                ctx.abort.removeEventListener("abort", onAbort)
+              }),
+            ),
+          ),
+      )
+    })
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      jsonSchema: flags.experimentalBackgroundSubagents ? undefined : ToolJsonSchema.fromSchema(BaseParameters),
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+        run(params, ctx).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/engine/tool/tool/task.txt

@@ -0,0 +1,58 @@
+Launch a new agent to handle complex, multistep tasks autonomously.
+
+When using the Task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+When to use the Task tool:
+- When you are instructed to execute custom slash commands. Use the Task tool with the slash command invocation as the entire prompt. The slash command can take arguments. For example: Task(description="Check the file", prompt="/check-file path/to/file.py")
+
+When NOT to use the Task tool:
+- If you want to read a specific file path, use the Read or Glob tool instead of the Task tool, to find the match more quickly
+- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
+- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Task tool, to find the match more quickly
+- Other tasks that are not related to the agent descriptions above
+
+
+Usage notes:
+1. Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+2. 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. If OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS is enabled, background=true launches the subagent asynchronously. Use task_status(task_id=..., wait=false) to poll, or wait=true to block until done.
+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).
+7. If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
+
+Example usage (NOTE: The agents below are fictional examples for illustration only - use the actual agents listed above):
+
+<example_agent_descriptions>
+"code-reviewer": use this agent after you are done writing a significant piece of code
+"greeting-responder": use this agent when to respond to user greetings with a friendly joke
+</example_agent_description>
+
+<example>
+user: "Please write a function that checks if a number is prime"
+assistant: Sure let me write a function that checks if a number is prime
+assistant: First let me use the Write tool to write a function that checks if a number is prime
+assistant: I'm going to use the Write tool to write the following code:
+<code>
+function isPrime(n) {
+  if (n <= 1) return false
+  for (let i = 2; i * i <= n; i++) {
+    if (n % i === 0) return false
+  }
+  return true
+}
+</code>
+<commentary>
+Since a significant piece of code was written and the task was completed, now use the code-reviewer agent to review the code
+</commentary>
+assistant: Now let me use the code-reviewer agent to review the code
+assistant: Uses the Task tool to launch the code-reviewer agent
+</example>
+
+<example>
+user: "Hello"
+<commentary>
+Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
+</commentary>
+assistant: "I'm going to use the Task tool to launch the with the greeting-responder agent"
+</example>

package/src/engine/tool/tool/task_status.ts

@@ -0,0 +1,179 @@
+import * as Tool from "./tool"
+import DESCRIPTION from "./task_status.txt"
+import { BackgroundJob } from "@/background/job"
+import { Session } from "@/session/session"
+import { MessageV2 } from "@/session/message-v2"
+import { SessionID } from "@/session/schema"
+import { SessionStatus } from "@/session/status"
+import { PositiveInt } from "@opencode-ai/core/schema"
+import { RuntimeFlags } from "@/effect/runtime-flags"
+import { Effect, Option, Schema } from "effect"
+
+const DEFAULT_TIMEOUT = 60_000
+const POLL_MS = 300
+
+const Parameters = Schema.Struct({
+  task_id: SessionID.annotate({ description: "The task_id returned by the task tool" }),
+  wait: Schema.optional(Schema.Boolean).annotate({
+    description: "When true, wait until the task reaches a terminal state or timeout",
+  }),
+  timeout_ms: Schema.optional(PositiveInt).annotate({
+    description: "Maximum milliseconds to wait when wait=true (default: 60000)",
+  }),
+})
+
+type State = BackgroundJob.Status
+type InspectResult = { state: State; text: string }
+
+function format(input: { taskID: SessionID; state: State; text: string }) {
+  const tag = input.state === "completed" || input.state === "running" ? "task_result" : "task_error"
+  return [`task_id: ${input.taskID}`, `state: ${input.state}`, "", `<${tag}>`, input.text, `</${tag}>`].join("\n")
+}
+
+function errorText(error: NonNullable<MessageV2.Assistant["error"]>) {
+  const data = Reflect.get(error, "data")
+  const message = data && typeof data === "object" ? Reflect.get(data, "message") : undefined
+  if (typeof message === "string" && message) return message
+  return error.name
+}
+
+function inspectMessage(message: MessageV2.WithParts): InspectResult | undefined {
+  if (message.info.role !== "assistant") return
+  const text = message.parts.findLast((part) => part.type === "text")?.text ?? ""
+  if (message.info.error) return { state: "error", text: text || errorText(message.info.error) }
+  if (message.info.finish && !["tool-calls", "unknown"].includes(message.info.finish))
+    return { state: "completed", text }
+  return { state: "running", text: text || "Task is still running." }
+}
+
+export const TaskStatusTool = Tool.define(
+  "task_status",
+  Effect.gen(function* () {
+    const jobs = yield* BackgroundJob.Service
+    const sessions = yield* Session.Service
+    const status = yield* SessionStatus.Service
+    const flags = yield* RuntimeFlags.Service
+
+    const inspect: (taskID: SessionID) => Effect.Effect<InspectResult> = Effect.fn("TaskStatusTool.inspect")(function* (
+      taskID: SessionID,
+    ) {
+      const job = yield* jobs.get(taskID)
+      if (job) {
+        return {
+          state: job.status,
+          text:
+            job.output ??
+            job.error ??
+            (job.status === "running"
+              ? "Task is still running."
+              : job.status === "cancelled"
+                ? "Task was cancelled."
+                : ""),
+        }
+      }
+
+      const current = yield* status.get(taskID)
+      if (current.type === "busy" || current.type === "retry") {
+        return {
+          state: "running",
+          text: current.type === "retry" ? `Task is retrying: ${current.message}` : "Task is still running.",
+        }
+      }
+
+      const latestAssistant = yield* sessions
+        .findMessage(taskID, (item) => item.info.role === "assistant")
+        .pipe(Effect.orDie)
+      if (Option.isSome(latestAssistant)) {
+        const latest = inspectMessage(latestAssistant.value)
+        if (!latest) return { state: "error", text: "Task is not running in this process." }
+        if (latest.state === "running")
+          return { state: "error", text: "Task is not running in this process and has no final output." }
+        return latest
+      }
+      return { state: "error", text: "Task is not running in this process and has not produced output." }
+    })
+
+    const waitForTerminal: (
+      taskID: SessionID,
+      timeout: number,
+    ) => Effect.Effect<{ result: InspectResult; timedOut: boolean }> = Effect.fn("TaskStatusTool.waitForTerminal")(
+      function* (taskID: SessionID, timeout: number) {
+        const result = yield* inspect(taskID)
+        if (result.state !== "running") return { result, timedOut: false }
+        if (timeout <= 0) return { result, timedOut: true }
+        const sleep = Math.min(POLL_MS, timeout)
+        yield* Effect.sleep(`${sleep} millis`)
+        return yield* waitForTerminal(taskID, timeout - sleep)
+      },
+    )
+
+    const run = Effect.fn("TaskStatusTool.execute")(function* (
+      params: Schema.Schema.Type<typeof Parameters>,
+      _ctx: Tool.Context,
+    ) {
+      if (!flags.experimentalBackgroundSubagents) {
+        return yield* Effect.fail(new Error("task_status requires OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true"))
+      }
+
+      const session = yield* sessions.get(params.task_id).pipe(Effect.catchCause(() => Effect.succeed(undefined)))
+      if (!session) {
+        return {
+          title: "Task status",
+          metadata: {
+            task_id: params.task_id,
+            state: "error" as const,
+            timed_out: false,
+          },
+          output: format({
+            taskID: params.task_id,
+            state: "error",
+            text: `Task not found: ${params.task_id}`,
+          }),
+        }
+      }
+
+      const waited =
+        params.wait === true
+          ? yield* jobs.wait({ id: params.task_id, timeout: params.timeout_ms ?? DEFAULT_TIMEOUT })
+          : { info: yield* jobs.get(params.task_id), timedOut: false }
+      const inspected = waited.info
+        ? {
+            result: {
+              state: waited.info.status,
+              text:
+                waited.info.output ??
+                waited.info.error ??
+                (waited.info.status === "running" ? "Task is still running." : ""),
+            },
+            timedOut: waited.timedOut,
+          }
+        : params.wait === true
+          ? yield* waitForTerminal(params.task_id, params.timeout_ms ?? DEFAULT_TIMEOUT)
+          : { result: yield* inspect(params.task_id), timedOut: false }
+      const text = inspected.timedOut
+        ? `Timed out after ${params.timeout_ms ?? DEFAULT_TIMEOUT}ms while waiting for task completion.`
+        : inspected.result.text
+
+      return {
+        title: "Task status",
+        metadata: {
+          task_id: params.task_id,
+          state: inspected.result.state,
+          timed_out: inspected.timedOut,
+        },
+        output: format({
+          taskID: params.task_id,
+          state: inspected.result.state,
+          text,
+        }),
+      }
+    })
+
+    return {
+      description: DESCRIPTION,
+      parameters: Parameters,
+      execute: (params: Schema.Schema.Type<typeof Parameters>, ctx: Tool.Context) =>
+        run(params, ctx).pipe(Effect.orDie),
+    }
+  }),
+)

package/src/engine/tool/tool/task_status.txt

@@ -0,0 +1,13 @@
+Poll the status of a background subagent task launched with the task tool.
+
+Use this for tasks started with `task(background=true)`.
+
+Parameters:
+- `task_id` (required): the task session id returned by the task tool
+- `wait` (optional): when true, wait for completion
+- `timeout_ms` (optional): max wait duration in milliseconds when `wait=true`
+
+Returns compact, parseable output:
+- `task_id`
+- `state` (`running`, `completed`, `error`, or `cancelled`)
+- `<task_result>...</task_result>` or `<task_error>...</task_error>` containing final output, error summary, or current progress text