The Local Control Model: Prompt, Policy, Effect, and Record

Pi's request loop, provider boundary, and extension surface become easier to judge when they are treated as one local control model. The model separates five things that are easy to blur together: what the user intends, what the agent sends as context, what capabilities are available, what effect actually runs, and what the system records afterward. That separation lets you locate a change or a failure without calling every part of Pi “the agent.”

The distinction is useful for a simple repository task: “find the failing test and patch it.” The request begins as intent. It becomes a sequence of model-facing messages. The model proposes a read or edit capability. A tool gate and implementation decide whether an effect occurs. The result returns to context, and a session records the path. At each step, a different part of Pi owns the decision. The question is not which layer is most important in the abstract; it is which layer is allowed to change which part of the chain.

One coding request crosses five ownership boundaries

Intent is the user's goal and constraints. Pi does not manufacture that goal, although prompt templates, input handlers, or extensions may transform how it is expressed. Context is the information made available to the next provider request: the system prompt, selected messages, tool descriptions, and any application-specific material that survives projection. The agent core maintains a richer message state and converts it at the provider boundary.

Capability is what the model is permitted to request in the current turn. A tool definition gives a name, description, and parameter schema. The active tool set and its prompt guidance shape what the model can see. An extension may add a tool or turn one on dynamically. A hook may inspect the proposed call and block it. Capability is therefore more than a model's general ability; it is the intersection of the model's request, the active registry, and the policies surrounding execution.

Effect is the work performed outside the model's text generation: reading a file, running a command, or applying an edit. The tool implementation owns how the validated arguments are interpreted. The agent core orders and observes that work, but it does not infer the semantics of every custom tool. A remote-operation adapter can move the effect to another machine while preserving the tool-facing contract. The host still owns the environment in which the effect has consequences.

Record is what remains after the live operation has emitted its events and results. The session layer can retain messages, tool results, model changes, extension state, and the relationship among entries. A record is not the same thing as live execution: it can describe an attempted, blocked, failed, or completed step. That distinction becomes critical when a process stops while an effect is in flight, but it is already present in the ordinary loop.

stateDiagram-v2 [*] --> Intent Intent --> ContextProjection ContextProjection --> ProviderRequest ProviderRequest --> AssistantResponse ProviderRequest --> AbortOrError: provider failure or abort AssistantResponse --> ToolGate: tool call AssistantResponse --> Result: text-only response ToolGate --> ExternalEffect: allowed and validated ToolGate --> Result: blocked or invalid ToolGate --> AbortOrError: cancelled before execution ExternalEffect --> Result: success or tool error result Result --> ContextProjection: another turn needed Result --> SettledRecord: no more work AbortOrError --> SettledRecord SettledRecord --> [*]

The sequence is not a claim that every turn has exactly one tool or that every result is successful. It is a map of ownership. The core loop mediates context and transitions.