Name context, tools, model, guardrail · Trace every step of an AI call

Stable names let two engineers read the same trace. Use these four, in this order, unless a hop did not run.

1Context pack

2Tool call

1Context pack

2Tool call

3Model

1Context pack

2Tool call

3Model

4Guardrail

Hop	What you time	What goes wrong
Context pack	Build instructions, attachments, and history for this request	A long transcript, a fat Dynamic Profile, or a late disk read
Tool call	Each tool the session invoked, including your code inside the tool	A slow fetch, a retry loop, or the wrong tool
Model	The Foundation Models inference itself	A long prompt, a profile switch that drops the KV cache, or a PCC round trip
Guardrail	Your check after the model, before the UI	A blocked reply, a retry, or a silent rewrite

enum AIHop: String, Sendable {
    case request = "ai.request"
    case contextPack = "ai.context_pack"
    case tool = "ai.tool"
    case model = "ai.model"
    case guardrail = "ai.guardrail"
}

func answer(_ question: String, session: LanguageModelSession) async throws -> String {
    // Same four names you will wrap with OSSignposter in lesson 04.
    let packed = packContext(question)          // ai.context_pack
    let reply = try await session.respond(to: packed) // ai.model (tools nest under this)
    return try applyGuardrail(reply)            // ai.guardrail
}

Context pack includes Dynamic Instructions and any historyTransform you run. Tool call includes Apple system tools and your tools. Model is the inference lane you will see in Instruments. Guardrail is yours. Apple does not ship your product policy.

Put the prompt version and the profile name on the request, not inside the hop name. Hop names stay short. Version prompts like product copy is where those versions live.

Rule. Same four hop names in every feature. Do not invent a new name per screen.

Next, see what Apple already draws for you.

Key concepts

The four hops in order are context pack, tool call, model, and guardrail.
Context pack includes instructions, attachments, history, and historyTransform.
Tool call includes Apple system tools and your tools.
Prompt version and profile name go on the request, not in hop names.

Takeaways

Use the same four hop names in every feature.
Put prompt version and profile name on request attributes.
Dynamic Instructions and history work belong in context pack.