Approving Destructive Actions in Chat

When a task on a hosted gateway encounters a destructive or critical shell command, execution pauses and an approval card appears in your chat interface. You review the command details and explicitly approve or deny execution before anything happens.

Use this page when

• You need to understand how destructive actions (file deletes, force pushes, drop commands) are intercepted and sent to approval queues.
• You are configuring approval workflows for high-risk shell commands executed through the hosted gateway.
• You want to review, approve, or deny a pending destructive action in the console.

Primary audience

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

The Approval Flow

Task requests command execution
  → Gateway classifies command as destructive/critical
    → Gateway creates pending action
      → Task pauses and persists continuation state
        → Approval card appears in chat
          → You review command preview and risk details
            → Approve: command executes exactly once
            → Deny: command never executes, task step stops

What You See in Chat

When a destructive command needs your approval, an approval card appears with:

Field	Description
Command preview	The exact command that will execute
Working directory	Where the command will run on the gateway host
Risk level	destructive or critical
Risk reason	Why the command received this classification
Requested scope	What the command will affect
Task context	Which task and agent requested execution
Controls	Approve and Stop buttons

Example Approval Card

┌─────────────────────────────────────────────────┐
│ ⚠️  Destructive Command Requires Approval        │
│                                                   │
│ Command:  rm -rf ./build/output                   │
│ Directory: /srv/projects/my-app                   │
│ Risk:     destructive                             │
│ Reason:   Recursive file deletion                 │
│ Scope:    ./build/output (within allowed root)    │
│ Task:     build-cleanup (agent: ci-assistant)     │
│                                                   │
│ [Approve]  [Stop]                                 │
└─────────────────────────────────────────────────┘

Approving a Command

When you click Approve:

1. The approval is recorded with your user identity and timestamp
2. The gateway verifies the approval is valid (not expired, correct command digest)
3. The command executes exactly once on the gateway host
4. The pending action transitions to consumed status
5. The task receives the command output and continues
6. An audit event records the approval and execution

The approval is single-use. Once the command executes, the approval cannot be reused — even for an identical command in a subsequent task step.

Denying a Command

When you click Stop:

1. The denial is recorded with your user identity and timestamp
2. The command never executes
3. The pending action transitions to denied status
4. The task step is marked as stopped-by-user
5. The task receives a denial response and can decide how to proceed
6. An audit event records the denial

Approval Properties

Every approval carries these security properties:

Single-Use

Each approval authorizes exactly one execution. After the command runs, the approval is consumed and cannot be reused. A task that needs to run the same command again must request a new approval.

Time-Limited

Approvals expire after a configurable timeout (default: 5 minutes). If you do not respond within the timeout, the pending action transitions to expired and the command does not execute. The task receives an expiry notification.

Scoped to Exact Command

The approval is bound to the cryptographic digest of the exact command string. If the command changes in any way — different arguments, different flags, different target path — the existing approval is invalid. The task must request a new approval for the modified command.

Scoped to Context

The approval is bound to:

• Command digest — the exact command that will run
• Gateway ID — the specific hosted gateway
• Task ID — the specific task execution
• User ID — the user who granted approval
• Expiry timestamp — when the approval becomes invalid

A command approved on one gateway cannot execute on a different gateway. A command approved for one task cannot be reused by a different task.

Audit-Logged

Every approval decision (approve, deny, expire) produces a governance event that includes:

• Who made the decision
• What command was approved or denied
• The risk level and classification reason
• The timestamp and expiry
• Whether the command subsequently executed successfully

Modified Commands Cannot Reuse Approvals

If a task modifies a command after requesting approval — even slightly — the original approval is invalid. This prevents:

• Time-of-check to time-of-use (TOCTOU) attacks
• Command injection through approval reuse
• Unintended execution of altered commands

The gateway verifies the command digest at execution time, not just at approval time.

Multiple Pending Approvals

A task may have multiple pending approvals at once if it requests several destructive commands in sequence. Each approval card appears independently in chat, and each must be reviewed individually. Approving one command does not approve others.

Approval Timeout Behavior

When an approval expires:

• The pending action transitions to expired
• The behavior is identical to an explicit denial
• The command never executes
• The task step is notified of the expiry
• An audit event records the timeout

You can configure the timeout duration in your gateway configuration:

hosted_gateway:
  shell:
    approval_timeout_seconds: 300  # 5 minutes (default)

What You Should Check Before Approving

Before clicking Approve, verify:

1. The command is expected — does this command make sense for what the task is doing?
2. The scope is appropriate — is the working directory and target path correct?
3. The risk is acceptable — are you comfortable with the potential impact?
4. The task context is right — is this the correct task and agent requesting execution?

If anything looks unexpected, click Stop and investigate. Denied commands can always be re-requested if they turn out to be legitimate.

Security Notes

• The approval card shows the command preview and risk metadata only — never full command output or environment variables
• Approval decisions are attributed to your user identity in the audit log
• You cannot approve commands on behalf of another user
• The gateway enforces approval requirements regardless of the agent's instructions — an agent cannot bypass the approval flow
• Critical commands always require approval, even if you remove critical from approval_required_risk_levels

For AI systems

• Canonical terms: Keeptrusts, destructive action approval, approval card, pending action, single-use approval, command digest, hosted gateway, risk classification.
• Exact feature/config names: hosted_gateway.shell.approval_required_risk_levels, approval_timeout_seconds, approval states (pending, approved, consumed, denied, expired), command_digest field.
• Best next pages: Pending Action Lifecycle, Shell Command Risk Classification, Shell Allow and Deny Lists.

For engineers

• Approval cards appear in chat when a task encounters a destructive/critical classified command — review command preview, working directory, risk level, and task context before deciding.
• Approvals are single-use, time-limited (default 5 minutes), and scoped to the exact command digest + gateway + task + user.
• Click Approve for legitimate commands; click Stop if anything looks unexpected — denied commands can be re-requested.
• Configure timeout via hosted_gateway.shell.approval_timeout_seconds in gateway YAML.
• Critical commands always require approval regardless of approval_required_risk_levels configuration.

For leaders

• The approval flow ensures no destructive automated operation executes without explicit human authorization — agents cannot bypass it.
• Every approval/denial is attributed to a specific user identity and recorded in the governance audit log for compliance.
• Single-use + time-limited + command-digest-scoped design prevents approval reuse, replay attacks, and stale authorizations.
• Tune approval_timeout_seconds to match your team's response cadence — too short risks expiry; too long holds tasks unnecessarily.

Next steps

• Pending Action Lifecycle — full lifecycle from pause through resolution
• Shell Command Risk Classification — how commands get classified as destructive/critical
• Shell Allow and Deny Lists — control which commands reach the approval flow