Approval Workflows

Pencel includes multiple approval mechanisms so you stay in control of what your agents do. Each mechanism works at a different level — from entire workflow runs down to individual tool calls. This page explains all four and helps you choose the right level of oversight for your use case.

The four approval layers

Layer	Scope	Setting	What happens
Workflow-level	Entire run	approvalRequired on the workflow	Run will not start until you approve it
Step-level	Single step within a run	approval step type in the workflow	Run pauses mid-execution for your review
Agent-level	Agent's execution plan	planApproval on the agent	Agent shows its plan before executing any steps
Connection-level	Individual tool call	Auto-approve toggle per tool	Agent pauses before using a specific integration tool

These layers are independent. You can use any combination of them. A single run might require workflow approval to start, show the agent's plan for review, pause at a step-level approval gate, and ask permission before calling an external tool.

Workflow-level approval

What it does: When approvalRequired is turned on for a workflow, the run will not begin until you explicitly approve it. This is the broadest gate — it controls whether the entire workflow kicks off.

When to use it:

• Workflows that run on a schedule and you want to review before each execution
• High-stakes workflows where you want to confirm the timing and context before the agent starts
• Workflows triggered by hooks or events where you want a human checkpoint

How it works in the UI:

1. The run appears on the Jobs page (/jobs) with a "Pending Approval" status.
2. You see a summary of the workflow, the assigned agent, and the trigger context.
3. Click Approve to start the run or Reject to cancel it.

TIP

Use workflow-level approval for workflows you have not fully tested yet. Once you are confident the workflow works correctly, you can turn off approvalRequired to let it run automatically.

Step-level approval

What it does: You can add an approval step anywhere in a workflow. When the run reaches that step, it pauses and waits for your review before continuing.

When to use it:

• Before a step that sends external communications (emails, Slack messages)
• After a data-gathering phase, so you can review findings before the agent acts on them
• Before any irreversible action (deleting records, publishing content)

How it works in the UI:

1. The run progresses normally until it hits the approval step.
2. The Jobs page shows the step as "Awaiting Approval" with the agent's work so far.
3. You review the output from previous steps and decide whether to continue.
4. Click Approve to proceed or Reject to stop the run.

Example workflow with an approval gate:

Step 1: Search the workspace for all overdue invoices.
Step 2: Create a summary table of overdue accounts.
Step 3: [Approval] Review the summary before proceeding.
Step 4: Draft follow-up emails for each overdue account.
Step 5: [Approval] Review the draft emails before sending.
Step 6: Send the emails via the email integration.

INFO

You can place multiple approval steps in a single workflow. This gives you checkpoints at each critical transition — for example, after data gathering, after drafting, and before sending.

Agent-level plan approval

What it does: When an agent's planApproval is set to require_approval, the agent generates a step-by-step plan and shows it to you before executing anything.

When to use it:

• For agents that handle varied, open-ended tasks where the approach matters
• When you want to verify the agent's reasoning before it starts working
• For new agents you are still calibrating

How it works in the UI:

1. You start a run or send a chat message in action mode.
2. The agent creates a plan listing the steps it intends to take.
3. The plan appears on the Jobs page or in the chat panel.
4. You review the plan and click Approve to let the agent proceed or Reject to stop and give different instructions.

What the plan looks like:

Plan:
1. Search workspace for Q1 sales data
2. Extract revenue figures by region
3. Calculate quarter-over-quarter growth rates
4. Create a summary table
5. Write an executive overview (3-5 bullet points)
6. Save as artifact "Q1 Sales Summary"

Awaiting your approval to proceed.

WARNING

Plan approval adds one extra API call (to generate the plan) before the actual work begins. This is a small cost increase, but it gives you visibility into the agent's intended approach before any actions are taken.

Connection-level tool approval

What it does: Each tool exposed by a connection can be set to auto-approve or require manual approval. When manual approval is on, the agent pauses every time it wants to use that tool.

When to use it:

• For write operations on external systems (creating records, sending messages, modifying files)
• For tools you have not tested thoroughly yet
• For any tool that costs money or has rate limits

How it works in the UI:

1. The agent decides it needs to use a tool from a connection.
2. If the tool requires approval, the run pauses.
3. You see the tool name, the parameters the agent wants to pass, and a preview of what will happen.
4. Click Approve to let the tool run or Reject to skip it.

Example approval prompt:

Tool: github_create_issue
Connection: GitHub — Engineering Repo
Parameters:
  - title: "Fix login timeout on mobile"
  - body: "Users report session expiring after 5 minutes..."
  - labels: ["bug", "mobile"]

Approve this action?

TIP

Auto-approve read-only tools (search, list, get) early on. Keep manual approval for write tools (create, update, delete) until you have seen them work correctly several times. See the Trust & Permissions guide for a graduated approach.

Choosing the right level of oversight

Here are common scenarios and the recommended approval configuration for each.

Scenario	Workflow approval	Step approval	Plan approval	Tool approval
New agent, first run	On	Add at key transitions	Required	All manual
Internal report, tested workflow	Off	Not needed	Auto	Auto for read tools
Customer email campaign	On	Before each send step	Required	All manual
Scheduled daily summary	Off	Not needed	Auto	Auto for read tools
Data migration or bulk update	On	Before destructive steps	Required	All manual
Research and brainstorming	Off	Not needed	Auto	Auto for all tools

How approvals appear in the UI

All approval requests appear on the Jobs page (/jobs). When a run is waiting for approval:

1. The run status changes to Awaiting Approval (highlighted so you notice it).
2. The step detail shows you what the agent has done so far and what it wants to do next.
3. You have two buttons: Approve (continue) and Reject (stop).

If you reject:

• Workflow-level: The run is cancelled. Nothing executes.
• Step-level: The run stops at that step. Previous steps' output is preserved.
• Plan-level: The agent does not execute. You can give new instructions and try again.
• Tool-level: The specific tool call is skipped. The agent continues and may try an alternative approach.

INFO

You will not miss an approval request. Pending approvals remain on the Jobs page until you act on them. The agent does not time out — it waits as long as needed.

Reducing approval fatigue

If you find yourself approving the same action repeatedly, that is a signal to adjust your settings:

• Auto-approve tools you always approve. If you have approved "search_workspace" 50 times, auto-approve it.
• Remove step-level approvals from mature workflows. Once a workflow runs reliably, the mid-run checkpoints add friction without adding safety.
• Switch from plan approval to auto-approve for trusted agents. After an agent consistently produces good plans, let it proceed without waiting.

The goal is not to eliminate all approvals — it is to focus your attention on the decisions that actually need human judgment.