Match rustfmt wrapper re-export layout

Split the MCP template wrapper re-exports into the item layout expected by CI rustfmt.

Co-authored-by: Codex <noreply@openai.com>

codex-rs/Cargo.lock

@@ -1932,11 +1932,13 @@ dependencies = [
  "codex-execpolicy",
  "codex-features",
  "codex-feedback",
+ "codex-file-watcher",
  "codex-git-utils",
  "codex-hooks",
  "codex-instructions",
  "codex-login",
  "codex-mcp",
+ "codex-mcp-tool-approval-templates",
  "codex-model-provider",
  "codex-model-provider-info",
  "codex-models-manager",
@@ -1988,7 +1990,6 @@ dependencies = [
  "insta",
  "libc",
  "maplit",
- "notify",
  "once_cell",
  "openssl-sys",
  "opentelemetry",
@@ -2263,6 +2264,17 @@ dependencies = [
  "tokio",
 ]
 
+[[package]]
+name = "codex-file-watcher"
+version = "0.0.0"
+dependencies = [
+ "notify",
+ "pretty_assertions",
+ "tempfile",
+ "tokio",
+ "tracing",
+]
+
 [[package]]
 name = "codex-git-utils"
 version = "0.0.0"
@@ -2440,6 +2452,16 @@ dependencies = [
  "url",
 ]
 
+[[package]]
+name = "codex-mcp-tool-approval-templates"
+version = "0.0.0"
+dependencies = [
+ "pretty_assertions",
+ "serde",
+ "serde_json",
+ "tracing",
+]
+
 [[package]]
 name = "codex-mcp-server"
 version = "0.0.0"

codex-rs/Cargo.toml

@@ -38,10 +38,12 @@ members = [
     "execpolicy",
     "execpolicy-legacy",
     "keyring-store",
+    "file-watcher",
     "file-search",
     "linux-sandbox",
     "lmstudio",
     "login",
+    "mcp-tool-approval-templates",
     "codex-mcp",
     "mcp-server",
     "model-provider-info",
@@ -139,6 +141,7 @@ codex-experimental-api-macros = { path = "codex-experimental-api-macros" }
 codex-features = { path = "features" }
 codex-feedback = { path = "feedback" }
 codex-install-context = { path = "install-context" }
+codex-file-watcher = { path = "file-watcher" }
 codex-file-search = { path = "file-search" }
 codex-git-utils = { path = "git-utils" }
 codex-hooks = { path = "hooks" }
@@ -147,6 +150,7 @@ codex-keyring-store = { path = "keyring-store" }
 codex-linux-sandbox = { path = "linux-sandbox" }
 codex-lmstudio = { path = "lmstudio" }
 codex-login = { path = "login" }
+codex-mcp-tool-approval-templates = { path = "mcp-tool-approval-templates" }
 codex-mcp = { path = "codex-mcp" }
 codex-mcp-server = { path = "mcp-server" }
 codex-model-provider-info = { path = "model-provider-info" }

codex-rs/core/Cargo.toml

@@ -39,8 +39,10 @@ crypto_box = { workspace = true }
 codex-exec-server = { workspace = true }
 codex-features = { workspace = true }
 codex-feedback = { workspace = true }
+codex-file-watcher = { workspace = true }
 codex-login = { workspace = true }
 codex-mcp = { workspace = true }
+codex-mcp-tool-approval-templates = { workspace = true }
 codex-model-provider-info = { workspace = true }
 codex-models-manager = { workspace = true }
 ed25519-dalek = { workspace = true }
@@ -87,7 +89,6 @@ iana-time-zone = { workspace = true }
 image = { workspace = true, features = ["jpeg", "png", "webp"] }
 indexmap = { workspace = true }
 libc = { workspace = true }
-notify = { workspace = true }
 once_cell = { workspace = true }
 rand = { workspace = true }
 regex-lite = { workspace = true }

codex-rs/core/src/file_watcher.rs

@@ -1,856 +1 @@
-//! Watches subscribed files or directories and routes coarse-grained change
-//! notifications to the subscribers that own matching watched paths.
-
-use std::collections::BTreeSet;
-use std::collections::HashMap;
-use std::path::Path;
-use std::path::PathBuf;
-use std::sync::Arc;
-use std::sync::Mutex;
-use std::sync::RwLock;
-use std::sync::atomic::AtomicUsize;
-use std::sync::atomic::Ordering;
-use std::time::Duration;
-
-use notify::Event;
-use notify::EventKind;
-use notify::RecommendedWatcher;
-use notify::RecursiveMode;
-use notify::Watcher;
-use tokio::runtime::Handle;
-use tokio::sync::Mutex as AsyncMutex;
-use tokio::sync::Notify;
-use tokio::sync::mpsc;
-use tokio::time::Instant;
-use tokio::time::sleep_until;
-use tracing::warn;
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-/// Coalesced file change notification for a subscriber.
-pub struct FileWatcherEvent {
-    /// Changed paths delivered in sorted order with duplicates removed.
-    pub paths: Vec<PathBuf>,
-}
-
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-/// Path subscription registered by a [`FileWatcherSubscriber`].
-pub struct WatchPath {
-    /// Root path to watch.
-    pub path: PathBuf,
-    /// Whether events below `path` should match recursively.
-    pub recursive: bool,
-}
-
-type SubscriberId = u64;
-
-#[derive(Default)]
-struct WatchState {
-    next_subscriber_id: SubscriberId,
-    path_ref_counts: HashMap<PathBuf, PathWatchCounts>,
-    subscribers: HashMap<SubscriberId, SubscriberState>,
-}
-
-struct SubscriberState {
-    watched_paths: HashMap<SubscriberWatchKey, SubscriberWatchState>,
-    tx: WatchSender,
-}
-
-/// Immutable per-subscriber watch identity.
-#[derive(Clone, Debug, Eq, Hash, PartialEq)]
-struct SubscriberWatchKey {
-    /// Original path requested by the subscriber. Notifications are reported
-    /// in this namespace so clients do not see canonicalization artifacts.
-    requested: WatchPath,
-    /// Canonical equivalent of `requested` used to match backend events.
-    /// Some backends report canonical paths such as `/private/var/...` even
-    /// when the watch was registered through `/var/...`.
-    matched: WatchPath,
-}
-
-/// Mutable per-subscriber watch state.
-struct SubscriberWatchState {
-    /// Existing path passed to the OS watcher and used for ref-counting. This
-    /// is usually `requested`, but missing targets use an existing ancestor.
-    actual: WatchPath,
-    count: usize,
-    /// Whether the requested path existed the last time an ancestor event was
-    /// handled. This preserves delete notifications for fallback watches.
-    last_exists: bool,
-    /// Whether this watch started from a missing path. Such watches normalize
-    /// ancestor create/delete events back to `requested`.
-    fallback: bool,
-}
-
-/// Registration-time watch data before it is merged into subscriber state.
-///
-/// The key is stable for unregistering while `actual` may later move closer
-/// to the requested path as missing path components are created.
-#[derive(Clone)]
-struct SubscriberWatchRegistration {
-    /// Immutable subscriber-visible identity for this registration.
-    key: SubscriberWatchKey,
-    /// Existing path initially passed to the OS watcher.
-    actual: WatchPath,
-    /// Whether registration started from a missing path fallback.
-    fallback: bool,
-}
-
-/// Receives coalesced change notifications for a single subscriber.
-pub struct Receiver {
-    inner: Arc<ReceiverInner>,
-}
-
-struct WatchSender {
-    inner: Arc<ReceiverInner>,
-}
-
-struct ReceiverInner {
-    changed_paths: AsyncMutex<BTreeSet<PathBuf>>,
-    notify: Notify,
-    sender_count: AtomicUsize,
-}
-
-impl Receiver {
-    /// Waits for the next batch of changed paths, or returns `None` once the
-    /// corresponding subscriber has been removed and no more events can arrive.
-    pub async fn recv(&mut self) -> Option<FileWatcherEvent> {
-        loop {
-            let notified = self.inner.notify.notified();
-            {
-                let mut changed_paths = self.inner.changed_paths.lock().await;
-                if !changed_paths.is_empty() {
-                    return Some(FileWatcherEvent {
-                        paths: std::mem::take(&mut *changed_paths).into_iter().collect(),
-                    });
-                }
-                if self.inner.sender_count.load(Ordering::Acquire) == 0 {
-                    return None;
-                }
-            }
-            notified.await;
-        }
-    }
-}
-
-impl WatchSender {
-    async fn add_changed_paths(&self, paths: &[PathBuf]) {
-        if paths.is_empty() {
-            return;
-        }
-
-        let mut changed_paths = self.inner.changed_paths.lock().await;
-        let previous_len = changed_paths.len();
-        changed_paths.extend(paths.iter().cloned());
-        if changed_paths.len() != previous_len {
-            self.inner.notify.notify_one();
-        }
-    }
-}
-
-impl Clone for WatchSender {
-    fn clone(&self) -> Self {
-        self.inner.sender_count.fetch_add(1, Ordering::Relaxed);
-        Self {
-            inner: Arc::clone(&self.inner),
-        }
-    }
-}
-
-impl Drop for WatchSender {
-    fn drop(&mut self) {
-        if self.inner.sender_count.fetch_sub(1, Ordering::AcqRel) == 1 {
-            self.inner.notify.notify_waiters();
-        }
-    }
-}
-
-fn watch_channel() -> (WatchSender, Receiver) {
-    let inner = Arc::new(ReceiverInner {
-        changed_paths: AsyncMutex::new(BTreeSet::new()),
-        notify: Notify::new(),
-        sender_count: AtomicUsize::new(1),
-    });
-    (
-        WatchSender {
-            inner: Arc::clone(&inner),
-        },
-        Receiver { inner },
-    )
-}
-
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
-struct PathWatchCounts {
-    non_recursive: usize,
-    recursive: usize,
-}
-
-impl PathWatchCounts {
-    fn increment(&mut self, recursive: bool, amount: usize) {
-        if recursive {
-            self.recursive += amount;
-        } else {
-            self.non_recursive += amount;
-        }
-    }
-
-    fn decrement(&mut self, recursive: bool, amount: usize) {
-        if recursive {
-            self.recursive = self.recursive.saturating_sub(amount);
-        } else {
-            self.non_recursive = self.non_recursive.saturating_sub(amount);
-        }
-    }
-
-    fn effective_mode(self) -> Option<RecursiveMode> {
-        if self.recursive > 0 {
-            Some(RecursiveMode::Recursive)
-        } else if self.non_recursive > 0 {
-            Some(RecursiveMode::NonRecursive)
-        } else {
-            None
-        }
-    }
-
-    fn is_empty(self) -> bool {
-        self.non_recursive == 0 && self.recursive == 0
-    }
-}
-
-struct FileWatcherInner {
-    watcher: RecommendedWatcher,
-    watched_paths: HashMap<PathBuf, RecursiveMode>,
-}
-
-/// Coalesces bursts of watch notifications and emits at most once per interval.
-pub struct ThrottledWatchReceiver {
-    rx: Receiver,
-    interval: Duration,
-    next_allowed: Option<Instant>,
-}
-
-impl ThrottledWatchReceiver {
-    /// Creates a throttling wrapper around a raw watcher [`Receiver`].
-    pub fn new(rx: Receiver, interval: Duration) -> Self {
-        Self {
-            rx,
-            interval,
-            next_allowed: None,
-        }
-    }
-
-    /// Receives the next event, enforcing the configured minimum delay after
-    /// the previous emission.
-    pub async fn recv(&mut self) -> Option<FileWatcherEvent> {
-        if let Some(next_allowed) = self.next_allowed {
-            sleep_until(next_allowed).await;
-        }
-
-        let event = self.rx.recv().await;
-        if event.is_some() {
-            self.next_allowed = Some(Instant::now() + self.interval);
-        }
-        event
-    }
-}
-
-/// Handle used to register watched paths for one logical consumer.
-pub struct FileWatcherSubscriber {
-    id: SubscriberId,
-    file_watcher: Arc<FileWatcher>,
-}
-
-impl FileWatcherSubscriber {
-    /// Registers the provided paths for this subscriber and returns an RAII
-    /// guard that unregisters them on drop.
-    pub fn register_paths(&self, watched_paths: Vec<WatchPath>) -> WatchRegistration {
-        let watched_paths = dedupe_watched_paths(watched_paths)
-            .into_iter()
-            .map(|requested| {
-                let (actual, matched, fallback) = actual_watch_path(&requested);
-                let key = SubscriberWatchKey { requested, matched };
-                SubscriberWatchRegistration {
-                    key,
-                    actual,
-                    fallback,
-                }
-            })
-            .collect::<Vec<_>>();
-        self.file_watcher.register_paths(self.id, &watched_paths);
-
-        WatchRegistration {
-            file_watcher: Arc::downgrade(&self.file_watcher),
-            subscriber_id: self.id,
-            watched_paths: watched_paths
-                .iter()
-                .map(|watch| watch.key.clone())
-                .collect(),
-        }
-    }
-
-    #[cfg(test)]
-    pub(crate) fn register_path(&self, path: PathBuf, recursive: bool) -> WatchRegistration {
-        self.register_paths(vec![WatchPath { path, recursive }])
-    }
-}
-
-impl Drop for FileWatcherSubscriber {
-    fn drop(&mut self) {
-        self.file_watcher.remove_subscriber(self.id);
-    }
-}
-
-/// RAII guard for a set of active path registrations.
-pub struct WatchRegistration {
-    file_watcher: std::sync::Weak<FileWatcher>,
-    subscriber_id: SubscriberId,
-    watched_paths: Vec<SubscriberWatchKey>,
-}
-
-impl Default for WatchRegistration {
-    fn default() -> Self {
-        Self {
-            file_watcher: std::sync::Weak::new(),
-            subscriber_id: 0,
-            watched_paths: Vec::new(),
-        }
-    }
-}
-
-impl Drop for WatchRegistration {
-    fn drop(&mut self) {
-        if let Some(file_watcher) = self.file_watcher.upgrade() {
-            file_watcher.unregister_paths(self.subscriber_id, &self.watched_paths);
-        }
-    }
-}
-
-/// Multi-subscriber file watcher built on top of `notify`.
-pub struct FileWatcher {
-    inner: Option<Arc<Mutex<FileWatcherInner>>>,
-    state: Arc<RwLock<WatchState>>,
-}
-
-impl FileWatcher {
-    /// Creates a live filesystem watcher and starts its background event loop
-    /// on the current Tokio runtime.
-    pub fn new() -> notify::Result<Self> {
-        let (raw_tx, raw_rx) = mpsc::unbounded_channel();
-        let raw_tx_clone = raw_tx;
-        let watcher = notify::recommended_watcher(move |res| {
-            let _ = raw_tx_clone.send(res);
-        })?;
-        let inner = FileWatcherInner {
-            watcher,
-            watched_paths: HashMap::new(),
-        };
-        let state = Arc::new(RwLock::new(WatchState::default()));
-        let file_watcher = Self {
-            inner: Some(Arc::new(Mutex::new(inner))),
-            state,
-        };
-        file_watcher.spawn_event_loop(raw_rx);
-        Ok(file_watcher)
-    }
-
-    /// Creates an inert watcher that only supports test-driven synthetic
-    /// notifications.
-    pub fn noop() -> Self {
-        Self {
-            inner: None,
-            state: Arc::new(RwLock::new(WatchState::default())),
-        }
-    }
-
-    /// Adds a new subscriber and returns both its registration handle and its
-    /// dedicated event receiver.
-    pub fn add_subscriber(self: &Arc<Self>) -> (FileWatcherSubscriber, Receiver) {
-        let (tx, rx) = watch_channel();
-        let mut state = self
-            .state
-            .write()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        let subscriber_id = state.next_subscriber_id;
-        state.next_subscriber_id += 1;
-        state.subscribers.insert(
-            subscriber_id,
-            SubscriberState {
-                watched_paths: HashMap::new(),
-                tx,
-            },
-        );
-
-        let subscriber = FileWatcherSubscriber {
-            id: subscriber_id,
-            file_watcher: self.clone(),
-        };
-        (subscriber, rx)
-    }
-
-    fn register_paths(
-        &self,
-        subscriber_id: SubscriberId,
-        watched_paths: &[SubscriberWatchRegistration],
-    ) {
-        let mut state = self
-            .state
-            .write()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        let mut inner_guard: Option<std::sync::MutexGuard<'_, FileWatcherInner>> = None;
-
-        for registration in watched_paths {
-            let actual = {
-                let Some(subscriber) = state.subscribers.get_mut(&subscriber_id) else {
-                    return;
-                };
-                match subscriber.watched_paths.entry(registration.key.clone()) {
-                    std::collections::hash_map::Entry::Occupied(mut entry) => {
-                        entry.get_mut().count += 1;
-                        entry.get().actual.clone()
-                    }
-                    std::collections::hash_map::Entry::Vacant(entry) => {
-                        entry.insert(SubscriberWatchState {
-                            actual: registration.actual.clone(),
-                            count: 1,
-                            last_exists: registration.key.matched.path.exists(),
-                            fallback: registration.fallback,
-                        });
-                        registration.actual.clone()
-                    }
-                }
-            };
-
-            let counts = state
-                .path_ref_counts
-                .entry(actual.path.clone())
-                .or_default();
-            let previous_mode = counts.effective_mode();
-            counts.increment(actual.recursive, /*amount*/ 1);
-            let next_mode = counts.effective_mode();
-            if previous_mode != next_mode {
-                self.reconfigure_watch(&actual.path, next_mode, &mut inner_guard);
-            }
-        }
-    }
-
-    fn unregister_paths(&self, subscriber_id: SubscriberId, watched_paths: &[SubscriberWatchKey]) {
-        let mut state = self
-            .state
-            .write()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        let mut inner_guard: Option<std::sync::MutexGuard<'_, FileWatcherInner>> = None;
-
-        for subscriber_watch in watched_paths {
-            let actual = {
-                let Some(subscriber) = state.subscribers.get_mut(&subscriber_id) else {
-                    return;
-                };
-                let Some(subscriber_watch_state) =
-                    subscriber.watched_paths.get_mut(subscriber_watch)
-                else {
-                    continue;
-                };
-                let actual = subscriber_watch_state.actual.clone();
-                subscriber_watch_state.count = subscriber_watch_state.count.saturating_sub(1);
-                if subscriber_watch_state.count == 0 {
-                    subscriber.watched_paths.remove(subscriber_watch);
-                }
-                actual
-            };
-
-            let Some(counts) = state.path_ref_counts.get_mut(&actual.path) else {
-                continue;
-            };
-            let previous_mode = counts.effective_mode();
-            counts.decrement(actual.recursive, /*amount*/ 1);
-            let next_mode = counts.effective_mode();
-            if counts.is_empty() {
-                state.path_ref_counts.remove(&actual.path);
-            }
-            if previous_mode != next_mode {
-                self.reconfigure_watch(&actual.path, next_mode, &mut inner_guard);
-            }
-        }
-    }
-
-    fn remove_subscriber(&self, subscriber_id: SubscriberId) {
-        let mut state = self
-            .state
-            .write()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        let Some(subscriber) = state.subscribers.remove(&subscriber_id) else {
-            return;
-        };
-
-        let mut inner_guard: Option<std::sync::MutexGuard<'_, FileWatcherInner>> = None;
-        for (_subscriber_watch, subscriber_watch_state) in subscriber.watched_paths {
-            let Some(path_counts) = state
-                .path_ref_counts
-                .get_mut(&subscriber_watch_state.actual.path)
-            else {
-                continue;
-            };
-            let previous_mode = path_counts.effective_mode();
-            path_counts.decrement(
-                subscriber_watch_state.actual.recursive,
-                subscriber_watch_state.count,
-            );
-            let next_mode = path_counts.effective_mode();
-            if path_counts.is_empty() {
-                state
-                    .path_ref_counts
-                    .remove(&subscriber_watch_state.actual.path);
-            }
-            if previous_mode != next_mode {
-                self.reconfigure_watch(
-                    &subscriber_watch_state.actual.path,
-                    next_mode,
-                    &mut inner_guard,
-                );
-            }
-        }
-    }
-
-    fn reconfigure_watch<'a>(
-        &'a self,
-        path: &Path,
-        next_mode: Option<RecursiveMode>,
-        inner_guard: &mut Option<std::sync::MutexGuard<'a, FileWatcherInner>>,
-    ) {
-        Self::reconfigure_watch_inner(self.inner.as_ref(), path, next_mode, inner_guard);
-    }
-
-    fn reconfigure_watch_inner<'a>(
-        inner: Option<&'a Arc<Mutex<FileWatcherInner>>>,
-        path: &Path,
-        next_mode: Option<RecursiveMode>,
-        inner_guard: &mut Option<std::sync::MutexGuard<'a, FileWatcherInner>>,
-    ) {
-        let Some(inner) = inner else {
-            return;
-        };
-        if inner_guard.is_none() {
-            let guard = inner
-                .lock()
-                .unwrap_or_else(std::sync::PoisonError::into_inner);
-            *inner_guard = Some(guard);
-        }
-        let Some(guard) = inner_guard.as_mut() else {
-            return;
-        };
-
-        let existing_mode = guard.watched_paths.get(path).copied();
-        if existing_mode == next_mode {
-            return;
-        }
-
-        if existing_mode.is_some() {
-            if let Err(err) = guard.watcher.unwatch(path) {
-                warn!("failed to unwatch {}: {err}", path.display());
-            }
-            guard.watched_paths.remove(path);
-        }
-
-        let Some(next_mode) = next_mode else {
-            return;
-        };
-        if !path.exists() {
-            return;
-        }
-
-        if let Err(err) = guard.watcher.watch(path, next_mode) {
-            warn!("failed to watch {}: {err}", path.display());
-            return;
-        }
-        guard.watched_paths.insert(path.to_path_buf(), next_mode);
-    }
-
-    fn apply_actual_watch_move<'a>(
-        path_ref_counts: &mut HashMap<PathBuf, PathWatchCounts>,
-        old_actual: WatchPath,
-        new_actual: WatchPath,
-        count: usize,
-        inner: Option<&'a Arc<Mutex<FileWatcherInner>>>,
-        inner_guard: &mut Option<std::sync::MutexGuard<'a, FileWatcherInner>>,
-    ) {
-        if old_actual == new_actual {
-            return;
-        }
-
-        if let Some(counts) = path_ref_counts.get_mut(&old_actual.path) {
-            let previous_mode = counts.effective_mode();
-            counts.decrement(old_actual.recursive, count);
-            let next_mode = counts.effective_mode();
-            if counts.is_empty() {
-                path_ref_counts.remove(&old_actual.path);
-            }
-            if previous_mode != next_mode {
-                Self::reconfigure_watch_inner(inner, &old_actual.path, next_mode, inner_guard);
-            }
-        }
-
-        let counts = path_ref_counts.entry(new_actual.path.clone()).or_default();
-        let previous_mode = counts.effective_mode();
-        counts.increment(new_actual.recursive, count);
-        let next_mode = counts.effective_mode();
-        if previous_mode != next_mode {
-            Self::reconfigure_watch_inner(inner, &new_actual.path, next_mode, inner_guard);
-        }
-    }
-
-    // Bridge `notify`'s callback-based events into the Tokio runtime and
-    // notify the matching subscribers.
-    fn spawn_event_loop(&self, mut raw_rx: mpsc::UnboundedReceiver<notify::Result<Event>>) {
-        if let Ok(handle) = Handle::try_current() {
-            let state = Arc::clone(&self.state);
-            let inner = self.inner.as_ref().map(Arc::downgrade);
-            handle.spawn(async move {
-                loop {
-                    match raw_rx.recv().await {
-                        Some(Ok(event)) => {
-                            if !is_mutating_event(&event) {
-                                continue;
-                            }
-                            if event.paths.is_empty() {
-                                continue;
-                            }
-                            let inner = inner.as_ref().and_then(std::sync::Weak::upgrade);
-                            Self::notify_subscribers(&state, inner.as_ref(), &event.paths).await;
-                        }
-                        Some(Err(err)) => {
-                            warn!("file watcher error: {err}");
-                        }
-                        None => break,
-                    }
-                }
-            });
-        } else {
-            warn!("file watcher loop skipped: no Tokio runtime available");
-        }
-    }
-
-    async fn notify_subscribers(
-        state: &RwLock<WatchState>,
-        inner: Option<&Arc<Mutex<FileWatcherInner>>>,
-        event_paths: &[PathBuf],
-    ) {
-        let subscribers_to_notify: Vec<(WatchSender, Vec<PathBuf>)> = {
-            let mut state = state
-                .write()
-                .unwrap_or_else(std::sync::PoisonError::into_inner);
-            let mut actual_watch_moves = Vec::new();
-            let mut subscribers_to_notify = Vec::new();
-
-            for subscriber in state.subscribers.values_mut() {
-                let mut changed_paths = Vec::new();
-                for event_path in event_paths {
-                    for (subscriber_watch, subscriber_watch_state) in &mut subscriber.watched_paths
-                    {
-                        if let Some(path) = changed_path_for_event(
-                            subscriber_watch,
-                            subscriber_watch_state,
-                            event_path,
-                        ) {
-                            changed_paths.push(path);
-                        }
-
-                        let (new_actual, _new_matched, fallback) =
-                            actual_watch_path(&subscriber_watch.requested);
-                        subscriber_watch_state.fallback |= fallback;
-                        if subscriber_watch_state.actual != new_actual {
-                            let old_actual = subscriber_watch_state.actual.clone();
-                            let count = subscriber_watch_state.count;
-                            subscriber_watch_state.actual = new_actual.clone();
-                            actual_watch_moves.push((old_actual, new_actual, count));
-                        }
-                    }
-                }
-                if !changed_paths.is_empty() {
-                    subscribers_to_notify.push((subscriber.tx.clone(), changed_paths));
-                }
-            }
-
-            let mut inner_guard: Option<std::sync::MutexGuard<'_, FileWatcherInner>> = None;
-            for (old_actual, new_actual, count) in actual_watch_moves {
-                Self::apply_actual_watch_move(
-                    &mut state.path_ref_counts,
-                    old_actual,
-                    new_actual,
-                    count,
-                    inner,
-                    &mut inner_guard,
-                );
-            }
-
-            subscribers_to_notify
-        };
-
-        for (subscriber, changed_paths) in subscribers_to_notify {
-            subscriber.add_changed_paths(&changed_paths).await;
-        }
-    }
-
-    #[cfg(test)]
-    pub(crate) async fn send_paths_for_test(&self, paths: Vec<PathBuf>) {
-        Self::notify_subscribers(&self.state, self.inner.as_ref(), &paths).await;
-    }
-
-    #[cfg(test)]
-    pub(crate) fn spawn_event_loop_for_test(
-        &self,
-        raw_rx: mpsc::UnboundedReceiver<notify::Result<Event>>,
-    ) {
-        self.spawn_event_loop(raw_rx);
-    }
-
-    #[cfg(test)]
-    pub(crate) fn watch_counts_for_test(&self, path: &Path) -> Option<(usize, usize)> {
-        let state = self
-            .state
-            .read()
-            .unwrap_or_else(std::sync::PoisonError::into_inner);
-        state
-            .path_ref_counts
-            .get(path)
-            .map(|counts| (counts.non_recursive, counts.recursive))
-    }
-}
-
-fn is_mutating_event(event: &Event) -> bool {
-    matches!(
-        event.kind,
-        EventKind::Create(_) | EventKind::Modify(_) | EventKind::Remove(_)
-    )
-}
-
-fn dedupe_watched_paths(mut watched_paths: Vec<WatchPath>) -> Vec<WatchPath> {
-    watched_paths.sort_unstable_by(|a, b| {
-        a.path
-            .as_os_str()
-            .cmp(b.path.as_os_str())
-            .then(a.recursive.cmp(&b.recursive))
-    });
-    watched_paths.dedup();
-    watched_paths
-}
-
-/// Returns the actual OS watch path and canonical match path for a request.
-///
-/// Missing targets are watched non-recursively through the nearest existing
-/// directory ancestor. As path components appear, the actual watch is moved
-/// closer to the requested path so broad recursive ancestor watches are never
-/// needed.
-fn actual_watch_path(requested: &WatchPath) -> (WatchPath, WatchPath, bool) {
-    if requested.path.exists() {
-        let matched_path = requested
-            .path
-            .canonicalize()
-            .unwrap_or_else(|_| requested.path.clone());
-        let actual = requested.clone();
-        let matched = WatchPath {
-            path: matched_path,
-            recursive: requested.recursive,
-        };
-        return (actual, matched, false);
-    }
-
-    let requested_parent = requested.path.parent();
-    let mut ancestor = requested_parent;
-    while let Some(path) = ancestor {
-        if path.is_dir() {
-            let actual_path = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
-            let matched_path = requested
-                .path
-                .strip_prefix(path)
-                .map(|suffix| actual_path.join(suffix))
-                .unwrap_or_else(|_| requested.path.clone());
-            let actual = WatchPath {
-                path: path.to_path_buf(),
-                recursive: false,
-            };
-            let matched = WatchPath {
-                path: matched_path,
-                recursive: requested.recursive,
-            };
-            return (actual, matched, true);
-        }
-        ancestor = path.parent();
-    }
-
-    (requested.clone(), requested.clone(), false)
-}
-
-/// Converts one raw backend event path into the subscriber-visible path.
-///
-/// Matching first uses the canonical path namespace reported by many OS
-/// backends, then falls back to the originally requested namespace for
-/// synthetic tests and backends that preserve the input spelling.
-fn changed_path_for_event(
-    subscriber_watch: &SubscriberWatchKey,
-    subscriber_watch_state: &mut SubscriberWatchState,
-    event_path: &Path,
-) -> Option<PathBuf> {
-    if let Some(path) = changed_path_for_matched_path(
-        subscriber_watch,
-        subscriber_watch_state,
-        &subscriber_watch.matched,
-        event_path,
-    ) {
-        return Some(path);
-    }
-    if subscriber_watch.matched.path == subscriber_watch.requested.path {
-        return None;
-    }
-    changed_path_for_matched_path(
-        subscriber_watch,
-        subscriber_watch_state,
-        &subscriber_watch.requested,
-        event_path,
-    )
-}
-
-/// Applies the watch matching rules in one path namespace and maps any emitted
-/// path back into the subscriber's requested namespace.
-fn changed_path_for_matched_path(
-    subscriber_watch: &SubscriberWatchKey,
-    subscriber_watch_state: &mut SubscriberWatchState,
-    matched: &WatchPath,
-    event_path: &Path,
-) -> Option<PathBuf> {
-    let requested = &subscriber_watch.requested;
-    if event_path == matched.path {
-        subscriber_watch_state.last_exists = matched.path.exists();
-        return Some(requested.path.clone());
-    }
-    if matched.path.starts_with(event_path) {
-        let now_exists = matched.path.exists();
-        if subscriber_watch_state.fallback {
-            let should_notify = now_exists || subscriber_watch_state.last_exists;
-            subscriber_watch_state.last_exists = now_exists;
-            return should_notify.then(|| requested.path.clone());
-        }
-        if subscriber_watch_state.actual.path != matched.path {
-            let should_notify = now_exists || subscriber_watch_state.last_exists;
-            subscriber_watch_state.last_exists = now_exists;
-            return should_notify.then(|| requested.path.clone());
-        }
-        subscriber_watch_state.last_exists = now_exists;
-        return Some(event_path.to_path_buf());
-    }
-    if !event_path.starts_with(&matched.path) {
-        return None;
-    }
-    if !(matched.recursive || event_path.parent() == Some(matched.path.as_path())) {
-        return None;
-    }
-    subscriber_watch_state.last_exists = matched.path.exists();
-    Some(
-        event_path
-            .strip_prefix(&matched.path)
-            .map(|suffix| requested.path.join(suffix))
-            .unwrap_or_else(|_| event_path.to_path_buf()),
-    )
-}
-
-#[cfg(test)]
-#[path = "file_watcher_tests.rs"]
-mod tests;
+pub use codex_file_watcher::*;

