# Handle approvals, questions, and forms

Keep user decisions explicit and preserve the exact options offered by the running agent.

An agent may pause for permission, ask a question, or request structured input. These are typed interaction records. Do not infer permission from a conversational message.

## Observe and answer

Wait for input. Show the pending interaction to an authorized user. Show every offered permission option. Show the question or supported form schema as appropriate. Call the relevant function below only after that user supplies a response.

### Python

```python
from wkala import InputRequired

try:
    result = await run.wait(timeout=120)
except InputRequired as required:
    for interaction in required.interactions:
        print(interaction.id, interaction.kind, interaction.prompt)
        print(interaction.permission_options, interaction.form_schema)
```

```python
async def choose_option(interaction, option_id):
    if not any(option.id == option_id for option in interaction.permission_options):
        raise ValueError("That option was not offered")
    return await agents.interactions.respond(
        interaction.id,
        option_id=option_id,
    )


async def answer_question(interaction, answer):
    return await agents.interactions.respond(interaction.id, message=answer)


async def submit_form(interaction, data):
    return await agents.interactions.respond(interaction.id, data=data)
```

Python also provides `run.reply()` for questions and `run.respond()` for forms. `run.approve()` selects the unique offered allow-once choice, not a remembered permission. Supply `interaction_id=` when more than one interaction matches.


### TypeScript

```typescript
import { InputRequired } from "@wkala/client"

try {
  const result = await run.wait({ timeout: 120 })
} catch (error) {
  if (!(error instanceof InputRequired)) {
    throw error
  }

  for (const interaction of error.interactions) {
    console.log(interaction.id, interaction.kind, interaction.prompt)
    console.log(interaction.permission_options, interaction.schema)
  }
}
```

```typescript
import type { Interaction, JSONObject } from "@wkala/client"

async function chooseOption(interaction: Interaction, optionId: string) {
  if (!interaction.permission_options.some(option => option.id === optionId)) {
    throw new Error("That option was not offered")
  }
  return agents.interactions.respond(interaction.id, { option_id: optionId })
}

async function answerQuestion(interaction: Interaction, answer: string) {
  return agents.interactions.respond(interaction.id, { message: answer })
}

async function submitForm(interaction: Interaction, data: JSONObject) {
  return agents.interactions.respond(interaction.id, { data })
}
```

The TypeScript client submits each response through `agents.interactions.respond()`.


## Preserve the offered response

Response variants are exclusive: `{option_id}`, `{message}`, `{data}`, or `{decision}`. Form data must match the offered schema and preserve booleans, numbers, arrays, and enum values. Make unsupported schemas explicit. Do not silently coerce them to text.

Repeating the same normalized response is idempotent. A conflicting, late, expired, or cancelled response is rejected. Refresh the interaction and explain its current status. Approvals do not override the application's own record-level authorization.

## Waiting is not cancellation

`wait()` raises `InputRequired` by default. An observation timeout stops waiting and leaves execution running. Use `run.cancel()` to request cancellation deliberately.

### Python

Use `on_input="wait"` when another authorized component handles the interaction.


### TypeScript

Use `onInput: "wait"` when another authorized component handles the interaction.
