sift-light 1.0.5-1 → 1.0.5-6

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.0.5-6 — 2026-10-10
+
+- Add structured `repairExamples` to invalid-regex and missing-path diagnostics. The examples preserve bounded search filters, never auto-convert regex input, and are omitted when redaction would make request data unsafe to echo.
+- Extend model-facing guidance for `redact=true`, including its sensitive-search use cases and its boundary as display masking rather than filesystem sandboxing.
+- Add regression coverage for the audited request failures and verify the same typed recovery details through the real MCP, ripgrep and packaged host paths.
+
 ## 1.0.5-1 — 2026-10-09
 
 - Fix OMP plugin-cache searches when the generated bundle cannot resolve its platform ripgrep package. Bundled ripgrep remains preferred; an executable `rg` on `PATH` is now a bounded compatibility fallback, while explicit `SIFT_LIGHT_RG_PATH` values retain strict absolute-path and executable validation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.5-1",
+  "version": "1.0.5-6",
   "description": "Context-efficient local search for files, documents, notes and logs across Pi, OMP and MCP clients",
   "keywords": [
     "ai-agent",
@@ -90,7 +90,6 @@
     "@huggingface/transformers": "4.3.1",
     "@modelcontextprotocol/sdk": "1.31.0",
     "@vscode/ripgrep": "1.18.0",
-    "typebox": "1.3.19",
     "web-tree-sitter": "0.25.10",
     "zod": "4.5.4"
   },
@@ -104,12 +103,14 @@
     "oxlint-tsgolint": "^7.0.2001",
     "tree-sitter-bash": "0.25.1",
     "tree-sitter-powershell": "0.26.4",
