S005: Agent Shim

Overview

outcall-agent is an opt-in command mediation shim for managed containers. When helper mounts are enabled, outcalld bind-mounts the binary read-only at /usr/local/bin/outcall and exposes only the agent API socket at /run/outcall/agent.sock.

The shim mediates commands explicitly invoked through it:

outcall exec git status
outcall bash make test
outcall git status

It is not transparent syscall interception and it does not wrap an arbitrary agent process automatically. fetch and file forms perform policy checks but do not execute network or file operations. Actual recipe egress is enforced by the managed bridge, DNS service, HTTP proxy, and nftables policy described in S015. Files already mounted into a container are container-visible files; undeclared host resources remain absent.

The built-in Claude and Codex recipes currently disable helper mounts because their primary boundary is the hardened container and enforced network path. They can still use the separately tokenized, rule-gated host resource broker.

For an explicit invocation, the shim checks in, receives a session token, requests a verdict, executes an allowed command, and maintains a heartbeat while the child runs. The daemon derives container identity from Unix peer credentials; the shim does not submit a caller-controlled hostname or PID. Daemon loss kills the active child and exits with code 5.

Requirements Summary

Out of Scope

• Transparent syscall, shell, file, or network interception
• Network packet enforcement, which belongs to S006, S007, and S015
• Host API access, rule authoring, or container lifecycle management
• Supervising commands that were not explicitly launched through the shim

Cross-Spec Dependencies

• Depends on: S004 for check-in and verdicts
• Depends on: S003 for policy evaluation
• Complements: S015, the mandatory outer boundary