wave-agent-sdk 0.10.4 → 0.11.1

package/builtin/skills/init/SKILL.md

@@ -0,0 +1,26 @@
+---
+disable-model-invocation: true
+---
+
+Please analyze this codebase and create a AGENTS.md file, which will be given to future instances of Agent to operate in this repository.
+
+What to add:
+1. Commands that will be commonly used, such as how to build, lint, and run tests. Include the necessary commands to develop in this codebase, such as how to run a single test.
+2. High-level code architecture and structure so that future instances can be productive more quickly. Focus on the "big picture" architecture that requires reading multiple files to understand.
+
+Usage notes:
+- If there's already a AGENTS.md, suggest improvements to it.
+- When you make the initial AGENTS.md, do not repeat yourself and do not include obvious instructions like "Provide helpful error messages to users", "Write unit tests for all new utilities", "Never include sensitive information (API keys, tokens) in code or commits".
+- Avoid listing every component or file structure that can be easily discovered.
+- Don't include generic development practices.
+- If there are Cursor rules (in .cursor/rules/ or .cursorrules) or Copilot rules (in .github/copilot-instructions.md), make sure to include the important parts.
+- Do NOT include rules from .wave/rules/ as they are automatically loaded by the system.
+- If there is a README.md, make sure to include the important parts.
+- Do not make up information such as "Common Development Tasks", "Tips for Development", "Support and Documentation" unless this is expressly included in other files that you read.
+- Be sure to prefix the file with the following text:
+
+```
+# AGENTS.md
+
+This file provides guidance to Agent when working with code in this repository.
+```

package/builtin/skills/loop/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: loop
+description: Parses user input into an interval and prompt, converts the interval to a cron expression, and schedules a recurring task
+allowed-tools: CronCreate, Skill
+---
+# /loop — schedule a recurring prompt
+
+Parse the input below into `[interval] <prompt…>` and schedule it with CronCreate.
+
+## Parsing (in priority order)
+
+1. **Leading token**: if the first whitespace-delimited token matches `^\d+[smhd]$` (e.g. `5m`, `2h`), that's the interval; the rest is the prompt.
+2. **Trailing "every" clause**: otherwise, if the input ends with `every <N><unit>` or `every <N> <unit-word>` (e.g. `every 20m`, `every 5 minutes`, `every 2 hours`), extract that as the interval and strip it from the prompt. Only match when what follows "every" is a time expression — `check every PR` has no interval.
+3. **Default**: otherwise, interval is `10m` and the entire input is the prompt.
+
+If the resulting prompt is empty, show usage `/loop [interval] <prompt>` and stop — do not call CronCreate.
+
+Examples:
+- `5m /babysit-prs` → interval `5m`, prompt `/babysit-prs` (rule 1)
+- `check the deploy every 20m` → interval `20m`, prompt `check the deploy` (rule 2)
+- `run tests every 5 minutes` → interval `5m`, prompt `run tests` (rule 2)
+- `check the deploy` → interval `10m`, prompt `check the deploy` (rule 3)
+- `check every PR` → interval `10m`, prompt `check every PR` (rule 3 — "every" not followed by time)
+- `5m` → empty prompt → show usage
+
+## Interval → cron
+
+Supported suffixes: `s` (seconds, rounded up to nearest minute, min 1), `m` (minutes), `h` (hours), `d` (days). Convert:
+
+| Interval pattern      | Cron expression     | Notes                                    |
+|-----------------------|---------------------|------------------------------------------|
+| `Nm` where N ≤ 59   | `*/N * * * *`     | every N minutes                          |
+| `Nm` where N ≥ 60   | `0 */H * * *`     | round to hours (H = N/60, must divide 24)|
+| `Nh` where N ≤ 23   | `0 */N * * *`     | every N hours                            |
+| `Nd`                | `0 0 */N * *`     | every N days at midnight local           |
+| `Ns`                | treat as `ceil(N/60)m` | cron minimum granularity is 1 minute  |
+
+**If the interval doesn't cleanly divide its unit** (e.g. `7m` → `*/7 * * * *` gives uneven gaps at :56→:00; `90m` → 1.5h which cron can't express), pick the nearest clean interval and tell the user what you rounded to before scheduling.
+
+**Thundering herd prevention**: For approximate requests like "hourly" or "every morning", pick a random minute (e.g., 7) instead of 0 to avoid global sync issues.
+
+## Action
+
+1. Call CronCreate with:
+   - `cron`: the expression from the table above
+   - `prompt`: the parsed prompt from above, verbatim (slash commands are passed through unchanged)
+   - `recurring`: `true`
+2. Briefly confirm: what's scheduled, the cron expression, the human-readable cadence, that recurring tasks auto-expire after 7 days, and that they can cancel sooner with CronDelete (include the job ID).
+3. **Then immediately execute the parsed prompt now** — don't wait for the first cron fire. If it's a slash command, invoke it via the Skill tool; otherwise act on it directly.
+
+## Input
+
+$ARGUMENTS

