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

Tool configuration uses the single object agent_toolset_20260401, selectively enabling atomic tools via the enabled_tools array (the old per-tool-object schema is deprecated): 
{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit"]
    }
  ]
}
How the permission field (allow / ask / deny) maps onto the new schema is pending further verification. The Pending Action flow described in this section still applies, but the precise configuration method may be adjusted.
Specify when creating the Agent: 
curl -X POST https://api.qoder.com/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "cautious-agent",
    "model": "ultimate",
    "instructions": "Execute tasks cautiously",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit"]
      }
    ]
  }'

​
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://api.qoder.com/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://api.qoder.com/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "safe-dev",
    "model": "ultimate",
    "instructions": "Development assistant",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit"]
      }
    ]
  }'

​
2. Send a Task that Triggers a Tool Call

curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": [{"type": "text", "text": "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://api.qoder.com/api/v1/cloud/sessions/sess_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://api.qoder.com/api/v1/cloud/sessions/sess_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.