Agent Orchestration

Let agents operate Craig without surrendering the control plane.

Agent orchestration is an experimental workspace-local preview. Its commands and state formats may change.

Enable it in .craig/config.json:

{
  "previews": {
    "agentOrchestration": true
  }
}

What the preview adds

  • A durable workspace event journal and event-backed agent waits.
  • Idempotent prompt delivery to a specific task and agent tab.
  • Capability-scoped child-task delegation with bounded depth and concurrency.
  • Fury: versioned YAML DAGs with explicit completion and human-review checkpoints.

Agent status and durable prompts

craig agent list --json
craig agent status --task <task-id> --json
craig agent send --task <task-id> --prompt "Review the latest CI failure" --json
craig task wait <task-id> --state ready,error --timeout 10m --json

Agent listing, status, and task waits work without the preview. Durable prompt creation through agent send requires it.

Prompt delivery defaults to when-ready. Use --delivery immediate only when the new prompt should interrupt a busy target. A delivered command means the live PTY accepted the input; it does not claim that the agent understood or completed the request.

Delegation and capabilities

Preview-enabled agent PTYs receive an opaque, workspace-local capability scoped to their own task. The capability limits allowed command families, expiry, child count, depth, concurrency, and prompt size. Agents cannot approve human-review checkpoints. After enabling the preview, create or restart an agent tab so its PTY receives a capability. 

craig task create-child --parent <task-id> --runner codex "Investigate the failing test" --json
craig task children <task-id> --json
craig task cancel-tree <task-id> --json

If no repository or workspace is supplied, the child inherits its parent's target. Disabling the preview stops new prompt and child creation. Agent status and waits remain available, as do prompt-command inspection, waiting, and cancellation plus task-lineage inspection and cancel-tree. Event queries and Fury operations require the preview.

Fury workflows

Fury definitions are strict, versioned YAML DAGs. Keeping them under .craig/fury/ is a useful convention, but Craig accepts a definition file from any path. Planning resolves inputs and persists an immutable content-hashed plan. A human must approve that exact plan before it can run. 

version: 1
name: inspect-and-review
limits: { max_concurrency: 2, max_tasks: 4, timeout: 2h }
inputs:
  task_id: { type: string, required: true }
steps:
  inspect:
    task: "${{ inputs.task_id }}"
    prompt: Inspect the task and submit structured findings.
    output:
      schema: { type: object, required: [findings] }
  review:
    needs: [inspect]
    human_review:
      title: Review findings
      summary: Review the findings before execution continues.
      feedback_target: { task: "${{ steps.inspect.task_id }}" }
      timeout: 1h
craig fury validate .craig/fury/inspect-and-review.yaml --json
craig fury plan .craig/fury/inspect-and-review.yaml --root-task <task-id> --input task_id=<task-id> --json
craig fury approve <plan-id> --json
craig fury run <plan-id> --json
craig fury watch <run-id> --format jsonl

Every agent step must explicitly report completion or failure. Terminal silence is never success. Declared outputs are JSON-schema validated before dependents run, and human-review steps remain blocked until a human approves, rejects, or requests changes.

Events and recovery

craig events watch --task <task-id> --format jsonl
craig command list --task <task-id> --json
craig fury status <run-id> --json
craig fury resume <run-id> --json

The workspace daemon reconciles interrupted prompt dispatch, deadlines, missing sessions, pending reviews, and unfinished Fury runs. All orchestration state remains local to the Craig workspace.

Workspace attachment

An interactive Craig launched from inside an agent session will not implicitly attach to that agent's live workspace. Pass --workspace-root <live-root> to confirm the attachment. A client also refuses to replace a live PTY daemon with an incompatible protocol; exit the other Craig instance before restarting it.

See the CLI reference for the command families available to humans and agents.