This design document describes integrating external CLI tools (like Claude CLI, Codex CLI) as a new Provider type in pi. The goal is to create an abstraction layer that takes streaming JSON output from external CLIs and converts it into pi's native AssistantMessageEvent format.

This document describes the workflow for an orchestrator agent to break down a large task into sub-tasks, delegate to worker agents, and coordinate the work to completion.

┌─────────────────────────────────────────────────────────────────┐
│                     Orchestrator Agent                          │
│                                                                 │

This pattern uses iptables to redirect outbound HTTP/HTTPS traffic through a transparent MITM proxy such as kcosr/acl-proxy (WIP prototype), allowing you to filter requests by URL, inspect content, log traffic, enforce allow/deny lists, or even inject credentials you don't want to deploy in the container.

Note: This approach can be used without containers if you trust that all commands invoked by the agent CLI will respect HTTP_PROXY environment variables.

1. Container starts with temporary sudo access to iptables
2. Entrypoint script configures iptables to redirect traffic to the proxy

This pattern allows a non-root container user to run utilities that use file-based credentials (e.g., gh, git) while limiting direct access to those credentials files. Credentials are mounted into root's home read by utilities run using sudo.

If a priviledged utility can be instructed to read arbitrary files or dump credentials, no security is provided beyond obfuscation. This pattern can be useful to prevent accidental reads or low-complexity exploits but will not block access. A proxy-based approach, combined with credentials injection in the request, is better.

gh auth token