byterover-cli 0.4.1 → 1.0.1

package/README.md

@@ -6,14 +6,6 @@ Command-line interface for ByteRover, featuring an interactive REPL with a moder
 [![Downloads/week](https://img.shields.io/npm/dw/byterover-cli.svg)](https://npmjs.org/package/byterover-cli)
 [![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen.svg)](https://nodejs.org)
 
-## Important
-
-Starting with version **0.2.0**, the ByteRover CLI command has been renamed from `br` to `brv` to avoid conflicts with [broot](https://github.com/Canop/broot), another popular CLI tool that also uses the `br` command.
-
-This is a **breaking change** that requires action from existing users.
-
-Please check the migration guide [here](https://docs.byterover.dev/beta/migration-br-brv).
-
 ## Table of Contents
 
 * [Installation](#installation)
@@ -284,7 +276,7 @@ If you encounter issues or have questions:
 
 1. Check the command help in the REPL
 2. Run `/status` to review your project state
-3. Visit [ByteRover Docs](https://docs.byterover.dev/beta)
+3. Visit [ByteRover Docs](https://docs.byterover.dev)
 4. Contact ByteRover support
 
 ---

package/dist/commands/curate.d.ts

@@ -1,5 +1,5 @@
 import { Command } from '@oclif/core';
-import type { ICurateUseCase } from '../core/interfaces/usecase/i-curate-use-case.js';
+import { ICurateUseCase } from '../core/interfaces/usecase/i-curate-use-case.js';
 export default class Curate extends Command {
     static args: {
         context: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
@@ -7,8 +7,6 @@ export default class Curate extends Command {
     static description: string;
     static examples: string[];
     static flags: {
-        apiKey?: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions> | undefined;
-        model?: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions> | undefined;
         verbose?: import("@oclif/core/interfaces").BooleanFlag<boolean> | undefined;
         files: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };

package/dist/commands/curate.js

@@ -1,6 +1,5 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { isDevelopment } from '../config/environment.js';
-import { ProjectConfigStore } from '../infra/config/file-config-store.js';
 import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
 import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
 import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
@@ -13,9 +12,9 @@ export default class Curate extends Command {
             required: false,
         }),
     };
-    static description = `Curate context to the context tree (autonomous mode)
+    static description = `Curate context to the context tree (connects to running brv instance)
 
-For interactive mode, use REPL: brv repl then /curate
+Requires a running brv instance. Start one with: brv start
 
 Good examples:
 - "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts"
@@ -24,47 +23,23 @@ Bad examples:
 - "Authentication" or "JWT tokens" (too vague, lacks context)
 - "Rate limiting" (no implementation details or file references)`;
     static examples = [
-        '# Autonomous mode - LLM auto-categorizes your context',
+        '# Curate context - queues task for background processing',
         '<%= config.bin %> <%= command.id %> "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts"',
         '',
-        '# Include relevant files for comprehensive context (use sparingly, max 5 files)',
-        '- NOTE: CONTEXT argument must come BEFORE --files flag',
-        '- NOTE: For multiple files, repeat --files (or -f) flag for each file',
-        '- NOTE: Only text/code files from current project directory.',
+        '# Include relevant files for comprehensive context (max 5 files)',
+        '<%= config.bin %> <%= command.id %> "Authentication middleware validates JWT tokens" -f src/middleware/auth.ts',
         '',
-        '## Single file',
-        '<%= config.bin %> <%= command.id %> "Authentication middleware validates JWT tokens and attaches user context" -f src/middleware/auth.ts',
-        '',
-        '## Multiple files',
-        '<%= config.bin %> <%= command.id %> "JWT authentication implementation with refresh token rotation" --files src/auth/jwt.ts --files docs/auth.md',
-        '',
-        ...(isDevelopment()
-            ? [
-                '# Autonomous mode with OpenRouter (development only)',
-                '<%= config.bin %> <%= command.id %> -k YOUR_API_KEY "React components follow atomic design in src/components/. Atoms in atoms/, molecules in molecules/, organisms in organisms/"',
-                '',
-                '# Autonomous mode with custom model (development only)',
-                '<%= config.bin %> <%= command.id %> -k YOUR_API_KEY -m anthropic/claude-sonnet-4 "API rate limit is 100 req/min per user. Implemented using Redis with sliding window in rateLimiter.ts"',
-            ]
-            : []),
+        '# Multiple files',
+        '<%= config.bin %> <%= command.id %> "JWT authentication implementation" --files src/auth/jwt.ts --files docs/auth.md',
     ];
     static flags = {
         files: Flags.string({
             char: 'f',
-            description: 'Include specific file paths for critical context (max 5 files). Only text/code files from the current project directory are allowed. Use sparingly - only for truly relevant files like docs or key implementation details. NOTE: CONTEXT argument must come BEFORE this flag.',
+            description: 'Include specific file paths for critical context (max 5 files)',
             multiple: true,
         }),
         ...(isDevelopment()
             ? {
-                apiKey: Flags.string({
-                    char: 'k',
-                    description: 'OpenRouter API key (use OpenRouter instead of internal gRPC backend) [Development only]',
-                    env: 'OPENROUTER_API_KEY',
-                }),
-                model: Flags.string({
-                    char: 'm',
-                    description: 'Model to use (default: google/gemini-2.5-pro for OpenRouter, gemini-2.5-pro for gRPC) [Development only]',
-                }),
                 verbose: Flags.boolean({
                     char: 'v',
                     default: false,
@@ -76,25 +51,13 @@ Bad examples:
     createUseCase() {
         const tokenStore = new KeychainTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
-        return new CurateUseCase({
-            projectConfigStore: new ProjectConfigStore(),
-            terminal: new OclifTerminal(this),
-            tokenStore,
-            trackingService: new MixpanelTrackingService({ globalConfigStore, tokenStore }),
-        });
+        const terminal = new OclifTerminal(this);
+        const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });
+        return new CurateUseCase({ terminal, trackingService });
     }
     async run() {
-        const { args, flags } = await this.parse(Curate);
-        if (!args.context) {
-            this.log('Context argument is required.\nFor interactive mode, use REPL: brv /curate');
-            return;
-        }
-        await this.createUseCase().run({
-            apiKey: flags.apiKey,
-            context: args.context,
-            files: flags.files,
-            model: flags.model,
-            verbose: flags.verbose,
-        });
+        const { args, flags: rawFlags } = await this.parse(Curate);
+        const flags = rawFlags;
+        return this.createUseCase().run({ context: args.context, files: flags.files, verbose: flags.verbose });
     }
 }

package/dist/commands/main.d.ts

@@ -1,4 +1,12 @@
 import { Command } from '@oclif/core';
+/**
+ * Main command - Entry point for ByteRover CLI.
+ *
+ * Architecture v0.5.0:
+ * - Main Process: Spawns Transport and Agent processes
+ * - TUI discovers Transport via TransportClientFactory (same as external CLIs)
+ * - All task communication via Socket.IO (NO IPC)
+ */
 export default class Main extends Command {
     static description: string;
     /**

package/dist/commands/main.js

@@ -1,10 +1,20 @@
 import { Command } from '@oclif/core';
 import { ProjectConfigStore } from '../infra/config/file-config-store.js';
+import { getProcessManager } from '../infra/process/index.js';
 import { startRepl } from '../infra/repl/repl-startup.js';
-import { FileGlobalConfigStore } from "../infra/storage/file-global-config-store.js";
+import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
 import { FileOnboardingPreferenceStore } from '../infra/storage/file-onboarding-preference-store.js';
 import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
 import { MixpanelTrackingService } from '../infra/tracking/mixpanel-tracking-service.js';
+import { initSessionLog } from '../utils/process-logger.js';
+/**
+ * Main command - Entry point for ByteRover CLI.
+ *
+ * Architecture v0.5.0:
+ * - Main Process: Spawns Transport and Agent processes
+ * - TUI discovers Transport via TransportClientFactory (same as external CLIs)
+ * - All task communication via Socket.IO (NO IPC)
+ */
 export default class Main extends Command {
     static description = 'ByteRover CLI - Interactive REPL';
     /**
@@ -12,23 +22,34 @@ export default class Main extends Command {
      */
     static hidden = true;
     async run() {
+        // Initialize session log (creates ~/.brv/logs/brv-{timestamp}.log)
+        initSessionLog();
         // Check if running in an interactive terminal
         if (!process.stdin.isTTY || !process.stdout.isTTY) {
             this.log('ByteRover REPL requires an interactive terminal.');
             this.log("Run 'brv --help' for available commands.");
             return;
         }
+        // Start Transport and Agent processes (v0.5.0 architecture)
+        const processManager = getProcessManager();
+        await processManager.start();
         const tokenStore = new KeychainTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
         const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });
         const onboardingPreferenceStore = new FileOnboardingPreferenceStore();
         // Start the interactive REPL
-        await startRepl({
-            onboardingPreferenceStore,
-            projectConfigStore: new ProjectConfigStore(),
-            tokenStore,
-            trackingService,
-            version: this.config.version,
-        });
+        // TUI will discover Transport via TransportClientFactory (same as external CLIs)
+        try {
+            await startRepl({
+                onboardingPreferenceStore,
+                projectConfigStore: new ProjectConfigStore(),
+                tokenStore,
+                trackingService,
+                version: this.config.version,
+            });
+        }
+        finally {
+            await processManager.stop();
+        }
     }
 }

package/dist/commands/query.d.ts

@@ -1,5 +1,5 @@
 import { Command } from '@oclif/core';
-import type { IQueryUseCase } from '../core/interfaces/usecase/i-query-use-case.js';
+import { IQueryUseCase } from '../core/interfaces/usecase/i-query-use-case.js';
 export default class Query extends Command {
     static args: {
         query: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
@@ -7,8 +7,6 @@ export default class Query extends Command {
     static description: string;
     static examples: string[];
     static flags: {
-        apiKey?: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions> | undefined;
-        model?: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions> | undefined;
         verbose?: import("@oclif/core/interfaces").BooleanFlag<boolean> | undefined;
     };
     static strict: boolean;

package/dist/commands/query.js

@@ -1,6 +1,5 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { isDevelopment } from '../config/environment.js';
-import { ProjectConfigStore } from '../infra/config/file-config-store.js';
 import { FileGlobalConfigStore } from '../infra/storage/file-global-config-store.js';
 import { KeychainTokenStore } from '../infra/storage/keychain-token-store.js';
 import { OclifTerminal } from '../infra/terminal/oclif-terminal.js';
@@ -13,7 +12,10 @@ export default class Query extends Command {
             required: true,
         }),
     };
-    static description = `Query and retrieve information from the context tree
+    static description = `Query and retrieve information from the context tree (connects to running brv instance)
+
+Requires a running brv instance. Start one with: brv start
+
 Good:
 - "How is user authentication implemented?"
 - "What are the API rate limits and where are they enforced?"
@@ -24,32 +26,10 @@ Bad:
         '# Ask questions about patterns, decisions, or implementation details',
         '<%= config.bin %> <%= command.id %> What are the coding standards?',
         '<%= config.bin %> <%= command.id %> How is authentication implemented?',
-        '',
-        ...(isDevelopment()
-            ? [
-                '# Query with OpenRouter (development only)',
-                '<%= config.bin %> <%= command.id %> -k YOUR_API_KEY Show me all API endpoints',
-                '',
-                '# Query with custom model (development only)',
-                '<%= config.bin %> <%= command.id %> -k YOUR_API_KEY -m anthropic/claude-sonnet-4 Explain the database schema',
-                '',
-                '# Query with verbose output (development only)',
-                '<%= config.bin %> <%= command.id %> -v What testing strategies are used?',
-            ]
-            : []),
     ];
     static flags = {
         ...(isDevelopment()
             ? {
-                apiKey: Flags.string({
-                    char: 'k',
-                    description: 'OpenRouter API key (use OpenRouter instead of internal gRPC backend) [Development only]',
-                    env: 'OPENROUTER_API_KEY',
-                }),
-                model: Flags.string({
-                    char: 'm',
-                    description: 'Model to use (default: google/gemini-2.5-pro for OpenRouter, gemini-2.5-pro for gRPC) [Development only]',
-                }),
                 verbose: Flags.boolean({
                     char: 'v',
                     default: false,
@@ -62,21 +42,14 @@ Bad:
     createUseCase() {
         const tokenStore = new KeychainTokenStore();
         const globalConfigStore = new FileGlobalConfigStore();
+        const trackingService = new MixpanelTrackingService({ globalConfigStore, tokenStore });
         return new QueryUseCase({
-            projectConfigStore: new ProjectConfigStore(),
             terminal: new OclifTerminal(this),
-            tokenStore,
-            trackingService: new MixpanelTrackingService({ globalConfigStore, tokenStore }),
+            trackingService,
         });
     }
     async run() {
-        const { argv, flags } = await this.parse(Query);
-        const queryTerms = argv.join(' ');
-        await this.createUseCase().run({
-            apiKey: flags.apiKey,
-            model: flags.model,
-            query: queryTerms,
-            verbose: flags.verbose ?? false,
-        });
+        const { args, flags } = await this.parse(Query);
+        await this.createUseCase().run({ query: args.query, verbose: flags.verbose });
     }
 }

package/dist/config/context-tree-domains.d.ts

@@ -9,4 +9,9 @@ export interface DomainConfig {
 /**
  * Predefined domains that will be scaffolded during project initialization.
  */
+export declare const DEFAULT_CONTEXT_TREE_DOMAINS: DomainConfig[];
+/**
+ * Alias for backward compatibility.
+ * @deprecated Use DEFAULT_CONTEXT_TREE_DOMAINS instead
+ */
 export declare const CONTEXT_TREE_DOMAINS: DomainConfig[];

package/dist/config/context-tree-domains.js

@@ -1,7 +1,7 @@
 /**
  * Predefined domains that will be scaffolded during project initialization.
  */
-export const CONTEXT_TREE_DOMAINS = [
+export const DEFAULT_CONTEXT_TREE_DOMAINS = [
     {
         description: 'Ensure all code follows style guidelines and quality standards',
         name: 'code_style',
@@ -27,3 +27,8 @@ export const CONTEXT_TREE_DOMAINS = [
         name: 'bug_fixes',
     },
 ];
+/**
+ * Alias for backward compatibility.
+ * @deprecated Use DEFAULT_CONTEXT_TREE_DOMAINS instead
+ */
+export const CONTEXT_TREE_DOMAINS = DEFAULT_CONTEXT_TREE_DOMAINS;

package/dist/config/environment.js

@@ -23,17 +23,17 @@ export const ENV_CONFIG = {
         webAppUrl: 'https://dev-beta-app.byterover.dev',
     },
     production: {
-        apiBaseUrl: 'https://beta-iam.byterover.dev/api/v1',
-        authorizationUrl: 'https://beta-iam.byterover.dev/api/v1/oidc/authorize',
-        clientId: 'byterover-cli',
-        cogitApiBaseUrl: 'https://beta-cgit.byterover.dev/api/v1',
-        issuerUrl: 'https://beta-iam.byterover.dev/api/v1/oidc',
-        llmApiBaseUrl: 'https://beta-llm.byterover.dev',
+        apiBaseUrl: 'https://iam.byterover.dev/api/v1',
+        authorizationUrl: 'https://iam.byterover.dev/api/v1/oidc/authorize',
+        clientId: 'byterover-cli-client',
+        cogitApiBaseUrl: 'https://v3-cgit.byterover.dev',
+        issuerUrl: 'https://iam.byterover.dev/api/v1/oidc',
+        llmApiBaseUrl: 'https://llm.byterover.dev',
         memoraApiBaseUrl: 'https://beta-memora-retrieve.byterover.dev/api/v3',
-        mixpanelToken: '4d1198b346d2d6ac75f2e77905cc65ac',
+        mixpanelToken: 'fac9051df8242c885a9e0eaf60f78b10',
         scopes: ['read', 'write'],
-        tokenUrl: 'https://beta-iam.byterover.dev/api/v1/oidc/token',
-        webAppUrl: 'https://beta-app.byterover.dev',
+        tokenUrl: 'https://iam.byterover.dev/api/v1/oidc/token',
+        webAppUrl: 'https://app.byterover.dev',
     },
 };
 /**

package/dist/constants.d.ts

@@ -1,6 +1,7 @@
 export declare const BRV_DIR = ".brv";
 export declare const BLOBS_DIR = "blobs";
 export declare const PROJECT_CONFIG_FILE = "config.json";
+export declare const INSTANCE_FILE = "instance.json";
 export declare const BRV_CONFIG_VERSION = "0.0.1";
 export declare const GLOBAL_CONFIG_DIR = "brv";
 export declare const GLOBAL_CONFIG_FILE = "config.json";
@@ -9,6 +10,8 @@ export declare const ACE_DIR = "ace";
 export declare const PROJECT = "byterover";
 export declare const CONTEXT_TREE_DIR = "context-tree";
 export declare const CONTEXT_FILE = "context.md";
+export declare const CONTEXT_FILE_EXTENSION = ".md";
+export declare const README_FILE = "README.md";
 export declare const SNAPSHOT_FILE = ".snapshot.json";
 /**
  * Default ByteRover branch name for memory storage.
@@ -20,3 +23,14 @@ export declare const DEFAULT_BRANCH = "main";
  * Used in CLI help output to direct users to online documentation.
  */
 export declare const DOCS_URL = "https://docs.byterover.dev/beta";
+export declare const TRANSPORT_HOST = "127.0.0.1";
+export declare const TRANSPORT_REQUEST_TIMEOUT_MS = 10000;
+export declare const TRANSPORT_ROOM_TIMEOUT_MS = 2000;
+export declare const TRANSPORT_CONNECT_TIMEOUT_MS = 3000;
+export declare const TRANSPORT_RECONNECTION_DELAY_MS = 50;
+export declare const TRANSPORT_RECONNECTION_DELAY_MAX_MS = 1000;
+export declare const TRANSPORT_RECONNECTION_ATTEMPTS = 30;
+export declare const TRANSPORT_PING_INTERVAL_MS = 5000;
+export declare const TRANSPORT_PING_TIMEOUT_MS = 10000;
+export declare const TRANSPORT_DEFAULT_TRANSPORTS: ('polling' | 'websocket')[];
+export declare const DEFAULT_LLM_MODEL = "gemini-2.5-pro";

package/dist/constants.js

@@ -1,6 +1,7 @@
 export const BRV_DIR = '.brv';
 export const BLOBS_DIR = 'blobs';
 export const PROJECT_CONFIG_FILE = 'config.json';
+export const INSTANCE_FILE = 'instance.json';
 export const BRV_CONFIG_VERSION = '0.0.1';
 // Global config constants (user-level, stored in XDG config directory)
 export const GLOBAL_CONFIG_DIR = 'brv';
@@ -12,6 +13,8 @@ export const PROJECT = 'byterover';
 // Context Tree directory structure constants
 export const CONTEXT_TREE_DIR = 'context-tree';
 export const CONTEXT_FILE = 'context.md';
+export const CONTEXT_FILE_EXTENSION = '.md';
+export const README_FILE = 'README.md';
 export const SNAPSHOT_FILE = '.snapshot.json';
 /**
  * Default ByteRover branch name for memory storage.
@@ -23,3 +26,18 @@ export const DEFAULT_BRANCH = 'main';
  * Used in CLI help output to direct users to online documentation.
  */
 export const DOCS_URL = 'https://docs.byterover.dev/beta';
+// Transport layer constants (optimized for localhost real-time)
+export const TRANSPORT_HOST = '127.0.0.1'; // Use hostname for better sandbox compatibility
+export const TRANSPORT_REQUEST_TIMEOUT_MS = 10_000; // 10s - most operations complete quickly
+export const TRANSPORT_ROOM_TIMEOUT_MS = 2000; // 2s - room ops are instant on localhost
+export const TRANSPORT_CONNECT_TIMEOUT_MS = 3000; // 3s - 127.0.0.1 connects in <10ms
+export const TRANSPORT_RECONNECTION_DELAY_MS = 50; // 50ms - ultra aggressive start
+export const TRANSPORT_RECONNECTION_DELAY_MAX_MS = 1000; // 1s cap - fail fast, retry fast
+export const TRANSPORT_RECONNECTION_ATTEMPTS = 30; // More attempts with faster retry
+export const TRANSPORT_PING_INTERVAL_MS = 5000; // 5s ping - reasonable for local communication
+export const TRANSPORT_PING_TIMEOUT_MS = 10_000; // 10s timeout - avoid false disconnects during GC/load
+// WebSocket-only transport to avoid HTTP polling issues in sandboxed environments (Cursor, etc.)
+// HTTP polling may be blocked by IDE sandboxes causing "xhr poll error"
+export const TRANSPORT_DEFAULT_TRANSPORTS = ['websocket'];
+// LLM Model defaults
+export const DEFAULT_LLM_MODEL = 'gemini-2.5-pro';

package/dist/core/domain/cipher/agent/agent-info.d.ts

@@ -0,0 +1,199 @@
+import { z } from 'zod';
+/**
+ * Permission values for agent operations.
+ * - allow: Operation is permitted without asking
+ * - deny: Operation is blocked
+ * - ask: User must approve the operation
+ */
+export declare const PermissionValue: z.ZodEnum<["allow", "deny", "ask"]>;
+export type PermissionValue = z.infer<typeof PermissionValue>;
+/**
+ * Agent mode determines how the agent can be used.
+ * - primary: Entry point agent (e.g., plan, cipher)
+ * - subagent: Can only be invoked by primary agents via TaskTool
+ * - all: Can be used as both primary and subagent
+ */
+export declare const AgentMode: z.ZodEnum<["primary", "subagent", "all"]>;
+export type AgentMode = z.infer<typeof AgentMode>;
+/**
+ * Permission configuration for an agent.
+ * Controls what operations the agent is allowed to perform.
+ */
+export declare const AgentPermissionSchema: z.ZodObject<{
+    /**
+     * Permission map for bash commands.
+     * Keys are command patterns (supports wildcards like 'git*', 'ls*').
+     * Value '*' applies to all commands not matched by other patterns.
+     * @default { '*': 'allow' }
+     */
+    bash: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<["allow", "deny", "ask"]>>>;
+    /**
+     * Permission for file editing operations (edit_file, write_file).
+     * @default 'allow'
+     */
+    edit: z.ZodDefault<z.ZodEnum<["allow", "deny", "ask"]>>;
+}, "strip", z.ZodTypeAny, {
+    edit: "allow" | "deny" | "ask";
+    bash: Record<string, "allow" | "deny" | "ask">;
+}, {
+    edit?: "allow" | "deny" | "ask" | undefined;
+    bash?: Record<string, "allow" | "deny" | "ask"> | undefined;
+}>;
+export type AgentPermission = z.infer<typeof AgentPermissionSchema>;
+/**
+ * Agent information schema.
+ * Defines the configuration for a Cipher agent (modeled after OpenCode's Agent.Info).
+ */
+export declare const AgentInfoSchema: z.ZodObject<{
+    /**
+     * Optional color for UI display (hex code like #RRGGBB).
+     */
+    color: z.ZodOptional<z.ZodString>;
+    /**
+     * Human-readable description of when to use this agent.
+     * Displayed to LLM when selecting subagents via TaskTool.
+     */
+    description: z.ZodOptional<z.ZodString>;
+    /**
+     * Whether this agent is hidden from user selection.
+     * Hidden agents can still be invoked programmatically.
+     * @default false
+     */
+    hidden: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Maximum number of LLM iterations for this agent.
+     * Overrides the default maxIterations from config.
+     */
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Agent mode: primary, subagent, or all.
+     * - primary: Direct entry point for users
+     * - subagent: Invoked via TaskTool from primary agents
+     * - all: Can be used in both contexts
+     */
+    mode: z.ZodEnum<["primary", "subagent", "all"]>;
+    /**
+     * Optional model override for this agent.
+     * If not specified, uses the default model from agent config.
+     */
+    model: z.ZodOptional<z.ZodObject<{
+        modelId: z.ZodString;
+        providerId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        modelId: string;
+        providerId?: string | undefined;
+    }, {
+        modelId: string;
+        providerId?: string | undefined;
+    }>>;
+    /**
+     * Unique identifier for the agent.
+     * Used to reference the agent in TaskTool and registry.
+     */
+    name: z.ZodString;
+    /**
+     * Whether this is a native (built-in) agent.
+     * Native agents are defined in code, not config files.
+     * @default true
+     */
+    native: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Permission configuration for this agent.
+     * Controls file editing and bash command access.
+     */
+    permission: z.ZodDefault<z.ZodObject<{
+        /**
+         * Permission map for bash commands.
+         * Keys are command patterns (supports wildcards like 'git*', 'ls*').
+         * Value '*' applies to all commands not matched by other patterns.
+         * @default { '*': 'allow' }
+         */
+        bash: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEnum<["allow", "deny", "ask"]>>>;
+        /**
+         * Permission for file editing operations (edit_file, write_file).
+         * @default 'allow'
+         */
+        edit: z.ZodDefault<z.ZodEnum<["allow", "deny", "ask"]>>;
+    }, "strip", z.ZodTypeAny, {
+        edit: "allow" | "deny" | "ask";
+        bash: Record<string, "allow" | "deny" | "ask">;
+    }, {
+        edit?: "allow" | "deny" | "ask" | undefined;
+        bash?: Record<string, "allow" | "deny" | "ask"> | undefined;
+    }>>;
+    /**
+     * Inline system prompt for this agent.
+     * Used when promptFile is not specified.
+     */
+    prompt: z.ZodOptional<z.ZodString>;
+    /**
+     * Reference to a YAML prompt file in src/resources/prompts/.
+     * The file content will be used as the agent's system prompt.
+     * Takes precedence over inline `prompt` if both are specified.
+     */
+    promptFile: z.ZodOptional<z.ZodString>;
+    /**
+     * LLM temperature for this agent.
+     * Controls randomness/creativity of responses.
+     */
+    temperature: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Tool enable/disable configuration.
+     * Keys are tool names, values are boolean (true = enabled, false = disabled).
+     * Supports wildcard '*' for all tools.
+     * Tools not listed inherit from parent/default configuration.
+     */
+    tools: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    hidden: boolean;
+    mode: "primary" | "subagent" | "all";
+    native: boolean;
+    permission: {
+        edit: "allow" | "deny" | "ask";
+        bash: Record<string, "allow" | "deny" | "ask">;
+    };
+    tools: Record<string, boolean>;
+    prompt?: string | undefined;
+    maxIterations?: number | undefined;
+    model?: {
+        modelId: string;
+        providerId?: string | undefined;
+    } | undefined;
+    description?: string | undefined;
+    color?: string | undefined;
+    temperature?: number | undefined;
+    promptFile?: string | undefined;
+}, {
+    name: string;
+    mode: "primary" | "subagent" | "all";
+    prompt?: string | undefined;
+    maxIterations?: number | undefined;
+    model?: {
+        modelId: string;
+        providerId?: string | undefined;
+    } | undefined;
+    description?: string | undefined;
+    hidden?: boolean | undefined;
+    color?: string | undefined;
+    temperature?: number | undefined;
+    native?: boolean | undefined;
+    permission?: {
+        edit?: "allow" | "deny" | "ask" | undefined;
+        bash?: Record<string, "allow" | "deny" | "ask"> | undefined;
+    } | undefined;
+    promptFile?: string | undefined;
+    tools?: Record<string, boolean> | undefined;
+}>;
+/**
+ * Type for agent information.
+ */
+export type AgentInfo = z.infer<typeof AgentInfoSchema>;
+/**
+ * Default permission configuration for agents.
+ */
+export declare const DEFAULT_AGENT_PERMISSION: AgentPermission;
+/**
+ * Read-only permission configuration (for planning agents).
+ */
+export declare const READONLY_AGENT_PERMISSION: AgentPermission;