Fix subprocess proxy guidance

Author: bglusman

README.md

@@ -65,8 +65,8 @@ again after editing config or moving services. It
 validates config, checks referenced secret files without printing
 values, flags stale active-agent/model state, detects suspicious
 self-routing into the local model gateway, warns if the Calciforge
-service itself has ambient proxy env, checks whether subprocess agents
-define explicit proxy env, warns about externally managed agent daemons
+service itself has ambient proxy env, flags subprocess agents that explicitly
+set proxy env, warns about externally managed agent daemons
 whose outbound proxy environment cannot be proven,
 validates configured scanner policy files and rule syntax, and can probe
 configured agent endpoints. Use `--no-network` for a purely local check.
@@ -75,12 +75,18 @@ Channel-based secret input is intentionally being de-emphasized because
 chat transports can retain plaintext values. Prefer the local paste UI
 or direct `fnox` input for new secrets.
 
-Calciforge-managed subprocess agents should get proxy environment from their
-agent config or installer-generated config. Do not put proxy variables on the
-Calciforge daemon itself; that can route Calciforge's own provider and
-control-plane traffic through its security proxy. For externally managed agent
-daemons that Calciforge does not launch, set plain HTTP proxying on the agent
-process or its service manager and validate it against `security-proxy` logs:
+Do not put proxy variables on the Calciforge daemon itself; that can route
+Calciforge's own provider and control-plane traffic through its security proxy.
+Do not assume CLI agents can be wrapped by setting `HTTP_PROXY` or
+`HTTPS_PROXY`; Codex, Claude, ACPX, npm-backed adapters, and streaming clients
+may use CONNECT, WebSockets, or browser-backed auth flows that the current
+proxy cannot inspect and may break. Use OpenAI-compatible gateway routes,
+explicit fetch/tool integrations, or tested wrappers for traffic that must pass
+through `security-proxy`.
+
+For externally managed agent daemons that Calciforge does not launch, proxying
+has to be configured on that daemon or its service manager and validated
+against `security-proxy` logs:
 
 ```bash
 export HTTP_PROXY=http://127.0.0.1:8888
@@ -107,7 +113,6 @@ id = "codex"
 kind = "codex-cli"
 model = "gpt-5.5"
 timeout_ms = 600000
-env = { HTTP_PROXY = "http://127.0.0.1:8888", NO_PROXY = "localhost,127.0.0.1,::1" }
 
 [[routing]]
 identity = "owner"

crates/calciforge/examples/config.toml

@@ -83,7 +83,6 @@ args = [
     "--skip-git-repo-check",
     "-"
 ]
-env = { HTTP_PROXY = "http://127.0.0.1:8888", NO_PROXY = "localhost,127.0.0.1,::1" }
 timeout_ms = 600000
 
 [agents.registry]
@@ -99,7 +98,6 @@ id = "dirac"
 kind = "dirac-cli"
 command = "dirac"
 args = ["--yolo", "--json"]
-env = { HTTP_PROXY = "http://127.0.0.1:8888", NO_PROXY = "localhost,127.0.0.1,::1" }
 timeout_ms = 600000
 
 [agents.registry]

crates/calciforge/src/doctor.rs

@@ -383,23 +383,23 @@ fn check_proxy_environment_in(env: ProxyEnvironment, report: &mut DoctorReport)
         (Some(http), Some(https)) => {
             if http == https {
                 report.warn(format!(
-                    "Current calciforge doctor process has ambient HTTP(S)_PROXY configured ({}); if the service runs with the same env, model-provider and control-plane traffic can route through security-proxy. Prefer explicit proxy env on agent subprocesses instead.",
+                    "Current calciforge doctor process has ambient HTTP(S)_PROXY configured ({}); if the service runs with the same env, model-provider, channel, and control-plane traffic can route through security-proxy. Prefer no ambient proxy on the Calciforge service.",
                     display_proxy_value(http)
                 ));
             } else {
                 report.warn(format!(
-                    "Current calciforge doctor process has ambient HTTP_PROXY and HTTPS_PROXY configured but they differ; HTTP_PROXY={}, HTTPS_PROXY={}. Prefer no ambient proxy on the Calciforge service and explicit proxy env on agent subprocesses.",
+                    "Current calciforge doctor process has ambient HTTP_PROXY and HTTPS_PROXY configured but they differ; HTTP_PROXY={}, HTTPS_PROXY={}. Prefer no ambient proxy on the Calciforge service.",
                     display_proxy_value(http),
                     display_proxy_value(https)
                 ));
             }
         }
         (Some(http), None) => report.warn(format!(
-            "Current calciforge doctor process has ambient HTTP_PROXY set ({}). Prefer no ambient proxy on the Calciforge service and explicit proxy env on agent subprocesses.",
+            "Current calciforge doctor process has ambient HTTP_PROXY set ({}). Prefer no ambient proxy on the Calciforge service.",
             display_proxy_value(http)
         )),
         (None, Some(https)) => report.warn(format!(
-            "Current calciforge doctor process has ambient HTTPS_PROXY set ({}) but HTTP_PROXY is not set. Prefer no ambient proxy on the Calciforge service and explicit proxy env on agent subprocesses.",
+            "Current calciforge doctor process has ambient HTTPS_PROXY set ({}) but HTTP_PROXY is not set. Prefer no ambient proxy on the Calciforge service.",
             display_proxy_value(https)
         )),
         (None, None) => report.ok(
@@ -455,7 +455,7 @@ fn check_agent_proxy_coverage(
 
         if has_http_proxy(env) {
             report.warn(
-                "Current calciforge doctor process has ambient HTTP_PROXY; subprocess inheritance works if the service has the same env, but it also risks proxying Calciforge's own provider/control-plane calls. Move proxy env to agent-level config or wrappers.",
+                "Current calciforge doctor process has ambient HTTP_PROXY; subprocess inheritance works only if the service has the same env, and it can break CLI agents that use CONNECT, WebSockets, npm, or browser-backed auth. Prefer no ambient proxy and only wrap agents through tested recipes.",
             );
         }
 
@@ -467,28 +467,28 @@ fn check_agent_proxy_coverage(
 
         if incomplete_count > 0 {
             report.warn(format!(
-                "{incomplete_count} subprocess agent(s) define incomplete proxy env; set HTTP_PROXY to the intended security-proxy endpoint or clear proxy env keys"
+                "{incomplete_count} subprocess agent(s) define partial proxy env; either remove proxy env or use a tested wrapper that the agent supports"
             ));
         }
 
-        if complete_count == subprocess_count && clearing_count == 0 && incomplete_count == 0 {
+        if complete_count > 0 {
+            report.warn(format!(
+                "{complete_count} subprocess agent(s) define explicit HTTP_PROXY env; verify the specific CLI supports that proxy path. HTTPS_PROXY/CONNECT traffic is not inspected by security-proxy and may break streaming agents."
+            ));
+        }
+
+        let missing_count = subprocess_agents
+            .iter()
+            .filter(|agent| {
+                !has_complete_agent_proxy_env(agent)
+                    && !has_incomplete_agent_proxy_env(agent)
+                    && !clears_agent_proxy_env(agent)
+            })
+            .count();
+        if missing_count > 0 {
             report.ok(format!(
-                "{subprocess_count} subprocess agent(s) define explicit HTTP_PROXY env; verify these point at security-proxy and include NO_PROXY for loopback"
+                "{missing_count} subprocess agent(s) have no explicit proxy env; use explicit tool/fetch integration or a tested wrapper for traffic that must pass through security-proxy"
             ));
-        } else {
-            let missing_count = subprocess_agents
-                .iter()
-                .filter(|agent| {
-                    !has_complete_agent_proxy_env(agent)
-                        && !has_incomplete_agent_proxy_env(agent)
-                        && !clears_agent_proxy_env(agent)
-                })
-                .count();
-            if missing_count > 0 {
-                report.warn(format!(
-                    "{missing_count} subprocess agent(s) lack explicit HTTP_PROXY env; Calciforge no longer supplies ambient proxy env"
-                ));
-            }
         }
     }
 
@@ -1428,7 +1428,7 @@ mod tests {
     }
 
     #[test]
-    fn subprocess_agent_proxy_coverage_warns_without_complete_proxy_env() {
+    fn subprocess_agent_proxy_coverage_accepts_missing_proxy_env() {
         let mut config = base_config();
         config.agents = vec![AgentConfig {
             id: "codex".to_string(),
@@ -1448,13 +1448,13 @@ mod tests {
         );
 
         assert!(report.findings.iter().any(|finding| {
-            finding.severity == Severity::Warn
-                && finding.message.contains("lack explicit HTTP_PROXY env")
+            finding.severity == Severity::Ok
+                && finding.message.contains("have no explicit proxy env")
         }));
     }
 
     #[test]
-    fn subprocess_agent_proxy_coverage_accepts_complete_agent_proxy_env() {
+    fn subprocess_agent_proxy_coverage_warns_on_complete_agent_proxy_env() {
         let mut config = base_config();
         config.agents = vec![AgentConfig {
             id: "dirac".to_string(),
@@ -1484,7 +1484,7 @@ mod tests {
         );
 
         assert!(report.findings.iter().any(|finding| {
-            finding.severity == Severity::Ok
+            finding.severity == Severity::Warn
                 && finding.message.contains("define explicit HTTP_PROXY env")
         }));
     }
@@ -1515,7 +1515,7 @@ mod tests {
 
         assert!(report.findings.iter().any(|finding| {
             finding.severity == Severity::Warn
-                && finding.message.contains("define incomplete proxy env")
+                && finding.message.contains("define partial proxy env")
         }));
     }
 

docs/MANUAL_INSTALL.md

@@ -104,9 +104,16 @@ systemctl enable adversary-detector security-gateway clashd
 systemctl start adversary-detector security-gateway clashd
 ```
 
