Interactive Confirmation Flow
Relevant source files
The following files were used as context for generating this wiki page:
The Interactive Confirmation Flow is a critical safety-first component of caro. Its primary purpose is to act as a final checkpoint, ensuring that users review and explicitly approve commands generated by the LLM before they are executed. This prevents accidental execution of dangerous, incorrect, or unintended shell commands. The system employs multiple layers of confirmation, from pre-generation clarification to post-generation risk assessment, making it a cornerstone of the project's commitment to user safety.
This flow is not a single step but a series of potential user interactions designed to refine intent, validate output, and secure user consent. It is deeply integrated with the Safety Validation System and can be configured through various CLI flags and configuration settings.
Sources: exports/session-logs/2025-09-13-readme.txt:100-103, CONTRIBUTING.md:20-22, specs/006-intelligent-prompt-generation/spec.md:10-16
Core Confirmation Logic
The standard confirmation flow is triggered after a command has been generated and validated by the safety module. The user is presented with the generated command and prompted for execution.
This diagram illustrates the standard command generation and confirmation pipeline.
Triggers for Confirmation
Confirmation is not required for every command. The decision to prompt the user is based on the command's assessed risk level and the configured safety level.
| Risk Level | Strict Safety Level | Moderate Safety Level (Default) | Permissive Safety Level |
|---|---|---|---|
Critical | Blocked | Confirmation Required | Warn Only |
High | Confirmation Required | Confirmation Required | Warn Only |
Moderate | Confirmation Required | No Confirmation (Warn) | No Confirmation (Warn) |
Safe | No Confirmation | No Confirmation | No Confirmation |
- Risk Levels (
Safe,Moderate,High,Critical) are determined by theSafetyValidator. - Safety Levels (
Strict,Moderate,Permissive) are user-configurable settings that define the confirmation threshold.
Sources: specs/002-implement-tdd-green/plan.md:175-181, CONTRIBUTING.md:178-180
Bypassing Confirmation
Users can bypass the interactive prompt using CLI flags. This is intended for trusted scripts or high-confidence use cases.
| Option | Shorthand | Description | Default |
|---|---|---|---|
--auto | - | Executes the generated command without asking for confirmation. This is overridden if a command is flagged as dangerous, unless --allow-dangerous is also used. | false |
--allow-dangerous | - | Allows the execution of commands identified as potentially dangerous (e.g., rm -rf, mkfs). This is an explicit override for advanced users. | false |
| Non-Interactive Mode | - | When input is piped via stdin or provided with the -p/--prompt flag, confirmation prompts are automatically skipped. | false |
Sources: exports/session-logs/2025-09-13-readme.txt:33, 80, kitty-specs/002-unquoted-cli-arguments/tasks.md:78-79
Advanced Confirmation Flows
Beyond the simple "yes/no" prompt, caro implements more sophisticated interactive flows to improve command accuracy and safety.
Ambiguity Clarification
When a user's initial prompt is too vague (e.g., "clean up disk space"), caro can initiate a clarification dialogue before generating a command. The Orchestrator Agent detects ambiguity and hands off to the Clarification Agent to generate specific questions.
This sequence diagram shows the clarification process.
This pre-generation confirmation ensures the final command more closely matches the user's true intent, reducing the likelihood of generating an incorrect or unsafe command.
Sources: specs/006-intelligent-prompt-generation/spec.md:73-95, 274-301
Multi-Turn Validation Loop
If a generated command fails the internal validation (e.g., uses GNU flags on a BSD system), caro can enter a multi-turn validation loop. Instead of failing outright, it provides feedback to the Generator Agent and attempts to regenerate a valid command.
This flow represents a form of automated, internal confirmation and correction.
This loop can retry up to a configured maximum (e.g., 3 times) before escalating or failing. This reduces user friction by automatically fixing common LLM mistakes.
Sources: specs/006-intelligent-prompt-generation/spec.md:97-111, 249-272
Shell Integration Confirmation
When caro is integrated directly into the shell, it provides a pre-execution confirmation workflow as part of its policy engine. This is distinct from the standard CLI confirmation and is configured via safety levels within the shell integration.
| Safety Level | Behavior |
|---|---|
off | No safety checks are performed. |
passive | Shows warnings for risky commands but allows execution to proceed without a prompt. |
active | Prompts the user for confirmation on high-risk commands and blocks critical-risk commands entirely. |
This confirmation happens within the shell's pre-execution hook (preexec), allowing caro to intercept and validate commands just before they run.
Sources: specs/007-caro-shell-integration/milestones.md:65-79
Key System Components
The interactive confirmation flow is orchestrated by several modules across the caro codebase.
| Module/File | Responsibility |
|---|---|
src/safety/confirmation.rs | Contains the core logic for the user confirmation system, likely handling the "Execute this command? (y/N)" prompt. |
src/core/interaction.rs | Manages user interaction workflows, including the presentation of generated commands and capturing user responses. |
src/cli/mod.rs | Defines and parses CLI arguments like --auto that control the confirmation flow. |
src/agents/orchestrator.rs | Decides which confirmation flow to use (Single-Shot, Multi-Turn, Clarification) based on ambiguity and confidence scores. |
src/agents/clarification.rs | Generates interactive questions to refine user intent before command generation. |
src/shell/policy/mod.rs | Implements the policy engine for shell integration, including the active mode confirmation prompt. |
Sources: specs/001-create-a-comprehensive/tasks.md:83, 107, specs/006-intelligent-prompt-generation/spec.md:162, 219, specs/007-caro-shell-integration/milestones.md:59
Conclusion
The Interactive Confirmation Flow in caro is a multi-layered defense mechanism that embodies the "Safety-First" principle. It ranges from simple "yes/no" prompts controlled by CLI flags to sophisticated, context-aware dialogues that clarify user intent and automatically correct LLM errors. By placing the user in control at critical decision points, caro builds trust and provides a robust safeguard against the inherent unpredictability of LLM-generated code, ensuring that power and convenience do not come at the cost of safety.