@octocodeai/octocode-engine 16.6.0 → 16.7.0

package/dist/lsp/serverManifest.js

@@ -0,0 +1,116 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { detectPlatformId } from './platform.js';
+import { MANIFEST } from './serverManifestData.js';
+function loadManifest() {
+    return MANIFEST;
+}
+function sha256File(filePath) {
+    try {
+        return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+function readCacheMarker(markerPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(markerPath, 'utf8'));
+        if (typeof parsed.binarySha256 !== 'string' ||
+            !/^[0-9a-f]{64}$/u.test(parsed.binarySha256) ||
+            typeof parsed.size !== 'number' ||
+            !Number.isSafeInteger(parsed.size) ||
+            parsed.size < 0) {
+            return null;
+        }
+        return { binarySha256: parsed.binarySha256, size: parsed.size };
+    }
+    catch {
+        return null;
+    }
+}
+/** The configured auto-install policy. Defaults to `prompt` when unset (asks before downloading). Set OCTOCODE_LSP_AUTO_INSTALL=off to disable all downloads, or =auto to skip the prompt. */
+export function provisionMode(env = process.env) {
+    const raw = (env.OCTOCODE_LSP_AUTO_INSTALL ?? '').trim().toLowerCase();
+    if (raw === 'auto' || raw === 'off')
+        return raw;
+    return 'prompt';
+}
+/** The manifest entry for a server, keyed by its bare command name. */
+export function manifestServer(serverName) {
+    return loadManifest().servers[path.basename(serverName)] ?? null;
+}
+/** Every auto-downloadable server in the manifest (for `lsp-server list`). */
+export function listManifestServers() {
+    return Object.entries(loadManifest().servers).map(([name, server]) => ({
+        name,
+        languageId: server.languageId,
+        releaseTag: server.releaseTag,
+    }));
+}
+/** Whether the manifest can, in principle, auto-provide this server. */
+export function isAutoDownloadable(serverName) {
+    return manifestServer(serverName) != null;
+}
+/**
+ * Root of the managed server cache. Defaults to `~/.octocode/lsp` (consistent
+ * with the rest of octocode's home), overridable via `OCTOCODE_LSP_CACHE_DIR`
+ * for read-only/ephemeral sandbox HOMEs or to point at a pre-baked image path.
+ */
+export function managedCacheRoot(env = process.env) {
+    const override = env.OCTOCODE_LSP_CACHE_DIR?.trim();
+    if (override)
+        return path.resolve(override);
+    return path.join(homedir(), '.octocode', 'lsp');
+}
+/** Where a provisioned binary lives once installed/extracted. */
+export function cachedServerBinPath(serverName, platformId = detectPlatformId()) {
+    const server = manifestServer(serverName);
+    const asset = server?.platforms[platformId];
+    if (!server || !asset)
+        return null;
+    return path.join(managedCacheRoot(), path.basename(serverName), server.releaseTag, asset.binName);
+}
+/**
+ * If a managed binary is already present AND verified in the cache (downloaded
+ * by a prior run, by CI, or pre-baked), return its absolute path. A binary is
+ * only trusted when its sibling `<binName>.ok` completion marker contains the
+ * current binary's SHA-256 and size. A half-written or tampered binary from an
+ * interrupted install has no matching marker and is ignored, so it never
+ * resolves as "installed". Read-only — always safe to call.
+ */
+export function resolveCachedServer(serverName, platformId = detectPlatformId()) {
+    const binPath = cachedServerBinPath(serverName, platformId);
+    if (!binPath || !existsSync(binPath))
+        return null;
+    const marker = readCacheMarker(`${binPath}.ok`);
+    if (!marker)
+        return null;
+    let size;
+    try {
+        size = statSync(binPath).size;
+    }
+    catch {
+        return null;
+    }
+    if (size !== marker.size)
+        return null;
+    return sha256File(binPath) === marker.binarySha256 ? binPath : null;
+}
+/** Human-readable provisioning guidance for a server with no resolved binary. */
+export function manifestInstallHint(serverName) {
+    const server = manifestServer(serverName);
+    if (!server)
+        return null;
+    const platformId = detectPlatformId();
+    const unsupported = server.unsupportedPlatforms?.[platformId];
+    if (unsupported)
+        return unsupported;
+    const mode = provisionMode();
+    if (mode === 'off') {
+        return `${serverName} can be auto-downloaded from ${server.repo} (${server.releaseTag}). Re-enable with OCTOCODE_LSP_AUTO_INSTALL=prompt (or =auto), or run \`lsp-server install ${serverName}\`.`;
+    }
+    return `${serverName} (${server.releaseTag}) will be auto-downloaded on first use from ${server.repo}.`;
+}

