Add AST-based security middleware and enforcement wiring

docs/orchestration-engine.md

@@ -45,4 +45,13 @@ Node payloads are persisted under the state root. Nodes do not inherit in-memory
 
 ## Security note
 
-Tool clearance allowlists/banlists are currently data-model stubs. Enforcement must be implemented in the tool execution boundary before relying on these policies for hard guarantees.
+Security enforcement now lives in `src/security`:
+
+- `bash-parser` AST parsing for shell command tokenization (`Command`/`Word` nodes).
+- Zod-validated shell/tool policy schemas.
+- `SecurityRulesEngine` for binary allowlists, path traversal checks, worktree boundaries, and tool clearance checks.
+- `SecureCommandExecutor` for controlled `child_process` execution with timeout + explicit env policy.
+
+`PipelineExecutor` treats `SecurityViolationError` via configurable policy:
+- `hard_abort` (default): immediate pipeline termination.
+- `validation_fail`: maps to retry-unrolled remediation.

docs/pipeline-policies.md

@@ -14,6 +14,7 @@
 - `PipelineExecutor` (`src/agents/pipeline.ts`)
   - Coordinates DAG traversal and retry behavior.
   - Computes aggregate run status from executed terminal nodes plus critical-path failures.
+  - Applies dedicated `SecurityViolationError` handling policy (`hard_abort` or `validation_fail` mapping).
 
 ## Aggregate status semantics
 

docs/security-middleware.md

@@ -0,0 +1,42 @@
+# Security Middleware
+
+## Scope
+
+This middleware provides a first-pass hardening layer for agent-executed shell commands and MCP tool usage.
+
+## 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.
+- `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`
+  - Enforces:
+    - binary allowlist
+    - cwd boundary (`AGENT_WORKTREE_ROOT`)
+    - argument path boundary and `../` traversal rejection
+    - protected path blocking (`AGENT_STATE_ROOT`, `AGENT_PROJECT_CONTEXT_PATH`)
+    - unified tool allowlist/banlist checks
+- `src/security/executor.ts`
+  - Runs commands via `child_process.spawn` using explicit env construction (no implicit full parent env inheritance).
+  - Supports timeout enforcement, optional uid/gid drop, and stdout/stderr stream callbacks.
+- `src/security/audit-log.ts`
+  - File-backed audit sink (`ndjson`) for profiling emitted shell commands and tool access decisions.
+
+## Pipeline behavior
+
+`SecurityViolationError` is treated as a first-class error type by `PipelineExecutor`:
+
+- `hard_abort` (default): fail fast and stop the pipeline.
+- `validation_fail`: map violation to retry-unrolled behavior so the actor can attempt a compliant alternative.
+
+## MCP integration
+
+`McpRegistry.resolveServerWithHandler(...)` now accepts optional tool clearance and applies it to resolved Codex MCP tool lists (`enabled_tools`, `disabled_tools`).
+
+## Known limits and TODOs
+
+- AST validation is token-based and does not yet model full shell evaluation semantics (e.g. runtime-generated paths from env expansion).
+- Audit output is line-oriented file logging; move to a centralized telemetry pipeline for long-term profiling.
+- Deno sandbox mode is not enforced yet. A future executor mode can wrap shell runs via `deno run` with strict `--allow-read/--allow-run` flags.