Turn Control
End a blocked turn with a structured input-required result and a visible question.
Ask one blocking question
What it enables
Let the agent stop a turn as `input-required`, show a specific question, and resume when the user replies in the same thread.
- Status
- Core
- Availability
- Installed by `
auggy create`.
Contributes
When the model cannot reasonably proceed without missing user input, `request_input` emits the prompt as normal assistant text and terminates the current turn with a structured result. The user's next message starts a new turn in the same conversation.
Generated install
`auggy create <name>` adds `turnControl` to `agent.yaml`, copies `<agent>/skills/turnControl/SKILL.md`, and writes this exact metadata file at `<agent>/augments/turnControl/augment.yaml`.
type: turnControlTurn Control is YAML-configurable. Add `config.requestInputDescription` only when the model needs project-specific selection guidance:
type: turnControl
config:
requestInputDescription: >-
Ask one short question only when a required deployment target is missing
and no safe default exists. Never use this as a closing pleasantry.Resolve a real deployment ambiguity
If a user asks to deploy but the agent has two configured production services and no basis for choosing, the model can stop on one answerable choice:
request_input({
prompt: "Which production service should I deploy: api-west or api-east?",
reason: "Two production targets are configured and neither is the default."
})The user sees only `prompt`. `reason` is optional tracing context and is not shown in the assistant reply.
Runtime surfaces
| Surface | Exact behavior |
|---|---|
| Tool | `request_input({ prompt, reason? })`; `prompt` must be 1-2000 characters. |
| Tool result | Returns `content: prompt` and `terminate: { status: "input-required", message: prompt }`. |
| Assistant output | The prompt is emitted as a normal assistant text message before the terminal event. |
| Kernel result | After the current tool batch settles, the turn ends with status `input-required` and no next model inference runs. |
| AG-UI | `RUN_FINISHED.result` contains `{ status: "input-required", message: prompt }`; HTTP remains 200 SSE. |
| Resume | The next user message starts another turn; clients preserve the thread ID to retain conversation context. |
| Admin | Reports the exposed tool, behavior, and whether the tool description is default or overridden. |
Boundaries
| Area | Boundary |
|---|---|
| Trust | The tool has no trust-level gate. It asks for information; it does not authenticate a user, grant authorization, or confirm that a consequential action is allowed. |
| Persistence | `input-required` is a turn result, not a durable job. Turn Control stores no pending task and performs no background work while waiting. |
| Deployment | The Console understands the result. Other AG-UI clients should branch on `RUN_FINISHED.result.status`; older clients still receive the visible assistant question but may treat the run as normally finished. |
| Limits | It produces only `input-required`. It does not cancel sibling tools already executing in the same model-emitted batch, and it does not produce `auth-required`, failure, cancellation, rejection, deferred execution, retries, or approval workflows. |
Tool guidance is not enforcement
The default description and bundled skill tell the model not to ask closing pleasantries or avoid defensible decisions. That guidance can reduce misuse but cannot guarantee model selection. Downstream code must treat the structured status as a request for input, not as authorization.
Verify
cd <agent>
auggy run- 1Give the agent a task with two equally valid named targets and no default.
- 2Inspect the tool call and confirm `prompt` is specific, answerable, and no longer than 2000 characters.
- 3Confirm the same prompt appears as the assistant message and the turn ends without another model inference.
- 4In the network response, confirm the terminal `RUN_FINISHED.result.status` is `input-required` and `result.message` equals the prompt.
- 5Reply with one target in the same thread and confirm the agent continues on a new turn rather than running in the background.