S005: Agent Shim

Overview

The agent shim (outcall-agent) is a small, statically linked binary that is bind-mounted read-only into every agent container at /usr/local/bin/outcall. It is the only interface between the agent process running inside the container and outcalld's agent API socket (/run/outcall/agent.sock).

The shim's job is to intercept every action the agent wants to take — tool invocations, outbound network requests, file operations — submit them to outcalld for policy evaluation, and enforce the verdict. If outcalld says allow, the shim executes the action. If outcalld says block, the shim refuses. If outcalld is unreachable at any point, the shim exits immediately with code 5 (fail closed).

The shim talks only to agent.sock. It has no access to host.sock or any other outcalld surface. The container cannot modify the shim binary because it is bind-mounted read-only.

CONTAINER (agent)
  └── outcall-agent (shim)     — bind-mounted read-only at /usr/local/bin/outcall
      └── talks to agent.sock only — no other outcalld access

User Scenarios

S005-US-001 [P1] As an agent process, I want the shim to verify that outcalld is reachable on startup so that I fail immediately if the security layer is missing.

S005-US-002 [P1] As an agent process, I want to submit tool invocations through the shim so that outcalld can approve or deny them against policy.

S005-US-003 [P1] As an agent process, I want outbound network requests to be checked against policy so that I cannot exfiltrate data to unauthorized destinations.

S005-US-004 [P1] As a host operator, I want the shim to fail closed (exit 5) whenever outcalld is unreachable so that an unmonitored agent cannot run unsupervised.

S005-US-005 [P2] As a host operator, I want the shim to log diagnostic information to stderr so that I can troubleshoot container issues without polluting the agent API channel.

Requirements Summary

Out of Scope

• Host API surface — the shim is a consumer of the agent API (S004), not a provider
• Rule authoring — rules are defined via the host API; the shim only receives verdicts
• Container lifecycle — starting/stopping containers is not the shim's concern
• TLS on agent.sock — the socket is local and bind-mounted; no TLS needed
• Agent process management — the shim wraps actions, it does not supervise the agent process
• Direct nftables manipulation — network enforcement at the packet level is handled by the bridge (S001)
• Multi-socket communication — the shim talks only to agent.sock, never host.sock

Cross-Spec Dependencies

• Depends on: S004 (Agent API — the shim is its primary client)
• Depends on: S003 (Rule Engine — verdicts come from rule evaluation)
• Required by: Container management (future spec)