codex-rs/core/src/mcp_tool_approval_templates.rs

@@ -1,371 +1,2 @@
-use std::collections::HashSet;
-use std::sync::LazyLock;
-
-use serde::Deserialize;
-use serde::Serialize;
-use serde_json::Map;
-use serde_json::Value;
-use tracing::warn;
-
-const CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES_SCHEMA_VERSION: u8 = 4;
-const CONNECTOR_NAME_TEMPLATE_VAR: &str = "{connector_name}";
-
-static CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES: LazyLock<
-    Option<Vec<ConsequentialToolMessageTemplate>>,
-> = LazyLock::new(load_consequential_tool_message_templates);
-
-#[derive(Clone, Debug, PartialEq)]
-pub(crate) struct RenderedMcpToolApprovalTemplate {
-    pub(crate) question: String,
-    pub(crate) elicitation_message: String,
-    pub(crate) tool_params: Option<Value>,
-    pub(crate) tool_params_display: Vec<RenderedMcpToolApprovalParam>,
-}
-
-#[derive(Clone, Debug, PartialEq, Serialize)]
-pub(crate) struct RenderedMcpToolApprovalParam {
-    pub(crate) name: String,
-    pub(crate) value: Value,
-    pub(crate) display_name: String,
-}
-
-#[derive(Debug, Deserialize)]
-struct ConsequentialToolMessageTemplatesFile {
-    schema_version: u8,
-    templates: Vec<ConsequentialToolMessageTemplate>,
-}
-
-#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
-struct ConsequentialToolMessageTemplate {
-    connector_id: String,
-    server_name: String,
-    tool_title: String,
-    template: String,
-    template_params: Vec<ConsequentialToolTemplateParam>,
-}
-
-#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
-struct ConsequentialToolTemplateParam {
-    name: String,
-    label: String,
-}
-
-pub(crate) fn render_mcp_tool_approval_template(
-    server_name: &str,
-    connector_id: Option<&str>,
-    connector_name: Option<&str>,
-    tool_title: Option<&str>,
-    tool_params: Option<&Value>,
-) -> Option<RenderedMcpToolApprovalTemplate> {
-    let templates = CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES.as_ref()?;
-    render_mcp_tool_approval_template_from_templates(
-        templates,
-        server_name,
-        connector_id,
-        connector_name,
-        tool_title,
-        tool_params,
-    )
-}
-
-fn load_consequential_tool_message_templates() -> Option<Vec<ConsequentialToolMessageTemplate>> {
-    let templates = match serde_json::from_str::<ConsequentialToolMessageTemplatesFile>(
-        include_str!("consequential_tool_message_templates.json"),
-    ) {
-        Ok(templates) => templates,
-        Err(err) => {
-            warn!(error = %err, "failed to parse consequential tool approval templates");
-            return None;
-        }
-    };
-
-    if templates.schema_version != CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES_SCHEMA_VERSION {
-        warn!(
-            found_schema_version = templates.schema_version,
-            expected_schema_version = CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES_SCHEMA_VERSION,
-            "unexpected consequential tool approval templates schema version"
-        );
-        return None;
-    }
-
-    Some(templates.templates)
-}
-
-fn render_mcp_tool_approval_template_from_templates(
-    templates: &[ConsequentialToolMessageTemplate],
-    server_name: &str,
-    connector_id: Option<&str>,
-    connector_name: Option<&str>,
-    tool_title: Option<&str>,
-    tool_params: Option<&Value>,
-) -> Option<RenderedMcpToolApprovalTemplate> {
-    let connector_id = connector_id?;
-    let tool_title = tool_title.map(str::trim).filter(|name| !name.is_empty())?;
-    let template = templates.iter().find(|template| {
-        template.server_name == server_name
-            && template.connector_id == connector_id
-            && template.tool_title == tool_title
-    })?;
-    let elicitation_message = render_question_template(&template.template, connector_name)?;
-    let (tool_params, tool_params_display) = match tool_params {
-        Some(Value::Object(tool_params)) => {
-            render_tool_params(tool_params, &template.template_params)?
-        }
-        Some(_) => return None,
-        None => (None, Vec::new()),
-    };
-
-    Some(RenderedMcpToolApprovalTemplate {
-        question: elicitation_message.clone(),
-        elicitation_message,
-        tool_params,
-        tool_params_display,
-    })
-}
-
-fn render_question_template(template: &str, connector_name: Option<&str>) -> Option<String> {
-    let template = template.trim();
-    if template.is_empty() {
-        return None;
-    }
-
-    if template.contains(CONNECTOR_NAME_TEMPLATE_VAR) {
-        let connector_name = connector_name
-            .map(str::trim)
-            .filter(|name| !name.is_empty())?;
-        return Some(template.replace(CONNECTOR_NAME_TEMPLATE_VAR, connector_name));
-    }
-
-    Some(template.to_string())
-}
-
-fn render_tool_params(
-    tool_params: &Map<String, Value>,
-    template_params: &[ConsequentialToolTemplateParam],
-) -> Option<(Option<Value>, Vec<RenderedMcpToolApprovalParam>)> {
-    let mut display_params = Vec::new();
-    let mut display_names = HashSet::new();
-    let mut handled_names = HashSet::new();
-
-    for template_param in template_params {
-        let label = template_param.label.trim();
-        if label.is_empty() {
-            return None;
-        }
-        let Some(value) = tool_params.get(&template_param.name) else {
-            continue;
-        };
-        if !display_names.insert(label.to_string()) {
-            return None;
-        }
-        display_params.push(RenderedMcpToolApprovalParam {
-            name: template_param.name.clone(),
-            value: value.clone(),
-            display_name: label.to_string(),
-        });
-        handled_names.insert(template_param.name.as_str());
-    }
-
-    let mut remaining_params = tool_params
-        .iter()
-        .filter(|(name, _)| !handled_names.contains(name.as_str()))
-        .collect::<Vec<_>>();
-    remaining_params.sort_by(|(left_name, _), (right_name, _)| left_name.cmp(right_name));
-
-    for (name, value) in remaining_params {
-        if handled_names.contains(name.as_str()) {
-            continue;
-        }
-        if !display_names.insert(name.clone()) {
-            return None;
-        }
-        display_params.push(RenderedMcpToolApprovalParam {
-            name: name.clone(),
-            value: value.clone(),
-            display_name: name.clone(),
-        });
-    }
-
-    Some((Some(Value::Object(tool_params.clone())), display_params))
-}
-
-#[cfg(test)]
-mod tests {
-    use pretty_assertions::assert_eq;
-    use serde_json::json;
-
-    use super::*;
-
-    #[test]
-    fn renders_exact_match_with_readable_param_labels() {
-        let templates = vec![ConsequentialToolMessageTemplate {
-            connector_id: "calendar".to_string(),
-            server_name: "codex_apps".to_string(),
-            tool_title: "create_event".to_string(),
-            template: "Allow {connector_name} to create an event?".to_string(),
-            template_params: vec![
-                ConsequentialToolTemplateParam {
-                    name: "calendar_id".to_string(),
-                    label: "Calendar".to_string(),
-                },
-                ConsequentialToolTemplateParam {
-                    name: "title".to_string(),
-                    label: "Title".to_string(),
-                },
-            ],
-        }];
-
-        let rendered = render_mcp_tool_approval_template_from_templates(
-            &templates,
-            "codex_apps",
-            Some("calendar"),
-            Some("Calendar"),
-            Some("create_event"),
-            Some(&json!({
-                "title": "Roadmap review",
-                "calendar_id": "primary",
-                "timezone": "UTC",
-            })),
-        );
-
-        assert_eq!(
-            rendered,
-            Some(RenderedMcpToolApprovalTemplate {
-                question: "Allow Calendar to create an event?".to_string(),
-                elicitation_message: "Allow Calendar to create an event?".to_string(),
-                tool_params: Some(json!({
-                    "title": "Roadmap review",
-                    "calendar_id": "primary",
-                    "timezone": "UTC",
-                })),
-                tool_params_display: vec![
-                    RenderedMcpToolApprovalParam {
-                        name: "calendar_id".to_string(),
-                        value: json!("primary"),
-                        display_name: "Calendar".to_string(),
-                    },
-                    RenderedMcpToolApprovalParam {
-                        name: "title".to_string(),
-                        value: json!("Roadmap review"),
-                        display_name: "Title".to_string(),
-                    },
-                    RenderedMcpToolApprovalParam {
-                        name: "timezone".to_string(),
-                        value: json!("UTC"),
-                        display_name: "timezone".to_string(),
-                    },
-                ],
-            })
-        );
-    }
-
-    #[test]
-    fn returns_none_when_no_exact_match_exists() {
-        let templates = vec![ConsequentialToolMessageTemplate {
-            connector_id: "calendar".to_string(),
-            server_name: "codex_apps".to_string(),
-            tool_title: "create_event".to_string(),
-            template: "Allow {connector_name} to create an event?".to_string(),
-            template_params: Vec::new(),
-        }];
-
-        assert_eq!(
-            render_mcp_tool_approval_template_from_templates(
-                &templates,
-                "codex_apps",
-                Some("calendar"),
-                Some("Calendar"),
-                Some("delete_event"),
-                Some(&json!({})),
-            ),
-            None
-        );
-    }
-
-    #[test]
-    fn returns_none_when_relabeling_would_collide() {
-        let templates = vec![ConsequentialToolMessageTemplate {
-            connector_id: "calendar".to_string(),
-            server_name: "codex_apps".to_string(),
-            tool_title: "create_event".to_string(),
-            template: "Allow {connector_name} to create an event?".to_string(),
-            template_params: vec![ConsequentialToolTemplateParam {
-                name: "calendar_id".to_string(),
-                label: "timezone".to_string(),
-            }],
-        }];
-
-        assert_eq!(
-            render_mcp_tool_approval_template_from_templates(
-                &templates,
-                "codex_apps",
-                Some("calendar"),
-                Some("Calendar"),
-                Some("create_event"),
-                Some(&json!({
-                    "calendar_id": "primary",
-                    "timezone": "UTC",
-                })),
-            ),
-            None
-        );
-    }
-
-    #[test]
-    fn bundled_templates_load() {
-        assert_eq!(CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES.is_some(), true);
-    }
-
-    #[test]
-    fn renders_literal_template_without_connector_substitution() {
-        let templates = vec![ConsequentialToolMessageTemplate {
-            connector_id: "github".to_string(),
-            server_name: "codex_apps".to_string(),
-            tool_title: "add_comment".to_string(),
-            template: "Allow GitHub to add a comment to a pull request?".to_string(),
-            template_params: Vec::new(),
-        }];
-
-        let rendered = render_mcp_tool_approval_template_from_templates(
-            &templates,
-            "codex_apps",
-            Some("github"),
-            /*connector_name*/ None,
-            Some("add_comment"),
-            Some(&json!({})),
-        );
-
-        assert_eq!(
-            rendered,
-            Some(RenderedMcpToolApprovalTemplate {
-                question: "Allow GitHub to add a comment to a pull request?".to_string(),
-                elicitation_message: "Allow GitHub to add a comment to a pull request?".to_string(),
-                tool_params: Some(json!({})),
-                tool_params_display: Vec::new(),
-            })
-        );
-    }
-
-    #[test]
-    fn returns_none_when_connector_placeholder_has_no_value() {
-        let templates = vec![ConsequentialToolMessageTemplate {
-            connector_id: "calendar".to_string(),
-            server_name: "codex_apps".to_string(),
-            tool_title: "create_event".to_string(),
-            template: "Allow {connector_name} to create an event?".to_string(),
-            template_params: Vec::new(),
-        }];
-
-        assert_eq!(
-            render_mcp_tool_approval_template_from_templates(
-                &templates,
-                "codex_apps",
-                Some("calendar"),
-                /*connector_name*/ None,
-                Some("create_event"),
-                Some(&json!({})),
-            ),
-            None
-        );
-    }
-}
+pub(crate) use codex_mcp_tool_approval_templates::RenderedMcpToolApprovalParam;
+pub(crate) use codex_mcp_tool_approval_templates::render_mcp_tool_approval_template;

