S004: Agent API

Overview

The Agent API is the sole communication surface between AI agent containers and outcalld. It is served on a Unix domain socket (agent.sock) that is bind-mounted into each container. Through this socket, agents check in, request permission before executing tools or making network calls, submit rule requests for host operator approval, and query the status of those requests.

The Agent API enforces a strict trust boundary: containers see only verdicts and request acknowledgements. They never receive rule definitions, policy internals, host configuration, or any information about other containers. All rule evaluation happens host-side before any tool execution proceeds.

If the agent socket is unreachable, the outcall-agent shim exits with code 5 (fail closed). There is no fallback, no retry loop, and no degraded mode.

User Scenarios

S004-US-001 [P1] As an AI agent, I want to check in with outcalld so that I receive my container identity and policy context before doing any work.

S004-US-002 [P1] As an AI agent, I want to request permission before executing a tool so that outcalld can evaluate rules and return a verdict.

S004-US-003 [P1] As an AI agent, I want to request permission before making a network call so that outcalld can evaluate rules and return a verdict.

S004-US-004 [P2] As an AI agent, I want to submit a rule request so that a host operator can approve new capabilities for my container.

S004-US-005 [P2] As an AI agent, I want to query the status of a pending rule request so that I know whether to proceed or wait.

S004-US-006 [P1] As a host operator, I want the agent API to enforce a strict trust boundary so that agents cannot access host-side configuration or rule definitions.

Requirements Summary

Cross-Spec Dependencies

• Depends on: S001 (bridge must be up; agent socket listens on bridge IP)
• Depends on: S003 (rule evaluation happens host-side via the rule engine)
• Required by: S005, S008