Permission policies control whether the Agent needs human approval before performing a tool action, letting 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:
| Policy | Behavior | Best for |
|---|
allow | The Agent runs the action without confirmation | Low-risk operations (reading files, viewing status) |
ask | The Agent pauses and waits for human approval | High-risk operations (deleting files, network requests) |
deny | The Agent cannot perform the action | Forbidden operations (production deployments, sensitive data) |
Configuration
Configure tools by using the agent_toolset_20260401 object and enabling specific tools in the enabled_tools array (the 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 to the new schema is still being verified. The Pending Action flow described in this section still applies, but the exact configuration method may change.
curl -X POST https://api.qoder.com.cn/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 set to ask:
- The Agent emits a Pending Action event.
- The Session moves to idle (awaiting human input).
- The client receives a pending-action notification over SSE.
- Approval is given via the Turn Resolve API.
- The Agent continues execution.
Turn Resolve API
POST https://api.qoder.com.cn/api/v1/cloud/sessions/{session_id}/turns/{turn_id}/resolve
{
"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.cn/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"]
}
]
}'
curl -X POST https://api.qoder.com.cn/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.cn/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.cn/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
| Scenario | Suggested configuration |
|---|
| Internal development | All allow for maximum efficiency |
| Production operations | bash ask, text_editor allow |
| Demos or evaluation | All ask for full control |
| Read-only analysis | bash 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. 
