Prime Agent Trust Model for Programmatic IPython Tool Execution

Prime Agent's trust model treats the persistent IPython kernel as a trusted execution environment while isolating all external inputs as untrusted, with strict envelope validation and credential isolation.

The Prime Agent open-source agent framework implements a multi-layered trust model for programmatic IPython tool execution through its RLM (Runtime Language Model) programming model. This design enables powerful code execution capabilities while maintaining security boundaries between trusted kernel operations and untrusted external data. Understanding this trust model is essential for developers building secure AI agents that execute arbitrary code.

Kernel-Level Trust: The Persistent IPython Environment

Prime Agent launches an IPython kernel once per session that remains alive across conversation turns. This kernel constitutes a trusted execution environment owned entirely by the Prime Agent process.

All code executing inside the kernel—including Python cells, imported skills, and persistent variables—runs within this controlled process. Critical security property: the kernel's state is never serialized or transmitted over the network, preventing untrusted data from persisting in the execution environment.

The trust establishment occurs in packages/coding-agent/src/modes/interactive/interactive-mode.ts, where the session explicitly "trusts the live connection" to the kernel:

// From interactive-mode.ts#L1693
// The session marks the kernel connection as trusted for the duration
// of the agent's lifecycle. No external process can inject state.

This architectural choice means that once the kernel is established, operations within it maintain trust continuity without requiring re-validation on every tool call.

Tool-Call Envelope Validation

When the language model invokes Python execution, it does so through the built-in IPython tool. This tool call follows a strict envelope pattern that separates trusted kernel output from untrusted input vectors.

The ACP (Agent-Controlled-Protocol) layer enforces schema validation on tool outputs. Only fields defined by the tool schema—text output, images, and rich display data—are accepted; any additional payload is discarded. This prevents arbitrary data injection into the kernel environment.

The validation logic appears in packages/coding-agent/src/modes/rpc/rpc-client.ts#L666:

// From rpc-client.ts#L666
// After the command executes, the response is cast to the expected
// tool output shape. Malformed responses are rejected at this boundary.

This schema-enforced validation effectively "trusts" only well-formed tool outputs that conform to the expected contract.

Untrusted External Input Handling

Prime Agent applies a default-deny posture to all data originating outside the kernel. Raw shell commands, network replies, and user-provided code are treated as untrusted and require explicit markers or authorization.

Shell Execution Requires Explicit Markers

Shell commands must use the %%bash magic marker, enforced by the framework:

await tool.execute({
  title: "IPython cell",
  source: "%%bash\nls -l /tmp",
});
// The kernel parser validates the %%bash marker before shell execution.
// Commands without this marker are rejected for shell operations.

Dependency Installation Requires User Authorization

The system refuses to install Python packages into the kernel without explicit user authorization, preventing supply-chain attacks through dependency injection.

Socket Peer Filtering

In packages/coding-agent/src/modes/daemon/daemon-protocol.ts#L184, incoming messages from socket peers are re-filtered because the peer is explicitly not trusted:

// From daemon-protocol.ts#L184
// Messages from the socket peer are untrusted and must be
// re-validated before entering the trusted kernel boundary.

Credential Isolation and Ephemeral Injection

Credentials never persist in the IPython environment. API keys, OAuth tokens, and other secrets follow a strict fetch-and-inject pattern:

1. Credentials are retrieved from secure storage (env-api-keys.ts)
2. They are substituted only for the duration of the specific call
3. The kernel never holds or "trusts" a persisted secret

This policy is enforced in packages/coding-agent/src/core/mcp/mcp-manager.ts#L135, where the comment explicitly states that auth.json entries are not trusted for kernel use:

// From mcp-manager.ts#L135
// Auth credentials from auth.json are fetched per-use and never
// trusted as kernel-local state. Each injection is ephemeral.

State Restoration with Process Verification

When sessions resume, the kernel may restore previous state. However, Prime Agent implements verifiable state restoration through a trusted marker protocol.

The restoration message is always prefixed with ◆ Restored IPython kernel state, enabling the model to confirm that the kernel is the same trusted process it originally created. This marker prevents session hijacking or substitution attacks.

Tests in packages/coding-agent/test/suite/regressions/4530-ipython-state-restore-message.test.ts#L115-L122 assert this security property:

// State restoration verification pattern
if (output.startsWith("◆ Restored IPython kernel state")) {
  // Trust the restored state: signature matches original kernel
  proceedWithTrustedSession();
} else {
  // Potential substitution attack: reject restoration
  throw new SecurityError("Untrusted kernel state");
}

Trust Model Implementation Files

Component	File Path	Security Function
Kernel trust establishment	packages/coding-agent/src/modes/interactive/interactive-mode.ts#L1693	Marks live kernel connection as trusted
Tool output validation	packages/coding-agent/src/modes/rpc/rpc-client.ts#L666	Schema-enforced envelope validation
Untrusted peer filtering	packages/coding-agent/src/modes/daemon/daemon-protocol.ts#L184	Re-filters socket messages
Credential isolation	packages/coding-agent/src/core/mcp/mcp-manager.ts#L135	Ephemeral credential injection
State restore verification	packages/coding-agent/test/suite/regressions/4530-ipython-state-restore-message.test.ts#L115-L122	Tests trusted restore marker
RLM design documentation	packages/coding-agent/docs/rlm.md	Authoritative trust model specification

Summary

Prime Agent's trust model for programmatic IPython tool execution implements defense in depth through five key mechanisms:

• Kernel-level trust: Single persistent process with no network serialization of state
• Schema-enforced tool envelopes: ACP validation rejects malformed outputs
• Untrusted input isolation: Default-deny posture for external data with explicit markers required
• Credential ephemerality: Secrets injected per-call, never persisted in kernel
• Verifiable state restoration: Cryptographic-style marker confirms process identity across sessions

This architecture enables powerful, stateful code execution while maintaining strict boundaries between trusted kernel operations and untrusted external inputs.

Frequently Asked Questions

How does Prime Agent prevent malicious code injection through tool outputs?

Prime Agent's ACP layer validates tool outputs against strict schemas in rpc-client.ts#L666. Only fields defined by the IPython tool schema—text, images, and display data—are accepted. Additional or malformed payload fields are discarded, preventing injection attacks through oversized or malicious tool responses.

Can the IPython kernel be compromised by network-based attacks?

No. The kernel never receives serialized state over the network. It is launched locally by Prime Agent and maintains trust through its process identity. The session "trusts the live connection" as noted in interactive-mode.ts#L1693, meaning network intermediaries cannot influence kernel state without breaking the local process boundary.

What happens if user-provided code attempts to access shell or install packages?

Untrusted user code receives default-deny enforcement. Shell commands require the explicit %%bash marker, which the kernel parser validates. Package installation requires explicit user authorization through the framework's permission system. These constraints are implemented in the kernel's cell processing pipeline before execution occurs.

How does state restoration maintain security across session resumptions?

Restored states carry a verifiable marker (◆ Restored IPython kernel state) that confirms the kernel's process identity. Tests in 4530-ipython-state-restore-message.test.ts enforce this marker's presence. Without this marker, the framework treats the restored state as potentially substituted and rejects the session continuation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}