+    "typebox": "1.3.19",
     "typescript": "7.0.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-ai": {

package/plugins/sift-light/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.5-1",
+  "version": "1.0.5-6",
   "description": "Require sift-light for conventional local searches while keeping development tools available.",
   "author": {
     "name": "baoer"

package/plugins/sift-light/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.5-1",
+  "version": "1.0.5-6",
   "description": "Require sift-light for conventional local searches while keeping development tools available.",
   "author": {
     "name": "baoer"

package/plugins/sift-light/.mcp.json

@@ -5,7 +5,7 @@
       "args": [
         "--yes",
         "--package",
-        "sift-light-runtime@npm:sift-light@1.0.5-1",
+        "sift-light-runtime@npm:sift-light@1.0.5-6",
         "sift-light-mcp",
         "--stdio"
       ],

package/plugins/sift-light/kimi.plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.5-1",
+  "version": "1.0.5-6",
   "description": "Require sift-light for conventional local searches while keeping development tools available.",
   "author": {
     "name": "baoer"
@@ -13,7 +13,7 @@
       "args": [
         "--yes",
         "--package",
-        "sift-light-runtime@npm:sift-light@1.0.5-1",
+        "sift-light-runtime@npm:sift-light@1.0.5-6",
         "sift-light-mcp",
         "--stdio"
       ],

package/plugins/sift-light/omp-extension.mjs

@@ -362,7 +362,7 @@ class RipgrepInputError extends SiftLightError {
   code;
   guidance;
   details;
-  constructor(code, message, guidance) {
+  constructor(code, message, guidance, repairExamples = []) {
     super(`${message} ${guidance}`);
     this.name = "RipgrepInputError";
     this.code = code;
@@ -375,7 +375,8 @@ class RipgrepInputError extends SiftLightError {
           reason: guidance
         }
       ],
-      recovery: { action: "manual", reason: guidance }
+      recovery: { action: "manual", reason: guidance },
+      ...repairExamples.length > 0 ? { repairExamples } : {}
     };
   }
 }
@@ -915,7 +916,7 @@ async function resolveRipgrepExecutable() {
 }
 
 // src/ripgrep-diagnostics.ts
-import { resolve as resolve3 } from "path";
+import { basename, resolve as resolve3 } from "path";
 
 // src/redaction.ts
 var PRIVATE_KEY = /-----BEGIN ([^-\r\n]*PRIVATE KEY)-----[\s\S]*?-----END \1-----/g;
@@ -1049,15 +1050,70 @@ function missingPathFromDiagnostics(stderr) {
   }
   return;
 }
-function createRipgrepInputError(stderr, redact = false) {
+var RIPGREP_RECOVERY_FIELDS = [
+  "path",
+  "glob",
+  "exclude",
+  "literal",
+  "ignoreCase",
+  "hidden",
+  "ignorePolicy",
+  "wholeWord",
+  "context",
+  "scope",
+  "redact"
+];
+function copyRipgrepRecoveryFields(request) {
+  const result = {};
+  for (const field of RIPGREP_RECOVERY_FIELDS) {
+    const value = request[field];
+    if (value !== undefined)
+      result[field] = value;
+  }
+  return result;
+}
+function ripgrepRepairExamples(code, request, redact) {
+  if (request === undefined || redact && containsSensitiveText(request))
+    return [];
+  if (code === "E_REGEX_INVALID") {
+    return [
+      {
+        label: "\u6309\u539F\u6587\u67E5\u627E",
+        request: {
+          mode: "matches",
+          ...copyRipgrepRecoveryFields(request),
+          pattern: request.pattern,
+          literal: true
+        }
+      }
+    ];
+  }
+  if (code === "E_SEARCH_PATH_NOT_FOUND" && request.path !== undefined) {
+    const fileName = basename(request.path.replaceAll("\\", "/"));
+    if (fileName === "." || fileName === "/" || fileName.length === 0)
+      return [];
+    return [
+      {
+        label: "\u6309\u6587\u4EF6\u540D\u67E5\u627E",
+        request: {
+          mode: "files",
+          query: fileName,
+          ...request.redact === true ? { redact: true } : {}
+        }
+      }
+    ];
+  }
+  return [];
+}
+function createRipgrepInputError(stderr, redact = false, request) {
   const code = classifyRipgrepInputFailure(stderr);
   if (code === "E_REGEX_INVALID") {
-    return new RipgrepInputError(code, "ripgrep regex parse error: pattern is not a valid regular expression.", "Correct pattern or set literal=true for source text; no automatic literal conversion was attempted.");
+    return new RipgrepInputError(code, "ripgrep regex parse error: pattern is not a valid regular expression.", "Correct pattern or set literal=true for source text; no automatic literal conversion was attempted.", ripgrepRepairExamples(code, request, redact));
   }
   if (code === "E_SEARCH_PATH_NOT_FOUND") {
     const path = missingPathFromDiagnostics(stderr);
     const location = path ? ` (${JSON.stringify(boundedRipgrepDiagnostic(path, redact))})` : "";
-    return new RipgrepInputError(code, `A searched path${location} does not exist or became unavailable.`, "Provide an existing exact path, or use mode=files with query to discover an unknown filename; no retry or scope expansion was attempted.");
+    return new RipgrepInputError(code, `A searched path${location} does not exist or became unavailable.`, "Provide an existing exact path, or use mode=files with query to discover an unknown filename; no retry or scope expansion was attempted.", ripgrepRepairExamples(code, request, redact));
   }
   return;
 }
@@ -1278,7 +1334,7 @@ async function captureBatch(paths, revisions, signal, onRevisionError) {
   if (signal?.aborted)
     throw abortError();
 }
-async function captureCandidateRevisions(executable, args2, cwd, maxFiles, signal, redact = false) {
+async function captureCandidateRevisions(executable, args2, cwd, maxFiles, signal, redact = false, request) {
   const revisions = new Map;
   let candidateCount = 0;
   let enumerationTruncated = false;
@@ -1332,7 +1388,7 @@ async function captureCandidateRevisions(executable, args2, cwd, maxFiles, signa
     await captureBatch(batch, revisions, signal, recordMetadataFailure);
   });
   const diagnostics = classifyRipgrepDiagnostics(result.stderr);
-  const inputError = createRipgrepInputError(result.stderr, redact);
+  const inputError = createRipgrepInputError(result.stderr, redact, request);
   const unreadable = [...diagnostics.unreadable, ...diagnostics.recoverable, ...metadataFailures];
   if (inputError)
     throw inputError;
@@ -1658,7 +1714,7 @@ function createRipgrepRunner(options = {}) {
         ...policy.ripgrepGlobArguments(validatedSearchPath),
         "--",
         searchTarget
-      ], ripgrepCwd, maxSourceRevisionFiles, signal, request.redact);
+      ], ripgrepCwd, maxSourceRevisionFiles, signal, request.redact, request);
       let ignoredFileCount = 0;
       let ignoredFileSamples = [];
       let filesystemCoverage = "complete";
@@ -1688,7 +1744,7 @@ function createRipgrepRunner(options = {}) {
           ...policy.ripgrepGlobArguments(validatedSearchPath),
           "--",
           searchTarget
-        ], ripgrepCwd, maxSourceRevisionFiles, signal, request.redact);
+        ], ripgrepCwd, maxSourceRevisionFiles, signal, request.redact, request);
         const ignored = [...allCandidates.revisions.keys()].filter((path) => !before.revisions.has(path));
         ignoredFileCount = ignored.length;
         ignoredFileSamples = ignored.slice(0, 20).map((path) => displayPath(path, cwd).displayPath);
