goatchain 0.0.13 → 0.0.14

package/dist/lib/access-control/controller.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Tool Access Controller
+ *
+ * Provides methods to query tool access modes based on a policy.
+ */
+import type { ToolAccessPolicy, ToolAccessMode } from './types';
+/**
+ * Tool Access Controller
+ *
+ * Responsible for determining tool access modes based on a policy.
+ */
+export declare class ToolAccessController {
+    private policy;
+    constructor(policy: ToolAccessPolicy);
+    /**
+     * Get the access mode for a specific tool
+     *
+     * @param toolName - Name of the tool
+     * @returns The access mode for the tool
+     */
+    getAccessMode(toolName: string): ToolAccessMode;
+    /**
+     * Get all blocked tool names
+     *
+     * @returns Array of tool names that are blocked
+     */
+    getBlockedTools(): string[];
+    /**
+     * Get all restricted tool names
+     *
+     * Restricted tools require special handling (e.g., BashTool read-only mode).
+     *
+     * @returns Array of tool names that are restricted
+     */
+    getRestrictedTools(): string[];
+    /**
+     * Check if a tool is blocked
+     *
+     * @param toolName - Name of the tool
+     * @returns true if the tool is blocked
+     */
+    isBlocked(toolName: string): boolean;
+    /**
+     * Check if a tool is restricted
+     *
+     * @param toolName - Name of the tool
+     * @returns true if the tool is restricted
+     */
+    isRestricted(toolName: string): boolean;
+    /**
+     * Check if a tool has full access
+     *
+     * @param toolName - Name of the tool
+     * @returns true if the tool has full access
+     */
+    hasFullAccess(toolName: string): boolean;
+}