-## Step 5: Set up proxy env vars
+## Step 5: Configure optional external-agent proxy env
+
+Do not set `HTTP_PROXY` or `HTTPS_PROXY` globally for Calciforge itself. The
+Calciforge service should call providers, channels, and control-plane endpoints
+directly unless a stronger host/container boundary is configured.
+
+For an external agent daemon that you have tested with `security-proxy`, set
+proxy environment in that daemon's service manager instead of in
+`/etc/profile.d`. For example:
 
-Create `/etc/profile.d/calciforge-proxy.sh`:
 ```bash
 export HTTP_PROXY=http://127.0.0.1:8080
 export NO_PROXY=localhost,127.0.0.1,10.*.*.*,172.16.*.*,192.168.*.*
@@ -115,11 +122,8 @@ export NO_PROXY=localhost,127.0.0.1,10.*.*.*,172.16.*.*,192.168.*.*
 `HTTPS_PROXY` is intentionally omitted from the basic setup because standard
 HTTPS proxying uses CONNECT tunnels that Calciforge cannot inspect without a
 separate MITM design. Use explicit Calciforge fetch/tool integration for HTTPS
-content that must be scanned or rewritten.
-
-```bash
-chmod +x /etc/profile.d/calciforge-proxy.sh
-```
+content that must be scanned or rewritten, or run the agent inside a controlled
+container/VM profile that forces egress through Calciforge services.
 
 ## Step 6: Set API credentials
 

docs/agent-adapters.md

@@ -52,8 +52,9 @@ parsing or safety behavior.
 
 Use a recipe when an upstream tool is useful but its protocol is still just a
 documented command invocation. Recipes can still be security-aware: Calciforge
-owns identity checks, routing, proxy environment, per-run artifact directories,
-timeouts, output validation, and audit logs.
+owns identity checks, routing, per-run artifact directories, timeouts, output
+validation, audit logs, and tested network wrappers where the upstream runtime
+supports them.
 
 Use a named adapter when Calciforge needs upstream-specific parsing or safety
 defaults that cannot be expressed cleanly as a recipe. Dirac is the current
@@ -95,7 +96,6 @@ args = [
   "{message}",
 ]
 timeout_ms = 120000
-env = { HTTP_PROXY = "http://127.0.0.1:8888", NO_PROXY = "localhost,127.0.0.1,::1" }
 ```
 
 The command above must read the actual task from stdin. `{message}` is a safe
