Explore Agent

{
  "model": "grok-code-fast-1",
  "temperature": 0.1
}

// Free tier option
{
  "model": "minimax-m2.5-free"
}

// Fast Claude option
{
  "model": "claude-haiku-4-5"
}

// Minimal option
{
  "model": "gpt-5-nano"
}

<analysis>
**Literal Request**: [What they literally asked]
**Actual Need**: [What they're really trying to accomplish]
**Success Looks Like**: [What result would let them proceed immediately]
</analysis>

{`<results>`}
<files>
- /absolute/path/to/file1.ts — [why this file is relevant]
- /absolute/path/to/file2.ts — [why this file is relevant]
</files>

{`<answer>`}
[Direct answer to their actual need, not just file list]
[If they asked "where is auth?", explain the auth flow you found]
{`</answer>`}

{`<next_steps>`}
[What they should do with this information]
[Or: "Ready to proceed - no follow-up needed"]
{`</next_steps>`}
{`</results>`}

// Delegated from main agent
task(
  subagent_type="explore",
  run_in_background=true,
  load_skills=[],
  description="Find authentication patterns",
  prompt="[CONTEXT]: I'm implementing JWT authentication for the REST API 
          in src/api/routes/. I need to match existing auth conventions so 
          my code fits seamlessly.
          
          [GOAL]: I need to decide on middleware structure and token flow.
          
          [DOWNSTREAM]: I'll use this to structure my middleware chain and 
          choose where to validate tokens.
          
          [REQUEST]: Find:
          - Auth middleware implementations  
          - Login/signup handlers
          - Token generation patterns
          - Credential validation logic
          
          Focus on src/ — skip tests. Return file paths with pattern descriptions."
)

// Explore execution:
<analysis>
**Literal Request**: Find auth-related files and patterns
**Actual Need**: Understand existing auth architecture to implement compatible JWT system
**Success Looks Like**: Clear picture of middleware flow, token handling, and validation patterns
</analysis>

// Parallel tool calls (4 simultaneous)
grep(pattern: "middleware.*auth", path: "src/", include: "*.ts")
grep(pattern: "jwt|token", path: "src/", include: "*.ts")
ast_grep_search('function login', path: 'src/')
lsp_symbols(workspace: true, query: "authenticate")

// Response:
{`<results>`}
<files>
- /home/user/project/src/middleware/auth.ts — Main auth middleware, validates tokens
- /home/user/project/src/routes/auth.ts — Login/register endpoints, token generation
- /home/user/project/src/services/auth/jwt.ts — JWT sign/verify utilities
- /home/user/project/src/services/auth/password.ts — Password hashing with bcrypt
- /home/user/project/src/types/express.d.ts — Extended Request type with user property
</files>

{`<answer>`}
Auth architecture follows standard Express middleware pattern:

**Flow**:
1. Login/register hits `/api/auth/login` (auth.ts route)
2. Password validated via bcrypt (password.ts service)
3. JWT generated and returned (jwt.ts service)
4. Protected routes use auth middleware (middleware/auth.ts)
5. Middleware extracts token, validates, attaches user to req.user

**Middleware pattern** (auth.ts:15-45):
```typescript
export const authenticate = async (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1]
  if (!token) return res.status(401).json({ error: 'No token' })
  
  try {
    const payload = jwt.verify(token)
    req.user = await User.findById(payload.userId)
    next()
  } catch (err) {
    res.status(401).json({ error: 'Invalid token' })
  }
}

export const generateToken = (userId: string) => {
  return jwt.sign({ userId }, process.env.JWT_SECRET, { expiresIn: '15m' })
}

### Example 2: Cross-Layer Discovery

```typescript
task(
  subagent_type="explore",
  run_in_background=true,
  description="Find error handling patterns",
  prompt="[CONTEXT]: Adding error handling to new API endpoints. Need to 
          follow existing error conventions.
          
          [GOAL]: Understand error response format and global error handling.
          
          [DOWNSTREAM]: Will structure my try/catch blocks and error responses 
          to match existing code.
          
          [REQUEST]: Find:
          - Custom Error subclasses
          - Error response format (JSON shape)
          - Try/catch patterns in route handlers  
          - Global error middleware
          
          Skip test files. Return error class hierarchy and response format."
)

// Explore execution:
// Parallel tools (5 simultaneous)
grep(pattern: "class.*Error.*extends", path: "src/", include: "*.ts")
grep(pattern: "app.use.*error", path: "src/", include: "*.ts") 
ast_grep_search('try { $$$ } catch ($E) { $$$ }', path: 'src/routes/')
glob(pattern: "**/errors/*.ts", path: "src/")
lsp_symbols(workspace: true, query: "Error")

{`<results>`}
<files>
- /home/user/project/src/errors/AppError.ts — Base error class
- /home/user/project/src/errors/ValidationError.ts — 400 validation errors
- /home/user/project/src/errors/AuthError.ts — 401 auth errors  
- /home/user/project/src/errors/NotFoundError.ts — 404 not found
- /home/user/project/src/middleware/errorHandler.ts — Global error middleware
- /home/user/project/src/routes/users.ts — Example error handling pattern
</files>

{`<answer>`}
Error handling uses custom Error hierarchy with global middleware:

**Error class hierarchy**:

**Base class** (AppError.ts:3-10):
```typescript
export class AppError extends Error {
  constructor(
    public message: string,
    public statusCode: number,
    public code?: string
  ) {
    super(message)
  }
}

app.use((err, req, res, next) => {
  if (err instanceof AppError) {
    return res.status(err.statusCode).json({
      error: err.message,
      code: err.code
    })
  }
  // Unexpected errors
  res.status(500).json({ error: 'Internal server error' })
})

try {
  const user = await User.findById(req.params.id)
  if (!user) throw new NotFoundError('User not found')
  res.json(user)
} catch (err) {
  next(err) // Pass to global error handler
}

### Example 3: History Investigation

```typescript
task(
  subagent_type="explore",
  run_in_background=true,
  description="When was rate limiting added?",
  prompt="[CONTEXT]: Debugging rate limit behavior, need to understand when 
          and why it was implemented.
          
          [GOAL]: Find the commit, PR, and reasoning for rate limiting.
          
          [REQUEST]: Find when rate limiting was added, who added it, and why. 
          Check git history, blame, and any related comments/docs."
)

// Explore execution:
// Parallel tools
grep(pattern: "rate.*limit", path: "src/", include: "*.ts")
bash("git log --all --oneline --grep='rate limit'")
bash("git log --all --oneline -- '**/rateLimit*'")

// After finding file
bash("git log --follow -- src/middleware/rateLimit.ts")
bash("git blame src/middleware/rateLimit.ts")

{`<results>`}
<files>
- /home/user/project/src/middleware/rateLimit.ts — Rate limiting middleware
</files>

{`<answer>`}
Rate limiting added on 2025-11-15 by @alice in commit abc123f.

**Commit**: abc123f - "Add rate limiting to auth endpoints"
**Author**: Alice Chen <[email protected]>
**Date**: 2025-11-15

**Why it was added** (from commit message):

**Implementation** (rateLimit.ts:8-15):
```typescript
import rateLimit from 'express-rate-limit'

export const authRateLimit = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 5, // 5 requests per window
  message: 'Too many attempts, please try again later'
})

router.post('/login', authRateLimit, loginHandler)
router.post('/register', authRateLimit, registerHandler)

## Search Stop Conditions

STOP searching when:

<Check>You have enough context to proceed confidently</Check>
<Check>Same information appearing across multiple sources</Check>
<Check>2 search iterations yielded no new useful data</Check>
<Check>Direct answer found</Check>

**DO NOT over-explore. Time is precious.**

## Configuration

Customize Explore in `oh-my-opencode.jsonc`:

```jsonc
{
  "agents": {
    "explore": {
      "model": "github-copilot/grok-code-fast-1",
      "temperature": 0.1,
      "prompt_append": "Additional search guidelines...",
      "disable": false
    }
  }
}