package/dist/lib/access-control/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Tool Access Control Module
+ *
+ * Provides a unified system for controlling tool access in different
+ * execution contexts (Plan Mode, Explore subagent, etc.).
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   ToolAccessController,
+ *   PLAN_MODE_POLICY,
+ *   isReadOnlyBashCommand
+ * } from '../lib/access-control'
+ *
+ * const controller = new ToolAccessController(PLAN_MODE_POLICY)
+ * const blockedTools = controller.getBlockedTools()
+ * // ['Write', 'Edit', 'ast_grep_replace', 'TodoWrite']
+ *
+ * const bashMode = controller.getAccessMode('Bash')
+ * // 'restricted'
+ *
+ * const validation = isReadOnlyBashCommand('ls -la')
+ * // { isAllowed: true }
+ * ```
+ */
+export type { ToolAccessMode, ToolAccessPolicy, ToolValidationResult } from './types';
+export { ToolAccessController } from './controller';
+export { PLAN_MODE_POLICY, EXPLORE_POLICY, GENERAL_PURPOSE_POLICY, } from './policies';
+export { READ_ONLY_COMMANDS, FORBIDDEN_PATTERNS, isReadOnlyBashCommand, assertReadOnlyBashCommand, } from './validators';

package/dist/lib/access-control/policies.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Predefined Tool Access Policies
+ *
+ * Provides standard access policies for different execution contexts.
+ */
+import type { ToolAccessPolicy } from './types';
+/**
+ * Plan Mode Read-Only Policy
+ *
+ * Allows:
+ * - All read tools (Read, Glob, Grep, WebSearch, WebFetch)
+ * - Read-only Bash commands (via BashTool internal validation)
+ * - User interaction tools (AskUserQuestion)
+ * - Task tool (limited to Explore subagent only)
+ *
+ * Blocks:
+ * - All write tools (Write, Edit)
+ * - Code modification tools (ast_grep_replace)
+ * - TodoWrite (use TodoPlan instead in Plan Mode)
+ * - Non-read-only Bash commands (validated by BashTool)
+ * - Task calls to non-Explore subagents (validated by TaskTool)
+ *
+ * Note: 'restricted' mode tools are not blocked by Session's blocked list.
+ * The actual restrictions are enforced internally by the tool based on ctx.metadata:
+ * - Bash: checks ctx.metadata.readOnlyBash, calls isReadOnlyBashCommand()
+ * - Task: checks ctx.metadata.planMode, only allows subagent_type === 'Explore'
+ */
+export declare const PLAN_MODE_POLICY: ToolAccessPolicy;
+/**
+ * Explore Subagent Read-Only Policy
+ *
+ * Allows only read operations for fast codebase exploration.
+ */
+export declare const EXPLORE_POLICY: ToolAccessPolicy;
+/**
+ * General Purpose Agent Policy
+ *
+ * Full access to all tools except Task (to prevent infinite recursion).
+ */
+export declare const GENERAL_PURPOSE_POLICY: ToolAccessPolicy;

package/dist/lib/access-control/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tool Access Control Types
+ *
+ * Defines types for controlling tool access in different execution contexts
+ * (e.g., Plan Mode, Explore subagent).
+ */
+/**
+ * Tool access mode
+ */
+export type ToolAccessMode = 'full' | 'restricted' | 'blocked';
+/**
+ * Tool access policy
+ *
+ * Defines which tools are allowed, restricted, or blocked in a given context.
+ */
+export interface ToolAccessPolicy {
+    /** Default access mode for tools not explicitly listed in overrides */
+    defaultMode: ToolAccessMode;
+    /** Tool-specific access mode overrides */
+    overrides?: Record<string, ToolAccessMode>;
+}
+/**
+ * Tool validation result
+ *
+ * Used by tools in 'restricted' mode to indicate whether
+ * a specific operation is allowed.
+ */
+export interface ToolValidationResult {
+    /** Whether the operation is allowed */
+    isAllowed: boolean;
+    /** Reason for rejection if not allowed */
+    reason?: string;
+    /** The matched pattern/rule that caused rejection */
+    matchedPattern?: string;
+}

package/dist/lib/access-control/validators/bash.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Bash Command Validator
+ *
+ * Provides validation for Bash commands to ensure they are read-only operations.
+ * Used by Plan Mode and Explore subagent to prevent file modifications.
+ */
+import type { ToolValidationResult } from '../types';
+/**
+ * Whitelist of read-only commands that are allowed
+ *
+ * Note: This list is for documentation purposes. The actual validation
+ * uses FORBIDDEN_PATTERNS (blacklist approach).
+ */
+export declare const READ_ONLY_COMMANDS: readonly ["ls", "find", "file", "stat", "tree", "du", "df", "wc", "cat", "head", "tail", "less", "more", "grep", "awk", "sed", "sort", "uniq", "cut", "tr", "xargs", "git status", "git log", "git diff", "git show", "git branch", "git remote", "git tag", "git blame", "git rev-parse", "git ls-files", "git ls-tree", "pwd", "which", "whereis", "type", "echo", "printf", "date", "env", "printenv"];
+/**
+ * Patterns that indicate forbidden (write) operations
+ */
+export declare const FORBIDDEN_PATTERNS: RegExp[];
+/**
+ * Validates if a bash command is read-only and safe
+ *
+ * @param command - The bash command to validate
+ * @returns Validation result with isAllowed flag and optional reason
+ *
+ * @example
+ * ```typescript
+ * isReadOnlyBashCommand('ls -la')
+ * // { isAllowed: true }
+ *
+ * isReadOnlyBashCommand('rm file.txt')
+ * // { isAllowed: false, reason: 'File modification commands are not allowed...', matchedPattern: 'rm' }
+ *
+ * isReadOnlyBashCommand('echo "test" > file.txt')
+ * // { isAllowed: false, reason: 'Command contains redirect operator...', matchedPattern: '>' }
+ * ```
+ */
+export declare function isReadOnlyBashCommand(command: string): ToolValidationResult;
+/**
+ * Validates a bash command and throws an error if not allowed
+ *
+ * @param command - The bash command to validate
+ * @throws Error if the command is not read-only
+ *
+ * @example
+ * ```typescript
+ * assertReadOnlyBashCommand('ls -la') // passes
+ * assertReadOnlyBashCommand('rm file.txt') // throws Error
+ * ```
+ */
+export declare function assertReadOnlyBashCommand(command: string): void;

package/dist/lib/access-control/validators/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tool Validators
+ *
+ * Exports validators for different tools in restricted mode.
+ */
+export { READ_ONLY_COMMANDS, FORBIDDEN_PATTERNS, isReadOnlyBashCommand, assertReadOnlyBashCommand, } from './bash';

package/dist/middleware/parallelSubagentMiddleware.d.ts

@@ -55,7 +55,7 @@ export interface ParallelSubagentMiddlewareOptions {
  * const model = createDefaultModel()
  *
  * const middleware = createParallelSubagentMiddleware({
- *   subagents: [fileSearchSpecialist],
+ *   subagents: [exploreAgent],
  *   globalToolRegistry,
  *   model,
  *   debug: true,
@@ -68,7 +68,7 @@ export interface ParallelSubagentMiddlewareOptions {
  * ```typescript
  * const middleware = createParallelSubagentMiddleware({
  *   subagents: [
- *     { name: 'Explore', description: 'Code explorer', tools: ['Read', 'Grep'] },
+ *     { name: 'Explore', description: 'Code explorer', accessPolicy: EXPLORE_POLICY },
  *   ],
  *   executor: async (args) => {
  *     const subAgent = createSubAgent(args.subagent_type)

package/dist/middleware/planModeMiddleware.d.ts

@@ -1,5 +1,6 @@
 import type { Middleware } from '../agent/middleware';
 import type { AgentLoopState } from '../agent/types';
+import type { ToolAccessPolicy } from '../lib/access-control';
 /**
  * Configuration options for plan mode middleware.
  */
@@ -34,6 +35,11 @@ export interface PlanModeMiddlewareOptions {
      * When true, adds stronger emphasis on Phase 3 synthesis step.
      */
     requireSynthesisPhase?: boolean;
+    /**
+     * Custom tool access policy (optional).
+     * If not provided, uses the default PLAN_MODE_POLICY.
+     */
+    accessPolicy?: ToolAccessPolicy;
 }
 /**
  * Creates a middleware that injects a plan mode system reminder into the conversation.

package/dist/subagent/bash-validator.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Bash Command Validator for Explore Subagent
+ *
+ * This module provides validation for Bash commands to ensure
+ * they are read-only operations. Used by the Explore subagent
+ * to prevent any file modifications.
+ *
+ * @deprecated Import from '../lib/access-control' instead.
+ * This module re-exports for backward compatibility.
+ */
+import type { ToolExecutionContext } from '../tool/types';
+import type { CallToolResult, ToolInputSchema } from '../types';
+import { BaseTool } from '../tool/base';
+export { assertReadOnlyBashCommand, FORBIDDEN_PATTERNS, isReadOnlyBashCommand, READ_ONLY_COMMANDS, } from '../lib/access-control';
+export type { ToolValidationResult as BashValidationResult } from '../lib/access-control';
+/**
+ * Read-only Bash tool wrapper for Explore subagent
+ *
+ * This tool wraps the standard BashTool and validates commands
+ * before execution to ensure they are read-only operations.
+ */
+export declare class ReadOnlyBashTool extends BaseTool {
+    readonly name = "Bash";
+    readonly description: string;
+    readonly parameters: ToolInputSchema;
+    readonly riskLevel: "safe";
+    private innerBash;
+    constructor(options?: {
+        cwd?: string;
+        shell?: string;
+    });
+    execute(args: Record<string, unknown>, ctx: ToolExecutionContext): Promise<CallToolResult>;
+    setCwd(cwd: string): void;
+    getCwd(): string;
+}
+/**
+ * Creates a read-only Bash tool for use in Explore subagent
+ *
+ * @param options - Optional configuration for the Bash tool
+ * @param options.cwd - Working directory for bash commands
+ * @param options.shell - Shell to use for command execution
+ * @returns A ReadOnlyBashTool instance
+ */
+export declare function createReadOnlyBashTool(options?: {
+    cwd?: string;
+    shell?: string;
+}): ReadOnlyBashTool;

package/dist/subagent/explore.d.ts

@@ -0,0 +1,38 @@
+import type { SubagentDefinition } from '../tool/builtin/task';
+/**
+ * Thoroughness level for Explore subagent
+ *
+ * - quick: Fast targeted search, 1-2 search iterations, exact matches
+ * - medium: Balanced exploration, follows related files, multiple naming conventions
+ * - very thorough: Comprehensive analysis, multiple locations, deep analysis
+ */
+export type ThoroughnessLevel = 'quick' | 'medium' | 'very thorough';
+/**
+ * System prompt for Explore subagent
+ *
+ * This prompt defines the Explore agent's role as a READ-ONLY codebase explorer.
+ * It emphasizes speed, efficiency, and strict prohibition of file modifications.
+ */
+export declare function buildExplorePrompt(cwd: string, now?: Date): string;
+export declare const explorePrompt: string;
+/**
+ * Explore Subagent Definition
+ *
+ * A fast, read-only agent specialized for codebase exploration.
+ * Uses Haiku model for speed and cost efficiency.
+ *
+ * Features:
+ * - Supports thoroughness levels (quick/medium/very thorough)
+ * - Strict read-only mode with Bash command validation
+ * - Optimized for parallel tool calls
+ *
+ * @example
+ * ```typescript
+ * Task({
+ *   subagent_type: 'Explore',
+ *   description: 'Find auth files',
+ *   prompt: 'Find all authentication-related files. Thoroughness: quick'
+ * })
+ * ```
+ */
+export declare const exploreAgent: SubagentDefinition;

package/dist/subagent/index.d.ts

@@ -4,5 +4,6 @@
  * This module exports predefined subagent configurations
  * that can be used with the parallel subagent middleware.
  */
-export * from './file-search-specialist';
+export * from './bash-validator';
+export * from './explore';
 export * from './parallel-task-coordinator';

package/dist/tool/builtin/task.d.ts

@@ -1,5 +1,6 @@
 import type { CallToolResult, ToolInputSchema } from '../../types';
 import type { ToolExecutionContext } from '../types';
+import type { ToolAccessPolicy } from '../../lib/access-control';
 import { BaseTool } from '../base';
 /**
  * Definition of an available subagent type
@@ -9,10 +10,8 @@ export interface SubagentDefinition {
     name: string;
     /** Description of what the subagent does */
     description: string;
-    /** Tools available to this subagent (optional) */
-    tools?: string[];
-    /** Tools to explicitly block for this subagent (optional) */
-    blockedTools?: string[];
+    /** Tool access policy for this subagent */
+    accessPolicy: ToolAccessPolicy;
     /** System prompt for this subagent (optional) */
     systemPrompt?: string;
     /** Additional metadata (extensible for future use) */

package/dist/tool/types.d.ts

@@ -96,6 +96,16 @@ export interface ToolExecutionContext {
      * ```
      */
     emitEvent?: (event: Omit<import('../types').AgentEvent, 'sessionId'>) => void;
+    /**
+     * Runtime metadata passed from AgentLoopState.metadata.
+     *
+     * Used to communicate context-specific information to tools, such as:
+     * - readOnlyBash: boolean - Whether Bash tool is in read-only mode (Plan Mode)
+     * - planMode: boolean - Whether the session is in Plan Mode
+     *
+     * This is set by middleware and synchronized before each tool execution.
+     */
+    metadata?: Record<string, unknown>;
 }
 /**
  * Safe input shape for callers to provide context/capabilities/metadata.

package/dist/types/event.d.ts

@@ -228,7 +228,7 @@ export interface SubagentEvent extends BaseEvent {
     type: 'subagent_event';
     /** Subagent identifier (agent ID or task call ID) */
     subagentId: string;
-    /** Subagent type/name (e.g., 'FileSearchSpecialist') */
+    /** Subagent type/name (e.g., 'Explore') */
     subagentType: string;
     /** The original event emitted by the subagent */
     nestedEvent: AgentEvent;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "goatchain",
   "type": "module",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "workspaces": [
     "packages/*"
   ],
@@ -49,8 +49,10 @@
     "build:binary:windows": "bun run --filter 'dimcode' build:binary:windows",
     "build:all": "bun run clear:all && bun run build:lib && bun run build:tui && bun run build:cli && bun run build:binary",
     "clear:all": "rm -rf dist packages/cli/dist packages/cli/bin-release packages/tui/dist",
-    "cli": "cd packages/cli && esno ./src/cli.ts",
-    "cli:debug": "cd packages/cli && esno ./src/cli.ts --debug",
+    "cli": "cd packages/cli && bun run cli",
+    "cli:run": "cd packages/cli && bun run cli:run",
+    "cli:debug": "cd packages/cli && bun run cli:debug",
+    "cli:debug:run": "cd packages/cli && bun run cli:debug:run",
     "cli:smoke": "cd packages/cli && bun run smoke",
     "providers:update": "node packages/cli/scripts/update-provider-models.mjs",
     "release": "bumpp --commit --no-tag --no-push && bun run build && bun publish",
@@ -96,4 +98,4 @@
   ],
   "prettier": "@sxzz/prettier-config",
   "packageManager": "pnpm@10.16.0+sha512.8066e7b034217b700a9a4dbb3a005061d641ba130a89915213a10b3ca4919c19c037bec8066afdc559b89635fdb806b16ea673f2468fbb28aabfa13c53e3f769"
-}
+}

package/dist/subagent/file-search-specialist.d.ts

@@ -1,16 +0,0 @@
-import type { SubagentDefinition } from '../tool/builtin/task';
-/**
- * System prompt for File Search Specialist
- *
- * Based on the configuration from subagent_file.json, this prompt
- * defines the specialist's role, capabilities, and guidelines.
- */
-export declare function buildFileSearchSpecialistPrompt(cwd: string, now?: Date): string;
-export declare const fileSearchSpecialistPrompt: string;
-/**
- * File Search Specialist Subagent Definition
- *
- * This subagent specializes in navigating and exploring codebases,
- * finding files, searching content, and analyzing file structures.
- */
-export declare const fileSearchSpecialist: SubagentDefinition;