package/builtin/skills/settings/ENV.md

@@ -0,0 +1,64 @@
+# Wave Environment Variables Configuration
+
+Environment variables allow you to customize Wave's behavior, configure AI models, and provide context to hooks and tools. This document provides detailed guidance on how to configure environment variables in `settings.json`.
+
+## The `env` Field
+
+Environment variables are configured in the `env` field of `settings.json`. It is a simple key-value pair of strings.
+
+```json
+{
+  "env": {
+    "WAVE_MODEL": "gemini-3-flash",
+    "MY_CUSTOM_VAR": "some-value"
+  }
+}
+```
+
+## Supported `WAVE_*` Environment Variables
+
+Wave uses several environment variables to control its core functionality.
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `WAVE_API_KEY` | API key for the AI gateway. | - |
+| `WAVE_BASE_URL` | Base URL for the AI gateway. | - |
+| `WAVE_CUSTOM_HEADERS` | Custom HTTP headers for the AI gateway (JSON string). | - |
+| `WAVE_MODEL` | The primary AI model to use for the agent. | `gemini-3-flash` |
+| `WAVE_FAST_MODEL` | The fast AI model to use for quick tasks. | `gemini-2.5-flash` |
+| `WAVE_MAX_INPUT_TOKENS` | Maximum number of input tokens allowed. | `96000` |
+| `WAVE_MAX_OUTPUT_TOKENS` | Maximum number of output tokens allowed. | `8192` |
+| `WAVE_DISABLE_AUTO_MEMORY` | Set to `1` or `true` to disable the auto-memory feature. | `false` |
+| `WAVE_TASK_LIST_ID` | Explicitly set the task list ID for the session. | (Session ID) |
+
+## Configuration Scopes
+
+Environment variables can be set in different scopes, with the following precedence (highest to lowest):
+
+1.  **Local Scope**: `.wave/settings.local.json` (Local overrides, ignored by git)
+2.  **Project Scope**: `.wave/settings.json` (Project-specific settings, shared via git)
+3.  **User Scope**: `~/.wave/settings.json` (Global settings for all projects)
+4.  **System Environment**: Variables set in your shell (e.g., `export WAVE_API_KEY=...`)
+
+## Custom Environment Variables
+
+You can also define custom environment variables in the `env` field. These variables will be available to:
+
+- **Hooks**: Any shell command executed as a hook will have these variables in its environment.
+- **Tools**: Tools like `Bash` will have access to these variables.
+
+Example:
+```json
+{
+  "env": {
+    "PROJECT_NAME": "my-awesome-project",
+    "DEPLOY_TARGET": "staging"
+  }
+}
+```
+
+## Best Practices
+
+- **Use Local Overrides for Secrets**: Never commit sensitive information like `WAVE_API_KEY` to `settings.json`. Use `settings.local.json` instead.
+- **Standard Naming**: Use uppercase and underscores for environment variable names (e.g., `MY_VARIABLE`).
+- **Avoid Overriding System Variables**: Be careful not to override standard system variables like `PATH` or `HOME` unless you have a specific reason to do so.

package/builtin/skills/settings/HOOKS.md

