Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

Permission policies control whether the Agent needs human approval before performing a tool action. This is the foundation of human-in-the-loop control — it lets you balance Agent autonomy with human oversight.

​
Three Policies

When the Agent attempts to invoke a tool, the runtime checks the tool’s permission value:
PolicyBehaviorBest for
allowThe Agent runs the action without confirmationLow-risk operations (reading files, viewing status)
askThe Agent pauses and waits for human approvalHigh-risk operations (deleting files, network requests)
denyThe Agent cannot perform the actionForbidden operations (production deployments, sensitive data)

​
Configuration

Set the permission field on each tool object inside the tools array: 
{
  "tools": [
    {"type": "bash_20250124", "permission": "allow"},
    {"type": "text_editor_20250124", "permission": "allow"},
    {"type": "computer_20250124", "permission": "ask"}
  ]
}
Specify when creating the Agent: 
curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cautious-agent",
    "model": "qoder-best",
    "instructions": "Execute tasks cautiously",
    "tools": [
      {"type": "bash_20250124", "permission": "ask"},
      {"type": "text_editor_20250124", "permission": "allow"},
      {"type": "computer_20250124", "permission": "deny"}
    ]
  }'

​
Pending Action Mechanism

When the Agent triggers a tool with ask:
  1. The Agent emits a Pending Action event.
  2. The Session moves to idle (awaiting human input).
  3. The client receives a pending-action notification over SSE.
  4. Approval is given via the Turn Resolve API.
  5. The Agent continues execution.

​
Turn Resolve API

POST https://openapi.qoder.sh/api/v1/cloud/sessions/{session_id}/turns/{turn_id}/resolve
Request body to approve: 
{
  "action": "approve"
}
Or to deny: 
{
  "action": "deny",
  "reason": "This operation is outside the scope of the current task."
}

​
End-to-End Example

​
1. Create an Agent with the ask Policy

curl -X POST https://openapi.qoder.sh/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "safe-dev",
    "model": "qoder-best",
    "instructions": "Development assistant",
    "tools": [
      {"type": "bash_20250124", "permission": "ask"},
      {"type": "text_editor_20250124", "permission": "allow"}
    ]
  }'

​
2. Send a Task that Triggers a Tool Call

curl -X POST https://openapi.qoder.sh/api/v1/cloud/sessions/ses_abc123/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": "Delete every log file under /tmp."}
    ]
  }'

​
3. Listen on SSE and Receive a Pending Action

id: evt_02xyz
event: agent.message
data: {"content":"I need to run rm /tmp/*.log. Please confirm.","pending_action":{"turn_id":"turn_01","tool":"bash","command":"rm /tmp/*.log"}}

​
4. Approve the Action

curl -X POST https://openapi.qoder.sh/api/v1/cloud/sessions/ses_abc123/turns/turn_01/resolve \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve"}'

​
5. Or Deny It

curl -X POST https://openapi.qoder.sh/api/v1/cloud/sessions/ses_abc123/turns/turn_01/resolve \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"action": "deny", "reason": "Only delete logs older than 7 days."}'
When you deny, include a reason. The Agent uses the reason to adjust its plan and try again.

​
Policy Recommendations

ScenarioSuggested configuration
Internal developmentAll allow for maximum efficiency
Production operationsbash ask, text_editor allow
Demos or evaluationAll ask for full control
Read-only analysisbash deny, text_editor deny

​
FAQ

Q: What’s the default if I don’t set permission? A: The default is allow — the Agent executes directly. Q: Do pending actions time out? A: Yes — they follow the Session’s idle timeout. After it elapses, the Session may be reclaimed. Q: Can a single turn have multiple pending actions? A: Currently each turn has at most one pending action. The Agent requests confirmation step by step. Q: Can ask be applied dynamically based on command content? A: Today the policy applies per tool type. Finer-grained rules (such as command-pattern matching) are planned.