codex-rs/file-watcher/BUILD.bazel

@@ -0,0 +1,6 @@
+load("//:defs.bzl", "codex_rust_crate")
+
+codex_rust_crate(
+    name = "file-watcher",
+    crate_name = "codex_file_watcher",
+)

codex-rs/file-watcher/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "codex-file-watcher"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[lib]
+name = "codex_file_watcher"
+path = "src/lib.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+notify = { workspace = true }
+tokio = { workspace = true, features = [
+    "macros",
+    "rt",
+    "sync",
+    "time",
+] }
+tracing = { workspace = true, features = ["log"] }
+
+[dev-dependencies]
+pretty_assertions = { workspace = true }
+tempfile = { workspace = true }

codex-rs/file-watcher/src/lib.rs

@@ -0,0 +1,856 @@
+//! Watches subscribed files or directories and routes coarse-grained change
+//! notifications to the subscribers that own matching watched paths.
+
+use std::collections::BTreeSet;
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::sync::Mutex;
+use std::sync::RwLock;
+use std::sync::atomic::AtomicUsize;
+use std::sync::atomic::Ordering;
+use std::time::Duration;
+
+use notify::Event;
+use notify::EventKind;
+use notify::RecommendedWatcher;
+use notify::RecursiveMode;
+use notify::Watcher;
+use tokio::runtime::Handle;
+use tokio::sync::Mutex as AsyncMutex;
+use tokio::sync::Notify;
+use tokio::sync::mpsc;
+use tokio::time::Instant;
+use tokio::time::sleep_until;
+use tracing::warn;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+/// Coalesced file change notification for a subscriber.
+pub struct FileWatcherEvent {
+    /// Changed paths delivered in sorted order with duplicates removed.
+    pub paths: Vec<PathBuf>,
+}
+
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+/// Path subscription registered by a [`FileWatcherSubscriber`].
+pub struct WatchPath {
+    /// Root path to watch.
+    pub path: PathBuf,
+    /// Whether events below `path` should match recursively.
+    pub recursive: bool,
+}
+
+type SubscriberId = u64;
+
+#[derive(Default)]
+struct WatchState {
+    next_subscriber_id: SubscriberId,
+    path_ref_counts: HashMap<PathBuf, PathWatchCounts>,
+    subscribers: HashMap<SubscriberId, SubscriberState>,
+}
+
+struct SubscriberState {
+    watched_paths: HashMap<SubscriberWatchKey, SubscriberWatchState>,
+    tx: WatchSender,
+}
+
+/// Immutable per-subscriber watch identity.
+#[derive(Clone, Debug, Eq, Hash, PartialEq)]
+struct SubscriberWatchKey {
+    /// Original path requested by the subscriber. Notifications are reported
+    /// in this namespace so clients do not see canonicalization artifacts.
+    requested: WatchPath,
+    /// Canonical equivalent of `requested` used to match backend events.
+    /// Some backends report canonical paths such as `/private/var/...` even
+    /// when the watch was registered through `/var/...`.
+    matched: WatchPath,
+}
+
+/// Mutable per-subscriber watch state.
+struct SubscriberWatchState {
+    /// Existing path passed to the OS watcher and used for ref-counting. This
+    /// is usually `requested`, but missing targets use an existing ancestor.
+    actual: WatchPath,
+    count: usize,
+    /// Whether the requested path existed the last time an ancestor event was
+    /// handled. This preserves delete notifications for fallback watches.
+    last_exists: bool,
+    /// Whether this watch started from a missing path. Such watches normalize
+    /// ancestor create/delete events back to `requested`.
+    fallback: bool,
+}
+
+/// Registration-time watch data before it is merged into subscriber state.
+///
+/// The key is stable for unregistering while `actual` may later move closer
+/// to the requested path as missing path components are created.
+#[derive(Clone)]
+struct SubscriberWatchRegistration {
+    /// Immutable subscriber-visible identity for this registration.
+    key: SubscriberWatchKey,
+    /// Existing path initially passed to the OS watcher.
+    actual: WatchPath,
+    /// Whether registration started from a missing path fallback.
+    fallback: bool,
+}
+
+/// Receives coalesced change notifications for a single subscriber.
+pub struct Receiver {
+    inner: Arc<ReceiverInner>,
+}
+
+struct WatchSender {
+    inner: Arc<ReceiverInner>,
+}
+
+struct ReceiverInner {
+    changed_paths: AsyncMutex<BTreeSet<PathBuf>>,
+    notify: Notify,
+    sender_count: AtomicUsize,
+}
+
+impl Receiver {
+    /// Waits for the next batch of changed paths, or returns `None` once the
+    /// corresponding subscriber has been removed and no more events can arrive.
+    pub async fn recv(&mut self) -> Option<FileWatcherEvent> {
+        loop {
+            let notified = self.inner.notify.notified();
+            {
+                let mut changed_paths = self.inner.changed_paths.lock().await;
+                if !changed_paths.is_empty() {
+                    return Some(FileWatcherEvent {
+                        paths: std::mem::take(&mut *changed_paths).into_iter().collect(),
+                    });
+                }
+                if self.inner.sender_count.load(Ordering::Acquire) == 0 {
+                    return None;
+                }
+            }
+            notified.await;
+        }
+    }
+}
+
+impl WatchSender {
+    async fn add_changed_paths(&self, paths: &[PathBuf]) {
+        if paths.is_empty() {
+            return;
+        }
+
+        let mut changed_paths = self.inner.changed_paths.lock().await;
+        let previous_len = changed_paths.len();
+        changed_paths.extend(paths.iter().cloned());
+        if changed_paths.len() != previous_len {
+            self.inner.notify.notify_one();
+        }
+    }
+}
+
+impl Clone for WatchSender {
+    fn clone(&self) -> Self {
+        self.inner.sender_count.fetch_add(1, Ordering::Relaxed);
+        Self {
+            inner: Arc::clone(&self.inner),
+        }
+    }
+}
+
+impl Drop for WatchSender {
+    fn drop(&mut self) {
+        if self.inner.sender_count.fetch_sub(1, Ordering::AcqRel) == 1 {
+            self.inner.notify.notify_waiters();
+        }
+    }
+}
+
+fn watch_channel() -> (WatchSender, Receiver) {
+    let inner = Arc::new(ReceiverInner {
+        changed_paths: AsyncMutex::new(BTreeSet::new()),
+        notify: Notify::new(),
+        sender_count: AtomicUsize::new(1),
+    });
+    (
+        WatchSender {
+            inner: Arc::clone(&inner),
+        },
+        Receiver { inner },
+    )
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+struct PathWatchCounts {
+    non_recursive: usize,
+    recursive: usize,
+}
+
+impl PathWatchCounts {
+    fn increment(&mut self, recursive: bool, amount: usize) {
+        if recursive {
+            self.recursive += amount;
+        } else {
+            self.non_recursive += amount;
+        }
+    }
+
+    fn decrement(&mut self, recursive: bool, amount: usize) {
+        if recursive {
+            self.recursive = self.recursive.saturating_sub(amount);
+        } else {
+            self.non_recursive = self.non_recursive.saturating_sub(amount);
+        }
+    }
+
+    fn effective_mode(self) -> Option<RecursiveMode> {
+        if self.recursive > 0 {
+            Some(RecursiveMode::Recursive)
+        } else if self.non_recursive > 0 {
+            Some(RecursiveMode::NonRecursive)
+        } else {
+            None
+        }
+    }
+
+    fn is_empty(self) -> bool {
+        self.non_recursive == 0 && self.recursive == 0
+    }
+}
+
+struct FileWatcherInner {
+    watcher: RecommendedWatcher,
+    watched_paths: HashMap<PathBuf, RecursiveMode>,
+}
+
+/// Coalesces bursts of watch notifications and emits at most once per interval.
+pub struct ThrottledWatchReceiver {
+    rx: Receiver,
+    interval: Duration,
+    next_allowed: Option<Instant>,
+}
+
+impl ThrottledWatchReceiver {
+    /// Creates a throttling wrapper around a raw watcher [`Receiver`].
+    pub fn new(rx: Receiver, interval: Duration) -> Self {
+        Self {
+            rx,
+            interval,
+            next_allowed: None,
+        }
+    }
+
+    /// Receives the next event, enforcing the configured minimum delay after
+    /// the previous emission.
+    pub async fn recv(&mut self) -> Option<FileWatcherEvent> {
+        if let Some(next_allowed) = self.next_allowed {
+            sleep_until(next_allowed).await;
+        }
+
+        let event = self.rx.recv().await;
+        if event.is_some() {
+            self.next_allowed = Some(Instant::now() + self.interval);
+        }
+        event
+    }
+}
+
+/// Handle used to register watched paths for one logical consumer.
+pub struct FileWatcherSubscriber {
+    id: SubscriberId,
+    file_watcher: Arc<FileWatcher>,
+}
+
+impl FileWatcherSubscriber {
+    /// Registers the provided paths for this subscriber and returns an RAII
+    /// guard that unregisters them on drop.
+    pub fn register_paths(&self, watched_paths: Vec<WatchPath>) -> WatchRegistration {
+        let watched_paths = dedupe_watched_paths(watched_paths)
+            .into_iter()
+            .map(|requested| {
+                let (actual, matched, fallback) = actual_watch_path(&requested);
+                let key = SubscriberWatchKey { requested, matched };
+                SubscriberWatchRegistration {
+                    key,
+                    actual,
+                    fallback,
+                }
+            })
+            .collect::<Vec<_>>();
+        self.file_watcher.register_paths(self.id, &watched_paths);
+
+        WatchRegistration {
+            file_watcher: Arc::downgrade(&self.file_watcher),
+            subscriber_id: self.id,
+            watched_paths: watched_paths
+                .iter()
+                .map(|watch| watch.key.clone())
+                .collect(),
+        }
+    }
+
+    #[doc(hidden)]
+    pub fn register_path(&self, path: PathBuf, recursive: bool) -> WatchRegistration {
+        self.register_paths(vec![WatchPath { path, recursive }])
+    }
+}
+
+impl Drop for FileWatcherSubscriber {
+    fn drop(&mut self) {
+        self.file_watcher.remove_subscriber(self.id);
+    }
+}
+
+/// RAII guard for a set of active path registrations.
+pub struct WatchRegistration {
+    file_watcher: std::sync::Weak<FileWatcher>,
+    subscriber_id: SubscriberId,
+    watched_paths: Vec<SubscriberWatchKey>,
+}
+
+impl Default for WatchRegistration {
+    fn default() -> Self {
+        Self {
+            file_watcher: std::sync::Weak::new(),
+            subscriber_id: 0,
+            watched_paths: Vec::new(),
+        }
+    }
+}
+
+impl Drop for WatchRegistration {
+    fn drop(&mut self) {
+        if let Some(file_watcher) = self.file_watcher.upgrade() {
+            file_watcher.unregister_paths(self.subscriber_id, &self.watched_paths);
+        }
+    }
+}
+
+/// Multi-subscriber file watcher built on top of `notify`.
+pub struct FileWatcher {
+    inner: Option<Arc<Mutex<FileWatcherInner>>>,
+    state: Arc<RwLock<WatchState>>,
+}
+
+impl FileWatcher {
+    /// Creates a live filesystem watcher and starts its background event loop
+    /// on the current Tokio runtime.
+    pub fn new() -> notify::Result<Self> {
+        let (raw_tx, raw_rx) = mpsc::unbounded_channel();
+        let raw_tx_clone = raw_tx;
+        let watcher = notify::recommended_watcher(move |res| {
+            let _ = raw_tx_clone.send(res);
+        })?;
+        let inner = FileWatcherInner {
+            watcher,
+            watched_paths: HashMap::new(),
+        };
+        let state = Arc::new(RwLock::new(WatchState::default()));
+        let file_watcher = Self {
+            inner: Some(Arc::new(Mutex::new(inner))),
+            state,
+        };
+        file_watcher.spawn_event_loop(raw_rx);
+        Ok(file_watcher)
+    }
+
+    /// Creates an inert watcher that only supports test-driven synthetic
+    /// notifications.
+    pub fn noop() -> Self {
+        Self {
+            inner: None,
+            state: Arc::new(RwLock::new(WatchState::default())),
+        }
+    }
+
+    /// Adds a new subscriber and returns both its registration handle and its
+    /// dedicated event receiver.
+    pub fn add_subscriber(self: &Arc<Self>) -> (FileWatcherSubscriber, Receiver) {
+        let (tx, rx) = watch_channel();
+        let mut state = self
+            .state
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let subscriber_id = state.next_subscriber_id;
+        state.next_subscriber_id += 1;
+        state.subscribers.insert(
+            subscriber_id,
+            SubscriberState {
+                watched_paths: HashMap::new(),
+                tx,
+            },
+        );
+
+        let subscriber = FileWatcherSubscriber {
+            id: subscriber_id,
+            file_watcher: self.clone(),
+        };
+        (subscriber, rx)
+    }
+
+    fn register_paths(
+        &self,
+        subscriber_id: SubscriberId,
+        watched_paths: &[SubscriberWatchRegistration],
+    ) {
+        let mut state = self
+            .state
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let mut inner_guard: Option<std::sync::MutexGuard<'_, FileWatcherInner>> = None;
+
+        for registration in watched_paths {
+            let actual = {
+                let Some(subscriber) = state.subscribers.get_mut(&subscriber_id) else {
+                    return;
+                };
+                match subscriber.watched_paths.entry(registration.key.clone()) {
+                    std::collections::hash_map::Entry::Occupied(mut entry) => {
+                        entry.get_mut().count += 1;
+                        entry.get().actual.clone()
+                    }
+                    std::collections::hash_map::Entry::Vacant(entry) => {
+                        entry.insert(SubscriberWatchState {
+                            actual: registration.actual.clone(),
+                            count: 1,
+                            last_exists: registration.key.matched.path.exists(),
+                            fallback: registration.fallback,
+                        });
+                        registration.actual.clone()
+                    }
+                }
+            };
+
+            let counts = state
+                .path_ref_counts
+                .entry(actual.path.clone())
+                .or_default();
+            let previous_mode = counts.effective_mode();
+            counts.increment(actual.recursive, /*amount*/ 1);
+            let next_mode = counts.effective_mode();
+            if previous_mode != next_mode {
+                self.reconfigure_watch(&actual.path, next_mode, &mut inner_guard);
+            }
+        }
+    }
+
+    fn unregister_paths(&self, subscriber_id: SubscriberId, watched_paths: &[SubscriberWatchKey]) {
+        let mut state = self
+            .state
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let mut inner_guard: Option<std::sync::MutexGuard<'_, FileWatcherInner>> = None;
+
+        for subscriber_watch in watched_paths {
+            let actual = {
+                let Some(subscriber) = state.subscribers.get_mut(&subscriber_id) else {
+                    return;
+                };
+                let Some(subscriber_watch_state) =
+                    subscriber.watched_paths.get_mut(subscriber_watch)
+                else {
+                    continue;
+                };
+                let actual = subscriber_watch_state.actual.clone();
+                subscriber_watch_state.count = subscriber_watch_state.count.saturating_sub(1);
+                if subscriber_watch_state.count == 0 {
+                    subscriber.watched_paths.remove(subscriber_watch);
+                }
+                actual
+            };
+
+            let Some(counts) = state.path_ref_counts.get_mut(&actual.path) else {
+                continue;
+            };
+            let previous_mode = counts.effective_mode();
+            counts.decrement(actual.recursive, /*amount*/ 1);
+            let next_mode = counts.effective_mode();
+            if counts.is_empty() {
+                state.path_ref_counts.remove(&actual.path);
+            }
+            if previous_mode != next_mode {
+                self.reconfigure_watch(&actual.path, next_mode, &mut inner_guard);
+            }
+        }
+    }
+
+    fn remove_subscriber(&self, subscriber_id: SubscriberId) {
+        let mut state = self
+            .state
+            .write()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        let Some(subscriber) = state.subscribers.remove(&subscriber_id) else {
+            return;
+        };
+
+        let mut inner_guard: Option<std::sync::MutexGuard<'_, FileWatcherInner>> = None;
+        for (_subscriber_watch, subscriber_watch_state) in subscriber.watched_paths {
+            let Some(path_counts) = state
+                .path_ref_counts
+                .get_mut(&subscriber_watch_state.actual.path)
+            else {
+                continue;
+            };
+            let previous_mode = path_counts.effective_mode();
+            path_counts.decrement(
+                subscriber_watch_state.actual.recursive,
+                subscriber_watch_state.count,
+            );
+            let next_mode = path_counts.effective_mode();
+            if path_counts.is_empty() {
+                state
+                    .path_ref_counts
+                    .remove(&subscriber_watch_state.actual.path);
+            }
+            if previous_mode != next_mode {
+                self.reconfigure_watch(
+                    &subscriber_watch_state.actual.path,
+                    next_mode,
+                    &mut inner_guard,
+                );
+            }
+        }
+    }
+
+    fn reconfigure_watch<'a>(
+        &'a self,
+        path: &Path,
+        next_mode: Option<RecursiveMode>,
+        inner_guard: &mut Option<std::sync::MutexGuard<'a, FileWatcherInner>>,
+    ) {
+        Self::reconfigure_watch_inner(self.inner.as_ref(), path, next_mode, inner_guard);
+    }
+
+    fn reconfigure_watch_inner<'a>(
+        inner: Option<&'a Arc<Mutex<FileWatcherInner>>>,
+        path: &Path,
+        next_mode: Option<RecursiveMode>,
+        inner_guard: &mut Option<std::sync::MutexGuard<'a, FileWatcherInner>>,
+    ) {
+        let Some(inner) = inner else {
+            return;
+        };
+        if inner_guard.is_none() {
+            let guard = inner
+                .lock()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            *inner_guard = Some(guard);
+        }
+        let Some(guard) = inner_guard.as_mut() else {
+            return;
+        };
+
+        let existing_mode = guard.watched_paths.get(path).copied();
+        if existing_mode == next_mode {
+            return;
+        }
+
+        if existing_mode.is_some() {
+            if let Err(err) = guard.watcher.unwatch(path) {
+                warn!("failed to unwatch {}: {err}", path.display());
+            }
+            guard.watched_paths.remove(path);
+        }
+
+        let Some(next_mode) = next_mode else {
+            return;
+        };
+        if !path.exists() {
+            return;
+        }
+
+        if let Err(err) = guard.watcher.watch(path, next_mode) {
+            warn!("failed to watch {}: {err}", path.display());
+            return;
+        }
+        guard.watched_paths.insert(path.to_path_buf(), next_mode);
+    }
+
+    fn apply_actual_watch_move<'a>(
+        path_ref_counts: &mut HashMap<PathBuf, PathWatchCounts>,
+        old_actual: WatchPath,
+        new_actual: WatchPath,
+        count: usize,
+        inner: Option<&'a Arc<Mutex<FileWatcherInner>>>,
+        inner_guard: &mut Option<std::sync::MutexGuard<'a, FileWatcherInner>>,
+    ) {
+        if old_actual == new_actual {
+            return;
+        }
+
+        if let Some(counts) = path_ref_counts.get_mut(&old_actual.path) {
+            let previous_mode = counts.effective_mode();
+            counts.decrement(old_actual.recursive, count);
+            let next_mode = counts.effective_mode();
+            if counts.is_empty() {
+                path_ref_counts.remove(&old_actual.path);
+            }
+            if previous_mode != next_mode {
+                Self::reconfigure_watch_inner(inner, &old_actual.path, next_mode, inner_guard);
+            }
+        }
+
+        let counts = path_ref_counts.entry(new_actual.path.clone()).or_default();
+        let previous_mode = counts.effective_mode();
+        counts.increment(new_actual.recursive, count);
+        let next_mode = counts.effective_mode();
+        if previous_mode != next_mode {
+            Self::reconfigure_watch_inner(inner, &new_actual.path, next_mode, inner_guard);
+        }
+    }
+
+    // Bridge `notify`'s callback-based events into the Tokio runtime and
+    // notify the matching subscribers.
+    fn spawn_event_loop(&self, mut raw_rx: mpsc::UnboundedReceiver<notify::Result<Event>>) {
+        if let Ok(handle) = Handle::try_current() {
+            let state = Arc::clone(&self.state);
+            let inner = self.inner.as_ref().map(Arc::downgrade);
+            handle.spawn(async move {
+                loop {
+                    match raw_rx.recv().await {
+                        Some(Ok(event)) => {
+                            if !is_mutating_event(&event) {
+                                continue;
+                            }
+                            if event.paths.is_empty() {
+                                continue;
+                            }
+                            let inner = inner.as_ref().and_then(std::sync::Weak::upgrade);
+                            Self::notify_subscribers(&state, inner.as_ref(), &event.paths).await;
+                        }
+                        Some(Err(err)) => {
+                            warn!("file watcher error: {err}");
+                        }
+                        None => break,
+                    }
+                }
+            });
+        } else {
+            warn!("file watcher loop skipped: no Tokio runtime available");
+        }
+    }
+
+    async fn notify_subscribers(
+        state: &RwLock<WatchState>,
+        inner: Option<&Arc<Mutex<FileWatcherInner>>>,
+        event_paths: &[PathBuf],
+    ) {
+        let subscribers_to_notify: Vec<(WatchSender, Vec<PathBuf>)> = {
+            let mut state = state
+                .write()
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+            let mut actual_watch_moves = Vec::new();
+            let mut subscribers_to_notify = Vec::new();
+
+            for subscriber in state.subscribers.values_mut() {
+                let mut changed_paths = Vec::new();
+                for event_path in event_paths {
+                    for (subscriber_watch, subscriber_watch_state) in &mut subscriber.watched_paths
+                    {
+                        if let Some(path) = changed_path_for_event(
+                            subscriber_watch,
+                            subscriber_watch_state,
+                            event_path,
+                        ) {
+                            changed_paths.push(path);
+                        }
+
+                        let (new_actual, _new_matched, fallback) =
+                            actual_watch_path(&subscriber_watch.requested);
+                        subscriber_watch_state.fallback |= fallback;
+                        if subscriber_watch_state.actual != new_actual {
+                            let old_actual = subscriber_watch_state.actual.clone();
+                            let count = subscriber_watch_state.count;
+                            subscriber_watch_state.actual = new_actual.clone();
+                            actual_watch_moves.push((old_actual, new_actual, count));
+                        }
+                    }
+                }
+                if !changed_paths.is_empty() {
+                    subscribers_to_notify.push((subscriber.tx.clone(), changed_paths));
+                }
+            }
+
+            let mut inner_guard: Option<std::sync::MutexGuard<'_, FileWatcherInner>> = None;
+            for (old_actual, new_actual, count) in actual_watch_moves {
+                Self::apply_actual_watch_move(
+                    &mut state.path_ref_counts,
+                    old_actual,
+                    new_actual,
+                    count,
+                    inner,
+                    &mut inner_guard,
+                );
+            }
+
+            subscribers_to_notify
+        };
+
+        for (subscriber, changed_paths) in subscribers_to_notify {
+            subscriber.add_changed_paths(&changed_paths).await;
+        }
+    }
+
+    #[doc(hidden)]
+    pub async fn send_paths_for_test(&self, paths: Vec<PathBuf>) {
+        Self::notify_subscribers(&self.state, self.inner.as_ref(), &paths).await;
+    }
+
+    #[cfg(test)]
+    pub(crate) fn spawn_event_loop_for_test(
+        &self,
+        raw_rx: mpsc::UnboundedReceiver<notify::Result<Event>>,
+    ) {
+        self.spawn_event_loop(raw_rx);
+    }
+
+    #[cfg(test)]
+    pub(crate) fn watch_counts_for_test(&self, path: &Path) -> Option<(usize, usize)> {
+        let state = self
+            .state
+            .read()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        state
+            .path_ref_counts
+            .get(path)
+            .map(|counts| (counts.non_recursive, counts.recursive))
+    }
+}
+
+fn is_mutating_event(event: &Event) -> bool {
+    matches!(
+        event.kind,
+        EventKind::Create(_) | EventKind::Modify(_) | EventKind::Remove(_)
+    )
+}
+
+fn dedupe_watched_paths(mut watched_paths: Vec<WatchPath>) -> Vec<WatchPath> {
+    watched_paths.sort_unstable_by(|a, b| {
+        a.path
+            .as_os_str()
+            .cmp(b.path.as_os_str())
+            .then(a.recursive.cmp(&b.recursive))
+    });
+    watched_paths.dedup();
+    watched_paths
+}
+
+/// Returns the actual OS watch path and canonical match path for a request.
+///
+/// Missing targets are watched non-recursively through the nearest existing
+/// directory ancestor. As path components appear, the actual watch is moved
+/// closer to the requested path so broad recursive ancestor watches are never
+/// needed.
+fn actual_watch_path(requested: &WatchPath) -> (WatchPath, WatchPath, bool) {
+    if requested.path.exists() {
+        let matched_path = requested
+            .path
+            .canonicalize()
+            .unwrap_or_else(|_| requested.path.clone());
+        let actual = requested.clone();
+        let matched = WatchPath {
+            path: matched_path,
+            recursive: requested.recursive,
+        };
+        return (actual, matched, false);
+    }
+
+    let requested_parent = requested.path.parent();
+    let mut ancestor = requested_parent;
+    while let Some(path) = ancestor {
+        if path.is_dir() {
+            let actual_path = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
+            let matched_path = requested
+                .path
+                .strip_prefix(path)
+                .map(|suffix| actual_path.join(suffix))
+                .unwrap_or_else(|_| requested.path.clone());
+            let actual = WatchPath {
+                path: path.to_path_buf(),
+                recursive: false,
+            };
+            let matched = WatchPath {
+                path: matched_path,
+                recursive: requested.recursive,
+            };
+            return (actual, matched, true);
+        }
+        ancestor = path.parent();
+    }
+
+    (requested.clone(), requested.clone(), false)
+}
+
+/// Converts one raw backend event path into the subscriber-visible path.
+///
+/// Matching first uses the canonical path namespace reported by many OS
+/// backends, then falls back to the originally requested namespace for
+/// synthetic tests and backends that preserve the input spelling.
+fn changed_path_for_event(
+    subscriber_watch: &SubscriberWatchKey,
+    subscriber_watch_state: &mut SubscriberWatchState,
+    event_path: &Path,
+) -> Option<PathBuf> {
+    if let Some(path) = changed_path_for_matched_path(
+        subscriber_watch,
+        subscriber_watch_state,
+        &subscriber_watch.matched,
+        event_path,
+    ) {
+        return Some(path);
+    }
+    if subscriber_watch.matched.path == subscriber_watch.requested.path {
+        return None;
+    }
+    changed_path_for_matched_path(
+        subscriber_watch,
+        subscriber_watch_state,
+        &subscriber_watch.requested,
+        event_path,
+    )
+}
+
+/// Applies the watch matching rules in one path namespace and maps any emitted
+/// path back into the subscriber's requested namespace.
+fn changed_path_for_matched_path(
+    subscriber_watch: &SubscriberWatchKey,
+    subscriber_watch_state: &mut SubscriberWatchState,
+    matched: &WatchPath,
+    event_path: &Path,
+) -> Option<PathBuf> {
+    let requested = &subscriber_watch.requested;
+    if event_path == matched.path {
+        subscriber_watch_state.last_exists = matched.path.exists();
+        return Some(requested.path.clone());
+    }
+    if matched.path.starts_with(event_path) {
+        let now_exists = matched.path.exists();
+        if subscriber_watch_state.fallback {
+            let should_notify = now_exists || subscriber_watch_state.last_exists;
+            subscriber_watch_state.last_exists = now_exists;
+            return should_notify.then(|| requested.path.clone());
+        }
+        if subscriber_watch_state.actual.path != matched.path {
+            let should_notify = now_exists || subscriber_watch_state.last_exists;
+            subscriber_watch_state.last_exists = now_exists;
+            return should_notify.then(|| requested.path.clone());
+        }
+        subscriber_watch_state.last_exists = now_exists;
+        return Some(event_path.to_path_buf());
+    }
+    if !event_path.starts_with(&matched.path) {
+        return None;
+    }
+    if !(matched.recursive || event_path.parent() == Some(matched.path.as_path())) {
+        return None;
+    }
+    subscriber_watch_state.last_exists = matched.path.exists();
+    Some(
+        event_path
+            .strip_prefix(&matched.path)
+            .map(|suffix| requested.path.join(suffix))
+            .unwrap_or_else(|_| event_path.to_path_buf()),
+    )
+}
+
+#[cfg(test)]
+#[path = "file_watcher_tests.rs"]
+mod tests;

