Inputs

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.

Field	Meaning
`request_id`	Stable id for the pending approval. Use it in the resolve URL.
`kind`	The category of request, such as `tool_use`.
`tool`	Tool or action the harness wants to run, when available.
`message`	Human-readable approval prompt.
`options`	Allowed decisions for this request.

Resolve it

PUT /v1/sessions/{session_id}/inputs/{request_id} On the agent route family, the same operation is: PUT /{org}/{agent}/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. Verification signal: session.pending_input is null. If you chose deny, the continuation includes a terminal done event whose data marks the request as denied.

Decisions

Decision	Effect
`approve_once`	Allow this one action; prompt again next time.
`approve_session`	Allow this and similar actions for the rest of the session.
`deny`	Refuse 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(...).

Symptom	Likely cause	Fix
`404`	The session id is not visible to the caller.	Check the session id and API-key scope.
`422`	The request body is not valid JSON for the endpoint.	Send `{"decision":"approve_once"}`, `{"decision":"approve_session"}`, or `{"decision":"deny"}`.
Turn does not continue	The `request_id` does not match the current pending input.	Re-fetch the session and resolve the active `pending_input.request_id`.

Overview

Sessions

Consumer adapters

The input_required event

Resolve it

Response `200`

Decisions

Default behavior

​The input_required event

​Resolve it

​Response 200

​Decisions

​Default behavior

The input_required event

Resolve it

Response `200`

Decisions

Default behavior