refactor: implement schema command for runtime tool introspection and add input validation

Author: vinhnx

AGENTS.md

@@ -125,6 +125,13 @@ cargo clippy --workspace --all-targets -- -D warnings && cargo fmt --check && ca
 
 **Performance**: Single codegen unit, strict Clippy, no `expect_used`/`unwrap_used`.
 
+## Agent-First CLI Invariants
+
+- Prefer machine-readable output for automation (`vtcode ask --output-format json`, `vtcode exec --json`).
+- Introspect tool schemas at runtime before generating tool calls (`vtcode schema tools`).
+- Use `vtcode exec --dry-run` before mutation-oriented autonomous tasks.
+- Assume agent-generated input can be adversarial; keep input validation strict for CLI/MCP fields.
+
 **Pitfalls**:
 
 1. Don't assume paths — validate boundaries

CONTEXT.md

@@ -0,0 +1,29 @@
+# VT Code Agent Context
+
+This file captures runtime invariants for automation-oriented usage of VT Code.
+
+## Output Contracts
+
+- Use `vtcode ask --output-format json` when downstream tooling needs structured replies.
+- Use `vtcode exec --json` for JSONL event streams.
+- Use `vtcode exec --events <path>` to persist machine-readable transcripts.
+
+## Runtime Introspection
+
+- Discover built-in tool contracts from the binary at runtime:
+  - `vtcode schema tools`
+  - `vtcode schema tools --mode minimal`
+  - `vtcode schema tools --name unified_search --name unified_file`
+
+## Safety Defaults
+
+- For autonomous mutation-oriented work, run a read-only rehearsal first:
+  - `vtcode exec --dry-run "<task>"`
+- Treat prompts and MCP CLI values as untrusted input.
+- Prefer small, explicit tool arguments over broad/unbounded payloads.
+
+## Context Discipline
+
+- Limit request scope in prompts.
+- Prefer focused tool calls and incremental execution.
+- Avoid requesting full-file/full-workspace payloads unless required.

docs/modules/vtcode_docs_map.md

@@ -153,8 +153,8 @@ This document serves as an index of all VT Code documentation. When users ask qu
 
 - **File**: `docs/user-guide/exec-mode.md`
   - **Content**: Exec Mode Automation
-  - **Topics**: Launching exec mode, Structured event stream, Resuming sessions
-  - **User Questions**: "What can you tell me about Exec Mode Automation?", "How does Launching exec mode work?", "How does Structured event stream work?"
+  - **Topics**: Launching exec mode, Dry-run mode, Structured event stream, Resuming sessions
+  - **User Questions**: "What can you tell me about Exec Mode Automation?", "How does Launching exec mode work?", "How does Dry-run mode work?"
 
 - **File**: `docs/user-guide/getting-started.md`
   - **Content**: Getting Started with VT Code
@@ -878,7 +878,7 @@ This document serves as an index of all VT Code documentation. When users ask qu
 
 - **File**: `docs/user-guide/commands.md`
   - **Content**: Command Reference
-  - **Topics**: grep_file (ripgrep-like), File operations, Quick Actions in Chat Input, stats (session metrics), update (binary updates)
+  - **Topics**: grep_file (ripgrep-like), File operations, Quick Actions in Chat Input, stats (session metrics), schema (runtime tool introspection)
   - **User Questions**: "What can you tell me about Command Reference?", "How does grep_file (ripgrep-like) work?", "How does File operations work?"
 
 - **File**: `docs/user-guide/interactive-mode.md`

docs/user-guide/commands.md

@@ -93,6 +93,33 @@ Display current configuration, available tools, and live performance metrics for
 session. Use `--format` to choose `text`, `json`, or `html` output and `--detailed` to list each
 tool.
 
+## schema (runtime tool introspection)
+
+Inspect VT Code's built-in tool schemas at runtime so automation can discover exact tool names and
+input parameters without relying on stale docs.
+
+### Usage
+
+```bash
+# Full JSON document (default)
+vtcode schema tools
+
+# Compact schema descriptions for tighter context windows
+vtcode schema tools --mode minimal
+
+# NDJSON output for streaming parsers
+vtcode schema tools --format ndjson
+
+# Filter to specific tools
+vtcode schema tools --name unified_search --name unified_file
+```
+
+### Options
+
+- `--mode` — `minimal`, `progressive` (default), or `full`
+- `--format` — `json` (default) or `ndjson`
+- `--name` — repeatable exact tool-name filter
+
 ## update (binary updates)
 
 Check for and install binary updates of VT Code from GitHub Releases. Updates are downloaded and verified against checksums for security.

docs/user-guide/exec-mode.md

@@ -17,6 +17,17 @@ allowances or confirmation dialogs, so ensure the allow list covers every tool i
 `--last-message-file` or persist the raw JSON stream with `--events`. Use `--json` when you want to see the live JSONL feed on
 stdout.
 
+## Dry-run mode
+
+Use `--dry-run` to force read-only execution while still allowing the agent to analyze and plan:
+
+```bash
+vtcode exec --dry-run "identify required code changes for adding OAuth refresh token support"
+```
+
+In dry-run mode, VT Code enables plan/read-only enforcement for tool calls. Mutating operations are blocked, and the run reports what
+would be changed rather than applying edits.
+
 ## Structured event stream
 
 Use `vtcode exec --json` to emit JSON Lines that match the non-interactive Codex schema:

src/cli/exec.rs

