feat(mcp): add MCP Elicitation support (#2486)

MCP servers can now request structured user input mid-task via the
Elicitation protocol. The agent routes ElicitationRequest events to
the active channel at turn boundaries via a non-blocking drain loop.

- CLI channel: interactive prompt with server name attribution and
  field-by-field input collection; supports string, boolean, integer,
  number, and enum field types with type coercion and validation
- Non-interactive channels (TUI, Telegram, daemon, scheduler):
  auto-decline with a logged warning
- Sandboxed trust level: elicitation is unconditionally blocked
- Per-server override: `elicitation_enabled` in [[mcp.servers]] takes
  precedence over the global `[mcp] elicitation_enabled` setting
- Timeout: configurable `elicitation_timeout_secs` (default 120s)
- Phishing prevention: server name always shown before any prompt;
  message sanitized (control chars stripped, 500-char cap via
  char-level truncation to avoid UTF-8 boundary panics)
- Input validation: invalid input declines gracefully with a message
  rather than storing a wrong-type value

Known limitation: elicitation arriving during MCP tool call execution
times out because the agent loop is blocked; tracked as phase-2 work.

9 new tests: sanitize_elicitation_message (control chars, cap,
multi-byte boundary), build_elicitation_fields (type mapping, required
flag), sandboxed trust blocks elicitation, elicitation_enabled gate.
6980/6980 tests pass.

Author: bug-ops

CHANGELOG.md

@@ -23,6 +23,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - metrics: add `sanitizer_injection_fp_local` counter for injection flags on local (`ToolResult`) sources (#2515)
 - metrics: add `pii_ner_timeouts` counter for NER classifier timeout events (#2516)
+- feat(mcp): MCP Elicitation support — MCP servers can now request structured user input mid-task via the `elicitation/create` protocol method; requests are routed to the active channel (CLI prompts interactively, non-interactive channels auto-decline); CLI channel renders a phishing-prevention header showing the requesting server name before prompting; `ElicitationSchema` properties are mapped to typed `ElicitationField` entries (string, integer, number, boolean, enum); URL elicitation variant deferred to a future phase — auto-declined with a log message (closes #2486)
+- feat(config): `[mcp] elicitation_enabled` (default `false`) and `elicitation_timeout` (default 120 s) global config options; per-server `elicitation_enabled` override (`Option<bool>`) in `[[mcp.servers]]` entries — `null`/absent inherits the global flag; `Sandboxed` trust-level servers are never allowed to elicit regardless of config
 
 ## [0.18.1] - 2026-03-31
 

crates/zeph-acp/src/mcp_bridge.rs

@@ -38,6 +38,8 @@ pub fn acp_mcp_servers_to_entries(servers: &[acp::McpServer]) -> Vec<ServerEntry
                     expected_tools: Vec::new(),
                     roots: Vec::new(),
                     tool_metadata: HashMap::new(),
+                    elicitation_enabled: false,
+                    elicitation_timeout_secs: 120,
                 })
             }
             acp::McpServer::Http(http) => Some(ServerEntry {
@@ -52,6 +54,8 @@ pub fn acp_mcp_servers_to_entries(servers: &[acp::McpServer]) -> Vec<ServerEntry
                 expected_tools: Vec::new(),
                 roots: Vec::new(),
                 tool_metadata: HashMap::new(),
+                elicitation_enabled: false,
+                elicitation_timeout_secs: 120,
             }),
             acp::McpServer::Sse(sse) => {
                 // SSE is a legacy MCP transport; map to Streamable HTTP which is
@@ -68,6 +72,8 @@ pub fn acp_mcp_servers_to_entries(servers: &[acp::McpServer]) -> Vec<ServerEntry
                     expected_tools: Vec::new(),
                     roots: Vec::new(),
                     tool_metadata: HashMap::new(),
+                    elicitation_enabled: false,
+                    elicitation_timeout_secs: 120,
                 })
             }
             _ => {

crates/zeph-channels/src/any.rs

@@ -2,7 +2,8 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 
 use zeph_core::channel::{
-    Channel, ChannelError, ChannelMessage, StopHint, ToolOutputEvent, ToolStartEvent,
+    Channel, ChannelError, ChannelMessage, ElicitationRequest, ElicitationResponse, StopHint,
+    ToolOutputEvent, ToolStartEvent,
 };
 
 use crate::cli::CliChannel;
@@ -61,6 +62,13 @@ impl Channel for AnyChannel {
         dispatch_channel!(self, confirm, prompt)
     }
 
+    async fn elicit(
+        &mut self,
+        request: ElicitationRequest,
+    ) -> Result<ElicitationResponse, ChannelError> {
+        dispatch_channel!(self, elicit, request)
+    }
+
     fn try_recv(&mut self) -> Option<ChannelMessage> {
         match self {
             Self::Cli(c) => c.try_recv(),

crates/zeph-channels/src/cli.rs

@@ -5,7 +5,10 @@ use std::collections::VecDeque;
 use std::io::{BufReader, IsTerminal};
 
 use tokio::sync::mpsc;
-use zeph_core::channel::{Attachment, AttachmentKind, Channel, ChannelError, ChannelMessage};
+use zeph_core::channel::{
+    Attachment, AttachmentKind, Channel, ChannelError, ChannelMessage, ElicitationField,
+    ElicitationFieldType, ElicitationRequest, ElicitationResponse,
+};
 
 use crate::line_editor::{self, ReadLineResult};
 
@@ -346,6 +349,123 @@ impl Channel for CliChannel {
             ReadLineResult::Interrupted | ReadLineResult::Eof => Ok(false),
         }
     }
+
+    async fn elicit(
+        &mut self,
+        request: ElicitationRequest,
+    ) -> Result<ElicitationResponse, ChannelError> {
+        if !std::io::stdin().is_terminal() {
+            tracing::warn!(
+                server = request.server_name,
+                "non-interactive stdin, auto-declining elicitation"
+            );
+            return Ok(ElicitationResponse::Declined);
+        }
+
+        println!(
+            "\n[MCP server '{}' is requesting input]",
+            request.server_name
+        );
+        println!("{}", request.message);
+
+        let mut values = serde_json::Map::new();
+        for field in &request.fields {
+            let prompt = build_field_prompt(field);
+            let field_name = field.name.clone();
+            let result = tokio::task::spawn_blocking(move || line_editor::read_line(&prompt, &[]))
+                .await
+                .map_err(ChannelError::other)?
+                .map_err(ChannelError::Io)?;
+
+            match result {
+                ReadLineResult::Line(line) => {
+                    let trimmed = line.trim().to_owned();
+                    match coerce_field_value(&trimmed, &field.field_type) {
+                        Some(value) => {
+                            values.insert(field_name, value);
+                        }
+                        None => {
+                            println!(
+                                "Invalid input for '{}' (expected {:?}), declining.",
+                                field_name, field.field_type
+                            );
+                            return Ok(ElicitationResponse::Declined);
+                        }
+                    }
+                }
+                ReadLineResult::Interrupted | ReadLineResult::Eof => {
+                    return Ok(ElicitationResponse::Cancelled);
+                }
+            }
+        }
+
+        Ok(ElicitationResponse::Accepted(serde_json::Value::Object(
+            values,
+        )))
+    }
+}
+
+fn build_field_prompt(field: &ElicitationField) -> String {
+    let type_hint = match &field.field_type {
+        ElicitationFieldType::Boolean => " [true/false]",
+        ElicitationFieldType::Integer | ElicitationFieldType::Number => " [number]",
+        ElicitationFieldType::Enum(opts) if !opts.is_empty() => {
+            // Build hint dynamically below
+            return format!(
+                "{}{}: ",
+                field.name,
+                field
+                    .description
+                    .as_deref()
+                    .map(|d| format!(" ({})", d))
+                    .unwrap_or_default()
+            ) + &format!("[{}]: ", opts.join("/"));
+        }
+        _ => "",
+    };
+    format!(
+        "{}{}{}",
+        field.name,
+        field
+            .description
+            .as_deref()
+            .map(|d| format!(" ({})", d))
+            .unwrap_or_default(),
+        if type_hint.is_empty() {
+            ": ".to_owned()
+        } else {
+            format!("{type_hint}: ")
+        }
+    )
+}
+
+/// Coerce a raw user-input string into the JSON type required by the field.
+/// Returns `None` if the input cannot be converted to the declared type.
+fn coerce_field_value(raw: &str, field_type: &ElicitationFieldType) -> Option<serde_json::Value> {
+    match field_type {
+        ElicitationFieldType::String => Some(serde_json::Value::String(raw.to_owned())),
+        ElicitationFieldType::Boolean => match raw.to_ascii_lowercase().as_str() {
+            "true" | "yes" | "1" => Some(serde_json::Value::Bool(true)),
+            "false" | "no" | "0" => Some(serde_json::Value::Bool(false)),
+            _ => None,
+        },
+        ElicitationFieldType::Integer => raw
+            .parse::<i64>()
+            .ok()
+            .map(|n| serde_json::Value::Number(n.into())),
+        ElicitationFieldType::Number => raw
+            .parse::<f64>()
+            .ok()
+            .and_then(serde_json::Number::from_f64)
+            .map(serde_json::Value::Number),
+        ElicitationFieldType::Enum(opts) => {
+            if opts.iter().any(|o| o == raw) {
+                Some(serde_json::Value::String(raw.to_owned()))
+            } else {
+                None
+            }
+        }
+    }
 }
 
 #[cfg(test)]

crates/zeph-config/src/channels.rs

@@ -339,6 +339,10 @@ fn default_max_instructions_bytes() -> usize {
     2048
 }
 
+fn default_elicitation_timeout() -> u64 {
+    120
+}
+
 #[derive(Debug, Clone, Deserialize, Serialize)]
 pub struct McpConfig {
     #[serde(default)]
@@ -362,6 +366,14 @@ pub struct McpConfig {
     /// Maximum byte length for MCP server instructions. Truncated with "..." if exceeded. Default: 2048.
     #[serde(default = "default_max_instructions_bytes")]
     pub max_instructions_bytes: usize,
+    /// Enable MCP elicitation (servers can request user input mid-task).
+    /// Default: false — all elicitation requests are auto-declined.
+    /// Opt-in because it interrupts agent flow and could be abused by malicious servers.
+    #[serde(default)]
+    pub elicitation_enabled: bool,
+    /// Timeout for user to respond to an elicitation request (seconds). Default: 120.
+    #[serde(default = "default_elicitation_timeout")]
+    pub elicitation_timeout: u64,
 }
 
 impl Default for McpConfig {
@@ -375,6 +387,8 @@ impl Default for McpConfig {
             tool_discovery: ToolDiscoveryConfig::default(),
             max_description_bytes: default_max_description_bytes(),
             max_instructions_bytes: default_max_instructions_bytes(),
+            elicitation_enabled: false,
+            elicitation_timeout: default_elicitation_timeout(),
         }
     }
 }
@@ -426,6 +440,11 @@ pub struct McpServerConfig {
     /// When absent for a tool, metadata is inferred from the tool name via heuristics.
     #[serde(default)]
     pub tool_metadata: HashMap<String, ToolSecurityMeta>,
+    /// Per-server elicitation override. `None` = inherit global `elicitation_enabled`.
+    /// `Some(true)` = allow this server to elicit regardless of global setting.
+    /// `Some(false)` = always decline for this server.
+    #[serde(default)]
+    pub elicitation_enabled: Option<bool>,
 }
 
 /// A filesystem root exposed to an MCP server via `roots/list`.

crates/zeph-core/src/agent/builder.rs

@@ -609,6 +609,19 @@ impl<C: Channel> Agent<C> {
         self
     }
 
+    /// Set the elicitation receiver for MCP elicitation requests from server handlers.
+    ///
+    /// When set, the agent loop processes elicitation events concurrently with tool result
+    /// awaiting to prevent deadlock.
+    #[must_use]
+    pub fn with_mcp_elicitation_rx(
+        mut self,
+        rx: tokio::sync::mpsc::UnboundedReceiver<zeph_mcp::ElicitationEvent>,
+    ) -> Self {
+        self.mcp.elicitation_rx = Some(rx);
+        self
+    }
+
     #[must_use]
     pub fn with_security(mut self, security: SecurityConfig, timeouts: TimeoutConfig) -> Self {
         self.security.sanitizer =