Agent Safety Architecture

LumenFlow enforces agent safety through 9 layered protection mechanisms working in a defense-in-depth model. No single layer provides complete coverage — understanding which layers apply to your agent client is essential for maintaining workflow integrity.

Fleet Lifecycle Authority

Cleanup, recovery, completion, and orchestration use model-agnostic lifecycle evidence: WU id, lane lock, session/lease evidence, lane branch, worktree path, done stamp, and audit records. Provider names, model names, hosted runners, client UIs, and plugins are adapter metadata only.

Active or recently active WU leases block destructive cleanup. If an active WU lost its worktree but still has a lane branch, restore first:

pnpm wu:recover --id WU-042 --action restore

wu:prune --execute records recoverable tracked removals under .lumenflow/quarantine/worktrees/cleanup.jsonl; raw Git pruning remains an implementation detail, not lifecycle authority.

Bootstrap And Prereq Safety

Agent-facing root scripts should invoke LumenFlow commands through node tools/cli-entry.mjs <entry>, not direct packages/@lumenflow/cli/dist/*.js paths. The wrapper keeps clean WU worktrees from failing command discovery, memory, orchestration, and setup checks before the local CLI dist exists.

Use the package-script guard after alias changes:

pnpm verify:script-help
pnpm verify:script-help --run-probes

Use the prereq reporter before local database or model workflows:

pnpm lumenflow:setup-prereqs --json

It reports Supabase CLI, Docker, Supabase local stack, Ollama binary, OpenAI-compatible local API, and configured model readiness from project signals. The report intentionally omits local service keys and token-shaped values; agents must not paste raw supabase start, .envrc, or provider-token output into prompts, issues, or WU notes.

Protection Layers

Layer 1: Tool-Level Bash Blocking (Claude Code)

Intercepts Bash tool calls and blocks file-manipulation commands (cat >, echo >, sed -i, tee) that bypass Write/Edit tool validation. It also blocks raw local-main mutation commands from the main checkout (git pull, git merge, git rebase, git reset) and directs clean fast-forward catch-up to pnpm git:sync-main.

• Scope: Claude Code only
• Enforcement: Fail-closed (blocks when uncertain)
• File: .claude/hooks/block-bash-file-commands.sh

Layer 2: Worktree Path Validation (Claude Code)

Intercepts Write and Edit tool calls and validates that target file paths are inside an active worktree or in the allowlist.

• Scope: Claude Code only
• Enforcement: Fail-closed
• File: .claude/hooks/validate-worktree-path.sh

Caution

The allowlist permits writes to WU YAML specs and .lumenflow/* files, meaning agents can raw-edit config files without using config:set or wu:edit. See Constraint 9 below.

Layer 3: Pre-Commit Hook

Runs before every git commit. Enforces format checking, blocks WU commits from main checkout, and validates commit messages.

• Scope: All clients (universal, git-level)
• Enforcement: Active
• File: .husky/pre-commit.mjs

Layer 4: Pre-Push Hook

Runs before every git push. Validates branch naming, blocks force push to main, and ensures wu:done workflow compliance.

• Scope: All clients (universal, git-level)
• Enforcement: Active
• File: .husky/pre-push.mjs

Layer 5: Safe-Git Wrapper

Wraps git and blocks destructive commands (reset --hard, clean -fd, push --force, worktree remove/prune).

• Scope: Opt-in (recommended for Cursor)
• Enforcement: Optional
• File: scripts/safe-git

Layer 6: Policy Documents

Workflow rules as markdown documents in .lumenflow/rules/.

• Scope: Advisory (all clients)
• Enforcement: None (depends on agent compliance)

Layer 7: Constraints Capsule

Non-negotiable constraints in .lumenflow/constraints.md, injected into spawn prompts via wu:brief and wu:delegate.

• Scope: All clients (injected for Claude Code spawns)
• Enforcement: Soft (prompt-based)

Layer 8: Configuration-Driven Enforcement

Toggles in workspace.yaml for features like block_outside_worktree, require_wu_for_edits, and context_validation.

• Scope: Varies by setting and client
• Enforcement: Active for Claude Code, advisory for others

Layer 9: Ownership Guards (v3.19.0)

State-mutating commands (wu:block, wu:unblock, wu:release, wu:recover) validate session ownership before allowing state changes. Prevents one agent from modifying another session’s WU to free a lane.

• Scope: All clients (CLI-level)
• Enforcement: Active (blocks with SESSION OWNERSHIP VIOLATION or CLAIM OWNERSHIP VIOLATION)
• Override: --override-owner --reason "..." — audited to .lumenflow/ownership-override-audit.log

When the CLI already knows the target WU, it resolves .lumenflow/sessions/WU-XXXX.json directly. .lumenflow/sessions/current.json remains only as a temporary compatibility pointer for legacy readers during the migration window.

Coverage Matrix

Layer	Mechanism	Claude Code	Cursor	Codex	Windsurf	Manual
1	Bash blocking	Enforced	—	—	—	—
2	Path validation	Enforced	—	—	—	—
3	Pre-commit hook	Enforced	Enforced	Enforced	Enforced	Enforced
4	Pre-push hook	Enforced	Enforced	Enforced	Enforced	Enforced
5	Safe-git wrapper	Available	Recommended	Available	Available	Available
6	Policy documents	Advisory	Advisory	Advisory	Advisory	Advisory
7	Constraints capsule	Injected	Advisory	Advisory	Advisory	Advisory
8	Config enforcement	Enforced	Advisory	Advisory	Advisory	N/A
9	Ownership guards	Enforced	Enforced	Enforced	Enforced	Enforced

Legend: Enforced = actively blocks non-compliant operations. Recommended = configured but opt-in. Available = can be used. Advisory = documented policy only. Injected = included in spawn prompts. — = not applicable.

Governed Local Main Sync

Raw git pull from the main checkout is blocked for agents because it mutates local main without LumenFlow lifecycle guards. When local files need to catch up to canonical metadata on origin/main, use:

pnpm git:sync-main

git:sync-main fetches origin/main, requires a clean primary checkout on main, rejects WU worktrees and in-progress merge/rebase state, verifies local main is an ancestor of origin/main, and then performs a fast-forward-only update. If the checkout is dirty, divergent, not on main, or missing origin/main, the command exits non-zero with remediation guidance.

YAML Editing Policy

Danger

YAML configuration files are in the worktree path validation allowlist. Any agent can raw-edit them. This is a known gap. Always use CLI tooling instead.

Constraint 9: All YAML configuration files must be modified via CLI tooling only.

Config File

# Read a value
pnpm config:get --key software_delivery.methodology.testing

# Set a value (Zod-validated, atomic commit)
pnpm config:set --key software_delivery.methodology.testing --value test-after

# Set a boolean
pnpm config:set --key software_delivery.gates.enableCoverage --value false

WU Specs

# Edit WU fields
pnpm wu:edit --id WU-XXX --description "Updated description"

# Create new WU
pnpm wu:create --lane "Framework: Core" --title "Add feature" \
  --description "..." --acceptance "..."

Why CLI tooling:

1. Schema validation — config:set validates against the Zod schema before writing
2. Atomic commits — Uses micro-worktree pattern for race-safe writes
3. Audit trail — CLI commands produce structured log entries
4. Type coercion — Automatic boolean, number, and array handling

Reading YAML files with Read tools is acceptable for inspection.

Per-Client Setup

Claude Code

Claude Code has the strongest protection (Layers 1-8 all active).

# Generate enforcement hooks
pnpm lumenflow:integrate --client claude-code

Tool-level hooks block unsafe Bash commands and validate worktree paths. Constraints are injected into spawn prompts via wu:brief.

Cursor

Cursor relies on git hooks (Layers 3-4) and advisory rules.

# Initialize Cursor overlay
pnpm lumenflow:init --client cursor

Recommended: Use the safe-git wrapper (./scripts/safe-git) for additional protection. Configure in .cursorrules.

Codex

Codex operates in cloud/branch-PR mode with git hook enforcement.

# Claim in cloud mode
pnpm wu:claim --id WU-XXX --lane "Lane" --cloud

Codex uses agent/* branch patterns. Git hooks (Layers 3-4) apply at commit/push time.

Windsurf

Windsurf has minimal enforcement (git hooks + advisory docs).

# Initialize Windsurf overlay
pnpm lumenflow:init --client windsurf

Advisory rules in .windsurf/rules/lumenflow.md. No tool-level enforcement.

Known Gaps

Gap	Risk	Description	Mitigation
YAML allowlist	Medium	Path validation allows raw YAML edits	Constraint 9 policy; future hook enforcement
Non-Claude clients	High	No tool-level enforcement for Cursor/Codex/Windsurf	Git hooks + advisory docs
LUMENFLOW_FORCE	Medium	Bypasses all hooks; logged but not alerted	Policy requires user approval; audit log
No branch protection	Medium	All enforcement is local hooks only	Future GitHub branch protection rules
Passive audit logs	Low	Violations logged but not monitored	Logs are git-tracked; future alerting

References

• Constraints Capsule — The 9 non-negotiable rules
• config:set and config:get — Safe config modification commands
• Configuration Reference — All config keys and types