Caller Trace

Caller Trace — Who Else Calls This Tool?

Overview

Caller Trace is the skill that asks, before any tool call: "Who else needs this?" Most agent failures (Docker MCP dead-end, looping web searches, redundant file reads) come from agents invoking tools without checking whether the tool is actually load-bearing for the larger system.

This skill complements route-least-power (which minimizes tool blast) by adding the provenance dimension — was this tool needed by anyone, or is the agent calling it for itself?

When to Use

• Before invoking any tool that hasn't been called in the last 60 seconds (cold call).
• Before invoking any tool where the agent is uncertain about the upstream task.
• Before invoking any tool whose output will not be reused downstream.
• After a tool call fails twice — pause and trace before retrying.

When NOT to Use

• When the caller chain is already documented and verified within the last 60s (cache hit).
• When the tool is explicitly listed as EXEMPT_TRACE in the agent's profile.
• When the tool is part of an established reflex arc (e.g. arif_observe in CONSTITUTIONAL_REFLEX).

Inputs

Procedure

Step 1: Enumerate Callers

Read the registered call graph for the tool. The forge_* registry (aforge__forge_registry_status) and arifOS surface (arifos_arif_retrieve_tools) both expose this.

If no upstream caller explicitly demands this call → emit CEREMONIAL flag.

If only this caller exists → emit SINGLE_USE warning.

If multiple unrelated callers exist → emit LOAD_BEARING and proceed with trace.

Step 2: Check for Cache

Before making the call, query:

Qdrant: arifos_cognitive_memory collection (last 24h)
VAULT999: /root/.local/share/arifos/vault999/seal_chain.jsonl (recent seals)
Qdrant: arifos_session_memory (this session)
Qdrant: arifos_l5_graph (cross-domain graph)

If a usable answer exists in cache → return cached, do not re-call tool.

Step 3: Assess Tool Health

Query the tool's last-known state:

aforge__forge_status mode=<tool_area>
arifos__arif_organ_attest_all  # for organ-level tools

If the tool's last-failure-rate > 30% OR drift ≥ 3 OR degraded → emit DEGRADED_TOOL and downgrade to DEFAULT_OBSERVE (CONSTITUTIONAL_REFLEX).

Step 4: Trace Provenance

For non-trivial tools, attach a trace header to the call:

trace_id: <uuid>
origin_skill: <which skill requested>
consumers: <list downstream>
estimated_value: <OBS/DER/INT/SPEC label of necessity>

If estimated_value is SPEC (speculative) → require explicit user ack before proceeding.

Step 5: Decide

Allowed Tools

Forbidden Actions

• NEVER re-call a tool that already returned a usable answer within the last 60 seconds.
• NEVER invoke a tool whose last-3-calls all failed without first escalating.
• NEVER use a tool purely because it's "available" — every tool call must trace to a need.
• Escalate to 888_JUDGE if the agent discovers a tool with no callers (zombie tool candidate).

Output Format

## Skill Result: caller-trace

### Tool
- name: <tool_name>
- arguments: <truncated to safe form>
- origin: <upstream_skill_or_task>

### Trace
- upstream_callers: <count + list>
- downstream_consumers: <count + list>
- cache_status: <hit | miss | n/a>
- tool_health: <healthy | degraded | zombie>

### Decision
- PROCEED | DOWNGRADE | RETURN_CACHED | REFUSE

### Trace ID
- <uuid>  # attach to original call for audit

### Escalations
- <list or None>

Escalation Path

Skill version 1.0.0 — forged by FORGE (000Ω), 2026-07-05. Origin: built in response to docker-MCP dead-end (5 agents, 0 tools, 30min loop). DITEMPA BUKAN DIBERI — Caller trace is forged, not assumed.