Policy Engine

The Policy Engine evaluates rules at every decision point in the kernel — tool calls, task claims, and task completions. Its core invariant: a deny decision at any layer is final and cannot be reversed by any other layer.

The Four-Layer Stack

Policies are organized into four layers, evaluated in fixed order:

workspace → lane → pack → task

Layer	Who sets it	Purpose
Workspace	Workspace administrator	Organization-wide rules (e.g., “no network access”)
Lane	Lane configuration	Domain-specific restrictions (e.g., “this lane is read-only”)
Pack	Pack manifest	Domain rules from the pack author (e.g., “gates must pass before completion”)
Task	Task specification	Per-task rules (e.g., “this task cannot modify src/auth/”)

Each layer can contain a default decision and a list of rules.

Policy Rules

A rule has four parts:

Field	Type	Description
id	string	Unique identifier (e.g., software-delivery.gate.format)
trigger	enum	When to evaluate: on_tool_request, on_claim, on_completion, on_evidence_added
decision	enum	allow or deny
reason	string?	Human-readable explanation

Rules in pack manifests are static — they apply unconditionally when their trigger fires. Runtime rules (set programmatically) can include a when predicate for conditional evaluation (see Conditional Rules with when() below).

Deny-Wins Evaluation

The evaluation algorithm processes layers in order:

1. Start with deny. The effective decision begins as deny (fail-closed).
2. Apply defaults. The first layer to declare a default_decision sets the baseline. Subsequent layers can only tighten (deny), not loosen, unless explicitly granted allow_loosening.
3. Match rules. For each layer, find rules whose trigger matches the current context.
4. Sticky deny. Once any rule emits deny, no subsequent allow rule in any layer can reverse it.

Workspace: default=allow          → effective: allow
Lane:      (no default)           → effective: allow
Pack:      rule deny(on_completion) → effective: deny  ← sticky
Task:      rule allow(on_completion) → REJECTED (cannot loosen a hard deny)
                                    → final: deny

Caution

The allow_loosening flag on a layer only permits loosening an inherited default decision, not a hard deny from a specific rule. Once a rule says deny, the decision is final regardless of allow_loosening.

Triggers

Each trigger fires at a specific lifecycle moment:

Trigger	When it fires	Example use
on_tool_request	Every tool call, during authorization	Block specific tools, restrict write operations
on_claim	When a task is claimed (ready → active)	Require approval before work starts
on_completion	When a task completes (active → done)	Enforce gates (format, lint, test)
on_evidence_added	When a new evidence record is written	Reserved for future use

Gates as Policies

In the Software Delivery Pack, quality gates (format, lint, typecheck, test) are implemented as pack-layer policies with trigger: on_completion. When you run pnpm wu:prep or pnpm gates, the system evaluates these policies:

Gate	Policy ID	Trigger
Format check	software-delivery.gate.format	on_completion
Lint	software-delivery.gate.lint	on_completion
Type check	software-delivery.gate.typecheck	on_completion
Test	software-delivery.gate.test	on_completion

This means gates are not just CLI commands — they are kernel-enforced policies. An agent cannot skip gates by calling completeTask directly; the policy engine will deny the completion.

Built-in Policy IDs

The kernel reserves several policy IDs for internal use:

ID	Purpose
kernel.policy.allow-all	Development-only allow-all hook
kernel.scope.reserved-path	Blocks writes to .lumenflow/**
kernel.scope.boundary	Denies when scope intersection is empty
kernel.reconciliation	Marks crash-reconciled evidence entries

Conditional Rules with when()

Runtime policy rules can include a when predicate — a function that receives the full PolicyEvaluationContext and returns true if the rule should apply. Rules without a when predicate match unconditionally whenever their trigger fires.

const rule: PolicyRule = {
  id: 'my-pack.block-dangerous-paths',
  trigger: 'on_tool_request',
  decision: 'deny',
  reason: 'Writes to /etc are not permitted',
  when: (context) => {
    const args = context.tool_arguments;
    if (!args || typeof args.path !== 'string') return false;
    return args.path.startsWith('/etc');
  },
};

PolicyEvaluationContext

The when predicate receives a PolicyEvaluationContext with these fields:

Field	Type	Description
trigger	string	The trigger type that fired this evaluation
run_id	string	Current run identifier
tool_name	string?	Name of the tool being called (for on_tool_request)
task_id	string?	Active task identifier
lane_id	string?	Lane the task belongs to
pack_id	string?	Pack that provides the tool
tool_arguments	Record<string, unknown>?	Parsed tool input arguments (see below)

Argument-level policy evaluation

The tool_arguments field provides the parsed input arguments for the tool being called. The kernel extracts this automatically from the raw tool input: if the input is a plain object, it is passed as tool_arguments; otherwise the field is undefined.

This enables argument-level policy decisions — rules that inspect what a tool is doing, not just which tool is being called:

// Block file writes to sensitive directories
const rule: PolicyRule = {
  id: 'security.block-sensitive-writes',
  trigger: 'on_tool_request',
  decision: 'deny',
  reason: 'Cannot write to credentials directory',
  when: (context) => {
    if (context.tool_name !== 'file:write') return false;
    const args = context.tool_arguments;
    if (!args || typeof args.path !== 'string') return false;
    return args.path.includes('.credentials/');
  },
};

Note

The tool_arguments field is backwards compatible. Existing policy rules that do not reference it continue to work unchanged. The field is only populated for on_tool_request evaluations where the tool input is a plain object.

Evaluation Result

Every policy evaluation returns:

• decision — the final allow or deny
• decisions[] — every rule that matched, with its individual decision and reason
• warnings[] — any loosening attempts that were rejected

All of this is recorded in the evidence store as part of the tool trace, providing a complete audit trail of why an action was allowed or denied.

Next Steps

• Kernel Runtime — Where policy evaluation fits in the tool execution pipeline
• Scope Intersection — The permission model that runs alongside policies
• Evidence Store — How policy decisions are recorded
• Gates — How the Software Delivery Pack uses policies for quality checks