constrain

name: constrain
description: Enforce policies, guardrails, and permission boundaries; refuse unsafe actions and apply least privilege. Use when evaluating actions against policies, checking permissions, or reducing scope to safe boundaries.
argument-hint: "[action] [policy_id] [scope] [enforcement_level]"
disable-model-invocation: false
user-invocable: true
allowed-tools: Read, Grep
context: fork
agent: explore

Intent

Execute constrain to evaluate proposed actions against defined policies, enforce permission boundaries, and reduce scope to the minimum required for safe operation. This is the gatekeeper that prevents unsafe actions before they execute.

Success criteria:
- All relevant policies evaluated for the proposed action
- Clear allow/deny decision with rationale
- Scope reduced to minimum necessary permissions
- Violation actions documented (block, warn, log)

Compatible schemas:
- docs/schemas/policy_evaluation.yaml
- docs/schemas/permission_boundary.yaml

Inputs

Procedure

1) Identify applicable policies: Find all policies relevant to the action
- Load policy definitions from .policies/ or policy registry
- Match action type to policy triggers
- Consider context (user role, environment, time) for policy selection

2) Evaluate preconditions: Check if action meets basic safety requirements
- Is action within workspace boundaries?
- Does action target sensitive resources (.env, credentials)?
- Is checkpoint required but missing?
- Is approval required but not obtained?

3) Apply policy rules: Evaluate each policy condition
- Parse policy conditions (AND/OR/NOT expressions)
- Check each condition against action parameters
- Record which conditions pass and which fail
- Determine overall policy verdict (allow/deny/conditional)

4) Reduce scope: Apply least privilege principle
- Identify minimum permissions needed for action
- Remove unnecessary permissions from scope
- Document removed permissions and rationale

5) Determine enforcement action: Based on policy verdict
- block: Prevent action from executing
- warn: Allow but alert user to risk
- log: Record violation but allow action

6) Ground claims: Document policy evaluation evidence
- Format: policy:<policy_id>:<condition>, decision rationale
- Include any scope reductions applied

Output Contract

Return a structured object:

constraints_applied:
  - name: string  # Policy or constraint name
    type: policy | permission | rate_limit | scope
    target: string  # What the constraint applies to
    enforced: boolean  # Whether constraint was enforced
    violation_action: block | warn | log
policy_evaluation:
  policy_id: string  # Which policy was evaluated
  result: allow | deny | conditional
  conditions_met: array[string]  # Conditions that passed
  conditions_failed: array[string]  # Conditions that failed
scope_reduction:
  original_scope: object  # Permissions before constraining
  constrained_scope: object  # Permissions after constraining
  removed_permissions: array[string]  # What was removed
safe_to_proceed: boolean  # Overall go/no-go
blocked_reason: string | null  # Why blocked (if applicable)
confidence: number  # 0.0-1.0
evidence_anchors: ["policy:...", "file:..."]
assumptions: []

Field Definitions

Examples

Example 1: Constrain File Access to Safe Boundaries

Input:

action:
  capability: "edit"
  target: "/etc/passwd"
  parameters:
    content: "..."
enforcement_level: strict

Output:

constraints_applied:
  - name: "workspace_boundary"
    type: scope
    target: "/etc/passwd"
    enforced: true
    violation_action: block
  - name: "sensitive_file_protection"
    type: policy
    target: "/etc/passwd"
    enforced: true
    violation_action: block
policy_evaluation:
  policy_id: "sys_file_protection"
  result: deny
  conditions_met: []
  conditions_failed:
    - "path must be within workspace"
    - "system files are read-only"
scope_reduction:
  original_scope:
    paths: ["/**"]
  constrained_scope:
    paths: ["/workspace/**"]
  removed_permissions:
    - "write to system paths"
safe_to_proceed: false
blocked_reason: "Action targets system file outside workspace boundary. Editing /etc/passwd is prohibited."
confidence: 1.0
evidence_anchors:
  - "policy:workspace_boundary:path_check"
  - "policy:sys_file_protection:sensitive_paths"
