S013: Agent-Name Rule Context

Overview

The rule engine's CEL evaluation context currently exposes docker.image but not the container name or agent identity. This prevents operators from writing rules that gate on which agent container made the request — for example, "allow foo-1 to reach port 5432 but block bar-3."

This spec adds agent.name to the CEL evaluation context by resolving the caller's PID to a container IP using SO_PEERCRED, then looking up the container name via container_name_for_ip (already implemented in DockerManager).

Background

The agent naming convention strips the trailing -N from container names:

• Container foobar-1 → agent name foobar
• Container foobar-2 → agent name foobar
• Container my-agent-12 → agent name my-agent

The SO_PEERCRED socket option provides the caller's PID. The existing DockerManager::lookup_container_name_by_ip resolves an IP to container name.

User Scenarios

S013-US-001 [P1] As a host operator, I want to write rules that allow specific agents by name so that I can enforce per-agent access policies.

S013-US-002 [P1] As a host operator, I want agent.name exposed in the CEL context so that existing rule authors can use it immediately.

S013-US-003 [P2] As a host operator, I want to debug which agent made a request by inspecting the agent.name field in evaluation logs.

Requirements Summary

Implementation note (2026-05-10, release prep): S013 was originally drafted around the agent_api shim's SO_PEERCRED path. During v0.1 release prep the proxy/HTTPS path was identified as a parallel enrichment site and now resolves agent.name via TCP peer-IP → DockerManager::lookup_container_name_by_ip (filters on managed-by=outcalld). Both paths converge on the same derive_agent_name helper. FR-003 strict SO_PEERCRED in the agent_api path remains tracked in issue #4 — it does not block v0.1 because real apt/curl/HTTPS traffic transits the proxy path.

Cross-Spec Dependencies

• Depends on: S003 (CEL context structure, evaluation path)
• Depends on: S008 (lookup_container_name_by_ip exists)
• Required by: Operator rules that need per-agent gating (no downstream specs currently reference this)

Shared Types (outcall-api)

/// Agent identity resolved from SO_PEERCRED + container lookup.
/// None when resolution fails (non-Unix socket, container not found).
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct AgentContext {
    pub name: String,  // e.g. "foobar" from "foobar-1"
}

/// Full CEL evaluation context (S003, extended with agent).
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct EvalContext {
    pub network: Option<NetworkContext>,
    pub http: Option<HttpContext>,
    pub dns: Option<DnsContext>,
    pub docker: Option<DockerContext>,
    pub run: Option<RunContext>,
    pub agent: Option<AgentContext>,  // S013-FR-002
}

CEL Usage

Once implemented, operators can write:

rules:
  - id: "allow-foobar-db"
    condition: |
      agent.name == "foobar" &&
      network.port == 5432
    action: allow

  - id: "block-bar-agents-ssh"
    condition: agent.name == "bar" && network.port == 22
    action: block