Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.karta.sh/llms.txt

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

When the harness needs permission to act — run a tool, write a file — it emits an input_required event and the turn pauses. You resolve it with a decision, and the turn resumes.

​
The input_required event

event: input_required
data: {"type":"input_required","session_id":"sess_9f3a…","data":{
  "request_id":"req_7c1…","kind":"tool_use","tool":"write_file",
  "message":"Allow writing orders.csv?","options":["approve_once","approve_session","deny"]
}}
The session also records this as pending_input until resolved.

​
Resolve it

PUT /v1/sessions/{session_id}/inputs/{request_id}
​
decision
string
required
One of approve_once, approve_session, or deny.
curl -X PUT https://api.karta.sh/v1/sessions/$SID/inputs/req_7c1… \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision": "approve_once"}'

​
Response 200

{
  "events": [ { "type": "text", "data": { /* … */ } }, { "type": "done", "data": { /* … */ } } ],
  "session": { "id": "sess_9f3a…", "pending_input": null, "...": "…" }
}
The events array carries the turn’s continuation after your decision; the session reflects the cleared pending_input.

​
Decisions

DecisionEffect
approve_onceAllow this one action; prompt again next time.
approve_sessionAllow this and similar actions for the rest of the session.
denyRefuse the action; the agent continues without it.

​
Default behavior

How aggressively a turn prompts is governed by the session’s permission_mode and the input_required_policy config — an autonomous runtime maps to approve_session, while interactive prompts. In the SDK, resolve and continue streaming with session.stream_pending_input(...).