@@ -113,7 +113,6 @@ args = [
   "{artifact_dir}/image.png",
 ]
 timeout_ms = 180000
-env = { HTTP_PROXY = "http://127.0.0.1:8888", NO_PROXY = "localhost,127.0.0.1,::1" }
 ```
 
 Treat this npcsh command as a recipe to verify against the installed npcsh

docs/codex-openclaw-integration.md

@@ -30,7 +30,6 @@ id = "codex"
 kind = "codex-cli"
 model = "gpt-5.5"
 timeout_ms = 600000
-env = { HTTP_PROXY = "http://127.0.0.1:8888", NO_PROXY = "localhost,127.0.0.1,::1" }
 aliases = ["gpt", "openai"]
 
 [[routing]]
@@ -66,13 +65,14 @@ args = [
   "--skip-git-repo-check",
   "-",
 ]
-env = { HTTP_PROXY = "http://127.0.0.1:8888", NO_PROXY = "localhost,127.0.0.1,::1" }
 ```
 
-Do not assume ambient `HTTPS_PROXY` gives Calciforge visibility into encrypted
-model traffic. HTTPS clients normally use CONNECT tunnels; use explicit
-fetch/tool integration when encrypted content needs scanning or secret
-substitution.
+Do not wrap Codex CLI with generic `HTTP_PROXY`/`HTTPS_PROXY` unless you have
+validated that specific route. Codex uses streaming and browser/OAuth-backed
+control-plane calls; the current `security-proxy` does not inspect CONNECT
+tunnels and can break those flows. Use Calciforge's OpenAI-compatible gateway,
+exec models, or explicit fetch/tool integration for traffic that needs
+scanning or secret substitution.
 
 Keep chat-facing Codex agents conservative. `read-only` is the safer
 default for general messaging channels. Use `workspace-write` only for