package/dist/lsp/serverManifestData.d.ts

@@ -0,0 +1,2 @@
+import type { ManifestFile } from './serverManifest.js';
+export declare const MANIFEST: ManifestFile;

package/dist/lsp/serverManifestData.js

@@ -0,0 +1,96 @@
+export const MANIFEST = {
+    "$comment": "Auto-download manifest for portable, toolchain-free language servers. Verified 2026-06-28 against live GitHub Releases. SHA-256 pinned per asset — download is refused if the checksum mismatches. Scope: Rust (rust-analyzer, gz, auto-download ready), C/C++ (clangd, zip, auto-download ready). Toolchain-coupled servers (gopls/go, jdtls/jre) are detect-and-instruct; pure-JS servers (typescript-language-server, pyright, yaml/json/html/css) are bundled npm deps. Markdown/MDX handled by the MINIFIER, NOT LSP. This JSON is the source of truth; src/lsp/serverManifestData.ts is generated from it by scripts/gen-server-manifest.mjs (run via `yarn manifest:gen` / the `verify:manifest` gate).",
+    "version": 1,
+    "servers": {
+        "clangd": {
+            "languageId": "cpp",
+            "launchArgs": [],
+            "platforms": {
+                "darwin-arm64": {
+                    "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-mac-22.1.0.zip",
+                    "archive": "zip",
+                    "binPath": "clangd_22.1.0/bin/clangd",
+                    "binName": "clangd",
+                    "sha256": "e31e271fe11f6dcd7cf87ca74be4a12788ff8ce5a0b07762583e335c058e939a"
+                },
+                "darwin-x64": {
+                    "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-mac-22.1.0.zip",
+                    "archive": "zip",
+                    "binPath": "clangd_22.1.0/bin/clangd",
+                    "binName": "clangd",
+                    "sha256": "e31e271fe11f6dcd7cf87ca74be4a12788ff8ce5a0b07762583e335c058e939a"
+                },
+                "linux-x64": {
+                    "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-linux-22.1.0.zip",
+                    "archive": "zip",
+                    "binPath": "clangd_22.1.0/bin/clangd",
+                    "binName": "clangd",
+                    "sha256": "71eddc5303da9a5bc5e8b509488b5b2c5acf45f20e33b8394e71a12a56d67198"
+                },
+                "win32-x64": {
+                    "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-windows-22.1.0.zip",
+                    "archive": "zip",
+                    "binPath": "clangd_22.1.0/bin/clangd.exe",
+                    "binName": "clangd.exe",
+                    "sha256": "c54e57dbff3ccc9e8352367ddb7030ad3f624073ec58c7477424e7919f578572"
+                }
+            },
+            "releaseTag": "22.1.0",
+            "repo": "clangd/clangd",
+            "unsupportedPlatforms": {
+                "linux-arm64": "clangd publishes no linux-arm64 release asset; install via the system package manager."
+            }
+        },
+        "rust-analyzer": {
+            "languageId": "rust",
+            "platforms": {
+                "darwin-arm64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-aarch64-apple-darwin.gz",
+                    "archive": "gz",
+                    "binName": "rust-analyzer",
+                    "sha256": "c8cdf6d5e488752b907d5ee15e31768b59a78d992e9a54b9f9660e1bfdf39f27"
+                },
+                "darwin-x64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-apple-darwin.gz",
+                    "archive": "gz",
+                    "binName": "rust-analyzer",
+                    "sha256": "feb7c170d2c1a2e4b8a88ac73f937eddb576828e3821b0a63ee0e64bd0bc9440"
+                },
+                "linux-arm64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-aarch64-unknown-linux-gnu.gz",
+                    "archive": "gz",
+                    "binName": "rust-analyzer",
+                    "sha256": "bf65b0d4586f127ab11bf33476dd6aac82dad173946c5d3b1cede19d63ae85ed"
+                },
+                "linux-x64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-unknown-linux-gnu.gz",
+                    "archive": "gz",
+                    "binName": "rust-analyzer",
+                    "sha256": "9602ca5b24dcaa07a5a021274763bed367d8a32da9a226fe3e139de3306569cb"
+                },
+                "linux-x64-musl": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-unknown-linux-musl.gz",
+                    "archive": "gz",
+                    "binName": "rust-analyzer",
+                    "sha256": "fe1d7b0e9733f7a439e4b6f27b8c4cc7afd87ae28fc5b496eb8df31d674b78dd"
+                },
+                "win32-arm64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-aarch64-pc-windows-msvc.zip",
+                    "archive": "zip",
+                    "binPath": "rust-analyzer.exe",
+                    "binName": "rust-analyzer.exe",
+                    "sha256": "30f873713ea3663db10999c23e95b74fe19968c893d5c0e9b8a896b31dbf8cf8"
+                },
+                "win32-x64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-pc-windows-msvc.zip",
+                    "archive": "zip",
+                    "binPath": "rust-analyzer.exe",
+                    "binName": "rust-analyzer.exe",
+                    "sha256": "6071dc5b28aa6d22c715f63c08d75b827c066be4ea866796587e52ed48b2922f"
+                }
+            },
+            "releaseTag": "2026-06-22",
+            "repo": "rust-lang/rust-analyzer"
+        }
+    }
+};

