voidzero-dev
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,6 @@
 # Changelog
 
+- **Added** Runner-aware tools can now call `ignoreInput(path)` to exclude non-semantic reads from auto-inferred task cache inputs.
 - **Changed** Tracked environment values in task cache fingerprints are now stored only as SHA-256 digests, and env-related cache miss details report names without values.
 - **Added** Runner-aware `getEnvs` match sets can now participate in task cache fingerprints, so changing, adding, or removing a matching env var invalidates the cache ([#450](https://github.com/voidzero-dev/vite-task/pull/450)).
 - **Added** Runner-aware `getEnvs` calls now return env values served by the runner for matching env glob patterns ([#449](https://github.com/voidzero-dev/vite-task/pull/449)).

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/crates/vite_task/src/session/execute/cache_update.rs b/crates/vite_task/src/session/execute/cache_update.rs
@@ -3,6 +3,7 @@
 
 use std::{collections::BTreeMap, sync::Arc, time::Duration};
 
+use rustc_hash::FxHashSet;
 use vite_path::{AbsolutePath, RelativePathBuf};
 use vite_str::Str;
 use vite_task_plan::cache_metadata::{CacheMetadata, EnvValueHash};
@@ -67,6 +68,12 @@ pub(super) async fn update_cache(
         return (CacheUpdateStatus::NotUpdated(CacheNotUpdatedReason::ToolRequested), None);
     }
 
+    // Tool-reported paths to exclude from auto input tracking. Absolute paths
+    // are normalized to workspace-relative; anything outside is dropped.
+    let ignored_input_rels: FxHashSet<RelativePathBuf> = reports
+        .map(|r| normalize_ignored_paths(&r.ignored_inputs, workspace_root))
+        .unwrap_or_default();
+
     if cancelled {
         // Cancelled (Ctrl-C or sibling failure) — result is untrustworthy.
         return (CacheUpdateStatus::NotUpdated(CacheNotUpdatedReason::Cancelled), None);
@@ -77,7 +84,8 @@ pub(super) async fn update_cache(
         return (CacheUpdateStatus::NotUpdated(CacheNotUpdatedReason::NonZeroExitStatus), None);
     }
 
-    let fspy_outcome = observe_fspy(outcome, input_negative_globs, workspace_root);
+    let fspy_outcome =
+        observe_fspy(outcome, input_negative_globs, &ignored_input_rels, workspace_root);
 
     if let Some(TrackingOutcome { read_write_overlap: Some(path), .. }) = &fspy_outcome {
         // fspy-inferred read-write overlap: the task wrote to a file it also
@@ -167,6 +175,7 @@ pub(super) async fn update_cache(
 fn observe_fspy(
     outcome: &ChildOutcome,
     input_negative_globs: Option<&[wax::Glob<'static>]>,
+    ignored_input_rels: &FxHashSet<RelativePathBuf>,
     workspace_root: &AbsolutePath,
 ) -> Option<TrackingOutcome> {
     #[cfg(fspy)]
@@ -175,14 +184,19 @@ fn observe_fspy(
 
         outcome.path_accesses.as_ref().zip(input_negative_globs).map(|(raw, negatives)| {
             let tracked = TrackedPathAccesses::from_raw(raw, workspace_root, negatives);
+            let path_reads: HashMap<RelativePathBuf, PathRead> = tracked
+                .path_reads
+                .into_iter()
+                .filter(|(path, _)| !is_ignored(path, ignored_input_rels))
+                .collect();
             let read_write_overlap =
-                tracked.path_reads.keys().find(|p| tracked.path_writes.contains(*p)).cloned();
-            TrackingOutcome { path_reads: tracked.path_reads, read_write_overlap }
+                path_reads.keys().find(|p| tracked.path_writes.contains(*p)).cloned();
+            TrackingOutcome { path_reads, read_write_overlap }
         })
     }
     #[cfg(not(fspy))]
     {
-        let _ = (outcome, input_negative_globs, workspace_root);
+        let _ = (outcome, input_negative_globs, ignored_input_rels, workspace_root);
         None
     }
 }
@@ -201,6 +215,27 @@ fn collect_tracked_reports(
         .map(Option::unwrap_or_default)
 }
 
+/// Normalize tool-reported absolute paths to cleaned workspace-relative paths.
+/// Paths outside the workspace are dropped — they can't contribute to inputs.
+fn normalize_ignored_paths(
+    paths: &FxHashSet<Arc<AbsolutePath>>,
+    workspace_root: &AbsolutePath,
+) -> FxHashSet<RelativePathBuf> {
+    paths
+        .iter()
+        .filter_map(|p| p.strip_prefix(workspace_root).ok().flatten()?.clean().ok())
+        .collect()
+}
+
+/// Whether `path` is covered by any `ignored` entry. An ignored entry matches
+/// itself (exact file) and everything under it (directory subtree).
+fn is_ignored(path: &RelativePathBuf, ignored: &FxHashSet<RelativePathBuf>) -> bool {
+    if ignored.is_empty() {
+        return false;
+    }
+    ignored.contains(path) || ignored.iter().any(|ig| path.strip_prefix(ig).is_some())
+}
+
 /// Select tool-reported env records to embed in the post-run fingerprint.
 /// Names that the user already declared as fingerprinted are skipped because
 /// their values are already in the spawn fingerprint.
@@ -287,3 +322,28 @@ fn collect_and_archive_outputs(
 
     Ok(Some(archive_name))
 }
+
+#[cfg(test)]
+mod tests {
+    use std::sync::Arc;
+
+    use rustc_hash::FxHashSet;
+    use vite_path::{AbsolutePath, RelativePathBuf};
+
+    use super::normalize_ignored_paths;
+
+    #[test]
+    fn normalize_ignored_paths_cleans_relative_components() {
+        let workspace_root =
+            AbsolutePath::new(if cfg!(windows) { r"C:\repo" } else { "/repo" }).unwrap();
+        let ignored =
+            workspace_root.join(if cfg!(windows) { r"pkg\..\cache" } else { "pkg/../cache" });
+        let mut ignored_paths = FxHashSet::default();
+        ignored_paths.insert(Arc::<AbsolutePath>::from(ignored));
+
+        let normalized = normalize_ignored_paths(&ignored_paths, workspace_root);
+
+        let expected = RelativePathBuf::new("cache").unwrap();
+        assert!(normalized.contains(&expected));
+    }
+}
diff --git a/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/scripts/ignore_input.mjs b/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/scripts/ignore_input.mjs
@@ -0,0 +1,9 @@
+import { mkdirSync, readFileSync } from 'node:fs';
+import { ignoreInput } from '@voidzero-dev/vite-task-client';
+
+mkdirSync('cache_like', { recursive: true });
+
+ignoreInput('cache_like');
+
+const value = readFileSync('cache_like/input.txt', 'utf8').trim();
+console.log(value);
diff --git a/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots.toml b/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots.toml
@@ -1,3 +1,78 @@
+[[e2e]]
+name = "ignore_input_keeps_cache_valid"
+comment = """
+Exercises `ignoreInput` through `@voidzero-dev/vite-task-client`. The runner treats `cache_like/` as non-input for auto-inferred reads, but declared inputs under that path stay in the configured cache key.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vtt",
+    "write-file",
+    "cache_like/input.txt",
+    "before",
+  ], comment = "seed the file the task will read and ignore" },
+  { argv = [
+    "vt",
+    "run",
+    "ignore-input",
+  ], comment = "populate the cache" },
+  { argv = [
+    "vtt",
+    "write-file",
+    "cache_like/input.txt",
+    "after",
+  ], comment = "mutate the ignored input — would invalidate if tracked" },
+  { argv = [
+    "vt",
+    "run",
+    "ignore-input",
+  ], comment = "cache hit: cache_like/ was ignored via ignoreInput" },
+  { argv = [
+    "vtt",
+    "write-file",
+    "cache_like/input.txt",
+    "manual-before",
+  ], comment = "seed the declared input for input: [cache_like/input.txt]" },
+  { argv = [
+    "vt",
+    "run",
+    "ignore-input-manual-input",
+  ], comment = "populate the cache with the manual-only input fingerprint" },
+  { argv = [
+    "vtt",
+    "write-file",
+    "cache_like/input.txt",
+    "manual-after",
+  ], comment = "mutate the declared input for input: [cache_like/input.txt]" },
+  { argv = [
+    "vt",
+    "run",
+    "ignore-input-manual-input",
+  ], comment = "cache miss: manual input config wins over ignoreInput" },
+  { argv = [
+    "vtt",
+    "write-file",
+    "cache_like/input.txt",
+    "auto-manual-before",
+  ], comment = "seed the declared input for input: [{ auto: true }, cache_like/input.txt]" },
+  { argv = [
+    "vt",
+    "run",
+    "ignore-input-auto-manual-input",
+  ], comment = "populate the cache with the auto-plus-manual input fingerprint" },
+  { argv = [
+    "vtt",
+    "write-file",
+    "cache_like/input.txt",
+    "auto-manual-after",
+  ], comment = "mutate the declared input for input: [{ auto: true }, cache_like/input.txt]" },
+  { argv = [
+    "vt",
+    "run",
+    "ignore-input-auto-manual-input",
+  ], comment = "cache miss: explicit input still wins when auto inference is also enabled" },
+]
+
 [[e2e]]
 name = "disable_cache_forces_reexecution"
 comment = """

diff --git a/..._snapshots/fixtures/ipc_client_test/snapshots/ignore_input_keeps_cache_valid.md b/..._snapshots/fixtures/ipc_client_test/snapshots/ignore_input_keeps_cache_valid.md
@@ -0,0 +1,102 @@
+# ignore_input_keeps_cache_valid
+
+Exercises `ignoreInput` through `@voidzero-dev/vite-task-client`. The runner treats `cache_like/` as non-input for auto-inferred reads, but declared inputs under that path stay in the configured cache key.
+
+## `vtt write-file cache_like/input.txt before`
+
+seed the file the task will read and ignore
+
+```
+```
+
+## `vt run ignore-input`
+
+populate the cache
+
+```
+$ node scripts/ignore_input.mjs
+before
+```
+
+## `vtt write-file cache_like/input.txt after`
+
+mutate the ignored input — would invalidate if tracked
+
+```
+```
+
+## `vt run ignore-input`
+
+cache hit: cache_like/ was ignored via ignoreInput
+
+```
+$ node scripts/ignore_input.mjs ◉ cache hit, replaying
+before
+
+---
+vt run: cache hit.
+```
+
+## `vtt write-file cache_like/input.txt manual-before`
+
+seed the declared input for input: [cache_like/input.txt]
+
+```
+```
+
+## `vt run ignore-input-manual-input`
+
+populate the cache with the manual-only input fingerprint
+
+```
+$ node scripts/ignore_input.mjs
+manual-before
+```
+
+## `vtt write-file cache_like/input.txt manual-after`
+
+mutate the declared input for input: [cache_like/input.txt]
+
+```
+```
+
+## `vt run ignore-input-manual-input`
+
+cache miss: manual input config wins over ignoreInput
+
+```
+$ node scripts/ignore_input.mjs ○ cache miss: 'cache_like/input.txt' modified, executing
+manual-after
+```
+
+## `vtt write-file cache_like/input.txt auto-manual-before`
+
+seed the declared input for input: [{ auto: true }, cache_like/input.txt]
+
+```
+```
+
+## `vt run ignore-input-auto-manual-input`
+
+populate the cache with the auto-plus-manual input fingerprint
+
+```
+$ node scripts/ignore_input.mjs
+auto-manual-before
+```
+
+## `vtt write-file cache_like/input.txt auto-manual-after`
+
+mutate the declared input for input: [{ auto: true }, cache_like/input.txt]
+
+```
+```
+
+## `vt run ignore-input-auto-manual-input`
+
+cache miss: explicit input still wins when auto inference is also enabled
+
+```
+$ node scripts/ignore_input.mjs ○ cache miss: 'cache_like/input.txt' modified, executing
+auto-manual-after
+```
diff --git a/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/vite-task.json b/crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/vite-task.json
@@ -1,5 +1,21 @@
 {
   "tasks": {
+    "ignore-input": {
+      "command": "node scripts/ignore_input.mjs",
+      "cache": true
+    },
+    "ignore-input-manual-input": {
+      "command": "node scripts/ignore_input.mjs",
+      "input": ["cache_like/input.txt"],
+      "output": [],
+      "cache": true
+    },
+    "ignore-input-auto-manual-input": {
+      "command": "node scripts/ignore_input.mjs",
+      "input": [{ "auto": true }, "cache_like/input.txt"],
+      "output": [],
+      "cache": true
+    },
     "disable-cache": {
       "command": "node scripts/disable_cache.mjs",
       "cache": true

diff --git a/crates/vite_task_client/Cargo.toml b/crates/vite_task_client/Cargo.toml
@@ -9,6 +9,7 @@ rust-version.workspace = true
 [dependencies]
 native_str = { workspace = true }
 rustc-hash = { workspace = true }
+vite_path = { workspace = true }
 vite_task_ipc_shared = { workspace = true }
 wincode = { workspace = true, features = ["derive"] }