docs/index.md

@@ -205,6 +205,10 @@ tool permissions can be checked before traffic leaves the machine.
 Ambient `HTTPS_PROXY` is deliberately not presented as full protection:
 standard HTTPS proxying uses CONNECT tunnels, so encrypted request bodies
 cannot be inspected or rewritten without a separate MITM design.
+For agents that do not work with cooperative proxy env, Calciforge's
+security boundary shifts to model-gateway routing, explicit MCP/fetch tools,
+audited recipe wrappers, or future container/VM isolation profiles that deny
+egress except through Calciforge services.
 
 The gateway protects in three places:
 
@@ -507,9 +511,9 @@ correctly, for first-class adapter support. The working vocabulary is:
 
 - **Recipes** — documented, security-aware command configurations for
   local tools such as npcsh, opencode profiles, or one-off media agents.
-  Recipes can still use Calciforge identity checks, per-agent proxy
-  environment, timeouts, stdin prompt delivery, stderr redaction, audit
-  logs, and controlled artifact directories.
+  Recipes can still use Calciforge identity checks, timeouts, stdin prompt
+  delivery, stderr redaction, audit logs, controlled artifact directories,
+  and tested proxy wrappers where the upstream runtime supports them.
 - **Adapters** — first-class protocol integrations used when Calciforge
   must understand upstream-specific behavior, such as event streams,
   final-answer parsing, approval pauses, callbacks, or native session
@@ -542,7 +546,6 @@ kind = "artifact-cli"
 command = "/usr/local/bin/npcsh-vixynt-stdin"
 args = ["{artifact_dir}/image.png"]
 timeout_ms = 180000
-env = { HTTP_PROXY = "http://127.0.0.1:8888", NO_PROXY = "localhost,127.0.0.1,::1" }
 ```
 
 The command above is a recipe shape, not a promise that every npcsh
@@ -682,14 +685,16 @@ unverified, validates configured scanner policy files and rule syntax,
 and can probe configured endpoints.
 Use `calciforge doctor --no-network` when you want a local-only check.
 
-Calciforge-managed subprocess agents should get proxy environment from their
-agent config or installer-generated config. Do not put proxy variables in
-`~/.zshrc` for the Calciforge daemon itself; that can route Calciforge's own
-provider and control-plane traffic through its security proxy.
+Do not put proxy variables in `~/.zshrc` for the Calciforge daemon itself;
+that can route Calciforge's own provider and control-plane traffic through
+its security proxy. Do not assume CLI agents can be protected by generic
+`HTTP_PROXY` or `HTTPS_PROXY`; Codex, Claude, ACPX, npm-backed adapters, and
+streaming clients may use CONNECT, WebSockets, or browser-backed auth flows
+that the current proxy cannot inspect and may break.
 
-For externally managed agent daemons that Calciforge does not launch, set
-plain HTTP proxying on the agent process or its service manager and validate
-it against `security-proxy` logs:
+For externally managed agent daemons that Calciforge does not launch, configure
+a tested proxy path on the agent process or its service manager and validate it
+against `security-proxy` logs:
 
 ```bash
 # External agent process environment

docs/roadmap/placeholder-injection-mode.md

@@ -78,7 +78,7 @@ through PlaceholderMap before forwarding. Same code path as
 |---|---|---|
 | Agent never sees real secret | ✅ | ✅ |
 | Works without agent's awareness of Calciforge | ✅ | ✅ |
-| Kernel-enforced (agent can't bypass) | ✅ | ❌ (agent can unset HTTPS_PROXY, but then can't call out) |
+| Kernel-enforced (agent can't bypass) | ✅ | ❌ (agent can bypass cooperative proxy env unless paired with host/container egress controls) |
 | Linux only | yes | no — cross-platform |
 | Requires root | yes (CAP_BPF) | no |
 | Requires recent kernel | yes (5.x+) | no |
@@ -94,11 +94,9 @@ through PlaceholderMap before forwarding. Same code path as
 - Agent uploads its own env var to an untrusted endpoint → placeholder
 
 **Things only true eBPF catches:**
-- Agent intentionally bypasses HTTPS_PROXY env to talk directly →
-  placeholder is useless (no upstream knows what it means), but the
-  agent can't make ANY call. So the failure mode is "agent fails
-  loudly" rather than "agent leaks secret". Acceptable for our threat
-  model where the agent is mostly-trusted.
+- Agent intentionally bypasses cooperative proxy env to talk directly →
+  placeholder is useless because no upstream knows what it means. Pair this
+  mode with host/container egress controls when bypass resistance matters.
 
 **Things neither catches:**
 - Agent intentionally exfiltrates the placeholder + asks Calciforge