package/dist/lsp/serverProvisioner.d.ts

@@ -0,0 +1,19 @@
+import { type PlatformId } from './platform.js';
+import { provisionMode } from './serverManifest.js';
+export interface ProvisionResult {
+    ok: boolean;
+    path?: string;
+    source?: 'already-present' | 'downloaded';
+    error?: string;
+}
+/**
+ * Provision `serverName` into the managed cache. Idempotent: returns the
+ * already-present path when a verified copy exists. Pure-data inputs come from
+ * `serverManifest.json`; nothing is executed during install.
+ */
+export declare function provisionServer(serverName: string, options?: {
+    mode?: ReturnType<typeof provisionMode>;
+    signal?: AbortSignal;
+}): Promise<ProvisionResult>;
+/** Remove a server from the managed cache only (never touches external installs). */
+export declare function uninstallServer(serverName: string, platformId?: PlatformId): boolean;

package/dist/lsp/serverProvisioner.js

@@ -0,0 +1,262 @@
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, openSync, closeSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { gunzipSync, inflateRawSync } from 'node:zlib';
+import { detectPlatformId } from './platform.js';
+import { cachedServerBinPath, managedCacheRoot, manifestServer, provisionMode, resolveCachedServer, } from './serverManifest.js';
+/**
+ * The write half of LSP provisioning — downloads a pinned, verified portable
+ * server binary into the managed cache. This is invoked ONLY by the explicit
+ * `octocode lsp-server install` path, never lazily during a semantic query
+ * (the resolution ladder's L4 stays read-only). Provisioning a server is
+ * orthogonal to the runtime contract: when no server is available at query
+ * time the tool layer throws and the agent pivots to text search.
+ *
+ * Security invariants (all enforced here):
+ *   - opt-in: refuses unless OCTOCODE_LSP_AUTO_INSTALL is prompt|auto
+ *   - pinned SHA-256 gate: refuses if the manifest sha256 is null
+ *   - host allowlist on the request URL AND every redirect hop; https only
+ *   - atomic: download to a temp file in the dest dir, verify, chmod, rename
+ *   - `.ok` completion marker written last, so a partial install never resolves
+ *   - per-target lock so editor + CLI don't race the same download
+ * v1 handles `gz`, `zip`, and `none` (raw) assets with zero new deps; archive
+ * formats needing tar/xz extraction return a clear "install manually" error.
+ */
+const ALLOWED_HOSTS = new Set([
+    'github.com',
+    // GitHub release assets redirect to a CDN host; both the legacy
+    // (objects.) and current (release-assets.) hosts are GitHub-owned.
+    'objects.githubusercontent.com',
+    'release-assets.githubusercontent.com',
+    'releases.hashicorp.com',
+]);
+const MAX_REDIRECTS = 5;
+const LOCK_STALE_MS = 10 * 60 * 1000;
+function fail(error) {
+    return { ok: false, error };
+}
+function hostAllowed(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'https:' && ALLOWED_HOSTS.has(parsed.hostname);
+    }
+    catch {
+        return false;
+    }
+}
+/** Fetch following redirects manually, re-checking the host allowlist each hop. */
+async function fetchAllowlisted(url, signal) {
+    let current = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        if (!hostAllowed(current)) {
+            // Report only the host — release-asset URLs carry signed query tokens we
+            // must not echo into logs/CLI output.
+            let host;
+            try {
+                host = new URL(current).host;
+            }
+            catch {
+                host = '(unparseable url)';
+            }
+            return { ok: false, error: `Blocked non-allowlisted/insecure host: ${host}` };
+        }
+        let response;
+        try {
+            response = await fetch(current, { redirect: 'manual', signal });
+        }
+        catch (err) {
+            return { ok: false, error: `Download failed: ${err instanceof Error ? err.message : String(err)}` };
+        }
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get('location');
+            if (!location)
+                return { ok: false, error: 'Redirect without Location header' };
+            current = new URL(location, current).toString();
+            continue;
+        }
+        if (!response.ok) {
+            return { ok: false, error: `Download failed: HTTP ${response.status}` };
+        }
+        return { ok: true, body: await response.arrayBuffer() };
+    }
+    return { ok: false, error: 'Too many redirects' };
+}
+function sha256(buffer) {
+    return createHash('sha256').update(buffer).digest('hex');
+}
+/** Decode the downloaded asset into the final executable bytes. */
+function extractBinary(asset, raw) {
+    switch (asset.archive) {
+        case 'none':
+            return { ok: true, bytes: raw };
+        case 'gz':
+            return { ok: true, bytes: gunzipSync(raw) };
+        case 'zip': {
+            if (!asset.binPath) {
+                return { ok: false, error: 'zip asset is missing binPath in manifest' };
+            }
+            const extracted = extractFromZip(raw, asset.binPath);
+            if (!extracted) {
+                return {
+                    ok: false,
+                    error: `Could not find '${asset.binPath}' in zip archive — try installing via your package manager.`,
+                };
+            }
+            return { ok: true, bytes: extracted };
+        }
+        case 'tar.gz':
+        case 'tar.xz':
+            return {
+                ok: false,
+                error: `Archive format '${asset.archive}' is not supported; install the server via your package manager.`,
+            };
+        default:
+            return { ok: false, error: `Unknown archive format '${asset.archive}'` };
+    }
+}
+/**
+ * Minimal ZIP local-file-header parser. Handles stored (method 0) and deflate
+ * (method 8) entries — the two methods used by all known LSP server releases.
+ * Searches for `targetPath` by exact match or trailing-segment match so both
+ * `clangd_22.1.0/bin/clangd` and `./clangd_22.1.0/bin/clangd` resolve.
+ */
+function extractFromZip(zipBuffer, targetPath) {
+    const LOCAL_HEADER_SIG = 0x04034b50;
+    const normalizedTarget = targetPath.replace(/^\.?\//u, '');
+    let offset = 0;
+    while (offset + 30 < zipBuffer.length) {
+        if (zipBuffer.readUInt32LE(offset) !== LOCAL_HEADER_SIG)
+            break;
+        const compressionMethod = zipBuffer.readUInt16LE(offset + 8);
+        const compressedSize = zipBuffer.readUInt32LE(offset + 18);
+        const filenameLen = zipBuffer.readUInt16LE(offset + 26);
+        const extraLen = zipBuffer.readUInt16LE(offset + 28);
+        const filename = zipBuffer
+            .subarray(offset + 30, offset + 30 + filenameLen)
+            .toString('utf8')
+            .replace(/^\.?\//u, '');
+        const dataOffset = offset + 30 + filenameLen + extraLen;
+        // Guard against a malformed or truncated ZIP with bogus size fields —
+        // compressedSize is UInt32 and could overflow past the buffer.
+        if (dataOffset + compressedSize > zipBuffer.length)
+            break;
+        if (filename === normalizedTarget) {
+            const compressed = zipBuffer.subarray(dataOffset, dataOffset + compressedSize);
+            if (compressionMethod === 0)
+                return compressed; // stored
+            if (compressionMethod === 8)
+                return inflateRawSync(compressed); // deflate
+            return null; // unsupported method within zip
+        }
+        offset = dataOffset + compressedSize;
+    }
+    return null;
+}
+function acquireLock(lockPath) {
+    try {
+        closeSync(openSync(lockPath, 'wx'));
+        return true;
+    }
+    catch {
+        // Reclaim a stale lock from a crashed/killed installer.
+        try {
+            if (Date.now() - statSync(lockPath).mtimeMs > LOCK_STALE_MS) {
+                rmSync(lockPath, { force: true });
+                closeSync(openSync(lockPath, 'wx'));
+                return true;
+            }
+        }
+        catch {
+            /* fall through */
+        }
+        return false;
+    }
+}
+/**
+ * Provision `serverName` into the managed cache. Idempotent: returns the
+ * already-present path when a verified copy exists. Pure-data inputs come from
+ * `serverManifest.json`; nothing is executed during install.
+ */
+export async function provisionServer(serverName, options = {}) {
+    const platformId = detectPlatformId();
+    const mode = options.mode ?? provisionMode();
+    const server = manifestServer(serverName);
+    if (!server)
+        return fail(`${serverName} is not an auto-downloadable server.`);
+    const unsupported = server.unsupportedPlatforms?.[platformId];
+    if (unsupported)
+        return fail(unsupported);
+    const asset = server.platforms[platformId];
+    if (!asset) {
+        return fail(`No ${serverName} asset for platform ${platformId}.`);
+    }
+    // Idempotent: a verified copy is already present.
+    const existing = resolveCachedServer(serverName, platformId);
+    if (existing)
+        return { ok: true, path: existing, source: 'already-present' };
+    if (mode === 'off') {
+        return fail('Auto-install is off. Set OCTOCODE_LSP_AUTO_INSTALL=prompt|auto (or pass --yes) to allow downloading.');
+    }
+    if (!asset.sha256) {
+        return fail(`${serverName} has no pinned sha256 in the manifest yet; refusing to download unverified bytes.`);
+    }
+    const binPath = cachedServerBinPath(serverName, platformId);
+    if (!binPath)
+        return fail(`Cannot compute cache path for ${serverName}.`);
+    const dir = path.dirname(binPath);
+    mkdirSync(dir, { recursive: true });
+    const lockPath = path.join(dir, '.lock');
+    if (!acquireLock(lockPath)) {
+        return fail(`Another install of ${serverName} is in progress (${lockPath}).`);
+    }
+    try {
+        // Re-check after acquiring the lock (another process may have finished).
+        const racedWinner = resolveCachedServer(serverName, platformId);
+        if (racedWinner)
+            return { ok: true, path: racedWinner, source: 'already-present' };
+        const fetched = await fetchAllowlisted(asset.url, options.signal);
+        if (!fetched.ok)
+            return fail(fetched.error);
+        const downloaded = Buffer.from(fetched.body);
+        const actualSha = sha256(downloaded);
+        if (actualSha !== asset.sha256) {
+            return fail(`Checksum mismatch for ${serverName}: expected ${asset.sha256}, got ${actualSha}.`);
+        }
+        const extracted = extractBinary(asset, downloaded);
+        if (!extracted.ok)
+            return fail(extracted.error);
+        // Atomic: write a temp file in the same dir, chmod, then rename into place.
+        const tmpPath = `${binPath}.tmp-${process.pid}`;
+        writeFileSync(tmpPath, extracted.bytes);
+        if (process.platform !== 'win32')
+            chmodSync(tmpPath, 0o755);
+        renameSync(tmpPath, binPath);
+        // Completion marker LAST — resolveCachedServer trusts only a marker that
+        // matches the final binary's hash and size.
+        writeFileSync(`${binPath}.ok`, JSON.stringify({
+            assetSha256: asset.sha256,
+            binarySha256: sha256(extracted.bytes),
+            size: extracted.bytes.length,
+        }));
+        return { ok: true, path: binPath, source: 'downloaded' };
+    }
+    finally {
+        rmSync(lockPath, { force: true });
+    }
+}
+/** Remove a server from the managed cache only (never touches external installs). */
+export function uninstallServer(serverName, platformId = detectPlatformId()) {
+    const binPath = cachedServerBinPath(serverName, platformId);
+    if (!binPath)
+        return false;
+    const serverDir = path.dirname(path.dirname(binPath)); // <root>/<server>
+    if (!existsSync(serverDir))
+        return false;
+    // Guard: only ever delete inside the managed cache root.
+    const root = managedCacheRoot();
+    if (!path.resolve(serverDir).startsWith(path.resolve(root) + path.sep)) {
+        return false;
+    }
+    rmSync(serverDir, { recursive: true, force: true });
+    return true;
+}

package/dist/lsp/types.d.ts

@@ -1,4 +1,22 @@
 export type InitializationOptions = Record<string, unknown>;
+/**
+ * Outcome of `waitForReady` — a readiness signal that lets a zero-results
+ * semantic query be interpreted honestly:
+ *   - `progressIdle`   — a `$/progress` indexing cycle was seen and drained to
+ *     idle; an empty answer reflects the fully-indexed project.
+ *   - `settledFallback`— no `$/progress` was ever seen, only the fixed settle
+ *     window elapsed; indexing completion is unconfirmed.
+ *   - `timeout`        — `$/progress` was still active when the deadline hit;
+ *     the server is (as far as we know) still indexing.
+ */
+export type LspReadiness = 'progressIdle' | 'settledFallback' | 'timeout';
+/**
+ * Where a language-server executable was resolved from, for honest status
+ * reporting. Ordered by the resolution ladder (see docs/context/LSP_GUIDE.md):
+ * explicit override / PATH → bundled JS dep → project-local → ecosystem dir →
+ * managed download cache → IDE bridge; `unavailable` when nothing provides it.
+ */
+export type LspServerSource = 'path' | 'bundled' | 'project-local' | 'ecosystem' | 'managed-cache' | 'ide-bridge' | 'unavailable';
 export interface LanguageServerConfig {
     command: string;
     args?: string[];

package/dist/security/commandValidator.js

@@ -201,6 +201,15 @@ function validateCommandArgs(command, args) {
             };
         }
     }
+    else {
+        const backendError = validateArchiveBackendArgs(command, args);
+        if (backendError) {
+            return { isValid: false, error: backendError };
+        }
+    }
+    // grep: no per-flag allowlist — only the shared dangerous-pattern scan below
+    // applies. grep flags are wide (e.g. -r, -Z, --include) and intentionally
+    // left to the pattern scan rather than a strict allowlist.
     const patternPositions = getPatternArgPositions(command, args);
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -274,6 +283,64 @@ function getGrepPatternPositions(args) {
     }
     return positions;
 }
