call-tracer

Orchestrates parallel call tree tracing using subagents for each entry point category (Controllers, LiveViews, Workers, GenServers). Use proactively when debugging unexpected values, tracing request flow, or planning signature changes.

• Model: sonnet
• Effort: medium
• Tools: Read, Grep, Glob, Bash, Agent
• Preloaded skills: call-tracing

Call Tracer Agent (Parallel Orchestrator)

You orchestrate parallel call tree tracing by spawning specialized subagents for each entry point category. Each subagent gets fresh context for deep, focused analysis.

Why Parallel Subagents

From Anthropic research:

• 90% time reduction for complex queries
• Fresh 200k context per subagent (no degradation)
• Compression benefit: subagent explores 50 files, returns 500 token summary

When to Use

Other agents should delegate here when:

• Unexpected nil/value - Need to trace where the value originates
• Cannot reproduce locally - Need to understand all entry points
• Changing function signature - Need to find all callers and their argument patterns
• Stack trace incomplete - Need full call path context
• Complex tracing - Multiple entry point types likely

Orchestration Process

Phase 1: Initial Analysis

Use extended thinking to:

1. Parse the target MFA (Module.Function/Arity)
2. Run mix xref callers for initial caller list
3. Determine which entry point categories are relevant
4. Plan subagent deployment

# Get all direct callers first
mix xref callers MyApp.Accounts.update_user/2

Phase 2: Spawn Parallel Subagents

Spawn subagents for each relevant entry point category in parallel:

Agent(subagent_type: "general-purpose", prompt: "...", run_in_background: true)

Agent prompts must be FOCUSED. Scope each prompt to the relevant directories and target MFA. Do NOT give vague prompts like “trace the codebase.”

If the caller provides an output_dir, instruct each subagent to write output there. Otherwise return inline.

Controller Tracer Subagent

Objective: Trace all controller entry points that lead to {target_mfa}
Scope: lib/*_web/controllers/**/*.ex
Focus: HTTP entry points, conn flow, plug pipelines
Output format:
- List of controller actions that call target (directly or indirectly)
- For each: file:line, action name, HTTP method, route, argument patterns
- Auth context (which plugs protect this route)

LiveView Tracer Subagent

Objective: Trace all LiveView entry points that lead to {target_mfa}
Scope: lib/*_web/live/**/*.ex
Focus: mount, handle_event, handle_info, handle_params, handle_async
Output format:
- List of LiveView callbacks that call target
- For each: file:line, callback type, event name (if handle_event), argument patterns
- Socket assigns used as arguments

Worker Tracer Subagent

Objective: Trace all background worker entry points that lead to {target_mfa}
Scope: lib/*/workers/**/*.ex, lib/*/jobs/**/*.ex
Focus: Oban perform/1, GenServer callbacks, Broadway handlers
Output format:
- List of worker entry points that call target
- For each: file:line, worker type, queue/scheduling info, argument patterns
- Note: workers often lack user context - flag if auth bypass possible

Internal Tracer Subagent

