Skip to main content

​
Permissions

Permissions control whether a tool call can run immediately, must be denied, or must wait for approval.

​
Modes

The runtime exposes five global permission modes:
  • default
  • acceptEdits
  • bypassPermissions
  • plan
  • dontAsk
These modes change the approval behavior for sensitive operations without rewriting tool or agent logic. The JSON and runtime identifiers use the forms shown above. The CLI exposes the same modes with kebab-case flags such as accept-edits, bypass-permissions, and dont-ask. bypassPermissions converts approval prompts into allows but still preserves explicit deny rules. acceptEdits auto-allows edit approvals for write_file and edit_file, but also preserves explicit deny rules.

​
Rule scopes

Permission rules can be owned at three scopes:
  • user
  • project
  • session
This lets operators apply broad defaults while still narrowing or relaxing behavior for a specific deployment or session.

​
Approval behavior

When a tool call requires approval:
  1. the run pauses
  2. an approval request is persisted
  3. the caller or another client resolves the request
  4. the original run resumes with the approved or denied outcome

​
Auditability

Permission decisions are written into the session record stream as audit data. This gives operators a durable account of how a sensitive tool call was evaluated and resolved.

​
Hooks and permissions

Hooks can update permissions dynamically. This is powerful, but it should be treated as part of the operational security model rather than as a convenience feature.

​
Playbooks and flows

Playbooks and Flows do not bypass permissions. A Flow starts a normal session run, so tool calls still use the active permission mode, permission rules, approvals, hooks, and session credential boundary. Sidechain children cannot widen the parent session permission mode. If a parent is in default, the child cannot request acceptEdits or bypassPermissions; if a parent is in plan, the child remains in plan. Omitted child modes are pinned to the parent’s effective mode at spawn time, and session-scoped permission updates are copied to the child session.

​
Evidence Note

  • Code verified: crates/kheish-runtime/src/permissions.rs, crates/kheish-daemon/src/state/subagent_spawn.rs, crates/kheish-daemon/src/state/session_state.rs, crates/kheish-daemon/src/control_tools.rs.
  • CLI/API verified: sidechain permission-mode fields checked against SpawnSidechainRequest and spawn_agent descriptor.
  • Daemon live tested for this note: no; deterministic daemon tests cover mode widening rejection, explicit default pinning, stale reuse reset, and parent session permission update inheritance.
  • Provider-specific tested for this note: no; permission evaluation and sidechain spawn validation are daemon-local.