@@ -0,0 +1,94 @@
+# Wave Hooks Configuration
+
+Hooks allow you to automate tasks when certain events occur in Wave. This document provides detailed guidance on how to configure hooks in `settings.json`.
+
+## Hook Events
+
+Wave supports the following hook events:
+
+- `PreToolUse`: Triggered before a tool is executed.
+- `PostToolUse`: Triggered after a tool has finished executing.
+- `UserPromptSubmit`: Triggered when a user submits a prompt.
+- `PermissionRequest`: Triggered when Wave requests permission to use a tool.
+- `Stop`: Triggered when Wave finishes its response cycle (no more tool calls).
+- `SubagentStop`: Triggered when a subagent finishes its response cycle.
+- `WorktreeCreate`: Triggered when a new worktree is created.
+
+## Hook Configuration Structure
+
+Hooks are configured in the `hooks` field of `settings.json`. Each event can have multiple hook configurations.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "command": "pnpm lint",
+            "description": "Run lint before writing files"
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "command": "echo \"Permission requested for Bash tool\" >> hooks.log",
+            "description": "Log permission requests for Bash"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Hook Configuration Fields
+
+- `matcher`: (Optional) A pattern to match against the tool name (e.g., "Write", "Read*", "/^Edit/"). Only applicable for `PreToolUse`, `PostToolUse`, and `PermissionRequest`.
+- `hooks`: An array of hook commands to execute.
+  - `command`: The shell command to execute.
+  - `description`: A brief description of the hook's purpose.
+  - `async`: (Optional) Whether the hook should run in the background without blocking (default: `false`).
+  - `timeout`: (Optional) Maximum execution time in seconds (default: `600`).
+
+## Hook Input JSON
+
+Wave provides detailed context to hook processes via `stdin` as a JSON object. This allows hooks to make informed decisions based on the current state.
+
+### Common Fields
+- `session_id`: The current session ID.
+- `transcript_path`: Path to the session transcript file (JSON).
+- `cwd`: The current working directory.
+- `hook_event_name`: The name of the triggering event.
+
+### Event-Specific Fields
+- `tool_name`: (PreToolUse, PostToolUse, PermissionRequest) The name of the tool.
+- `tool_input`: (PreToolUse, PostToolUse, PermissionRequest) The input parameters passed to the tool.
+- `tool_response`: (PostToolUse) The result of the tool execution.
+- `user_prompt`: (UserPromptSubmit) The text submitted by the user.
+- `subagent_type`: (If executed by a subagent) The type of the subagent.
+- `name`: (WorktreeCreate) The name of the new worktree.
+
+## Hook Exit Codes
+
+Hooks can communicate status and control Wave's behavior using exit codes:
+
+- **Exit 0**: Success. Wave continues its normal execution.
+- **Exit 2**: Blocking Error. Wave blocks the current operation and provides feedback based on the event:
+    - `UserPromptSubmit`: Blocks prompt processing and shows `stderr` as a user error.
+    - `PreToolUse`: Blocks tool execution and provides `stderr` to the agent as feedback.
+    - `PostToolUse`: Appends `stderr` to the tool result as feedback for the agent.
+    - `Stop`: Blocks the stop operation and provides `stderr` to the agent.
+- **Other Exits (e.g., Exit 1)**: Non-blocking error. Wave continues execution but shows `stderr` as a warning to the user.
+
+## Best Practices
+
+- **Keep hooks fast**: Long-running hooks can slow down your workflow unless they are `async`.
+- **Use descriptive names**: Help yourself and others understand what each hook does.
+- **Test your hooks**: Run the commands manually first to ensure they work as expected.
+- **Use local overrides**: For machine-specific hooks, use `.wave/settings.local.json`.

package/builtin/skills/settings/MCP.md