assumptions: []

Evidence pattern: Policy definitions, path matching against workspace boundary.

Example 2: Constrain API Call with Rate Limiting

Input:

action:
  capability: "send"
  target: "https://api.external.com/data"
  parameters:
    method: "POST"
    payload: {...}
context:
  session_id: "abc123"
  requests_this_hour: 95
enforcement_level: advisory

Output:

constraints_applied:
  - name: "external_api_rate_limit"
    type: rate_limit
    target: "api.external.com"
    enforced: true
    violation_action: warn
  - name: "checkpoint_before_send"
    type: policy
    target: "send capability"
    enforced: true
    violation_action: block
policy_evaluation:
  policy_id: "external_communication"
  result: conditional
  conditions_met:
    - "destination is allowed domain"
    - "payload size within limits"
  conditions_failed:
    - "approaching rate limit (95/100 this hour)"
scope_reduction:
  original_scope:
    rate_limit: 100
    burst_allowed: true
  constrained_scope:
    rate_limit: 5
    burst_allowed: false
  removed_permissions:
    - "burst requests"
safe_to_proceed: true
blocked_reason: null
confidence: 0.9
evidence_anchors:
  - "policy:external_api_rate_limit:hourly_quota"
  - "context:requests_this_hour:95"
assumptions:
  - "Rate limit counter is accurate"
  - "Hour boundary resets at :00"

Example 3: Constrain Before Act-Plan

Input:

action:
  capability: "act-plan"
  target: "refactor_handlers_plan"
  parameters:
    plan_id: "plan_20240115_refactor"
enforcement_level: strict

Output:

constraints_applied:
  - name: "checkpoint_required"
    type: policy
    target: "act-plan"
    enforced: true
    violation_action: block
policy_evaluation:
  policy_id: "mutation_safety"
  result: conditional
  conditions_met:
    - "plan exists and is valid"
    - "files in scope are editable"
  conditions_failed:
    - "checkpoint not found for scope"
scope_reduction:
  original_scope:
    mutation_allowed: true
  constrained_scope:
    mutation_allowed: false
  removed_permissions:
    - "file mutation (pending checkpoint)"
safe_to_proceed: false
blocked_reason: "act-plan requires checkpoint. Call 'checkpoint' first with scope matching the plan."
confidence: 1.0
evidence_anchors:
  - "policy:mutation_safety:checkpoint_gate"
  - "composition_patterns.md:CAVR"
assumptions: []

Verification

Apply the following verification patterns:

• [ ] Policy Coverage: All applicable policies were evaluated
• [ ] Evidence Grounding: Decisions linked to specific policy conditions
• [ ] Scope Reduction Valid: Constrained scope is subset of original
• [ ] Safety Boundary Check: No sensitive files in allowed scope

Verification tools: Read (for policy files), Grep (for policy search)

Safety Constraints

• mutation: false (constrain is evaluation only)
• requires_checkpoint: false
• requires_approval: false
• risk: low

Capability-specific rules:
- Always evaluate workspace boundary policy
- Always check for sensitive file patterns (.env, credentials, secrets, .pem, .key)
- Apply strictest enforcement when ambiguous
- Never downgrade enforcement level silently
- Log all policy evaluations for audit

Composition Patterns

Commonly follows:
- plan - Constrain the planned actions before checkpoint
- critique - After identifying risks, constrain to mitigate

Commonly precedes:
- checkpoint - After constrain approves, create checkpoint
- send - REQUIRED: constrain before any external communication
- act-plan - Constrain as part of pre-execution checks

Anti-patterns:
- CRITICAL: Never skip constrain before send (no unchecked external comms)
- Never ignore blocked_reason and proceed anyway
- Never silently weaken policy enforcement
- Never evaluate constrain after mutation has begun

Workflow references:
- See composition_patterns.md#digital-twin-sync-loop for constrain-before-act
- See composition_patterns.md#risk-assessment for constrain placement
- See verification_patterns.md#safety-boundary for boundary checks