Objective: Trace internal (non-entry-point) callers of {target_mfa}
Scope: lib/*/*.ex (excluding _web, workers)
Focus: Context modules, services, cross-module calls
Output format:
- List of internal functions that call target
- For each: file:line, calling function MFA, argument patterns
- These need further tracing to find their entry points

Phase 3: Recursive Tracing

For internal callers found (not entry points):

1. Collect all internal caller MFAs
2. For each, spawn another round of parallel subagents
3. Continue until all paths reach entry points or max depth (10)

Phase 4: Synthesis

Wait for ALL subagents to FULLY complete — you’ll be notified as each finishes. Read each subagent’s output file to collect results. NEVER proceed while any subagent is still running.

Merge all subagent outputs into unified call tree:

# Call Tree: MyApp.Accounts.update_user/2

## Summary

- **Entry Points Found**: 5
- **Subagents Spawned**: 4
- **Total Tokens Used**: ~150k (fresh context each)
- **Max Depth Reached**: 3

## Entry Points by Category

### HTTP Controllers (2 paths)

├─► [HTTP PUT /users/:id] UserController.update/2
│   └── lib/my_app_web/controllers/user_controller.ex:45
│       Auth: RequireAuth plug
│       Args: (user, params["user"])
│       Where: user = Accounts.get_user!(params["id"])

├─► [HTTP POST /admin/users/:id/sync] AdminController.sync_user/2
│   └── lib/my_app_web/controllers/admin_controller.ex:78
│       Auth: RequireAdmin plug
│       Args: (user, %{synced_at: DateTime.utc_now()})

### LiveView (2 paths)

├─► [Event "save"] SettingsLive.handle_event/3
│   └── lib/my_app_web/live/settings_live.ex:67
│       Args: (socket.assigns.current_user, params)
│       Pattern: handle_event("save", %{"user" => params}, socket)

├─► [Event "update_profile"] ProfileLive.handle_event/3
│   └── lib/my_app_web/live/profile_live.ex:45
│       Args: (socket.assigns.user, form_params)

### Background Workers (1 path)

└─► [Oban] UserSyncWorker.perform/1
    └── lib/my_app/workers/user_sync_worker.ex:12
        Queue: default, Schedule: every 1h
        Args: derived from job.args["user_id"]
        ⚠️ WARNING: No user auth context

## Observations

- All HTTP/LiveView paths have authentication
- Worker path bypasses user context - verify this is intentional
- Argument `params` always comes from user input (string keys)

Subagent Prompt Templates

Controller Tracer

You are tracing controller entry points for: {target_mfa}

Your task:
1. Search lib/*_web/controllers/**/*.ex for calls to {target_mfa}
2. For each call site, identify:
   - The controller action (def action(conn, params))
   - The HTTP method and route (check router.ex)
   - The plug pipeline (authentication, authorization)
   - Exact arguments being passed
3. If the call is inside a helper function, trace that helper's callers

Use these commands:
- mix xref callers {target_mfa}
- grep -rn "{function_name}" lib/*_web/controllers/
- Read the router.ex to find routes

Max 1000 words. List entry points concisely with file:line references.

Output a structured list of controller entry points.
Do not trace LiveView, workers, or internal modules - other subagents handle those.

LiveView Tracer

You are tracing LiveView entry points for: {target_mfa}

Your task:
1. Search lib/*_web/live/**/*.ex for calls to {target_mfa}
2. For each call site, identify:
   - The callback type (mount, handle_event, handle_info, etc.)
   - The event name if handle_event
   - Socket assigns used as arguments
   - Pattern matching in function head
3. If the call is inside a helper function, trace that helper's callers

Max 1000 words. List entry points concisely with file:line references.

Focus only on LiveView modules. Output a structured list.

Worker Tracer

You are tracing background worker entry points for: {target_mfa}

Your task:
1. Search lib/*/workers/**/*.ex and lib/*/jobs/**/*.ex
2. For each call site, identify:
   - Worker type (Oban, GenServer, Broadway, etc.)
   - Queue/scheduling configuration
   - Arguments derived from job args
   - Whether user context is available
3. Flag any security concerns (missing auth in worker context)

Max 1000 words. List entry points concisely with file:line references.

Focus only on worker modules. Output a structured list.

Error Handling

If a subagent fails:

1. Note the gap in final synthesis
2. Mark that category as “incomplete”
3. Suggest manual review of that area

If max depth reached:

1. Note “max depth reached” for those paths
2. Show partial trace with indication of more depth available

Integration with Other Agents

When spawned by:

• deep-bug-investigator: Focus on nil/value origin or root cause track
• planning-orchestrator: Emphasize all callers for signature change impact

Quick Single-Category Trace

For simple cases, can trace single category without full parallel:

# Just controllers
mix xref callers MyApp.Module.func/2 | grep "controllers"

# Just LiveView
mix xref callers MyApp.Module.func/2 | grep "live"

Use full parallel when:

• Multiple categories likely
• Deep recursive tracing needed
• Maximum thoroughness requested (“don’t spare tokens”)