@@ -2,6 +2,7 @@ use anyhow::{Context, Result, bail};
 use std::io::{self, Read};
 use std::path::PathBuf;
 use std::str::FromStr;
+use vtcode_core::cli::input_hardening::validate_agent_safe_text;
 use vtcode_core::config::VTCodeConfig;
 use vtcode_core::config::WorkspaceTrustLevel;
 use vtcode_core::config::models::ModelId;
@@ -21,17 +22,27 @@ const EXEC_SESSION_PREFIX: &str = "exec-task";
 const EXEC_TASK_ID: &str = "exec-task";
 const EXEC_TASK_TITLE: &str = "Exec Task";
 const EXEC_TASK_INSTRUCTIONS: &str = "You are running vtcode in non-interactive exec mode. Complete the task autonomously using the configured full-auto tool allowlist. Do not request additional user input, confirmations, or allowances—operate solely with the provided information and available tools. Provide a concise summary of the outcome when finished.";
+const EXEC_TASK_INSTRUCTIONS_DRY_RUN: &str = "You are running vtcode in non-interactive exec dry-run mode. Plan and validate the approach in read-only mode without mutating files, running mutating commands, or requesting additional user input. If the task requires mutations, explain what would be changed and why.";
 
 #[derive(Debug, Clone)]
 pub struct ExecCommandOptions {
     pub json: bool,
+    pub dry_run: bool,
     pub events_path: Option<PathBuf>,
     pub last_message_file: Option<PathBuf>,
 }
 
+fn task_instructions(dry_run: bool) -> &'static str {
+    if dry_run {
+        EXEC_TASK_INSTRUCTIONS_DRY_RUN
+    } else {
+        EXEC_TASK_INSTRUCTIONS
+    }
+}
+
 fn resolve_prompt(prompt_arg: Option<String>, quiet: bool) -> Result<String> {
-    match prompt_arg {
-        Some(p) if p != "-" => Ok(p),
+    let prompt = match prompt_arg {
+        Some(p) if p != "-" => p,
         maybe_dash => {
             let force_stdin = matches!(maybe_dash.as_deref(), Some("-"));
             if io::stdin().is_tty_ext() && !force_stdin {
@@ -48,9 +59,12 @@ fn resolve_prompt(prompt_arg: Option<String>, quiet: bool) -> Result<String> {
                 .read_to_string(&mut buffer)
                 .context("Failed to read prompt from stdin")?;
             validate_non_empty(&buffer, "Prompt via stdin")?;
-            Ok(buffer)
+            buffer
         }
-    }
+    };
+
+    validate_agent_safe_text("prompt", &prompt)?;
+    Ok(prompt)
 }
 
 // OPTIMIZATION: Use inline hint for hot path
@@ -146,6 +160,9 @@ async fn handle_exec_command_impl(
         .await
         .context("Failed to apply workspace configuration to exec runner")?;
     runner.enable_full_auto(&automation_cfg.allowed_tools).await;
+    if options.dry_run {
+        runner.enable_plan_mode();
+    }
     runner.set_quiet(options.json);
     if options.json {
         runner.set_event_handler(|event| match serde_json::to_string(event) {
@@ -159,7 +176,7 @@ async fn handle_exec_command_impl(
         id: EXEC_TASK_ID.into(),
         title: EXEC_TASK_TITLE.into(),
         description: prompt.trim().to_string(),
-        instructions: Some(EXEC_TASK_INSTRUCTIONS.into()),
+        instructions: Some(task_instructions(options.dry_run).into()),
     };
 
     let max_retries = vt_cfg.agent.max_task_retries;
@@ -199,6 +216,7 @@ async fn handle_exec_command_impl(
 
         eprintln!("{}", style("[OUTCOME]").magenta().bold());
         eprintln!("  {:16} {}", "outcome", result.outcome);
+        eprintln!("  {:16} {}", "dry_run", options.dry_run);
         eprintln!("  {:16} {}", "turns", result.turns_executed);
         eprintln!("  {:16} {}", "duration_ms", result.total_duration_ms);
         eprintln!("  {:16} {}", "avg_turn_ms", avg_display);
@@ -252,3 +270,21 @@ async fn handle_exec_command_impl(
 
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::task_instructions;
+
+    #[test]
+    fn dry_run_instructions_are_read_only_focused() {
+        let instructions = task_instructions(true);
+        assert!(instructions.contains("read-only"));
+        assert!(instructions.contains("without mutating files"));
+    }
+
+    #[test]
+    fn normal_exec_instructions_do_not_use_dry_run_wording() {
+        let instructions = task_instructions(false);
+        assert!(!instructions.contains("dry-run mode"));
+    }
+}

src/cli/mod.rs

@@ -18,6 +18,7 @@ pub use vtcode_core::mcp::cli::handle_mcp_command;
 pub mod analyze;
 pub mod benchmark;
 pub mod exec;
+pub mod schema;
 pub mod skills;
 pub mod skills_ref;
 pub mod update;
@@ -73,6 +74,10 @@ pub async fn handle_exec_command(
     exec::handle_exec_command(&core_cfg, cfg, options, prompt).await
 }
 
+pub async fn handle_schema_command(command: vtcode_core::cli::args::SchemaCommands) -> Result<()> {
+    schema::handle_schema_command(command).await
+}
+
 pub async fn handle_analyze_command(
     core_cfg: vtcode_core::config::types::AgentConfig,
     analysis_type: analyze::AnalysisType,