pause

NAME

pause - halt workflow execution until manually resumed

SYNOPSIS

state-name:
  tool: pause
  arguments:
    reason: <explanation>
    condition:              # optional
      tool: bash
      command: <check-command>

DESCRIPTION

The pause tool halts workflow execution, saving the current state for later resumption. This enables workflows that wait for external events, require human approval, or need to span multiple sessions.

Paused workflows are resumed with fs resume.

ARGUMENTS

Argument	Required	Default	Description
reason	Yes	-	Explanation shown to user (max 500 chars)
condition	No	-	Condition to check before resuming

Condition Format

condition:
  tool: bash
  command: <shell-command>

The condition command must exit 0 for resume to proceed.

EXIT CODES

Code	Meaning
-1	Pause requested (internal code)
1	Invalid arguments

OUTPUT

The pause tool captures metadata internally. External output capture is not supported.

EXAMPLES

Simple Pause

await-approval:
  tool: pause
  arguments:
    reason: "Waiting for deployment approval"
  next: deploy

With Condition

wait-for-build:
  tool: pause
  arguments:
    reason: "Waiting for CI build to complete"
    condition:
      tool: bash
      command: 'gh run list --workflow=ci.yml --limit=1 --json status --jq ".[0].status" | grep -q "completed"'
  next: deploy

Human-in-the-Loop

start-at: prepare-changes

states:
  prepare-changes:
    tool: claude
    arguments:
      prompt: "Generate migration scripts for schema changes"
    output: file(./migrations/pending.sql)
    next: await-review

  await-review:
    tool: pause
    arguments:
      reason: "Review pending migrations at ./migrations/pending.sql"
    next: apply-migrations

  apply-migrations:
    tool: bash
    arguments:
      command: psql -f ./migrations/pending.sql

Polling Pattern

start-at: start-job

states:
  start-job:
    tool: bash
    arguments:
      command: ./start-long-job.sh
    output: var(job_id)
    next: wait-for-job

  wait-for-job:
    tool: pause
    arguments:
      reason: "Waiting for job {{ job_id }} to complete"
      condition:
        tool: bash
        command: './check-job-status.sh "{{ job_id }}" | grep -q "complete"'
    next: process-results

Multi-Stage Approval

start-at: deploy-staging

states:
  deploy-staging:
    tool: bash
    arguments:
      command: ./deploy.sh staging
    next: staging-approval

  staging-approval:
    tool: pause
    arguments:
      reason: "Staging deployment complete. Approve for production?"
    next: deploy-production

  deploy-production:
    tool: bash
    arguments:
      command: ./deploy.sh production
    next: production-approval

  production-approval:
    tool: pause
    arguments:
      reason: "Production deployment complete. Verify and close."

RESUME BEHAVIOR

Without Condition

fs resume my-instance

Workflow continues immediately to the next state.

With Condition

fs resume my-instance

1. Execute condition command
2. If exit 0: continue to next state
3. If non-zero: remain paused

Force Resume

fs resume my-instance --force

Skip condition check, proceed directly to next state.

LISTING PAUSED INSTANCES

fs list --paused

Shows all paused instances with:

• Instance name
• Workflow name
• Current state
• Time paused
• Pause reason

METADATA

The pause stores metadata in context.json:

{
  "status": "Paused",
  "currentState": "await-approval",
  "pausedAt": "2024-01-15T10:30:00Z",
  "pauseReason": "Waiting for approval",
  "pauseCondition": "{\"tool\":\"bash\",\"command\":\"...\"}"
}

USE CASES

External Event Waiting

Wait for webhooks, CI completion, or external system state changes.

Human Approval Gates

Require manual sign-off before critical operations.

Resource Availability

Wait for cloud resources, database slots, or rate limits to reset.

Scheduled Continuation

Pause overnight, resume during business hours.

SEE ALSO

• ask-user - For immediate user input
• switch - For conditional flow without pausing