Advanced Tools - Kraken, Look At, and More

Level: Enhancement (beyond minimal agent) Prerequisites: Tool system, subagents

---

What This Adds

Specialized tools for complex operations:

• Kraken - Multi-file refactoring with parallel execution
• Look At - Media/file analysis with vision models
• Fastmod - Bulk regex find-replace
• Diagnostics - LSP integration for type checking

---

Kraken: Multi-File Refactoring

The Problem

Renaming a function across 50 files is tedious with single-file edits. Kraken solves this with parallel execution.

Key Design Decision

Kraken deliberately avoids coordination complexity by requiring all edits be independent.

Question	Answer
How does it detect dependencies?	It doesn't. Only independent changes allowed.
How does it sequence executors?	It doesn't. All run truly parallel.
How does it handle conflicts?	It can't. Conflicts shouldn't occur.
Does it roll back on failure?	No. Errors aggregated, partial success remains.

Architecture

User: "Rename oldFunc to newFunc everywhere"
                    │
                    ▼
        ┌─────────────────────────┐
        │     SCOPE AGENT         │
        │     (Haiku 4.5)         │
        │                         │
        │ 1. Use fastmod for      │
        │    simple replacements  │
        │ 2. Search for complex   │
        │    cases                │
        │ 3. Immediately queue    │
        │    files for editing    │
        └───────────┬─────────────┘
                    │
        ┌───────────┼───────────┐
        ▼           ▼           ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐
   │EXECUTOR │ │EXECUTOR │ │EXECUTOR │
   │ file1   │ │ file2   │ │ file3   │
   │Haiku 4.5│ │Haiku 4.5│ │Haiku 4.5│
   └─────────┘ └─────────┘ └─────────┘
        │           │           │
        └───────────┴───────────┘
                    ▼
            Aggregate Results

Streaming Execution

Executors start immediately as files are discovered, not waiting for scope to finish:

Time ─────────────────────────────────────────────────▶

Scope:   [search] ──▶ [find file1] ──▶ [find file2] ──▶ [done]
                           │                │
Executor1:                 └─▶ [start] ─────────────▶ [done]
Executor2:                                  └─▶ [start] ─▶ [done]

Scope Agent Prompt

You are the Kraken Scope agent, responsible for identifying files
that need modification for a kraken operation.

If the change involves a simple string or regexp replacement, first
use the fastmod tool.

Key responsibilities:
- Use glob to find files by pattern
- Use Grep to search for specific strings
- Use fastmod for simple bulk replacements
- CRITICAL: After every tool call that reveals files, IMMEDIATELY
  call enqueue_file_edit

Guidelines:
- Provide absolute file paths only, NOT glob patterns
- DO NOT WAIT to call enqueue_file_edit until the end
- Interleave search calls with enqueue calls

Executor Agent Prompt

You are an Executor agent, applying code modifications to specific files.

Your role is to make targeted changes based on the kraken objective.

Key responsibilities:
- Read and understand the target files
- Apply necessary transformations
- Use edit_file for precise changes

Guidelines:
- Focus only on the paths you're given
- Work efficiently
- Do NOT print a summary, just stop

Implementation

interface KrakenRequest {
  objective: string;
  paths?: string[];  // Optional path constraints
}

async function runKraken(request: KrakenRequest): Promise<KrakenResult> {
  const fileQueue = new Subject<FileEdit>();
  const modifiedFiles = new Set<string>();

  // 1. Start scope agent
  const scopePromise = runScopeAgent({
    objective: request.objective,
    paths: request.paths,
    onFileQueued: (file, objective) => {
      fileQueue.next({ path: file, objective });
    }
  });

  // 2. Spawn executors in parallel (no concurrency limit)
  const executorResults = fileQueue.pipe(
    mergeMap(file => runExecutor({
      path: file.path,
      objective: file.objective,
      globalObjective: request.objective
    })),
    tap(result => {
      if (result.success) {
        modifiedFiles.add(result.path);
      }
    })
  ).toPromise();

  // 3. Wait for scope to complete, then close queue
  await scopePromise;
  fileQueue.complete();

  // 4. Wait for all executors
  const results = await executorResults;

  // 5. Aggregate results
  const errors = results.filter(r => !r.success);

  return {
    success: errors.length === 0,
    filesModified: Array.from(modifiedFiles),
    errors: errors.map(e => e.error)
  };
}

The enqueue_file_edit Tool

const enqueueFileEdit = {
  name: "enqueue_file_edit",
  description: `Queue files for editing. MUST call immediately after finding files.`,
  inputSchema: {
    type: "object",
    properties: {
      paths: {
        type: "array",
        items: { type: "string" },
        description: "Absolute file paths to edit"
      },
      objective: {
        type: "string",
        description: "Specific editing objective for these files"
      }
    },
    required: ["paths", "objective"]
  }
};