@@ -0,0 +1,55 @@
+# Model Context Protocol (MCP) Configuration
+
+The Model Context Protocol (MCP) allows Wave to connect to external servers that provide additional tools and context. This document explains how to configure and use MCP servers in Wave.
+
+## Configuration File: `.mcp.json`
+
+MCP servers are configured in a `.mcp.json` file. Wave looks for this file in your project root:
+
+1.  **Project Scope**: `.mcp.json` in your project root (Project-specific MCP servers)
+
+## Configuration Structure
+
+The `.mcp.json` file contains a list of MCP server configurations.
+
+```json
+{
+  "mcpServers": {
+    "sqlite": {
+      "command": "uvx",
+      "args": ["mcp-server-sqlite", "--db-path", "/path/to/your/database.db"]
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+### Fields for each server:
+
+- `command`: The executable to run (e.g., `npx`, `uvx`, `python`, `node`).
+- `args`: An array of command-line arguments for the executable.
+- `env`: (Optional) A record of environment variables for the server process.
+
+## Using MCP Tools
+
+Once configured, Wave will automatically connect to the MCP servers when it starts. Tools provided by these servers will be available to the agent with a prefix:
+
+`mcp__[serverName]__[toolName]`
+
+For example, if you have a server named `sqlite` with a tool named `query`, it will be available as `mcp__sqlite__query`.
+
+## Permissions for MCP Tools
+
+By default, MCP tools require user permission before execution. When you grant permission, you can choose to "Allow always" for a specific tool. These persistent rules are stored in your `settings.json` under the `permissions` field.
+
+## Troubleshooting
+
+- **Server Connection**: If a server fails to connect, Wave will log an error. You can check the status of MCP servers by asking the agent.
+- **Tool Availability**: If a tool is not appearing, ensure the server is running and the `.mcp.json` configuration is correct.
+- **Logs**: MCP server `stderr` is often used for logging and can be helpful for debugging connection issues.

package/builtin/skills/settings/MEMORY_RULES.md

@@ -0,0 +1,60 @@
+# Wave Memory Rules Configuration
+
+Memory rules allow you to provide context-specific instructions and guidelines to the agent. This document explains how to create and manage memory rules in Wave.
+
+## What are Memory Rules?
+
+Memory rules are Markdown files that contain instructions for the agent. They are used to:
+- Enforce coding styles and conventions.
+- Provide project-specific context (e.g., "always use pnpm").
+- Define architectural patterns and best practices.
+- Share common knowledge across the team.
+
+## Creating Memory Rules
+
+Wave looks for memory rules in the following locations:
+
+1.  **User Scope**: `~/.wave/rules/*.md` (Global memory rules)
+2.  **Project Scope**: `.wave/rules/*.md` (Project-specific memory rules)
+3.  **Project Root**: `AGENTS.md` (Legacy project-level memory rules)
+
+### File Structure
+
+A memory rule file is a standard Markdown file. It can optionally include YAML frontmatter to scope the rules to specific file paths.
+
+```markdown
+---
+paths:
+  - "src/api/**/*.ts"
+  - "src/services/**/*.ts"
+---
+
+# API and Service Guidelines
+
+- Always use `async/await` for asynchronous operations.
+- Use `Zod` for input validation.
+- Follow the repository pattern for data access.
+```
+
+### YAML Frontmatter Fields
+
+- `paths`: (Optional) A list of glob patterns. The rules in this file will only be active when the agent is working with files that match these patterns. If omitted, the rules are always active.
+
+## How Memory Rules are Loaded
+
+Wave automatically discovers and loads all `.md` files in the `.wave/rules/` directory and its immediate subdirectories.
+
+- **Path-Specific Activation**: If a memory rule has a `paths` field, it is only included in the agent's context if *any* file currently being read or modified matches the glob patterns.
+- **Union of Rules**: If multiple files are in context, Wave activates the union of all matching memory rules.
+- **Priority**: Project-level memory rules take priority over user-level memory rules if there is a conflict.
+
+## Best Practices
+
+- **Keep rules focused**: Create separate files for different topics (e.g., `testing.md`, `ui-components.md`).
+- **Use clear instructions**: Write rules in a way that is easy for the agent to understand and follow.
+- **Leverage path scoping**: Use the `paths` field to keep the agent's context window clean and relevant.
+- **Share rules with your team**: Commit `.wave/rules/` to your git repository to ensure everyone on the team has the same context.
+
+## Auto-Memory
+
+In addition to manual memory rules, Wave also has an **auto-memory** feature that automatically remembers important information across sessions. This is stored in `~/.wave/projects/<project-id>/memory/MEMORY.md`. You can disable this feature in `settings.json` by setting `"autoMemoryEnabled": false`.

package/{dist/builtin-skills → builtin/skills}/settings/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: settings
-description: Manage Wave settings and get guidance on settings.json
-allowed-tools: Bash, Read, Write
+description: Manage Wave settings and get guidance on settings.json, hooks, environment variables, permissions, MCP servers, memory rules, skills, and subagents. Use this when the user wants to view, update, or learn how to configure Wave.
 ---
 
 # Wave Settings Skill
@@ -25,6 +24,7 @@ For detailed hook configuration, see [HOOKS.md](${WAVE_SKILL_DIR}/HOOKS.md).
 
 ### 2. Environment Variables
 Set environment variables that will be available to all tools and hooks.
+For detailed environment variable configuration and available `WAVE_*` variables, see [ENV.md](${WAVE_SKILL_DIR}/ENV.md).
 ```json
 {
   "env": {
@@ -41,24 +41,13 @@ Manage tool permissions and define the "Safe Zone".
   "permissions": {
     "allow": ["Bash", "Read"],
     "deny": ["Write"],
-    "defaultMode": "interactive",
+    "permissionMode": "default",
     "additionalDirectories": ["/tmp/wave-exports"]
   }
 }
 ```
 
-### 4. Enabled Plugins
-Enable or disable specific plugins.
-```json
-{
-  "enabledPlugins": {
-    "git-plugin": true,
-    "experimental-plugin": false
-  }
-}
-```
-
-### 5. Model and Token Configuration
+### 4. Model and Token Configuration
 Define which AI models Wave should use and set token limits via environment variables.
 ```json
 {
@@ -71,7 +60,23 @@ Define which AI models Wave should use and set token limits via environment vari
 }
 ```
 
-### 6. Other Settings
+### 5. Model Context Protocol (MCP)
+Connect to external servers to provide additional tools and context.
+For detailed MCP configuration, see [MCP.md](${WAVE_SKILL_DIR}/MCP.md).
+
+### 6. Memory Rules
+Provide context-specific instructions and guidelines to the agent.
+For detailed memory rules configuration, see [MEMORY_RULES.md](${WAVE_SKILL_DIR}/MEMORY_RULES.md).
+
+### 7. Skills
+Extend Wave's functionality by creating custom skills.
+For detailed guidance on creating skills, see [SKILLS.md](${WAVE_SKILL_DIR}/SKILLS.md).
+
+### 8. Subagents
+Delegate tasks to specialized AI personalities.
+For detailed guidance on creating subagents, see [SUBAGENTS.md](${WAVE_SKILL_DIR}/SUBAGENTS.md).
+
+### 9. Other Settings
 - `language`: Preferred language for agent communication (e.g., `"en"`, `"zh"`).
 - `autoMemoryEnabled`: Enable or disable auto-memory (default: `true`).
 
@@ -82,5 +87,7 @@ You can ask me to:
 - "Update my project settings to enable auto-memory"
 - "How do I configure a post-commit hook?"
 - "What are the available permission modes?"
+- "How do I create a custom skill?"
+- "How do I define a new subagent?"
 
 I will guide you through the process and ensure your configuration is valid.

package/builtin/skills/settings/SKILLS.md

@@ -0,0 +1,63 @@
+# Creating and Managing Wave Skills
+
+Skills are discoverable capabilities that extend Wave's functionality. They allow you to package instructions, tools, and scripts into reusable modules.
+
+## Skill Structure
+
+A skill is a directory containing a `SKILL.md` file.
+
+```text
+my-skill/
+├── SKILL.md          # Main skill definition (required)
+├── reference.md      # Supporting documentation (optional)
+├── scripts/          # Custom scripts (optional)
+└── templates/        # Code templates (optional)
+```
+
+## The `SKILL.md` File
+
+The `SKILL.md` file uses YAML frontmatter for configuration and Markdown for instructions.
+
+```markdown
+---
+name: my-skill
+description: A brief description of what the skill does.
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# My Skill Instructions
+
+When this skill is invoked, follow these steps:
+1. Use the `Read` tool to examine the project structure.
+2. Use the `Bash` tool to run `npm test`.
+```
+
+### YAML Frontmatter Fields
+
+- `name`: (Required) Unique identifier (lowercase, numbers, hyphens).
+- `description`: (Required) Explains when the AI should use this skill.
+- `allowed-tools`: (Optional) List of tools the skill can use.
+- `context: fork`: (Optional) Run the skill in a separate subagent.
+- `agent`: (Optional) Specify the subagent type (e.g., `general-purpose`).
+
+## Skill Locations
+
+Wave looks for skills in two locations:
+
+1.  **User Skills**: `~/.wave/skills/` (Available in all projects)
+2.  **Project Skills**: `.wave/skills/` (Specific to the current project)
+
+Project skills take precedence over user skills with the same name.
+
+## Invoking Skills
+
+- **AI-Invoked**: The agent automatically discovers and uses skills based on their `description`.
+- **User-Invoked**: Use slash commands in the CLI (e.g., `/my-skill`).
+
+## Best Practices
+
+- **Clear Descriptions**: Write descriptions that help the AI understand exactly when the skill is relevant.
+- **Modular Design**: Keep skills focused on a single task or capability.
+- **Use `${WAVE_SKILL_DIR}`**: Use this placeholder to reference files within the skill directory.

package/builtin/skills/settings/SUBAGENTS.md

@@ -0,0 +1,60 @@
+# Creating and Managing Wave Subagents
+
+Subagents are specialized AI personalities that Wave can delegate tasks to. They have their own context windows, expertise areas, and tool configurations.
+
+## Subagent Structure
+
+A subagent is defined by a Markdown file with YAML frontmatter.
+
+```text
+.wave/agents/
+└── my-subagent.md    # Subagent definition
+```
+
+## The `subagent.md` File
+
+The `subagent.md` file uses YAML frontmatter for configuration and Markdown for the system prompt.
+
+```markdown
+---
+name: my-subagent
+description: A specialized subagent for a specific task.
+tools:
+  - Bash
+  - Read
+model: gemini-3-flash
+---
+
+# My Subagent System Prompt
+
+You are a specialized subagent for a specific task. Your goal is to:
+1. Use the `Read` tool to examine the project structure.
+2. Use the `Bash` tool to run `npm test`.
+```
+
+### YAML Frontmatter Fields
+
+- `name`: (Required) Unique identifier.
+- `description`: (Required) Explains the subagent's expertise and when to use it.
+- `tools`: (Optional) List of tools the subagent can use.
+- `model`: (Optional) Overrides the default model for this subagent.
+
+## Subagent Locations
+
+Wave looks for subagents in two locations:
+
+1.  **User Subagents**: `~/.wave/agents/` (Available in all projects)
+2.  **Project Subagents**: `.wave/agents/` (Specific to the current project)
+
+Project subagents take precedence over user subagents with the same name.
+
+## Delegating to Subagents
+
+- **Automatic Delegation**: Wave automatically recognizes when a task matches a subagent's expertise and delegates to it.
+- **Explicit Delegation**: You can explicitly request a specific subagent for a task.
+
+## Best Practices
+
+- **Focused Expertise**: Define subagents with clear, specific roles (e.g., "Testing Expert", "Refactoring Specialist").
+- **Detailed System Prompts**: Provide clear instructions and guidelines in the system prompt to ensure consistent behavior.
+- **Tool Selection**: Only provide the tools that are necessary for the subagent's role.

package/builtin/subagents/bash.md

@@ -0,0 +1,18 @@
+---
+description: Command execution specialist for running bash commands. Use this for git operations, command execution, and other terminal tasks.
+tools: [Bash]
+model: inherit
+---
+
+You are a command execution specialist. Your role is to execute bash commands efficiently and safely.
+
+Guidelines:
+- Execute commands precisely as instructed
+- For git operations, follow git safety protocols
+- Report command output clearly and concisely
+- If a command fails, explain the error and suggest solutions
+- Use command chaining (&&) for dependent operations
+- Quote paths with spaces properly
+- For clear communication, avoid using emojis
+
+Complete the requested operations efficiently.

package/builtin/subagents/explore.md

@@ -0,0 +1,42 @@
+---
+description: 'Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.'
+tools: [Glob, Grep, Read, Bash, LSP]
+model: fastModel
+---
+
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+	
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+- Using Language Server Protocol (LSP) for deep code intelligence (definitions, references, etc.)
+
+Guidelines:
+- Use Glob for broad file pattern matching
+- Use Grep for searching file contents with regex
+- Use Read when you know the specific file path you need to read
+- Use LSP for code intelligence features like finding definitions, references, implementations, and symbols. This is especially useful for understanding complex code relationships.
+- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Return file paths as absolute paths in your final response
+- For clear communication, avoid using emojis
+- Communicate your final report directly as a regular message - do NOT attempt to create files
+
+NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:
+- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations
+- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files
+
+Complete the user's search request efficiently and report your findings clearly.

package/builtin/subagents/general-purpose.md

@@ -0,0 +1,20 @@
+---
+description: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you.
+---
+
+You are an agent. Given the user's message, you should use the tools available to complete the task. Do what has been asked; nothing more, nothing less. When you complete the task simply respond with a detailed writeup.
+
+Your strengths:
+- Searching for code, configurations, and patterns across large codebases
+- Analyzing multiple files to understand system architecture
+- Investigating complex questions that require exploring many files
+- Performing multi-step research tasks
+
+Guidelines:
+- For file searches: Use Grep or Glob when you need to search broadly. Use Read when you know the specific file path.
+- For analysis: Start broad and narrow down. Use multiple search strategies if the first doesn't yield results.
+- Be thorough: Check multiple locations, consider different naming conventions, look for related files.
+- NEVER create files unless they're absolutely necessary for achieving your goal. ALWAYS prefer editing an existing file to creating a new one.
+- NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.
+- In your final response always share relevant file names and code snippets. Any file paths you return in your response MUST be absolute. Do NOT use relative paths.
+- For clear communication, avoid using emojis.