Clarify workflow auth and network requirements

README.md

@@ -104,6 +104,21 @@ as `WORKFLOW.md`, then change these fields before starting Symphony:
 
 If you want the dashboard, keep `server.port` in the workflow or pass `--port` on the CLI.
 
+If your agent workflow needs access to environment variables from the launching shell, configure
+Codex to inherit them in `codex.command`, for example:
+
+```yaml
+codex:
+  command: codex --config shell_environment_policy.inherit=all app-server
+```
+
+If your agent must push branches, open PRs, or call external APIs during a turn, also configure a
+turn sandbox policy that explicitly allows network access instead of relying on a minimal
+`workspaceWrite` sandbox object.
+
+If a specific external CLI still does not see the credentials it needs in your environment, provide
+that tool's credential via environment variables before launching Symphony.
+
 For a complete reference covering every supported field with defaults and inline documentation, see
 [docs/WORKFLOW.template.md](docs/WORKFLOW.template.md).
 

docs/DEV_GUIDE.md

@@ -186,7 +186,7 @@ issue to "In Review" and leave a comment summarizing what you did.
 | `agent.max_retry_backoff_ms` | Max retry back-off delay in ms (exponential cap) | `300000` |
 | `agent.max_concurrent_agents_by_state` | Per-state concurrency overrides (map of state → limit) | `{}` |
 | `codex.command` | Shell command to launch Codex | `codex app-server` |
-| `codex.approval_policy` | Codex approval policy: `never` / `on-failure` / `always` | Inherits Codex default |
+| `codex.approval_policy` | Codex approval policy, passed through to the installed Codex schema | Inherits Codex default |
 | `codex.thread_sandbox` | Thread-level sandbox mode (e.g. `workspace-write`) | `null` |
 | `codex.turn_sandbox_policy` | Per-turn sandbox policy object | `null` |
 | `codex.turn_timeout_ms` | Max wall-clock time in ms for a full agent turn | `3600000` |
@@ -215,6 +215,43 @@ node dist/src/cli/main.js --acknowledge-high-trust-preview --port 3000
 
 > `--acknowledge-high-trust-preview` is a required safety flag. Symphony runs agent code without sandboxing by default; this flag confirms you understand that.
 
+### Environment and networked CLI note
+
+If your workflow depends on environment variables from the launching shell, launch Codex with
+shell environment inheritance enabled:
+
+```yaml
+codex:
+  command: codex --config shell_environment_policy.inherit=all app-server
+```
+
+If the agent must use networked tools during a turn, configure an explicit
+`codex.turn_sandbox_policy` that allows network access, for example:
+
+```yaml
+codex:
+  approval_policy: never
+  thread_sandbox: workspace-write
+  turn_sandbox_policy:
+    type: workspaceWrite
+    writableRoots:
+      - /tmp/symphony_workspaces
+    readOnlyAccess:
+      type: fullAccess
+    networkAccess: true
+    excludeTmpdirEnvVar: false
+    excludeSlashTmp: false
+```
+
+With that in place, env-based credentials exported before launching Symphony are available to turn
+commands. If a specific external CLI still does not find usable credentials in your environment,
+provide that tool's credential explicitly via an env var such as `GH_TOKEN`, `GITHUB_TOKEN`, or a
+provider-specific API key.
+
+The exact accepted sandbox and approval values depend on the installed Codex app-server version. To
+inspect the local schema, run `codex app-server generate-json-schema --out <dir>` and inspect the
+generated `ThreadStartParams` and `TurnStartParams` schema files.
+
 ### Step 6: Trigger a Test Issue in Linear
 
 1. Open your Linear test project
@@ -325,4 +362,4 @@ These fields take effect on the next poll tick without restarting Symphony:
 - Structured JSON logs are the primary observability surface
 - Launch with `--port 3000` to access the HTTP dashboard at `http://localhost:3000`
 
----
+---

docs/WORKFLOW.template.md

@@ -95,11 +95,14 @@ agent:
 # ============================================================
 codex:
   # Shell command used to launch the Codex app-server.
+  # Add `--config shell_environment_policy.inherit=all` if agent turns
+  # should inherit environment variables from the launching shell.
   # Default: codex app-server
   command: codex app-server
 
   # Codex approval policy, passed through to the app-server.
-  # Common values: "never" | "on-failure" | "always"
+  # Common values depend on the installed Codex schema.
+  # Example values: never, on-request, on-failure
   # Default: (not set — inherits Codex default)
   approval_policy: never
 
@@ -111,7 +114,14 @@ codex:
   # Per-turn sandbox policy passed through to Codex.
   # Example:
   #   turn_sandbox_policy:
-  #     type: workspace-write
+  #     type: workspaceWrite
+  #     writableRoots:
+  #       - /tmp/symphony_workspaces
+  #     readOnlyAccess:
+  #       type: fullAccess
+  #     networkAccess: true
+  #     excludeTmpdirEnvVar: false
+  #     excludeSlashTmp: false
   # Default: (not set)
   turn_sandbox_policy: null
 
@@ -149,6 +159,18 @@ Rules:
 3. Run the test suite before finishing.
 4. Do not add secrets or credentials to the repository.
 
+If this workflow needs environment variables from the launching shell:
+
+1. Launch Codex with `--config shell_environment_policy.inherit=all`.
+2. Export the required environment variables before launching Symphony.
+
+If the agent must call networked tools during a turn:
+
+1. Configure `codex.turn_sandbox_policy` with explicit `networkAccess: true`.
+2. If a specific CLI still does not find usable credentials in your environment, provide that
+   tool's credential via an env var such as `GH_TOKEN`, `GITHUB_TOKEN`, or a provider-specific API
+   key.
+
 When finished:
 
 1. Update the Linear issue state to "Done" using the `linear_graphql` tool.