@pellux/goodvibes-agent 0.1.24 → 0.1.26

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to GoodVibes Agent will be recorded here.
 
+## 0.1.26 - 2026-05-31
+
+- dfb6147 Harden Agent read tool policy
+
+## 0.1.25 - 2026-05-31
+
+- cba5f6d Harden Agent find tool policy
+
 ## 0.1.24 - 2026-05-31
 
 - 2375df3 Bound web search tool policy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "private": false,
   "description": "Near-fork GoodVibes operator assistant with the GoodVibes TUI shell, renderer, input, fullscreen workspace, and daemon-connected Agent product brain.",
   "type": "module",

package/src/tools/agent-find-policy.ts

@@ -0,0 +1,124 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+
+type FindQueryArgs = {
+  readonly follow_symlinks?: unknown;
+  readonly include_hidden?: unknown;
+  readonly respect_gitignore?: unknown;
+  readonly [key: string]: unknown;
+};
+
+type FindOutputArgs = {
+  readonly format?: unknown;
+  readonly [key: string]: unknown;
+};
+
+type FindToolArgs = {
+  readonly queries?: unknown;
+  readonly output?: unknown;
+  readonly parallel?: unknown;
+  readonly [key: string]: unknown;
+};
+
+const READ_ONLY_FIND_OUTPUT_FORMATS = [
+  'count_only',
+  'files_only',
+  'locations',
+  'matches',
+  'context',
+  'with_stats',
+  'signatures',
+] as const;
+
+const READ_ONLY_FIND_OUTPUT_FORMAT_SET = new Set<string>(READ_ONLY_FIND_OUTPUT_FORMATS);
+
+const FIND_POLICY_DENIAL = [
+  'GoodVibes Agent only exposes serial, project-root, gitignore-respecting search from the main conversation.',
+  'Hidden-file scans, symlink traversal, gitignore bypass, broad file previews, full symbol dumps, and parallel search are disabled here.',
+  'Use explicit Agent CLI/slash commands or GoodVibes TUI delegation for deeper local inspection.',
+].join(' ');
+
+export const AGENT_READ_ONLY_FIND_OUTPUT_FORMATS = READ_ONLY_FIND_OUTPUT_FORMATS;
+export const AGENT_FIND_POLICY_DENIAL_MESSAGE = FIND_POLICY_DENIAL;
+
+export function wrapFindToolForAgentPolicy(tool: Tool): void {
+  narrowFindToolDefinitionForAgentPolicy(tool);
+  const originalExecute = tool.execute.bind(tool);
+  tool.execute = async (args) => {
+    const findArgs = args as FindToolArgs;
+    const denial = validateFindToolInvocationForAgentPolicy(findArgs);
+    if (denial) return { success: false, error: denial };
+    return originalExecute(normalizeFindToolInvocationForAgentPolicy(findArgs) as Parameters<Tool['execute']>[0]);
+  };
+}
+
+export function validateFindToolInvocationForAgentPolicy(args: FindToolArgs): string | null {
+  if (args.parallel === true) return FIND_POLICY_DENIAL;
+
+  if (Array.isArray(args.queries)) {
+    for (const query of args.queries) {
+      if (!isRecord(query)) continue;
+      const queryArgs = query as FindQueryArgs;
+      if (queryArgs.follow_symlinks === true) return FIND_POLICY_DENIAL;
+      if (queryArgs.include_hidden === true) return FIND_POLICY_DENIAL;
+      if (queryArgs.respect_gitignore === false) return FIND_POLICY_DENIAL;
+    }
+  }
+
+  if (isRecord(args.output)) {
+    const output = args.output as FindOutputArgs;
+    if (typeof output.format === 'string' && !READ_ONLY_FIND_OUTPUT_FORMAT_SET.has(output.format)) {
+      return FIND_POLICY_DENIAL;
+    }
+  }
+
+  return null;
+}
+
+export function normalizeFindToolInvocationForAgentPolicy(args: FindToolArgs): FindToolArgs {
+  return {
+    ...args,
+    parallel: false,
+  };
+}
+
+function narrowFindToolDefinitionForAgentPolicy(tool: Tool): void {
+  tool.definition.description = [
+    'Search the project for GoodVibes Agent using serial, gitignore-respecting read-only queries.',
+    'Hidden-file scans, symlink traversal, gitignore bypass, broad previews, full symbol dumps, and parallel search are disabled in the main conversation.',
+  ].join(' ');
+  tool.definition.sideEffects = ['read_fs'];
+  tool.definition.concurrency = 'serial';
+
+  const properties = tool.definition.parameters.properties;
+  if (!isRecord(properties)) return;
+  delete properties.parallel;
+
+  const queries = properties.queries;
+  if (isRecord(queries)) {
+    const itemSchema = queries.items;
+    if (isRecord(itemSchema)) {
+      const queryProperties = itemSchema.properties;
+      if (isRecord(queryProperties)) {
+        delete queryProperties.follow_symlinks;
+        delete queryProperties.include_hidden;
+        delete queryProperties.respect_gitignore;
+      }
+    }
+  }
+
+  const output = properties.output;
+  if (!isRecord(output)) return;
+  const outputProperties = output.properties;
+  if (!isRecord(outputProperties)) return;
+
+  const format = outputProperties.format;
+  if (isRecord(format)) {
+    format.enum = [...READ_ONLY_FIND_OUTPUT_FORMATS];
+    format.description = 'Bounded output format allowed by GoodVibes Agent main-conversation search policy.';
+  }
+  delete outputProperties.preview_lines;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/tools/agent-read-policy.ts

@@ -0,0 +1,179 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+
+type ReadFileArgs = {
+  readonly path?: unknown;
+  readonly image_mode?: unknown;
+  readonly [key: string]: unknown;
+};
+
+type ReadToolArgs = {
+  readonly files?: unknown;
+  readonly image_mode?: unknown;
+  readonly max_image_size?: unknown;
+  readonly [key: string]: unknown;
+};
+
+const READ_IMAGE_MODES = ['default', 'metadata-only', 'thumbnail-only'] as const;
+const READ_IMAGE_MODE_SET = new Set<string>(READ_IMAGE_MODES);
+const MAX_READ_FILES = 10;
+const MAX_READ_IMAGE_SIZE_BYTES = 5 * 1024 * 1024;
+
+const SECRET_FILE_EXTENSIONS = new Set([
+  '',
+  '.cfg',
+  '.conf',
+  '.env',
+  '.ini',
+  '.json',
+  '.properties',
+  '.toml',
+  '.txt',
+  '.yaml',
+  '.yml',
+]);
+
+const SECRET_EXACT_SEGMENTS = new Set([
+  '.netrc',
+  '.npmrc',
+  '.pypirc',
+  'apikey',
+  'api_key',
+  'credentials',
+  'id_dsa',
+  'id_ecdsa',
+  'id_ed25519',
+  'id_rsa',
+  'password',
+  'passwords',
+  'passwd',
+  'secret',
+  'secrets',
+  'token',
+  'tokens',
+]);
+
+const SECRET_EXACT_FILE_NAMES = new Set([
+  'known_hosts',
+]);
+
+const PRIVATE_KEY_EXTENSIONS = new Set([
+  '.key',
+  '.p12',
+  '.pem',
+  '.pfx',
+]);
+
+const READ_POLICY_DENIAL = [
+  'GoodVibes Agent only exposes bounded, non-secret project reads from the main conversation.',
+  'Hidden paths, secret-looking files, broad batches, unoptimized image extraction, and oversized image reads are disabled here.',
+  'Use explicit Agent CLI/slash commands or GoodVibes TUI delegation when the user intentionally asks for sensitive or deeper local inspection.',
+].join(' ');
+
+export const AGENT_READ_IMAGE_MODES = READ_IMAGE_MODES;
+export const AGENT_MAX_READ_FILES = MAX_READ_FILES;
+export const AGENT_MAX_READ_IMAGE_SIZE_BYTES = MAX_READ_IMAGE_SIZE_BYTES;
+export const AGENT_READ_POLICY_DENIAL_MESSAGE = READ_POLICY_DENIAL;
+
+export function wrapReadToolForAgentPolicy(tool: Tool): void {
+  narrowReadToolDefinitionForAgentPolicy(tool);
+  const originalExecute = tool.execute.bind(tool);
+  tool.execute = async (args) => {
+    const readArgs = args as ReadToolArgs;
+    const denial = validateReadToolInvocationForAgentPolicy(readArgs);
+    if (denial) return { success: false, error: denial };
+    return originalExecute(args);
+  };
+}
+
+export function validateReadToolInvocationForAgentPolicy(args: ReadToolArgs): string | null {
+  if (Array.isArray(args.files) && args.files.length > MAX_READ_FILES) return READ_POLICY_DENIAL;
+  if (args.image_mode === 'unoptimized') return READ_POLICY_DENIAL;
+  if (typeof args.image_mode === 'string' && !READ_IMAGE_MODE_SET.has(args.image_mode)) return READ_POLICY_DENIAL;
+  if (typeof args.max_image_size === 'number' && args.max_image_size > MAX_READ_IMAGE_SIZE_BYTES) {
+    return READ_POLICY_DENIAL;
+  }
+
+  if (!Array.isArray(args.files)) return null;
+  for (const file of args.files) {
+    if (!isRecord(file)) continue;
+    const fileArgs = file as ReadFileArgs;
+    if (fileArgs.image_mode === 'unoptimized') return READ_POLICY_DENIAL;
+    if (typeof fileArgs.image_mode === 'string' && !READ_IMAGE_MODE_SET.has(fileArgs.image_mode)) {
+      return READ_POLICY_DENIAL;
+    }
+    if (typeof fileArgs.path === 'string' && isBlockedReadPath(fileArgs.path)) return READ_POLICY_DENIAL;
+  }
+
+  return null;
+}
+
+export function isBlockedReadPath(path: string): boolean {
+  const segments = path.replaceAll('\\', '/').split('/').filter((segment) => segment.length > 0);
+  for (const segment of segments) {
+    if (segment === '.' || segment === '..') continue;
+    const lower = segment.toLowerCase();
+    if (lower.startsWith('.')) return true;
+    if (SECRET_EXACT_SEGMENTS.has(lower)) return true;
+  }
+
+  const fileName = segments.at(-1)?.toLowerCase() ?? '';
+  if (fileName.length === 0) return false;
+  if (SECRET_EXACT_FILE_NAMES.has(fileName)) return true;
+  const extension = getExtension(fileName);
+  if (PRIVATE_KEY_EXTENSIONS.has(extension)) return true;
+  const stem = extension.length > 0 ? fileName.slice(0, -extension.length) : fileName;
+  return SECRET_EXACT_SEGMENTS.has(stem) && SECRET_FILE_EXTENSIONS.has(extension);
+}
+
+function narrowReadToolDefinitionForAgentPolicy(tool: Tool): void {
+  tool.definition.description = [
+    'Read ordinary project files for GoodVibes Agent with bounded, non-secret, main-conversation policy.',
+    'Hidden paths, secret-looking files, broad batches, unoptimized image extraction, and oversized image reads are disabled.',
+  ].join(' ');
+  tool.definition.sideEffects = ['read_fs'];
+  tool.definition.concurrency = 'serial';
+
+  const properties = tool.definition.parameters.properties;
+  if (!isRecord(properties)) return;
+
+  const files = properties.files;
+  if (isRecord(files)) {
+    files.maxItems = MAX_READ_FILES;
+    files.description = 'Ordinary non-hidden, non-secret-looking project files to read. Sensitive paths require explicit user-directed workflows.';
+    const itemSchema = files.items;
+    if (isRecord(itemSchema)) {
+      const fileProperties = itemSchema.properties;
+      if (isRecord(fileProperties)) {
+        const pathProperty = fileProperties.path;
+        if (isRecord(pathProperty)) {
+          pathProperty.description = 'Relative or absolute path to a non-hidden, non-secret-looking project file.';
+        }
+        narrowImageModeProperty(fileProperties, 'image_mode');
+      }
+    }
+  }
+
+  narrowImageModeProperty(properties, 'image_mode');
+  const maxImageSize = properties.max_image_size;
+  if (isRecord(maxImageSize)) {
+    maxImageSize.maximum = MAX_READ_IMAGE_SIZE_BYTES;
+    maxImageSize.description = 'Maximum image file size in bytes allowed by GoodVibes Agent read policy.';
+  }
+}
+
+function narrowImageModeProperty(properties: Record<string, unknown>, key: string): void {
+  const property = properties[key];
+  if (!isRecord(property)) return;
+  property.enum = [...READ_IMAGE_MODES];
+  property.description = 'Image handling mode allowed by GoodVibes Agent read policy. Full-resolution unoptimized extraction is disabled.';
+}
+
+function getExtension(fileName: string): string {
+  const dotIndex = fileName.lastIndexOf('.');
+  if (dotIndex <= 0) return '';
+  return fileName.slice(dotIndex);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/tools/wrfc-agent-guard.ts

@@ -4,6 +4,8 @@ import {
   wrapAnalyzeToolForAgentPolicy,
   wrapRegistryToolForAgentPolicy,
 } from './agent-analysis-registry-policy.ts';
+import { wrapFindToolForAgentPolicy } from './agent-find-policy.ts';
+import { wrapReadToolForAgentPolicy } from './agent-read-policy.ts';
 import { wrapWebSearchToolForAgentPolicy } from './agent-web-search-policy.ts';
 
 type AgentToolArgs = {
@@ -197,6 +199,8 @@ export function installAgentToolPolicyGuard(registry: ToolRegistry, options: Age
   for (const tool of registry.list()) {
     if (tool.definition.name === 'exec') {
       wrapExecToolForAgentPolicy(tool);
+    } else if (tool.definition.name === 'read') {
+      wrapReadToolForAgentPolicy(tool);
     } else if (tool.definition.name === 'remote') {
       wrapModeRestrictedToolForAgentPolicy(tool, {
         allowedModes: READ_ONLY_REMOTE_TOOL_MODES,
@@ -231,6 +235,8 @@ export function installAgentToolPolicyGuard(registry: ToolRegistry, options: Age
       wrapAnalyzeToolForAgentPolicy(tool);
     } else if (tool.definition.name === 'registry') {
       wrapRegistryToolForAgentPolicy(tool);
+    } else if (tool.definition.name === 'find') {
+      wrapFindToolForAgentPolicy(tool);
     } else if (tool.definition.name === 'web_search') {
       wrapWebSearchToolForAgentPolicy(tool);
     } else if (tool.definition.name === 'control') {
@@ -556,6 +562,24 @@ export {
   wrapRegistryToolForAgentPolicy,
 } from './agent-analysis-registry-policy.ts';
 
+export {
+  AGENT_MAX_READ_FILES,
+  AGENT_MAX_READ_IMAGE_SIZE_BYTES,
+  AGENT_READ_IMAGE_MODES,
+  AGENT_READ_POLICY_DENIAL_MESSAGE,
+  isBlockedReadPath,
+  validateReadToolInvocationForAgentPolicy,
+  wrapReadToolForAgentPolicy,
+} from './agent-read-policy.ts';
+
+export {
+  AGENT_FIND_POLICY_DENIAL_MESSAGE,
+  AGENT_READ_ONLY_FIND_OUTPUT_FORMATS,
+  normalizeFindToolInvocationForAgentPolicy,
+  validateFindToolInvocationForAgentPolicy,
+  wrapFindToolForAgentPolicy,
+} from './agent-find-policy.ts';
+
 export {
   AGENT_MAX_WEB_SEARCH_EVIDENCE_TOP_N,
   AGENT_MAX_WEB_SEARCH_RESULTS,

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '0.1.24';
+let _version = '0.1.26';
 let _sdkVersion = '0.33.35';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8')) as {