Pending Action Lifecycle: From Pause to Resume

When a task on a hosted gateway encounters a command that requires approval, a pending action is created and the task pauses. This guide walks through the complete lifecycle of that pending action — from creation through final resolution.

Use this page when

• You need to understand the lifecycle states of a pending gateway action (queued → approved/denied → executed/expired).
• You are monitoring pending actions and want to set up expiration or auto-deny policies.
• You are troubleshooting why an action was not executed after approval.

Primary audience

• Primary: Technical Engineers
• Secondary: AI Agents, Technical Leaders

Lifecycle States

A pending action moves through these states:

pending → approved → consumed    (happy path)
pending → denied                  (user stops the command)
pending → expired                 (timeout reached without decision)
pending → cancelled               (task cancelled before decision)

Each transition is atomic, auditable, and irreversible.

State Diagram

┌─────────┐
│ pending │
└────┬────┘
     │
     ├──── user approves ────→ ┌──────────┐ ── gateway executes ──→ ┌──────────┐
     │                         │ approved │                          │ consumed │
     │                         └──────────┘                          └──────────┘
     │
     ├──── user denies ──────→ ┌────────┐
     │                         │ denied │
     │                         └────────┘
     │
     ├──── timeout elapsed ──→ ┌─────────┐
     │                         │ expired │
     │                         └─────────┘
     │
     └──── task cancelled ───→ ┌───────────┐
                               │ cancelled │
                               └───────────┘

Phase 1: Task Pauses

When the gateway classifies a command as requiring approval:

1. The gateway creates a pending action record with:

   • action_id — unique identifier
   • task_id — the owning task
   • gateway_id — the executing gateway
   • actor_user_id — who initiated the task
   • command_digest — cryptographic hash of the exact command
   • command_preview — human-readable command string
   • working_directory — where the command would execute
   • risk_level — destructive or critical
   • risk_reason — why the command received this classification
   • requested_scope — what the command affects
   • expires_at — when the approval window closes
   • status — set to pending

2. The task persists its continuation state — this is not held in memory. The continuation includes the task step index, local variables, and execution context needed to resume.

3. The task transitions to a paused state and releases its execution slot.

Continuation State Persistence

The continuation state is durably stored, not held in gateway process memory. This means:

• If the gateway restarts while a task is paused, the task can resume after approval
• Multiple tasks can be paused simultaneously without consuming execution resources
• The pending action record and continuation state survive infrastructure events

Phase 2: Chat Notification

Once the pending action exists:

1. The chat interface receives notification of the new pending action
2. An approval card renders in the conversation showing command preview, risk details, and controls
3. The chat client polls or subscribes for status updates on the pending action

Chat Polling

The chat client checks pending action status through the governance API. When the status transitions from pending to any terminal state, the approval card updates to reflect the outcome.

Phase 3a: Approval

When you click Approve in chat:

1. The API records the approval decision with your user identity and timestamp
2. The pending action transitions atomically from pending to approved
3. The gateway is notified of the status change
4. The gateway reloads the pending action and performs verification:
   • Verifies status is approved
   • Verifies command_digest matches the original command
   • Verifies gateway_id matches the current gateway
   • Verifies task_id matches the paused task
   • Verifies actor_user_id matches the approving user's authorization
   • Verifies expires_at has not passed
5. If all verifications pass, the gateway atomically marks the action as consumed
6. The command executes exactly once
7. The task reloads its continuation state and resumes with the command output

Verification Failure

If any verification fails at step 4, the command does not execute. This can happen if:

• The action expired between approval and execution
• The gateway ID does not match (action created on a different gateway)
• The command digest does not match (command was somehow altered)

In these cases, the action transitions to an error state and the task is notified.

Phase 3b: Denial

When you click Stop in chat:

1. The API records the denial with your user identity and timestamp
2. The pending action transitions atomically from pending to denied
3. The command never executes — there is no window between denial and potential execution
4. The task step is marked as stopped-by-user
5. The task reloads its continuation state and receives a denial result
6. The task can decide how to proceed (skip the step, try an alternative, or stop entirely)

Phase 3c: Expiry

When the approval window closes without a decision:

1. The API transitions the pending action from pending to expired
2. The behavior is identical to an explicit denial
3. The command never executes
4. The task step is notified of the expiry
5. The task can request the same command again (creating a new pending action with a new expiry)

Phase 3d: Cancellation

If the task is cancelled before a decision is made:

1. The pending action transitions from pending to cancelled
2. The approval card in chat updates to show the action was cancelled
3. No command executes
4. The task's continuation state is discarded

Audit Events

Each lifecycle transition emits a governance event:

Transition	Event Type	Key Fields
Created	task.action.pending	action_id, task_id, command_preview, risk_level
Approved	task.action.approved	action_id, approved_by, timestamp
Consumed	task.action.consumed	action_id, execution_duration, exit_code
Denied	task.action.denied	action_id, denied_by, timestamp
Expired	task.action.expired	action_id, expired_at
Cancelled	task.action.cancelled	action_id, cancelled_reason

These events provide a complete audit trail of every destructive action request and its outcome.

Gateway Restart Behavior

Because continuation state is persisted durably:

1. If a gateway restarts while a task is paused awaiting approval, the pending action remains in the API
2. When the gateway comes back online, it checks for approved actions that have not been consumed
3. If an approved action is found, the gateway reloads the continuation state and proceeds with verification and execution
4. If the action expired during the restart, the task is notified of the expiry

This ensures that infrastructure events do not cause approved commands to be lost or pending tasks to become orphaned.

Concurrent Pending Actions

A single task may have multiple pending actions simultaneously if it requested several commands in sequence before pausing. Each action is independent:

• Approving one does not approve others
• Denying one does not deny others
• Each has its own expiry timer
• Each must pass independent verification before execution

The task resumes one step at a time as each action is resolved.

Timing Guarantees

• Atomic transitions — status changes are atomic; there is no window where an action is in two states simultaneously
• Single execution — the consumed transition and command execution happen atomically; a command cannot execute twice
• No stale approvals — expiry is checked at verification time, not just at creation time
• Order preservation — if multiple actions are approved, they execute in the order the task originally requested them

For AI systems

• Canonical terms: Keeptrusts, pending action, lifecycle states, continuation state, task pause, task resume, approval verification, consumed, denied, expired, cancelled.
• Exact feature/config names: states (pending, approved, consumed, denied, expired, cancelled), action_id, command_digest, expires_at, continuation state persistence, approval_timeout_seconds.
• Best next pages: Destructive Action Approval, Shell Command Risk Classification, What Is Hosted Gateway Execution.

For engineers

• Lifecycle: pending → approved → consumed (happy path), pending → denied, pending → expired, pending → cancelled.
• Continuation state is durably stored (not in-process memory) — tasks survive gateway restarts while paused.
• Verification at execution time checks: status is approved, command_digest matches, gateway_id matches, task_id matches, action is not expired.
• Multiple pending actions from one task are independent: approving/denying one does not affect others.
• Atomic transitions guarantee single execution — a command cannot execute twice even under concurrent conditions.

For leaders

• The pending action system ensures destructive operations are never lost, orphaned, or executed without authorization — even during infrastructure events.
• Durable persistence means approved actions survive gateway restarts and infrastructure maintenance windows.
• Complete audit trail: every state transition records user identity, timestamp, and command details for compliance.
• Configurable expiry window prevents approvals from lingering indefinitely — stale approvals expire and require fresh review.

Next steps

• Destructive Action Approval — the approval UX in chat
• Shell Command Risk Classification — what triggers the pending action flow
• What Is Hosted Gateway Execution — task execution model overview