Code Agent Orchestration (OCA)

Code Agent Orchestration

Use openclaw-code-agent to run Claude Code, Codex, or experimental OpenCode sessions as background coding jobs from chat. Treat oca as the built-in short name for OpenClaw Code Agent when a user says phrases such as "let oca do ...", "ask oca to ...", or "have oca handle ...".

Launch

• Do not pass channel manually. Routing comes from agentChannels, the current chat context, and fallbackChannel.
• Sessions are multi-turn. Continue existing work with agent_respond or agent_launch(..., resume_session_id=...); do not start a fresh session for the same task.
• Always set a short kebab-case name when you care about later follow-up.
• Set workdir to the target repo.
• Use permission_mode: "plan" when the user wants a real review gate before implementation.
• Use permission_mode: "bypassPermissions" only for autonomous execution.
• Treat harness: "opencode" as experimental. Use it only when requested or configured and local opencode >= 1.16.2 has provider auth ready.
• defaultWorktreeStrategy defaults to delegate, so new sessions normally use branch isolation and orchestrator-led follow-through. Use worktree_strategy: "off" only when the task must run in the main checkout or outside a git repo.
• In plan mode, the plan belongs in normal session output. Do not ask the coding agent to write plan docs or transcript artifacts unless the user explicitly asked for a file.

Example:

agent_launch(
  prompt: "Fix the auth middleware bug and add tests",
  name: "fix-auth",
  workdir: "/home/user/projects/my-app"
)

Resume, Don't Respawn

When a session already exists for the task, keep using it.

• Waiting for plan approval: agent_respond(session, message, approve=true) or agent_request_plan_approval(...) if delegated approval must escalate to the user
• Waiting for a question answer: agent_respond(session, message)
• Killed/stopped by restart: agent_respond(session, message)
• Completed but needs follow-up: agent_launch(resume_session_id=session_id, prompt="...")
• Fresh agent_launch is only for genuinely independent work

Do not launch a new coding session from a wake event for the same task.

State and Monitoring

Use:

agent_sessions()
agent_output(session: "fix-auth", lines: 100)
agent_output(session: "fix-auth", full: true)

For worktree follow-through, inspect:

agent_worktree_status()
agent_worktree_status(session: "fix-auth")

For worktree cleanup and follow-through, use that tool's lifecycle, derived state, cleanup disposition, and retained reasons as the plugin state source. Avoid deciding cleanup safety from transcript summaries or branch names alone.

When wake payloads include these fields, use them as the plugin's recorded approval state:

• requestedPermissionMode
• effectivePermissionMode / currentPermissionMode
• approvalExecutionState

Use those deterministic fields for approval follow-through before consulting transcript fragments.

When OpenClaw exposes managed TaskFlow state for a session, use it as a high-level progress mirror of the plugin session. For operational follow-up, check agent_sessions, agent_output, and agent_worktree_status.

Approval/execution meanings:

• approved_then_implemented: normal approved execution
• implemented_without_required_approval: actual approval bypass
• awaiting_approval: still stopped at the approval gate
• not_plan_gated: no plan gate applied

Completion ownership:

• The plugin sends the canonical completion notification.
• The plugin owns the canonical completion status line; the orchestrator owns any additional plain-text follow-up.
• Completion wakes may arrive in a different chat than the session's original user route. Treat the wake's originRoute block as the source of truth for human follow-ups.
• If originRoute differs from the current chat, do not use a normal final assistant reply for the user-facing follow-up. Use a routed send path that preserves provider, target, and threadId instead.
• After a coding-agent session completes, the orchestrator should usually add at least a short human-useful summary of what changed, what was done, or the concrete outcome.
• That expectation applies to ordinary terminal/manual completions, manual no-change completions, and delegated worktree completions alike.
• Use the plugin's canonical ✅ line as the status signal and your follow-up as the factual outcome summary that should usually come right after it.
• That summary can be brief; one sentence is often enough.
• Extra synthesis, risk framing, and next-step guidance are optional. Add them when useful; do not force them every time.
• Do not generate your own heuristic completion summary from transcript tail lines. Base any summary on reliable result data such as agent_output(..., full=true), diff context, or deterministic tool state.
• Skip the summary only in narrow cases:
  • no user-facing follow-up will be sent at all because the orchestrator is silently continuing an internal multi-phase pipeline
  • the completion produced no meaningful outcome to report, or the reliable result data is still too incomplete to support even a short factual summary
  • the session is a silent cron/system pipeline that already returned NO_REPLY or otherwise explicitly opted out of a user-facing follow-up summary

Respond Rules

Auto-respond immediately only for:

• permission requests for file reads, writes, or shell commands
• explicit continuation prompts such as "Should I continue?"

Forward everything else to the user:

• architecture or design choices
• destructive operations
• scope changes
• credentials or production questions
• ambiguous requirements

When forwarding, quote the session's exact question. Do not add commentary.

Plan Approval

Use permission_mode: "plan" whenever the user wants a real planning checkpoint.

planApproval: "ask"