@@ -1732,7 +1788,7 @@ function createRipgrepRunner(options = {}) {
         }
       }));
       const diagnostics = classifyRipgrepDiagnostics(stderr);
-      const inputError = createRipgrepInputError(stderr, request.redact);
+      const inputError = createRipgrepInputError(stderr, request.redact, request);
       if (inputError)
         throw inputError;
       const filesystemDiagnostics = [...diagnostics.unreadable, ...diagnostics.recoverable];
@@ -1969,7 +2025,7 @@ function createCtagsStructureProvider(options = {}) {
 // package.json
 var package_default = {
   name: "sift-light",
-  version: "1.0.5-1",
+  version: "1.0.5-6",
   description: "Context-efficient local search for files, documents, notes and logs across Pi, OMP and MCP clients",
   keywords: [
     "ai-agent",
@@ -2059,7 +2115,6 @@ var package_default = {
     "@huggingface/transformers": "4.3.1",
     "@modelcontextprotocol/sdk": "1.31.0",
     "@vscode/ripgrep": "1.18.0",
-    typebox: "1.3.19",
     "web-tree-sitter": "0.25.10",
     zod: "4.5.4"
   },
@@ -2073,12 +2128,14 @@ var package_default = {
     "oxlint-tsgolint": "^7.0.2001",
     "tree-sitter-bash": "0.25.1",
     "tree-sitter-powershell": "0.26.4",
+    typebox: "1.3.19",
     typescript: "7.0.2"
   },
   peerDependencies: {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    typebox: "*"
   },
   peerDependenciesMeta: {
     "@earendil-works/pi-ai": {
@@ -11332,6 +11389,7 @@ var MODE_FIELD_SUMMARY = MODE_SUMMARY_MODES.map((mode) => modeFieldSummary(mode)
 var REQUEST_FIELD_GUIDANCE = {
   pattern: "pattern is regex by default; literal=true matches source text exactly",
   literal: "literal=true makes pattern exact source text; anyOf/allOf already use literal semantics",
+  redact: "redact=true masks credential-like values and private-key bodies in displayed evidence; it does not sandbox search or change counts",
   path: "path must be an existing exact file or root; use mode=files+query for unknown names",
   query: "files+query matches known filename/path text (not glob patterns); omit files query to list every file under path; concept/hybrid query is natural language",
   anyOf: "anyOf is case-sensitive exact-literal OR; omit pattern, allOf, literal, ignoreCase, roles",
@@ -11348,6 +11406,7 @@ function fieldGuidance(field) {
 }
 var GUIDANCE_FIELDS = [
   "pattern",
+  "redact",
   "literal",
   "path",
   "query",
@@ -11369,12 +11428,13 @@ var REQUEST_USAGE_GUIDANCE = [
 ].join("; ");
 var MODEL_USAGE_GUIDANCE = [
   "pattern is regex by default; literal=true matches source text exactly",
-  "path is an existing exact file or root; use files+query for an unknown name",
-  "anyOf/allOf are exact-literal OR/AND variants and exclude pattern/literal",
-  `limit/context are ordinary-search output budgets; limit <= ${String(MAX_PAGE_SIZE)}; omit both for hybrid/concept/outline/structure/inspect`,
-  "outline requires a concrete source file, not a directory; structure requires a nonempty AST pattern and JS/TS/TSX/Go sources, no lang field; use capabilities before unfamiliar language operations",
-  "outline supports JS/TS/TSX and bounded Python syntax; imports/tests are static candidates for JS/TS/TSX",
-  `selectors: ${modeFieldSummary("inspect")}; ${modeFieldSummary("hybrid")}; ${modeFieldSummary("capabilities")}`,
+  "redact=true masks credentials and private-key bodies in displayed evidence; use it for configs, logs or user directories; it does not sandbox search",
+  "path is an existing exact file/root; use files+query for unknown names",
+  "anyOf/allOf are exact-literal OR/AND variants; exclude pattern/literal",
+  `limit/context are ordinary-search budgets (limit <= ${String(MAX_PAGE_SIZE)}); omit for hybrid/concept/outline/structure/inspect`,
+  "outline needs a concrete JS/TS/TSX/Python-capable source file, not a directory; structure needs a nonempty AST pattern for JS/TS/TSX/Go, no lang; use capabilities before unfamiliar language operations",
+  "imports/tests are static JS/TS/TSX candidates",
+  "selectors: inspect, hybrid and capabilities use their cataloged fields",
   "exact, any-of and max_results are not parameters"
 ].join("; ");
 var MODE_CONTRACT_DESCRIPTION = [
@@ -22368,7 +22428,7 @@ var siftLightSchema = _Object_({
     description: "Named exact-literal checks for mode=audit. Each finding is present, absent_with_complete_coverage, or unknown."
   })),
   redact: Optional(Boolean2({
-    description: "Optional display-only masking for credential-like values and private-key bodies. Default false. It never changes searched files, admitted matches, counts, or cursor completeness."
+    description: "Optional display-only masking for credential-like values and private-key bodies. Default false. Use it for configuration, logs and user-directory searches when returned text may contain secrets. It never changes the search scope, searched files, admitted matches, counts or cursor completeness, and it is not a sandbox."
   })),
   modifiedAfter: Optional(Integer({
     minimum: 0,

package/plugins/sift-light/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sift-light",
-  "version": "1.0.5-1",
+  "version": "1.0.5-6",
   "private": true,
   "type": "module",
   "omp": {

package/src/errors.ts

@@ -51,7 +51,12 @@ export class RipgrepInputError extends SiftLightError {
   readonly guidance: string;
   readonly details: SiftLightDiagnosticDetails;
 
-  constructor(code: RipgrepInputErrorCode, message: string, guidance: string) {
+  constructor(
+    code: RipgrepInputErrorCode,
+    message: string,
+    guidance: string,
+    repairExamples: readonly SiftLightDiagnosticRepairExample[] = [],
+  ) {
     super(`${message} ${guidance}`);
     this.name = "RipgrepInputError";
     this.code = code;
@@ -65,6 +70,7 @@ export class RipgrepInputError extends SiftLightError {
         },
       ],
       recovery: { action: "manual", reason: guidance },
+      ...(repairExamples.length > 0 ? { repairExamples } : {}),
     };
   }
 }

package/src/mcp-server.mjs

@@ -7,7 +7,7 @@ import { URL as URL2 } from "node:url";
 // package.json
 var package_default = {
   name: "sift-light",
-  version: "1.0.5-1",
+  version: "1.0.5-6",
   description: "Context-efficient local search for files, documents, notes and logs across Pi, OMP and MCP clients",
   keywords: [
     "ai-agent",
@@ -97,7 +97,6 @@ var package_default = {
     "@huggingface/transformers": "4.3.1",
     "@modelcontextprotocol/sdk": "1.31.0",
     "@vscode/ripgrep": "1.18.0",
-    typebox: "1.3.19",
     "web-tree-sitter": "0.25.10",
     zod: "4.5.4"
   },
@@ -111,12 +110,14 @@ var package_default = {
     "oxlint-tsgolint": "^7.0.2001",
     "tree-sitter-bash": "0.25.1",
     "tree-sitter-powershell": "0.26.4",
+    typebox: "1.3.19",
     typescript: "7.0.2"
   },
   peerDependencies: {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    typebox: "*"
   },
   peerDependenciesMeta: {
     "@earendil-works/pi-ai": {
@@ -570,7 +571,7 @@ class RipgrepInputError extends SiftLightError {
   code;
   guidance;
   details;
-  constructor(code, message, guidance) {
+  constructor(code, message, guidance, repairExamples = []) {
     super(`${message} ${guidance}`);
     this.name = "RipgrepInputError";
     this.code = code;
@@ -583,7 +584,8 @@ class RipgrepInputError extends SiftLightError {
           reason: guidance
         }
       ],
-      recovery: { action: "manual", reason: guidance }
+      recovery: { action: "manual", reason: guidance },
+      ...repairExamples.length > 0 ? { repairExamples } : {}
     };
   }
 }
@@ -965,6 +967,7 @@ var MODE_FIELD_SUMMARY = MODE_SUMMARY_MODES.map((mode) => modeFieldSummary(mode)
 var REQUEST_FIELD_GUIDANCE = {
   pattern: "pattern is regex by default; literal=true matches source text exactly",
   literal: "literal=true makes pattern exact source text; anyOf/allOf already use literal semantics",
+  redact: "redact=true masks credential-like values and private-key bodies in displayed evidence; it does not sandbox search or change counts",
   path: "path must be an existing exact file or root; use mode=files+query for unknown names",
   query: "files+query matches known filename/path text (not glob patterns); omit files query to list every file under path; concept/hybrid query is natural language",
   anyOf: "anyOf is case-sensitive exact-literal OR; omit pattern, allOf, literal, ignoreCase, roles",
@@ -981,6 +984,7 @@ function fieldGuidance(field) {
 }
 var GUIDANCE_FIELDS = [
   "pattern",
+  "redact",
   "literal",
   "path",
   "query",
@@ -1002,12 +1006,13 @@ var REQUEST_USAGE_GUIDANCE = [
 ].join("; ");
 var MODEL_USAGE_GUIDANCE = [
   "pattern is regex by default; literal=true matches source text exactly",
-  "path is an existing exact file or root; use files+query for an unknown name",
-  "anyOf/allOf are exact-literal OR/AND variants and exclude pattern/literal",
-  `limit/context are ordinary-search output budgets; limit <= ${String(MAX_PAGE_SIZE)}; omit both for hybrid/concept/outline/structure/inspect`,
-  "outline requires a concrete source file, not a directory; structure requires a nonempty AST pattern and JS/TS/TSX/Go sources, no lang field; use capabilities before unfamiliar language operations",
-  "outline supports JS/TS/TSX and bounded Python syntax; imports/tests are static candidates for JS/TS/TSX",
-  `selectors: ${modeFieldSummary("inspect")}; ${modeFieldSummary("hybrid")}; ${modeFieldSummary("capabilities")}`,
+  "redact=true masks credentials and private-key bodies in displayed evidence; use it for configs, logs or user directories; it does not sandbox search",
+  "path is an existing exact file/root; use files+query for unknown names",
+  "anyOf/allOf are exact-literal OR/AND variants; exclude pattern/literal",
+  `limit/context are ordinary-search budgets (limit <= ${String(MAX_PAGE_SIZE)}); omit for hybrid/concept/outline/structure/inspect`,
+  "outline needs a concrete JS/TS/TSX/Python-capable source file, not a directory; structure needs a nonempty AST pattern for JS/TS/TSX/Go, no lang; use capabilities before unfamiliar language operations",
+  "imports/tests are static JS/TS/TSX candidates",
+  "selectors: inspect, hybrid and capabilities use their cataloged fields",
   "exact, any-of and max_results are not parameters"
 ].join("; ");
 var MODE_CONTRACT_DESCRIPTION = [
@@ -2029,7 +2034,7 @@ async function resolveRipgrepExecutable() {
 }
 
 // src/ripgrep-diagnostics.ts
-import { resolve as resolve3 } from "node:path";
+import { basename, resolve as resolve3 } from "node:path";
 var UNREADABLE_SUFFIX = /:\s+Permission denied(?:\s+\(os error 13\))?\s*$/iu;
 var UNREADABLE_CODE = /\(os error 13\)\s*$/iu;
 var RECOVERABLE_FILESYSTEM_CODE = /\(os error (?:4|5|22)\)\s*$/iu;
@@ -2068,15 +2073,70 @@ function missingPathFromDiagnostics(stderr) {
   }
   return;
 }
-function createRipgrepInputError(stderr, redact = false) {
+var RIPGREP_RECOVERY_FIELDS = [
+  "path",
+  "glob",
+  "exclude",
+  "literal",
+  "ignoreCase",
+  "hidden",
+  "ignorePolicy",
+  "wholeWord",
+  "context",
+  "scope",
+  "redact"
+];
+function copyRipgrepRecoveryFields(request) {
+  const result = {};
+  for (const field of RIPGREP_RECOVERY_FIELDS) {
+    const value = request[field];
+    if (value !== undefined)
+      result[field] = value;
+  }
+  return result;
+}
+function ripgrepRepairExamples(code, request, redact) {
+  if (request === undefined || redact && containsSensitiveText(request))
+    return [];
+  if (code === "E_REGEX_INVALID") {
+    return [
+      {
+        label: "按原文查找",
+        request: {
+          mode: "matches",
+          ...copyRipgrepRecoveryFields(request),
+          pattern: request.pattern,
+          literal: true
+        }
+      }
+    ];
+  }
+  if (code === "E_SEARCH_PATH_NOT_FOUND" && request.path !== undefined) {
+    const fileName = basename(request.path.replaceAll("\\", "/"));
+    if (fileName === "." || fileName === "/" || fileName.length === 0)
+      return [];
+    return [
+      {
+        label: "按文件名查找",
+        request: {
+          mode: "files",
+          query: fileName,
+          ...request.redact === true ? { redact: true } : {}
+        }
+      }
+    ];
+  }
+  return [];
+}
+function createRipgrepInputError(stderr, redact = false, request) {
   const code = classifyRipgrepInputFailure(stderr);
   if (code === "E_REGEX_INVALID") {
-    return new RipgrepInputError(code, "ripgrep regex parse error: pattern is not a valid regular expression.", "Correct pattern or set literal=true for source text; no automatic literal conversion was attempted.");
+    return new RipgrepInputError(code, "ripgrep regex parse error: pattern is not a valid regular expression.", "Correct pattern or set literal=true for source text; no automatic literal conversion was attempted.", ripgrepRepairExamples(code, request, redact));
   }
   if (code === "E_SEARCH_PATH_NOT_FOUND") {
     const path = missingPathFromDiagnostics(stderr);
     const location = path ? ` (${JSON.stringify(boundedRipgrepDiagnostic(path, redact))})` : "";
-    return new RipgrepInputError(code, `A searched path${location} does not exist or became unavailable.`, "Provide an existing exact path, or use mode=files with query to discover an unknown filename; no retry or scope expansion was attempted.");
+    return new RipgrepInputError(code, `A searched path${location} does not exist or became unavailable.`, "Provide an existing exact path, or use mode=files with query to discover an unknown filename; no retry or scope expansion was attempted.", ripgrepRepairExamples(code, request, redact));
   }
   return;
 }
@@ -2297,7 +2357,7 @@ async function captureBatch(paths, revisions, signal, onRevisionError) {
   if (signal?.aborted)
     throw abortError();
 }
-async function captureCandidateRevisions(executable, args, cwd, maxFiles, signal, redact = false) {
+async function captureCandidateRevisions(executable, args, cwd, maxFiles, signal, redact = false, request) {
   const revisions = new Map;
   let candidateCount = 0;
   let enumerationTruncated = false;
@@ -2351,7 +2411,7 @@ async function captureCandidateRevisions(executable, args, cwd, maxFiles, signal
     await captureBatch(batch, revisions, signal, recordMetadataFailure);
   });
   const diagnostics = classifyRipgrepDiagnostics(result.stderr);
-  const inputError = createRipgrepInputError(result.stderr, redact);
+  const inputError = createRipgrepInputError(result.stderr, redact, request);
   const unreadable = [...diagnostics.unreadable, ...diagnostics.recoverable, ...metadataFailures];
   if (inputError)
     throw inputError;
@@ -2677,7 +2737,7 @@ function createRipgrepRunner(options = {}) {
         ...policy.ripgrepGlobArguments(validatedSearchPath),
         "--",
         searchTarget
-      ], ripgrepCwd, maxSourceRevisionFiles, signal, request.redact);
+      ], ripgrepCwd, maxSourceRevisionFiles, signal, request.redact, request);
       let ignoredFileCount = 0;
       let ignoredFileSamples = [];
       let filesystemCoverage = "complete";
@@ -2707,7 +2767,7 @@ function createRipgrepRunner(options = {}) {
           ...policy.ripgrepGlobArguments(validatedSearchPath),
           "--",
           searchTarget
-        ], ripgrepCwd, maxSourceRevisionFiles, signal, request.redact);
+        ], ripgrepCwd, maxSourceRevisionFiles, signal, request.redact, request);
         const ignored = [...allCandidates.revisions.keys()].filter((path) => !before.revisions.has(path));
         ignoredFileCount = ignored.length;
         ignoredFileSamples = ignored.slice(0, 20).map((path) => displayPath(path, cwd).displayPath);
@@ -2751,7 +2811,7 @@ function createRipgrepRunner(options = {}) {
         }
       }));
       const diagnostics = classifyRipgrepDiagnostics(stderr);
-      const inputError = createRipgrepInputError(stderr, request.redact);
+      const inputError = createRipgrepInputError(stderr, request.redact, request);
       if (inputError)
         throw inputError;
       const filesystemDiagnostics = [...diagnostics.unreadable, ...diagnostics.recoverable];
@@ -14857,7 +14917,7 @@ var siftLightSchema = Type.Object({
     description: "Named exact-literal checks for mode=audit. Each finding is present, absent_with_complete_coverage, or unknown."
   })),
   redact: Type.Optional(Type.Boolean({
-    description: "Optional display-only masking for credential-like values and private-key bodies. Default false. It never changes searched files, admitted matches, counts, or cursor completeness."
+    description: "Optional display-only masking for credential-like values and private-key bodies. Default false. Use it for configuration, logs and user-directory searches when returned text may contain secrets. It never changes the search scope, searched files, admitted matches, counts or cursor completeness, and it is not a sandbox."
   })),
   modifiedAfter: Type.Optional(Type.Integer({
     minimum: 0,

package/src/request-contract-catalog.ts

@@ -169,6 +169,8 @@ export const REQUEST_FIELD_GUIDANCE: Partial<Record<RequestField, string>> = {
   pattern: "pattern is regex by default; literal=true matches source text exactly",
   literal:
     "literal=true makes pattern exact source text; anyOf/allOf already use literal semantics",
+  redact:
+    "redact=true masks credential-like values and private-key bodies in displayed evidence; it does not sandbox search or change counts",
   path: "path must be an existing exact file or root; use mode=files+query for unknown names",
   query:
     "files+query matches known filename/path text (not glob patterns); omit files query to list every file under path; concept/hybrid query is natural language",
@@ -193,6 +195,7 @@ export function fieldGuidance(field: RequestField): string {
 
 const GUIDANCE_FIELDS = [
   "pattern",
+  "redact",
   "literal",
   "path",
   "query",
@@ -219,12 +222,13 @@ export const REQUEST_USAGE_GUIDANCE = [
 
 export const MODEL_USAGE_GUIDANCE = [
   "pattern is regex by default; literal=true matches source text exactly",
-  "path is an existing exact file or root; use files+query for an unknown name",
-  "anyOf/allOf are exact-literal OR/AND variants and exclude pattern/literal",
-  `limit/context are ordinary-search output budgets; limit <= ${String(MAX_PAGE_SIZE)}; omit both for hybrid/concept/outline/structure/inspect`,
-  "outline requires a concrete source file, not a directory; structure requires a nonempty AST pattern and JS/TS/TSX/Go sources, no lang field; use capabilities before unfamiliar language operations",
-  "outline supports JS/TS/TSX and bounded Python syntax; imports/tests are static candidates for JS/TS/TSX",
-  `selectors: ${modeFieldSummary("inspect")}; ${modeFieldSummary("hybrid")}; ${modeFieldSummary("capabilities")}`,
+  "redact=true masks credentials and private-key bodies in displayed evidence; use it for configs, logs or user directories; it does not sandbox search",
+  "path is an existing exact file/root; use files+query for unknown names",
+  "anyOf/allOf are exact-literal OR/AND variants; exclude pattern/literal",
+  `limit/context are ordinary-search budgets (limit <= ${String(MAX_PAGE_SIZE)}); omit for hybrid/concept/outline/structure/inspect`,
+  "outline needs a concrete JS/TS/TSX/Python-capable source file, not a directory; structure needs a nonempty AST pattern for JS/TS/TSX/Go, no lang; use capabilities before unfamiliar language operations",
+  "imports/tests are static JS/TS/TSX candidates",
+  "selectors: inspect, hybrid and capabilities use their cataloged fields",
   "exact, any-of and max_results are not parameters",
 ].join("; ");
 

package/src/rg.ts

@@ -435,6 +435,7 @@ export function createRipgrepRunner(options: RipgrepRunnerOptions = {}) {
         maxSourceRevisionFiles,
         signal,
         request.redact,
+        request,
       );
       let ignoredFileCount = 0;
       let ignoredFileSamples: string[] = [];
@@ -475,6 +476,7 @@ export function createRipgrepRunner(options: RipgrepRunnerOptions = {}) {
           maxSourceRevisionFiles,
           signal,
           request.redact,
+          request,
         );
         const ignored = [...allCandidates.revisions.keys()].filter(
           (path) => !before.revisions.has(path),
@@ -528,7 +530,7 @@ export function createRipgrepRunner(options: RipgrepRunnerOptions = {}) {
           }),
       );
       const diagnostics = classifyRipgrepDiagnostics(stderr);
-      const inputError = createRipgrepInputError(stderr, request.redact);
+      const inputError = createRipgrepInputError(stderr, request.redact, request);
       if (inputError) throw inputError;
       const filesystemDiagnostics = [...diagnostics.unreadable, ...diagnostics.recoverable];
       if (hasRequestedRootUnreadable(diagnostics.unreadable, cwd, validatedSearchPath))

package/src/ripgrep-diagnostics.ts

@@ -1,6 +1,11 @@
-import { resolve } from "node:path";
-import { RipgrepInputError, type RipgrepInputErrorCode } from "./errors.js";
-import { redactDiagnosticText } from "./redaction.js";
+import { basename, resolve } from "node:path";
+import {
+  RipgrepInputError,
+  type RipgrepInputErrorCode,
+  type SiftLightDiagnosticRepairExample,
+} from "./errors.js";
+import { containsSensitiveText, redactDiagnosticText } from "./redaction.js";
+import type { SearchRequest } from "./types.js";
 
 export interface RipgrepUnreadableDiagnostic {
   message: string;
@@ -63,9 +68,85 @@ function missingPathFromDiagnostics(stderr: string): string | undefined {
   return undefined;
 }
 
+export type RipgrepRecoveryRequest = Pick<
+  SearchRequest,
+  | "pattern"
+  | "path"
+  | "glob"
+  | "exclude"
+  | "literal"
+  | "ignoreCase"
+  | "hidden"
+  | "ignorePolicy"
+  | "wholeWord"
+  | "context"
+  | "scope"
+  | "redact"
+>;
+
+const RIPGREP_RECOVERY_FIELDS = [
+  "path",
+  "glob",
+  "exclude",
+  "literal",
+  "ignoreCase",
+  "hidden",
+  "ignorePolicy",
+  "wholeWord",
+  "context",
+  "scope",
+  "redact",
+] as const satisfies readonly (keyof RipgrepRecoveryRequest)[];
+
+function copyRipgrepRecoveryFields(request: RipgrepRecoveryRequest): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const field of RIPGREP_RECOVERY_FIELDS) {
+    const value = request[field];
+    if (value !== undefined) result[field] = value;
+  }
+  return result;
+}
+
+function ripgrepRepairExamples(
+  code: RipgrepInputErrorCode,
+  request: RipgrepRecoveryRequest | undefined,
+  redact: boolean,
+): readonly SiftLightDiagnosticRepairExample[] {
+  if (request === undefined || (redact && containsSensitiveText(request))) return [];
+  if (code === "E_REGEX_INVALID") {
+    return [
+      {
+        label: "按原文查找",
+        request: {
+          mode: "matches",
+          ...copyRipgrepRecoveryFields(request),
+          pattern: request.pattern,
+          literal: true,
+        },
+      },
+    ];
+  }
+  if (code === "E_SEARCH_PATH_NOT_FOUND" && request.path !== undefined) {
+    const fileName = basename(request.path.replaceAll("\\", "/"));
+    if (fileName === "." || fileName === "/" || fileName.length === 0) return [];
+    return [
+      {
+        label: "按文件名查找",
+        request: {
+          mode: "files",
+          query: fileName,
+          ...(request.redact === true ? { redact: true } : {}),
+        },
+      },
+    ];
+  }
+  return [];
+}
+
 export function createRipgrepInputError(
   stderr: string,
   redact = false,
+  request?: RipgrepRecoveryRequest,
 ): RipgrepInputError | undefined {
   const code = classifyRipgrepInputFailure(stderr);
   if (code === "E_REGEX_INVALID") {
@@ -73,6 +154,7 @@ export function createRipgrepInputError(
       code,
       "ripgrep regex parse error: pattern is not a valid regular expression.",
       "Correct pattern or set literal=true for source text; no automatic literal conversion was attempted.",
+      ripgrepRepairExamples(code, request, redact),
     );
   }
   if (code === "E_SEARCH_PATH_NOT_FOUND") {
@@ -82,6 +164,7 @@ export function createRipgrepInputError(
       code,
       `A searched path${location} does not exist or became unavailable.`,
       "Provide an existing exact path, or use mode=files with query to discover an unknown filename; no retry or scope expansion was attempted.",
+      ripgrepRepairExamples(code, request, redact),
     );
   }
   // Known input failures above intentionally omit ripgrep's raw pattern and path echo.

package/src/scan-revisions.ts

@@ -5,6 +5,7 @@ import {
   boundedRipgrepDiagnostic,
   classifyRipgrepDiagnostics,
   createRipgrepInputError,
+  type RipgrepRecoveryRequest,
   type RipgrepUnreadableDiagnostic,
 } from "./ripgrep-diagnostics.js";
 import { getSourceRevision, sameSourceRevision } from "./source.js";
@@ -48,6 +49,7 @@ export async function captureCandidateRevisions(
   maxFiles: number,
   signal?: AbortSignal,
   redact = false,
+  request?: RipgrepRecoveryRequest,
 ): Promise<{
   revisions: Map<string, SourceRevision>;
   unreadable: RipgrepUnreadableDiagnostic[];
@@ -111,7 +113,7 @@ export async function captureCandidateRevisions(
     },
   );
   const diagnostics = classifyRipgrepDiagnostics(result.stderr);
-  const inputError = createRipgrepInputError(result.stderr, redact);
+  const inputError = createRipgrepInputError(result.stderr, redact, request);
   const unreadable = [...diagnostics.unreadable, ...diagnostics.recoverable, ...metadataFailures];
   if (inputError) throw inputError;
   if (result.code === 2 && diagnostics.other.length === 0 && unreadable.length > 0)

package/src/tool-schema.ts

@@ -234,7 +234,7 @@ export const siftLightSchema = Type.Object({
   redact: Type.Optional(
     Type.Boolean({
       description:
-        "Optional display-only masking for credential-like values and private-key bodies. Default false. It never changes searched files, admitted matches, counts, or cursor completeness.",
+        "Optional display-only masking for credential-like values and private-key bodies. Default false. Use it for configuration, logs and user-directory searches when returned text may contain secrets. It never changes the search scope, searched files, admitted matches, counts or cursor completeness, and it is not a sandbox.",
     }),
   ),
   modifiedAfter: Type.Optional(