docs: sync runtime env and security documentation

.env.example

@@ -6,6 +6,7 @@ CODEX_SKIP_GIT_CHECK=true
 MCP_CONFIG_PATH=./mcp.config.json
 
 # Anthropic Claude Agent SDK
+# CLAUDE_CODE_OAUTH_TOKEN takes precedence over ANTHROPIC_API_KEY when both are set.
 CLAUDE_CODE_OAUTH_TOKEN=
 ANTHROPIC_API_KEY=
 CLAUDE_MODEL=
@@ -34,6 +35,7 @@ AGENT_PORT_LOCK_DIR=.ai_ops/locks/ports
 AGENT_DISCOVERY_FILE_RELATIVE_PATH=.agent-context/resources.json
 
 # Security middleware
+# AGENT_SECURITY_VIOLATION_MODE: hard_abort | validation_fail
 AGENT_SECURITY_VIOLATION_MODE=hard_abort
 AGENT_SECURITY_ALLOWED_BINARIES=git,npm,node,cat,ls,pwd,echo,bash,sh
 AGENT_SECURITY_COMMAND_TIMEOUT_MS=120000
@@ -42,3 +44,7 @@ AGENT_SECURITY_ENV_INHERIT=PATH,HOME,TMPDIR,TMP,TEMP,LANG,LC_ALL
 AGENT_SECURITY_ENV_SCRUB=
 AGENT_SECURITY_DROP_UID=
 AGENT_SECURITY_DROP_GID=
+
+# Runtime-injected (do not set manually):
+# AGENT_REPO_ROOT, AGENT_WORKTREE_PATH, AGENT_WORKTREE_BASE_REF,
+# AGENT_PORT_RANGE_START, AGENT_PORT_RANGE_END, AGENT_PORT_PRIMARY, AGENT_DISCOVERY_FILE

AGENTS.md

@@ -47,6 +47,14 @@
   - `AGENT_SECURITY_ENV_SCRUB`
   - `AGENT_SECURITY_DROP_UID`
   - `AGENT_SECURITY_DROP_GID`
+- Runtime-injected resource context (provided by provisioning; do not set in `.env`):
+  - `AGENT_REPO_ROOT`
+  - `AGENT_WORKTREE_PATH`
+  - `AGENT_WORKTREE_BASE_REF`
+  - `AGENT_PORT_RANGE_START`
+  - `AGENT_PORT_RANGE_END`
+  - `AGENT_PORT_PRIMARY`
+  - `AGENT_DISCOVERY_FILE`
 
 ## Documentation Standards
 - Update `README.md` for user-facing behavior.

README.md

@@ -70,7 +70,6 @@ npm run dev -- claude "List potential improvements."
 `AgentManifest` (schema `"1"`) validates:
 
 - supported topologies (`sequential`, `parallel`, `hierarchical`, `retry-unrolled`)
-- persona definitions and tool-clearance metadata
 - persona definitions and tool-clearance policy (validated by shared Zod schema)
 - relationship DAG and unknown persona references
 - strict pipeline DAG
@@ -130,8 +129,8 @@ Actors can emit events in `ActorExecutionResult.events`. Pipeline status also em
 - `OPENAI_API_KEY`
 - `OPENAI_BASE_URL`
 - `CODEX_SKIP_GIT_CHECK`
-- `CLAUDE_CODE_OAUTH_TOKEN` (preferred for Claude auth)
-- `ANTHROPIC_API_KEY`
+- `CLAUDE_CODE_OAUTH_TOKEN` (preferred for Claude auth; takes precedence over `ANTHROPIC_API_KEY`)
+- `ANTHROPIC_API_KEY` (used when `CLAUDE_CODE_OAUTH_TOKEN` is unset)
 - `CLAUDE_MODEL`
 - `CLAUDE_CODE_PATH`
 - `MCP_CONFIG_PATH`
@@ -163,7 +162,7 @@ Actors can emit events in `ActorExecutionResult.events`. Pipeline status also em
 
 ### Security Middleware
 
-- `AGENT_SECURITY_VIOLATION_MODE`
+- `AGENT_SECURITY_VIOLATION_MODE` (`hard_abort` or `validation_fail`)
 - `AGENT_SECURITY_ALLOWED_BINARIES`
 - `AGENT_SECURITY_COMMAND_TIMEOUT_MS`
 - `AGENT_SECURITY_AUDIT_LOG_PATH`
@@ -172,6 +171,16 @@ Actors can emit events in `ActorExecutionResult.events`. Pipeline status also em
 - `AGENT_SECURITY_DROP_UID`
 - `AGENT_SECURITY_DROP_GID`
 
+### Runtime-Injected (Do Not Configure In `.env`)
+
+- `AGENT_REPO_ROOT`
+- `AGENT_WORKTREE_PATH`
+- `AGENT_WORKTREE_BASE_REF`
+- `AGENT_PORT_RANGE_START`
+- `AGENT_PORT_RANGE_END`
+- `AGENT_PORT_PRIMARY`
+- `AGENT_DISCOVERY_FILE`
+
 Defaults are documented in `.env.example`.
 
 ## Quality Gate

docs/security-middleware.md

@@ -7,8 +7,8 @@ This middleware provides a first-pass hardening layer for agent-executed shell c
 ## Components
 
 - `src/security/shell-parser.ts`
-  - Uses `bash-parser` to parse shell scripts and extract command-level data from `Command` and `Word` nodes.
-  - Traverses nested constructs (logical operators, pipelines, subshells, command expansions) so chained commands are fully visible to policy checks.
+  - Uses async `sh-syntax` (mvdan/sh parser) as a hard parser gate before validation.
+  - Performs fail-closed token-level command extraction and blocks unsupported expansions/subshell constructs.
 - `src/security/schemas.ts`
   - Zod schemas for shell policies, tool clearance policies, execution env policy, and security violation handling mode.
 - `src/security/rules-engine.ts`