• Approval belongs to the user.
• The plugin sends the canonical Approve / Revise / Reject prompt directly to the user.
• Telegram and Discord buttons use the shared direct-message presentation path; if buttons are missing, plain-text Approve, Revise, or Reject in the same thread drives the same decision path.
• If the user requests changes, wait for the revised plan from that same session; the revised submission becomes the latest actionable review version automatically.
• If the user rejects the plan or the session is killed, treat older plan prompts as stale and verify state with agent_sessions before acting.
• Wait for the user's answer, then forward it with agent_respond(...).
• Do not send a duplicate approval recap or second approval prompt.

planApproval: "delegate"

• Approval belongs to the orchestrator first.
• This is wake-first: the plugin wakes the orchestrator without user buttons.
• Before deciding, read the full plan with agent_output(session, full=true); do not rely on the truncated preview.
• Approve directly with agent_respond(..., approve=true) only when the latest actionable plan version is clearly in-bounds and low risk.
• When approving directly, pass a structured rationale with approval_rationale, for example: agent_respond(session='...', message='Approved. Go ahead.', approve=true, approval_rationale='Scope matches the request and the changes are low risk.')
• After approving directly, send the user a short plain-text follow-up explaining what was approved and why. The plugin's 👍 Plan approved line is only a fallback signal, not the full explanation.
• If a prior version had changes_requested, that stale state should not block approval of the latest revised plan version.
• If escalation is needed, call agent_request_plan_approval(session='...', summary='...') exactly once so the plugin sends the single canonical user approval prompt.
• That escalation summary must concisely explain why you are escalating, plus risk/scope notes the user needs to decide.
• After that canonical prompt exists, wait for the user's decision; do not send a second plain-text approval summary.

planApproval: "approve"

• Auto-approve only after verification per the session policy.

Worktree Decisions

Use worktrees as temporary task sandboxes, not as generic branch inventory.

Lifecycle meanings:

• pending_decision: still waiting for merge / PR / dismiss follow-through
• pr_open: PR exists; preserve the sandbox
• merged: normal ancestry merge landed
• released: content already landed on the base branch even though SHAs differ after rebase, squash, or cherry-pick
• dismissed: sandbox intentionally discarded
• no_change: no committed delta

If agent_worktree_status reports released, the sandbox content is already landed. Do not narrate it as "still unmerged" just because the branch appears ahead.

off

• No worktree. The session runs in the main checkout.

ask

• The plugin owns the user-facing completion/decision message and button UI.
• Do not call agent_merge or agent_pr unless the user explicitly asks after that.
• A completed ask-session worktree may later resolve as released if its content already landed on base through another path. Confirm that with agent_worktree_status(...) before deciding what follow-up is still needed.

delegate

• The plugin wakes the orchestrator with diff context and no automatic user buttons.
• Read the diff context and decide whether a local merge is clearly safe.
• agent_merge is acceptable for low-risk, clearly scoped changes that match the task.
• Never call agent_pr() autonomously in delegate flows. Escalate PR decisions to the user.
• If a merge/PR outcome wake has completionWakeSummaryRequired=true, read agent_output(..., full=true) when available and send one short factual summary. Honor the wake's origin route block; if it differs from the current chat, use a routed send path that preserves provider, target, and thread/topic.
• If the wake already says the plugin sent the canonical completion notification, do not repeat that status line. The follow-up summary is orchestrator-owned and should add only the useful confirmed outcome.

manual

• Wait for an explicit user request before calling agent_merge or agent_pr.

Cleanup

• Use agent_worktree_cleanup(mode: "preview_safe") to review what Clean all safe would remove.
• Use agent_worktree_cleanup(mode: "clean_safe") only when the user asked to clean up safe sandboxes.
• Use agent_worktree_cleanup(mode: "preview_all") when you need both safe candidates and retained reasons.
• Use retained reasons from agent_worktree_status / agent_worktree_cleanup as lifecycle data, not advisory prose.

Never

• Never use raw git merge or raw PR commands in place of plugin tools.
• Never invent your own workaround for a pending worktree decision; use agent_worktree_cleanup(session: "...", dismiss_session: true) to dismiss permanently.
• Never use agent_worktree_cleanup to force-delete unresolved worktrees. The supported bulk action is "clean all safe": omit session and let the plugin remove only lifecycle-safe worktrees while preserving anything active, pending, dirty, or PR-open.
• Never merge or PR an ask worktree behind the user's back.

File Artifact Policy

• Do not ask the coding agent to write planning documents, investigation notes, or analysis artifacts as files unless the user explicitly requested a file.
• Do not commit planning documents, investigation notes, or transcript-summary artifacts to the branch.
• Commit only actual code, configuration, tests, and explicitly requested documentation.

Anti-Patterns

• Do not pass multi_turn or multi_turn_disabled; all sessions are multi-turn.
• Do not pass channel manually unless you are debugging routing.
• Do not auto-answer design or scope questions.
• Do not infer approval/completion ownership from old transcript snippets when deterministic fields are present.
• Do not post duplicate completion or approval recaps when the plugin already sent the canonical message.