codex-rs/mcp-tool-approval-templates/BUILD.bazel

@@ -0,0 +1,7 @@
+load("//:defs.bzl", "codex_rust_crate")
+
+codex_rust_crate(
+    name = "mcp-tool-approval-templates",
+    crate_name = "codex_mcp_tool_approval_templates",
+    compile_data = ["src/consequential_tool_message_templates.json"],
+)

codex-rs/mcp-tool-approval-templates/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+edition.workspace = true
+license.workspace = true
+name = "codex-mcp-tool-approval-templates"
+version.workspace = true
+
+[lib]
+doctest = false
+name = "codex_mcp_tool_approval_templates"
+path = "src/lib.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+serde = { workspace = true, features = ["derive"] }
+serde_json = { workspace = true }
+tracing = { workspace = true, features = ["log"] }
+
+[dev-dependencies]
+pretty_assertions = { workspace = true }

codex-rs/mcp-tool-approval-templates/src/lib.rs

@@ -0,0 +1,371 @@
+use std::collections::HashSet;
+use std::sync::LazyLock;
+
+use serde::Deserialize;
+use serde::Serialize;
+use serde_json::Map;
+use serde_json::Value;
+use tracing::warn;
+
+const CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES_SCHEMA_VERSION: u8 = 4;
+const CONNECTOR_NAME_TEMPLATE_VAR: &str = "{connector_name}";
+
+static CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES: LazyLock<
+    Option<Vec<ConsequentialToolMessageTemplate>>,
+> = LazyLock::new(load_consequential_tool_message_templates);
+
+#[derive(Clone, Debug, PartialEq)]
+pub struct RenderedMcpToolApprovalTemplate {
+    pub question: String,
+    pub elicitation_message: String,
+    pub tool_params: Option<Value>,
+    pub tool_params_display: Vec<RenderedMcpToolApprovalParam>,
+}
+
+#[derive(Clone, Debug, PartialEq, Serialize)]
+pub struct RenderedMcpToolApprovalParam {
+    pub name: String,
+    pub value: Value,
+    pub display_name: String,
+}
+
+#[derive(Debug, Deserialize)]
+struct ConsequentialToolMessageTemplatesFile {
+    schema_version: u8,
+    templates: Vec<ConsequentialToolMessageTemplate>,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
+struct ConsequentialToolMessageTemplate {
+    connector_id: String,
+    server_name: String,
+    tool_title: String,
+    template: String,
+    template_params: Vec<ConsequentialToolTemplateParam>,
+}
+
+#[derive(Clone, Debug, Deserialize, PartialEq, Eq)]
+struct ConsequentialToolTemplateParam {
+    name: String,
+    label: String,
+}
+
+pub fn render_mcp_tool_approval_template(
+    server_name: &str,
+    connector_id: Option<&str>,
+    connector_name: Option<&str>,
+    tool_title: Option<&str>,
+    tool_params: Option<&Value>,
+) -> Option<RenderedMcpToolApprovalTemplate> {
+    let templates = CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES.as_ref()?;
+    render_mcp_tool_approval_template_from_templates(
+        templates,
+        server_name,
+        connector_id,
+        connector_name,
+        tool_title,
+        tool_params,
+    )
+}
+
+fn load_consequential_tool_message_templates() -> Option<Vec<ConsequentialToolMessageTemplate>> {
+    let templates = match serde_json::from_str::<ConsequentialToolMessageTemplatesFile>(
+        include_str!("consequential_tool_message_templates.json"),
+    ) {
+        Ok(templates) => templates,
+        Err(err) => {
+            warn!(error = %err, "failed to parse consequential tool approval templates");
+            return None;
+        }
+    };
+
+    if templates.schema_version != CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES_SCHEMA_VERSION {
+        warn!(
+            found_schema_version = templates.schema_version,
+            expected_schema_version = CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES_SCHEMA_VERSION,
+            "unexpected consequential tool approval templates schema version"
+        );
+        return None;
+    }
+
+    Some(templates.templates)
+}
+
+fn render_mcp_tool_approval_template_from_templates(
+    templates: &[ConsequentialToolMessageTemplate],
+    server_name: &str,
+    connector_id: Option<&str>,
+    connector_name: Option<&str>,
+    tool_title: Option<&str>,
+    tool_params: Option<&Value>,
+) -> Option<RenderedMcpToolApprovalTemplate> {
+    let connector_id = connector_id?;
+    let tool_title = tool_title.map(str::trim).filter(|name| !name.is_empty())?;
+    let template = templates.iter().find(|template| {
+        template.server_name == server_name
+            && template.connector_id == connector_id
+            && template.tool_title == tool_title
+    })?;
+    let elicitation_message = render_question_template(&template.template, connector_name)?;
+    let (tool_params, tool_params_display) = match tool_params {
+        Some(Value::Object(tool_params)) => {
+            render_tool_params(tool_params, &template.template_params)?
+        }
+        Some(_) => return None,
+        None => (None, Vec::new()),
+    };
+
+    Some(RenderedMcpToolApprovalTemplate {
+        question: elicitation_message.clone(),
+        elicitation_message,
+        tool_params,
+        tool_params_display,
+    })
+}
+
+fn render_question_template(template: &str, connector_name: Option<&str>) -> Option<String> {
+    let template = template.trim();
+    if template.is_empty() {
+        return None;
+    }
+
+    if template.contains(CONNECTOR_NAME_TEMPLATE_VAR) {
+        let connector_name = connector_name
+            .map(str::trim)
+            .filter(|name| !name.is_empty())?;
+        return Some(template.replace(CONNECTOR_NAME_TEMPLATE_VAR, connector_name));
+    }
+
+    Some(template.to_string())
+}
+
+fn render_tool_params(
+    tool_params: &Map<String, Value>,
+    template_params: &[ConsequentialToolTemplateParam],
+) -> Option<(Option<Value>, Vec<RenderedMcpToolApprovalParam>)> {
+    let mut display_params = Vec::new();
+    let mut display_names = HashSet::new();
+    let mut handled_names = HashSet::new();
+
+    for template_param in template_params {
+        let label = template_param.label.trim();
+        if label.is_empty() {
+            return None;
+        }
+        let Some(value) = tool_params.get(&template_param.name) else {
+            continue;
+        };
+        if !display_names.insert(label.to_string()) {
+            return None;
+        }
+        display_params.push(RenderedMcpToolApprovalParam {
+            name: template_param.name.clone(),
+            value: value.clone(),
+            display_name: label.to_string(),
+        });
+        handled_names.insert(template_param.name.as_str());
+    }
+
+    let mut remaining_params = tool_params
+        .iter()
+        .filter(|(name, _)| !handled_names.contains(name.as_str()))
+        .collect::<Vec<_>>();
+    remaining_params.sort_by(|(left_name, _), (right_name, _)| left_name.cmp(right_name));
+
+    for (name, value) in remaining_params {
+        if handled_names.contains(name.as_str()) {
+            continue;
+        }
+        if !display_names.insert(name.clone()) {
+            return None;
+        }
+        display_params.push(RenderedMcpToolApprovalParam {
+            name: name.clone(),
+            value: value.clone(),
+            display_name: name.clone(),
+        });
+    }
+
+    Some((Some(Value::Object(tool_params.clone())), display_params))
+}
+
+#[cfg(test)]
+mod tests {
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    use super::*;
+
+    #[test]
+    fn renders_exact_match_with_readable_param_labels() {
+        let templates = vec![ConsequentialToolMessageTemplate {
+            connector_id: "calendar".to_string(),
+            server_name: "codex_apps".to_string(),
+            tool_title: "create_event".to_string(),
+            template: "Allow {connector_name} to create an event?".to_string(),
+            template_params: vec![
+                ConsequentialToolTemplateParam {
+                    name: "calendar_id".to_string(),
+                    label: "Calendar".to_string(),
+                },
+                ConsequentialToolTemplateParam {
+                    name: "title".to_string(),
+                    label: "Title".to_string(),
+                },
+            ],
+        }];
+
+        let rendered = render_mcp_tool_approval_template_from_templates(
+            &templates,
+            "codex_apps",
+            Some("calendar"),
+            Some("Calendar"),
+            Some("create_event"),
+            Some(&json!({
+                "title": "Roadmap review",
+                "calendar_id": "primary",
+                "timezone": "UTC",
+            })),
+        );
+
+        assert_eq!(
+            rendered,
+            Some(RenderedMcpToolApprovalTemplate {
+                question: "Allow Calendar to create an event?".to_string(),
+                elicitation_message: "Allow Calendar to create an event?".to_string(),
+                tool_params: Some(json!({
+                    "title": "Roadmap review",
+                    "calendar_id": "primary",
+                    "timezone": "UTC",
+                })),
+                tool_params_display: vec![
+                    RenderedMcpToolApprovalParam {
+                        name: "calendar_id".to_string(),
+                        value: json!("primary"),
+                        display_name: "Calendar".to_string(),
+                    },
+                    RenderedMcpToolApprovalParam {
+                        name: "title".to_string(),
+                        value: json!("Roadmap review"),
+                        display_name: "Title".to_string(),
+                    },
+                    RenderedMcpToolApprovalParam {
+                        name: "timezone".to_string(),
+                        value: json!("UTC"),
+                        display_name: "timezone".to_string(),
+                    },
+                ],
+            })
+        );
+    }
+
+    #[test]
+    fn returns_none_when_no_exact_match_exists() {
+        let templates = vec![ConsequentialToolMessageTemplate {
+            connector_id: "calendar".to_string(),
+            server_name: "codex_apps".to_string(),
+            tool_title: "create_event".to_string(),
+            template: "Allow {connector_name} to create an event?".to_string(),
+            template_params: Vec::new(),
+        }];
+
+        assert_eq!(
+            render_mcp_tool_approval_template_from_templates(
+                &templates,
+                "codex_apps",
+                Some("calendar"),
+                Some("Calendar"),
+                Some("delete_event"),
+                Some(&json!({})),
+            ),
+            None
+        );
+    }
+
+    #[test]
+    fn returns_none_when_relabeling_would_collide() {
+        let templates = vec![ConsequentialToolMessageTemplate {
+            connector_id: "calendar".to_string(),
+            server_name: "codex_apps".to_string(),
+            tool_title: "create_event".to_string(),
+            template: "Allow {connector_name} to create an event?".to_string(),
+            template_params: vec![ConsequentialToolTemplateParam {
+                name: "calendar_id".to_string(),
+                label: "timezone".to_string(),
+            }],
+        }];
+
+        assert_eq!(
+            render_mcp_tool_approval_template_from_templates(
+                &templates,
+                "codex_apps",
+                Some("calendar"),
+                Some("Calendar"),
+                Some("create_event"),
+                Some(&json!({
+                    "calendar_id": "primary",
+                    "timezone": "UTC",
+                })),
+            ),
+            None
+        );
+    }
+
+    #[test]
+    fn bundled_templates_load() {
+        assert_eq!(CONSEQUENTIAL_TOOL_MESSAGE_TEMPLATES.is_some(), true);
+    }
+
+    #[test]
+    fn renders_literal_template_without_connector_substitution() {
+        let templates = vec![ConsequentialToolMessageTemplate {
+            connector_id: "github".to_string(),
+            server_name: "codex_apps".to_string(),
+            tool_title: "add_comment".to_string(),
+            template: "Allow GitHub to add a comment to a pull request?".to_string(),
+            template_params: Vec::new(),
+        }];
+
+        let rendered = render_mcp_tool_approval_template_from_templates(
+            &templates,
+            "codex_apps",
+            Some("github"),
+            /*connector_name*/ None,
+            Some("add_comment"),
+            Some(&json!({})),
+        );
+
+        assert_eq!(
+            rendered,
+            Some(RenderedMcpToolApprovalTemplate {
+                question: "Allow GitHub to add a comment to a pull request?".to_string(),
+                elicitation_message: "Allow GitHub to add a comment to a pull request?".to_string(),
+                tool_params: Some(json!({})),
+                tool_params_display: Vec::new(),
+            })
+        );
+    }
+
+    #[test]
+    fn returns_none_when_connector_placeholder_has_no_value() {
+        let templates = vec![ConsequentialToolMessageTemplate {
+            connector_id: "calendar".to_string(),
+            server_name: "codex_apps".to_string(),
+            tool_title: "create_event".to_string(),
+            template: "Allow {connector_name} to create an event?".to_string(),
+            template_params: Vec::new(),
+        }];
+
+        assert_eq!(
+            render_mcp_tool_approval_template_from_templates(
+                &templates,
+                "codex_apps",
+                Some("calendar"),
+                /*connector_name*/ None,
+                Some("create_event"),
+                Some(&json!({})),
+            ),
+            None
+        );
+    }
+}