+function isPathLikeArg(value) {
+    return value.length > 0 && !value.startsWith('-');
+}
+function exactArgs(args, expected) {
+    return args.length === expected.length && args.every((arg, i) => arg === expected[i]);
+}
+function validateArchiveBackendArgs(command, args) {
+    switch (command) {
+        case 'file':
+            return args.length === 3 && exactArgs(args.slice(0, 2), ['--mime-type', '-b']) && isPathLikeArg(args[2])
+                ? null
+                : 'file arguments are restricted to --mime-type -b <path>';
+        case 'zcat':
+        case 'bzcat':
+        case 'zstdcat':
+        case 'lz4cat':
+            return args.length === 1 && isPathLikeArg(args[0])
+                ? null
+                : `${command} arguments are restricted to <path>`;
+        case 'gunzip':
+            return args.length === 2 && args[0] === '-c' && isPathLikeArg(args[1])
+                ? null
+                : 'gunzip arguments are restricted to -c <path>';
+        case 'xzcat':
+            return (args.length === 1 && isPathLikeArg(args[0])) ||
+                (args.length === 2 && args[0] === '--format=lzma' && isPathLikeArg(args[1]))
+                ? null
+                : 'xzcat arguments are restricted to <path> or --format=lzma <path>';
+        case 'zstd':
+            return args.length === 2 && args[0] === '-dcq' && isPathLikeArg(args[1])
+                ? null
+                : 'zstd arguments are restricted to -dcq <path>';
+        case 'brotli':
+            return args.length === 2 && args[0] === '-dc' && isPathLikeArg(args[1])
+                ? null
+                : 'brotli arguments are restricted to -dc <path>';
+        case 'lzfse':
+            return args.length === 5 && exactArgs(args.slice(0, 2), ['-decode', '-i']) && isPathLikeArg(args[2]) && args[3] === '-o' && args[4] === '/dev/stdout'
+                ? null
+                : 'lzfse arguments are restricted to -decode -i <path> -o /dev/stdout';
+        case 'tar':
+        case 'bsdtar':
+            return args.length === 4 && args[0] === '-xOf' && isPathLikeArg(args[1]) && args[2] === '--' && args[3].length > 0
+                ? null
+                : `${command} arguments are restricted to -xOf <archive> -- <entry>`;
+        case 'unzip':
+            return args.length === 3 && args[0] === '-p' && isPathLikeArg(args[1]) && args[2].length > 0
+                ? null
+                : 'unzip arguments are restricted to -p <archive> <entry>';
+        case '7z':
+        case '7zz':
+            return args.length === 6 && exactArgs(args.slice(0, 4), ['e', '-so', '-bd', '--']) && isPathLikeArg(args[4]) && args[5].length > 0
+                ? null
+                : `${command} arguments are restricted to e -so -bd -- <archive> <entry>`;
+        default:
+            return null;
+    }
+}
 const FIND_PATTERN_ARGS = new Set([
     '-name',
     '-iname',
@@ -295,16 +362,13 @@ function getFindPatternPositions(args) {
     return positions;
 }
 function getPatternArgPositions(command, args) {
-    switch (true) {
-        case isRgCommand(command):
-            return getRgPatternPositions(args);
-        case command === 'grep':
-            return getGrepPatternPositions(args);
-        case command === 'find':
-            return getFindPatternPositions(args);
-        default:
-            return new Set();
-    }
+    if (isRgCommand(command))
+        return getRgPatternPositions(args);
+    if (command === 'grep')
+        return getGrepPatternPositions(args);
+    if (command === 'find')
+        return getFindPatternPositions(args);
+    return new Set();
 }
 function findDisallowedRgFlag(args) {
     for (let i = 0; i < args.length; i++) {

package/dist/security/contentSanitizer.js

@@ -163,9 +163,10 @@ function validateRecursive(params, depth, ancestorStack) {
                 hasValidationErrors = true;
                 r.warnings.forEach(w => warnings.add(`Invalid nested object in parameter ${key}: ${w}`));
             }
-            else {
-                sanitizedParams[key] = r.sanitizedParams;
-            }
+            // Always include sanitized data — tool handlers must not receive undefined
+            // for a key that was present in the input, even when the nested object had
+            // validation issues. The sanitized partial result is still safer than the raw.
+            sanitizedParams[key] = r.sanitizedParams;
         }
         else {
             sanitizedParams[key] = value;

package/dist/security/discoveryFilter.js

@@ -1,3 +1,10 @@
+// Discovery pruning lists: skip these dirs/files/extensions during tree walks.
+// SYNC NOTE: pathPatterns.ts:IGNORED_PATH_PATTERNS and
+// filePatterns.ts:IGNORED_FILE_PATTERNS overlap these lists (e.g. .git, .aws,
+// .ssh, .docker, .kube, id_rsa, .pem, .key). The two systems have different
+// roles — pathPatterns/filePatterns block *access* (read-time check);
+// discoveryFilter blocks *visibility* (tree-walk pruning). Both must be kept
+// in sync so that adding a sensitive path/file to one is reflected in the other.
 export const DISCOVERY_IGNORED_FOLDER_NAMES = [
     '.github',
     '.git',
@@ -62,6 +69,9 @@ export const DISCOVERY_IGNORED_FOLDER_NAMES = [
     '.mvn',
     '.aws',
     '.gcp',
+    '.ssh',
+    '.kube',
+    '.docker',
     'fastlane',
     'DerivedData',
     'xcuserdata',