The fastmod Tool

For simple bulk replacements:

const fastmod = {
  name: "fastmod",
  description: "Replace pattern with substitution across multiple files.",
  inputSchema: {
    type: "object",
    properties: {
      pattern: { type: "string", description: "Regex pattern" },
      substitution: { type: "string", description: "Replacement text" },
      glob: { type: "string", description: "File glob pattern" }
    },
    required: ["pattern", "substitution"]
  }
};

async function executeFastmod(args: FastmodArgs): Promise<string[]> {
  const regex = new RegExp(args.pattern, "g");
  const files = await glob(args.glob ?? "**/*");
  const modified: string[] = [];

  for (const file of files) {
    if (isBinary(file)) continue;

    const content = await readFile(file);
    if (regex.test(content)) {
      const newContent = content.replace(regex, args.substitution);
      if (newContent !== content) {
        await writeFile(file, newContent);
        modified.push(file);
      }
    }
  }

  return modified;
}

When to Use Kraken

Use for:

• Simple renames across many files
• Bulk import updates
• Pattern-based changes

Don't use for:

• Complex refactoring requiring context
• Changes needing human judgment
• Interdependent modifications

---

Look At: Media Analysis

Purpose

Analyze files that require vision capabilities:

• Screenshots
• UI mockups
• Diagrams
• Error screenshots

Model Selection

Uses a vision-capable model like Gemini 3 Flash Preview.

Prompt

You are an AI assistant that analyzes files for a software engineer.

# Core Principles
- Be concise and direct
- Focus only on the user's objective
- No preamble, disclaimers, or summaries

# Precision Guidelines
- When analyzing images: describe exactly what you see, do not guess
- When analyzing code: reference specific line numbers
- When analyzing documents: extract the specific information requested

# Comparing Files
When reference files are provided alongside the main file:
- Systematically identify differences
- Be specific: mention exact locations that differ
- Structure comparison clearly

# Output Format
- Use GitHub-flavored Markdown
- No emojis
- Keep responses focused and brief

Implementation

interface LookAtRequest {
  files: string[];
  objective: string;
  referenceFiles?: string[];
}

async function lookAt(request: LookAtRequest): Promise<string> {
  const contents = await Promise.all(
    request.files.map(async file => ({
      type: "image",
      source: {
        type: "base64",
        mediaType: getMediaType(file),
        data: await readFileAsBase64(file)
      }
    }))
  );

  const response = await inference({
    model: "gemini-3-flash-preview",
    system: LOOK_AT_PROMPT,
    messages: [{
      role: "user",
      content: [
        ...contents,
        { type: "text", text: request.objective }
      ]
    }],
    maxTokens: 4000
  });

  return extractText(response.content);
}

---

Diagnostics: LSP Integration

Purpose

Get type errors, lint issues, and other diagnostics from the language server.

Implementation

interface DiagnosticsRequest {
  path?: string;  // Specific file or all
  severity?: "error" | "warning" | "info";
}

const getDiagnostics = {
  name: "get_diagnostics",
  description: "Get diagnostics (errors, warnings) from the language server",
  inputSchema: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: "File path, or omit for all open files"
      },
      severity: {
        type: "string",
        enum: ["error", "warning", "info"],
        description: "Minimum severity to include"
      }
    }
  }
};

async function executeDiagnostics(args: DiagnosticsRequest): Promise<Diagnostic[]> {
  const lspClient = await getLSPClient();

  if (args.path) {
    return lspClient.getDiagnostics(args.path);
  }

  return lspClient.getAllDiagnostics();
}

Usage Pattern

After making changes, verify with diagnostics:

1. Edit file
2. Run get_diagnostics
3. If errors, fix them
4. Repeat until clean

---

Tool Availability by Context

Not all tools are available everywhere:

Tool	Main Agent	Finder	Oracle	Kraken Scope	Kraken Executor
Read	✓	✓	✓	✓	✓
edit_file	✓				✓
Grep	✓	✓	✓	✓	✓
glob	✓	✓	✓	✓	✓
enqueue_file_edit				✓
fastmod				✓
get_diagnostics	✓				✓
look_at	✓

---

When to Add Advanced Tools

Add these when:

1. Kraken - Many-file refactoring is common
2. Look At - Users share screenshots/mockups
3. Diagnostics - TypeScript/language server integration
4. Fastmod - Bulk text replacements needed

These are all optional enhancements beyond the core toolset.

---

Enhancement based on Amp Code v0.0.1769212917 patterns