openclaw - 💡(How to fix) Fix feat: Expose TaskFlow managed mode as Agent-accessible tools

Problem

TaskFlow's managed mode is designed for multi-step orchestration — creating flows, linking child tasks, setting wait states, resuming, and finishing. However, these capabilities are only available through the internal TypeScript API (api.runtime.tasks.flow), not exposed to Agents.

Currently, Agents can only:

• openclaw tasks flow list — list flows
• openclaw tasks flow show <id> — inspect a flow
• openclaw tasks flow cancel <id> — cancel a flow

There is no way for an Agent to:

• Create a managed flow
• Link child tasks to a flow (runTask)
• Set a flow to waiting state (setWaiting)
• Resume a flow (resume)
• Finish/fail a flow (finish/fail)

sessions_spawn automatically creates a mirrored flow per subagent, but this only tracks individual child task lifecycle — it cannot orchestrate a multi-phase workflow under a single parent flow.

Use Case

As an AI Agent orchestrator, I need to manage complex multi-step tasks:

Flow: Refactor project
  Phase 1: Research (researcher) → completed
  Phase 2: Implement (engineer) → completed
  Phase 3: QA (qa) → running
  Phase 4: Deliver → pending

This requires:

1. Creating a managed flow at the start
2. Linking each subagent as a child task
3. Setting wait states between phases (e.g., wait for user confirmation)
4. Resuming when conditions are met
5. Finishing/failing the flow on completion

Proposed Solution

Expose TaskFlow managed mode operations as Agent-accessible tools or CLI commands:

Option A: CLI commands

# Create a managed flow
openclaw tasks flow create --goal "Refactor project" --controller "main-orchestrator" --state-json '{"phase":"analyzing"}'

# Link a child task
openclaw tasks flow run-task <flow-id> --child-session "agent:main:subagent:uuid" --task "Research phase" --status running

# Set waiting
openclaw tasks flow set-waiting <flow-id> --step "await_user_confirm" --wait-json '{"kind":"user_input"}'

# Resume
openclaw tasks flow resume <flow-id> --step "implementing"

# Finish/fail
openclaw tasks flow finish <flow-id>
openclaw tasks flow fail <flow-id> --reason "timeout"

Option B: Agent tool

Expose a taskflow tool with actions:

• taskflow(action="create", goal="...", controller="...", stateJson={...})
• taskflow(action="runTask", flowId="...", childSessionKey="...", task="...")
• taskflow(action="setWaiting", flowId="...", currentStep="...", waitJson={...})
• taskflow(action="resume", flowId="...", currentStep="...")
• taskflow(action="finish", flowId="...")
• taskflow(action="fail", flowId="...", reason="...")
• taskflow(action="get", flowId="...") — get flow details with stateJson
• taskflow(action="list", status="active") — list flows with filters

Option C: Enhance sessions_spawn

Add a --flow-id parameter to sessions_spawn to link the child task to an existing managed flow instead of creating a new mirrored flow.

sessions_spawn --flow-id <flow-id> --task "..." --role engineer

Impact

• Without this: Agents must use file-based state management (state.json) for multi-phase orchestration, losing TaskFlow's persistence, revision tracking, and structured lifecycle management
• With this: Agents can leverage TaskFlow's managed mode for robust, persistent multi-step workflows that survive gateway restarts

Current Workaround

Use state.json files + sessions_spawn for orchestration. Works but lacks:

• Atomic state updates
• Revision-based conflict detection
• Structured flow lifecycle (wait/resume/finish)
• Unified view of multi-phase progress

Context

• OpenClaw version: 2026.5.26
• Use case: AI agent task orchestration system with DAG-based multi-phase workflows
• Related skills: taskflow, taskflow-inbox-triage