Give your agent a task that survives longer than one turn

• Goal
• Workflow
• Subagent
• Agent Teams
• Kanban pipeline
• Background tasks
• Tool system
• Safety
• Approval

An ordinary Session fits a single conversational task. Reach for these higher-level orchestration tools only when you actually need a persistent goal, an isolated context, parallel phases, or a shared task.

When you need to reuse the same work definition long after this Session ends, use Bots instead. Agent Teams serve collaborative work inside the current Session; a Bot has its own revision, permissions, Memory, Routine, Run, and lifecycle.

Goal: manage a task across many turns#

Goal fits software engineering work that has to keep running across multiple turns. It keeps the objective, completion criteria, budget, and state outside the Session itself, so a long task doesn't depend on a single conversation window staying open.

Creating a Goal#

Create a draft directly from the right-hand Dock, define one interactively with /write-goal, or let the agent create one through the Goal tool. A valid Goal includes:

• An objective.
• Observable completion criteria.
• Optional token, turn, and wall-clock budgets.

Completion criteria should be verifiable through command results, file state, test counts, or other concrete evidence.

Lifecycle#

draft -> active
active <-> paused
active <-> blocked
active -> budget_limited
budget_limited --adjust--> active
active -> complete
active -> canceled

A Goal can be activated, paused, resumed, completed, or canceled. It only reaches complete once every completion criterion has been individually verified. budget_limited can't resume directly — you have to raise the budget and continue, which moves it back to active.

The completion action is protected by a single per-Goal execution lock. kxen persists the operation ID and the SHA-256 identity of the contract/evidence first, writes prepared before crossing the provider boundary, and persists the verdict and usage receipt in sequence before entering complete. A result already scored under the same identity gets reused instead of paid for again; a different identity gets rejected until you explicitly adjust.

If the app is interrupted mid-way through an already-prepared paid verdict, the semantic result is marked UNKNOWN, the Goal moves to blocked, and a later start won't automatically resend the same verdict request. You check the provider-side result and budget, then use adjust to acknowledge the risk before submitting new evidence or re-judging.

blocked has two paths: a terminal-class reason triggers it immediately; any other reason triggers it after the same blocking reason repeats for 3 turns. Hitting a budget cap uses budget_limited — it's never disguised as task completion.

Budget and attribution#

• Wall-clock time only accrues while active; paused time doesn't consume budget.
• A run freezes its bound Goal ID at start; switching focus mid-run doesn't attribute usage to a different Goal.
• Business turns increment turn. Auxiliary model calls like compaction and completion verification only count tokens — they don't add a business turn.
• Pausing or canceling stops further execution, but requests already in flight still settle their real usage once they return.
• If there's a finite token budget but the provider returns no measurable usage, the Goal fails closed to budget_limited, waiting for you to confirm or adjust.
• Completion verification, compaction, embedding, and other auxiliary calls establish a durable usage attempt before crossing the provider boundary. Observed usage settles exactly; a call that started but whose result can't be recovered is recorded as UNKNOWN — never treated as zero.

Where you see it#

The current Goal shows up in the right-hand Dock, the status bar, and the Workspaces board. Goal state comes from the persisted backend record, not from whether the current page happens to be open.

When to use it#

Goal answers "what should keep happening, and when does it count as done." When you need parallelism, branching, or loops, use Workflow inside the Goal.

Subagent: isolate a single independent task#

Subagent is an independent execution unit dispatched by the current agent. It gets its own context window, and returns a conclusion or result to whoever called it once it's done.

Roles#

kxen uses roles to decide prompt, model routing, tool permissions, and the maximum number of execution turns. Common roles include thinking, planning, execution, review, and research.

• thinking and planning focus on analysis and approach.
• execution can implement and verify.
• review focuses on checking changes and evidence.
• research focuses on gathering material and code facts.

A role name doesn't directly grant permissions — the actual available tools come from the matching permission profile, and Safety always keeps the final say.

What's isolated#

A Subagent is separated from the main agent across:

• Conversation context.
• Tool call history.
• Token usage.
• Run turn count.
• Model routing result.

When you need filesystem isolation too, bind an independent Worktree. Without one, multiple write-capable Subagents can still operate on the same working directory.

Returning a result#

A Subagent returns a structured result on completion. The main agent decides how to merge, verify, or continue from it — it shouldn't treat several Subagents' unverified conclusions as final completion evidence on its own.

When to use it#

Hand off subtasks with clean boundaries that can complete independently to a Subagent. For sustained collaboration, messages between members, and shared tasks, use Agent Teams instead.

Workflow: orchestrate parallel steps and branches#

Workflow composes multiple agent calls into an executable process. It fits tasks where steps depend on each other, run in parallel, or pass intermediate results along.

How it runs#

The model generates JavaScript, and kxen executes it inside a QuickJS sandbox. Workflow describes execution relationships with controlled primitives and a read-only constraints snapshot:

• agent()
• parallel()
• phase()
• log()
• CONSTRAINTS

Workflow JavaScript can't reach the host filesystem or make arbitrary network calls directly — actual changes still happen through the dispatched agent's own tools and permissions.

What it can express#

• Multiple independent agents running in parallel.
• Sequential dependencies expressed through ordinary JavaScript await.
• Phases with verification requirements.
• Branching based on intermediate results.
• Bounded loops and retries.
• A final integration and verification phase.

Resource boundaries#

The sandbox limits memory, stack, total runtime, and agent call count. Every model call still goes through MRM, and is still bound by provider concurrency and account RPM limits.

When you cancel a Workflow, both the running and still-waiting agent calls receive the cancellation signal. Workflow can't use parallelism to route around Safety, Approval, or role permissions.

When to use it#

Use Workflow when the steps and dependencies are fixed and clear. Use Subagent when you only need one independent context, and Agent Teams when members need sustained collaboration and shared tasks.