feat(workflow): tool + context + plugin wiring (PR-5) — workflow tool, session/agent/skill integration

Brings the remaining net-state delta: the workflow TOOL (tool/workflow.ts +
workflow.txt) and its registry/task wiring; session integration (system,
prompt, tools, processor, mcp-lazy); agent/agent.ts, skill/index.ts; the core
plugin skill (plugin/skill.ts + workflows-instructions.md) and core v1/session;
acp/service, cli/cmd/run + run/workflow.shared; util/process; opencode/config.json;
and the workflow Layer wiring in effect/app-runtime.ts + storage/schema.ts. The
workflow engine itself (workflow/{workflow,errors,schema,types}.ts) stays at
PR-1's modularized form — its Workflow.* namespace already provides every symbol
the tool/session code imports, so nothing in workflow/ is re-touched here.

Excluded as base drift (0 workflow content, would revert current dev): all
unrelated package.json version bumps, mcp/{catalog,oauth-callback}, plugin/{index,
openai/codex,xai}, server/server.ts, stats/*. The 4 net-state workflow migrations
remain superseded by PR-1's single consolidated migration.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: VasyaYovbak <87126061+VasyaYovbak@users.noreply.github.com>

Author: 3 people

packages/core/src/plugin/skill.ts

@@ -7,8 +7,10 @@ import { Effect } from "effect"
 import { AbsolutePath } from "../schema"
 import { SkillV2 } from "../skill"
 import customizeOpencodeContent from "./skill/customize-opencode.md" with { type: "text" }
+import workflowsInstructionsContent from "./skill/workflows-instructions.md" with { type: "text" }
 
 export const CustomizeOpencodeContent = customizeOpencodeContent
+export const WorkflowsInstructionsContent = workflowsInstructionsContent
 
 export const Plugin = define({
   id: "skill",
@@ -26,6 +28,18 @@ export const Plugin = define({
           }),
         }),
       )
+      draft.source(
+        new SkillV2.EmbeddedSource({
+          type: "embedded",
+          skill: new SkillV2.Info({
+            name: "workflows-instructions",
+            description:
+              "Use when the user asks to create, modify, run, debug, or review opencode workflows. Explains workflow authoring, the native workflow tool, foreground/background execution, permissions, and how to inspect logs, agents, and results. Do not use for ordinary tasks unless the user explicitly wants workflow automation.",
+            location: AbsolutePath.make("/builtin/workflows-instructions.md"),
+            content: WorkflowsInstructionsContent,
+          }),
+        }),
+      )
     })
   }),
 })

packages/core/src/plugin/skill/workflows-instructions.md

@@ -56,15 +56,17 @@ export const ContentFilterError = NamedError.create("ContentFilterError", {
   message: Schema.String,
 })
 
-export class OutputFormatText extends Schema.Class<OutputFormatText>("OutputFormatText")({
+export const OutputFormatText = Schema.Struct({
   type: Schema.Literal("text"),
-}) {}
+}).annotate({ identifier: "OutputFormatText" })
+export type OutputFormatText = Schema.Schema.Type<typeof OutputFormatText>
 
-export class OutputFormatJsonSchema extends Schema.Class<OutputFormatJsonSchema>("OutputFormatJsonSchema")({
+export const OutputFormatJsonSchema = Schema.Struct({
   type: Schema.Literal("json_schema"),
   schema: Schema.Record(Schema.String, Schema.Any).annotate({ identifier: "JSONSchema" }),
   retryCount: NonNegativeInt.pipe(Schema.optional, Schema.withDecodingDefault(Effect.succeed(2))),
-}) {}
+}).annotate({ identifier: "OutputFormatJsonSchema" })
+export type OutputFormatJsonSchema = Schema.Schema.Type<typeof OutputFormatJsonSchema>
 
 export const Format = Schema.Union([OutputFormatText, OutputFormatJsonSchema]).annotate({
   discriminator: "type",

packages/core/src/v1/session.ts

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://opencode.ai/config.json"
+}

packages/opencode/config.json

@@ -717,23 +717,28 @@ function profiledRequest<T>(name: string, fn: () => Promise<T | SdkResponse<T>>,
 
 async function loadDirectorySnapshot(sdk: OpencodeClient, directory: string) {
   return ACPProfile.measure("acp.directory.load", async () => {
-    const [providersResponse, agentsResponse, commandsResponse, skillsResponse, configResponse] = await Promise.all([
-      ACPProfile.measure("acp.directory.provider.list", () =>
-        sdk.config.providers({ directory }, { throwOnError: true }),
-      ),
-      ACPProfile.measure("acp.directory.mode.defaultAgent.load", () =>
-        sdk.app.agents({ directory }, { throwOnError: true }),
-      ),
-      ACPProfile.measure("acp.directory.command.list", () => sdk.command.list({ directory }, { throwOnError: true })),
-      ACPProfile.measure("acp.directory.skill.list", () => sdk.app.skills({ directory }, { throwOnError: true })),
-      ACPProfile.measure("acp.directory.defaultModel.config", () =>
-        sdk.config.get({ directory }, { throwOnError: true }).catch(() => undefined),
-      ),
-    ])
+    const [providersResponse, agentsResponse, commandsResponse, skillsResponse, workflowsResponse, configResponse] =
+      await Promise.all([
+        ACPProfile.measure("acp.directory.provider.list", () =>
+          sdk.config.providers({ directory }, { throwOnError: true }),
+        ),
+        ACPProfile.measure("acp.directory.mode.defaultAgent.load", () =>
+          sdk.app.agents({ directory }, { throwOnError: true }),
+        ),
+        ACPProfile.measure("acp.directory.command.list", () => sdk.command.list({ directory }, { throwOnError: true })),
+        ACPProfile.measure("acp.directory.skill.list", () => sdk.app.skills({ directory }, { throwOnError: true })),
+        ACPProfile.measure("acp.directory.workflow.list", () =>
+          sdk.workflow.list({ directory }, { throwOnError: true }),
+        ),
+        ACPProfile.measure("acp.directory.defaultModel.config", () =>
+          sdk.config.get({ directory }, { throwOnError: true }).catch(() => undefined),
+        ),
+      ])
     const providersData = providersResponse.data!
     const agents = agentsResponse.data!
     const commandsData = commandsResponse.data!
     const skills = skillsResponse.data!
+    const workflows = workflowsResponse.data!
     const providers = Object.fromEntries(providersData.providers.map((provider) => [provider.id, provider])) as Record<
       ProviderV2.ID,
       Provider.Info
@@ -761,6 +766,33 @@ async function loadDirectorySnapshot(sdk: OpencodeClient, directory: string) {
         })),
     ] as Command.Info[]
 
+    // Discovery (Spec §5.3 T-ACP, Task 1): surface workflows in availableCommands
+    // with an argument hint derived from `meta.arguments`. Workflows reach the ACP
+    // layer here directly (not via Command.Info, which drops `arguments`) so the
+    // hint can be built. Invalid (broken) workflows cannot be started → skipped.
+    // Dedup by name: a workflow already present via command.list (the T-TUI path,
+    // hint-less) keeps its entry but inherits the hint here so the hint-bearing
+    // form wins; otherwise the workflow is appended as a new entry.
+    for (const wf of workflows) {
+      if (wf.valid === false) continue
+      const hints = argumentHints(wf.meta.arguments)
+      const existingIndex = commands.findIndex((command) => command.name === wf.name)
+      if (existingIndex !== -1) {
+        const existing = commands[existingIndex]
+        if ((existing.hints?.length ?? 0) === 0 && hints.length > 0) {
+          commands[existingIndex] = { ...existing, hints }
+        }
+        continue
+      }
+      commands.push({
+        name: wf.name,
+        description: wf.meta.description,
+        source: "workflow",
+        template: "",
+        hints,
+      })
+    }
+
     return Directory.build({
       directory,
       providers,
@@ -772,6 +804,19 @@ async function loadDirectorySnapshot(sdk: OpencodeClient, directory: string) {
   })
 }
 
+// Build a deterministic, sorted `name=<value>` argument hint for a workflow's
+// declared arguments. Empty/absent arguments yield no hint so the `input` field
+// is omitted (back-compat for hint-less entries). Sorted output keeps the wire
+// response stable across runs (analogous to the stableStringify convention).
+function argumentHints(args: Record<string, { default?: unknown }> | undefined): string[] {
+  if (!args) return []
+  const hint = Object.keys(args)
+    .toSorted((a, b) => a.localeCompare(b))
+    .map((key) => `${key}=<value>`)
+    .join(" ")
+  return hint ? [hint] : []
+}
+
 function defaultModelFromConfig(
   configuredModel: string | undefined,
   providers: Record<ProviderV2.ID, Provider.Info>,
@@ -888,10 +933,14 @@ function sendAvailableCommands(
         sessionId,
         update: {
           sessionUpdate: "available_commands_update",
-          availableCommands: snapshot.availableCommands.map((command) => ({
-            name: command.name,
-            description: command.description ?? "",
-          })),
+          availableCommands: snapshot.availableCommands.map((command) => {
+            const hint = command.hints?.[0]
+            return {
+              name: command.name,
+              description: command.description ?? "",
+              ...(hint ? { input: { hint } } : {}),
+            }
+          }),
         },
       })
     }, 0)

packages/opencode/src/acp/service.ts

@@ -163,6 +163,10 @@ export const layer = Layer.effect(
                 task: {
                   general: "deny",
                 },
+                // Workflow subagent sessions run with their own (default: build)
+                // permissions and would bypass plan mode's edit denies — same
+                // rationale as the `task.general` deny above (#31696 parity).
+                workflow: "deny",
                 external_directory: {
                   [path.join(Global.Path.data, "plans", "*")]: "allow",
                 },

packages/opencode/src/agent/agent.ts

@@ -25,6 +25,14 @@ import { Filesystem } from "@/util/filesystem"
 import { createOpencodeClient, type OpencodeClient, type ToolPart } from "@opencode-ai/sdk/v2"
 import { FormatError, FormatUnknownError } from "../error"
 import { INTERACTIVE_INPUT_ERROR, resolveInteractiveStdin } from "./run/runtime.stdin"
+import {
+  detectUltracodeKeyword,
+  formatParkedQuestion,
+  parseHeadlessWorkflowArgs,
+  RUN_ULTRACODE_DIRECTIVE,
+  stripUltracodeKeyword,
+  workflowExitCode,
+} from "./run/workflow.shared"
 
 type ModelInput = Parameters<OpencodeClient["session"]["prompt"]>[0]["model"]
 
@@ -144,6 +152,10 @@ export const RunCommand = effectCmd({
         describe: "the command to run, use message for args",
         type: "string",
       })
+      .option("workflow", {
+        describe: "run a workflow by name instead of a prompt; positional message becomes key=value args",
+        type: "string",
+      })
       .option("continue", {
         alias: ["c"],
         describe: "continue the last session",
@@ -280,6 +292,18 @@ export const RunCommand = effectCmd({
         die("--mini must be used without the run subcommand")
       }
 
+      // Delta 7a: --workflow is an orthogonal start path (not a session prompt),
+      // so it is mutually exclusive with the session/prompt flags. (Dev renamed
+      // the interactive split-footer flag to `--mini`; the local `interactive`
+      // is driven by it, so the interactive exclusion guards on that.)
+      if (args.workflow) {
+        if (args.command) die("--workflow cannot be used with --command")
+        if (interactive) die("--workflow cannot be used with --mini")
+        if (args.continue) die("--workflow cannot be used with --continue")
+        if (args.session) die("--workflow cannot be used with --session")
+        if (args.fork) die("--workflow cannot be used with --fork")
+      }
+
       if (args.demo && !interactive) {
         die("--demo requires --mini")
       }
@@ -400,7 +424,8 @@ export const RunCommand = effectCmd({
       message = resolveRunInput(message, piped) ?? ""
       const initialInput = resolveRunInput(rawMessage, piped)
 
-      if (message.trim().length === 0 && !args.command && !interactive) {
+      // Delta 7b: --workflow needs no prompt message (its positionals are args).
+      if (message.trim().length === 0 && !args.command && !interactive && !args.workflow) {
         UI.error("You must provide a message or a command")
         process.exit(1)
       }
@@ -650,6 +675,88 @@ export const RunCommand = effectCmd({
         return localAgent()
       }
 
+      // Headless --workflow path (Spec §5.2 (5), Delta 7): orthogonal to sessions.
+      // Start the workflow via the SDK (start/get ARE in the generated client;
+      // only `answer` is not — Delta 2), poll to a STOP status (robust in a
+      // short-lived headless process; the run.* events are not in the SDK either),
+      // print result/error, and exit with workflowExitCode. No permissionSessionID
+      // (no interactive session).
+      //
+      // Finding 6: `paused` is a NON-terminal status the engine parks to when a
+      // `ctx.question` step times out waiting for an answer. Headless mode has no
+      // interactive answerer, so polling for ONLY the terminal statuses would spin
+      // forever on such a run. We therefore stop polling on `paused` too and, when
+      // it carries a pending_question, print the question + the exact (resumable)
+      // answer command and exit with the distinct parked code (2) — we never
+      // auto-answer.
+      async function runWorkflow(sdk: OpencodeClient) {
+        const wfArgs = parseHeadlessWorkflowArgs([...args.message, ...(args["--"] || [])])
+        const started = await sdk.workflow
+          .start({ name: args.workflow!, workflowStartPayload: { args: wfArgs } })
+          .catch((error) => ({ error, data: undefined }) as { error: unknown; data: undefined })
+        if ((started as { error?: unknown }).error || !started.data) {
+          const error = (started as { error?: unknown }).error
+          UI.error(`Failed to start workflow ${args.workflow}: ${formatRunError(error) || "unknown error"}`)
+          process.exit(1)
+        }
+        const id = started.data.id
+        // `paused` is a stop status here even though the engine treats it as
+        // non-terminal: a headless run can never be answered, so we must not poll
+        // past it (Finding 6).
+        const stop = new Set(["completed", "failed", "cancelled", "interrupted", "paused"])
+        let final = started.data
+        while (!stop.has(final.status)) {
+          await Bun.sleep(500)
+          const polled = await sdk.workflow.get({ id }).catch(() => undefined)
+          if (polled?.data) final = polled.data
+        }
+        // A run that parked on an unanswerable question gets its own guidance +
+        // exit code; everything else falls through to the normal result print.
+        if (final.status === "paused" && final.pending_question) {
+          const guidance = formatParkedQuestion({
+            id,
+            question: final.pending_question.question,
+            options: final.pending_question.options,
+          })
+          if (args.format === "json") {
+            process.stdout.write(
+              JSON.stringify({
+                type: "workflow_parked",
+                timestamp: Date.now(),
+                id,
+                workflow: final.workflow,
+                status: final.status,
+                question: final.pending_question.question,
+                options: final.pending_question.options,
+              }) + EOL,
+            )
+          } else {
+            UI.error(guidance)
+          }
+          process.exitCode = workflowExitCode(final.status)
+          return
+        }
+        if (args.format === "json") {
+          process.stdout.write(
+            JSON.stringify({
+              type: "workflow_finished",
+              timestamp: Date.now(),
+              id,
+              workflow: final.workflow,
+              status: final.status,
+              result: final.result,
+              ...(final.error && { error: final.error }),
+            }) + EOL,
+          )
+        } else {
+          UI.println(`Workflow ${final.workflow} ${final.status}`)
+          if (final.result !== undefined)
+            UI.println(typeof final.result === "string" ? final.result : JSON.stringify(final.result, null, 2))
+          if (final.error) UI.error(final.error)
+        }
+        process.exitCode = workflowExitCode(final.status)
+      }
+
       async function execute(sdk: OpencodeClient) {
         const sess = await session(sdk)
         if (!sess?.id) {
@@ -839,12 +946,25 @@ export const RunCommand = effectCmd({
           }
 
           const model = pick(args.model)
+          // Ultracode keyword in the headless prompt path (Spec §5.2 (5)): when a
+          // standalone `ultracode` keyword is present (non-interactive only),
+          // strip it from the visible prompt and PREPEND the directive as a
+          // synthetic text part, mirroring the TUI prompt submit. Default-on like
+          // the TUI (config.workflows.ultracode_keyword is not easily read here
+          // before the workflow loads — Delta 6a note); a non-matching message is
+          // untouched.
+          const ultracode = detectUltracodeKeyword(message)
+          const promptText = ultracode ? stripUltracodeKeyword(message) : message
           const result = await client.session.prompt({
             sessionID,
             agent,
             model,
             variant: args.variant,
-            parts: [...files, { type: "text", text: message }],
+            parts: [
+              ...(ultracode ? [{ type: "text" as const, text: RUN_ULTRACODE_DIRECTIVE }] : []),
+              ...files,
+              { type: "text" as const, text: promptText },
+            ],
           })
           if (result.error) {
             if (!emit("error", { error: result.error })) UI.error(formatRunError(result.error))
@@ -920,7 +1040,7 @@ export const RunCommand = effectCmd({
 
       if (args.attach) {
         const sdk = attachSDK(directory)
-        return await execute(sdk)
+        return args.workflow ? await runWorkflow(sdk) : await execute(sdk)
       }
 
       const fetchFn = (async (input: RequestInfo | URL, init?: RequestInit) => {
@@ -936,6 +1056,7 @@ export const RunCommand = effectCmd({
         fetch: fetchFn,
         directory,
       })
+      if (args.workflow) return await runWorkflow(sdk)
       await execute(sdk)
     })
   }),
@@ -964,6 +1085,8 @@ export async function runMini(input: MiniCommandInput) {
     _: ["mini"],
     message: input.prompt ? [input.prompt] : [],
     command: undefined,
+    // --workflow is mutually exclusive with --mini (interactive); mini never runs one.
+    workflow: undefined,
     continue: input.continue,
     session: input.session,
     fork: input.fork,