Documentation

Agent Harness

Role-based access control, budgets, and governance for AI agents using lean-ctx.

The Agent Harness governs what AI agents can do, how much they can spend, and which tools they may use. It enforces role-based access control with real-time budget tracking.

What is the Agent Harness?

The Agent Harness is lean-ctx's governance layer. It assigns roles to agents, enforces tool policies, and tracks budgets (tokens, shell invocations, cost). When limits are approached, warnings are emitted. LeanCTX never blocks by default - it always helps your AI, even when budgets are exceeded. Blocking can be enabled explicitly for strict governance scenarios.

Built-in Roles

lean-ctx ships with 5 built-in roles. Each role defines tool access, shell policy, and resource limits. The default role is coder.

coder

Full tool access for code implementation. 200K token budget, 100 shell invocations, $5 cost limit.

reviewer

Read-only access for code review. No shell, no editing. 150K tokens, $3 cost limit.

debugger

Debug-focused with extended shell access. 150K tokens, 200 shell invocations, $5 cost limit.

ops

Infrastructure and CI/CD operations. Shell-heavy, no editing. 100K tokens, 300 shell invocations, $3 cost limit.

admin

Unrestricted access with high limits. 500K tokens, 500 shell invocations, $50 cost limit.

Budget Enforcement

Every tool call is tracked against the active role's budget. The budget has three dimensions:

Budget[coder]: tokens 50000/200000 (25%) | shell 5/100 (5%) | cost $0.50/$5.00 (10%) → OK

Budget Dimensions

  • Context Tokens - total tokens consumed by tool outputs
  • Shell Invocations - number of ctx_shell / ctx_execute calls
  • Estimated Cost - approximate USD cost of the session

Budget Signals

The harness emits signals based on budget consumption:

  • OK - usage below warn threshold (default: 80%)
  • WARNING - usage between warn (80%) and block (100%) thresholds. A warning is appended to tool responses.
  • EXHAUSTED - usage at or above threshold. By default, LeanCTX continues working with warnings (never blocks). For strict governance, set block_at_percent: 100 in the role config to enable blocking.

Tool Policies

Each role defines which tools are allowed and denied. Denied tools always override allowed tools. Use * as a wildcard.

[tools]
allowed = ["ctx_read", "ctx_search", "ctx_tree", "ctx_session"]
denied = ["ctx_edit", "ctx_shell"]

Shell Policy

  • track - shell allowed, commands are logged (default)
  • compress - shell allowed, output is compressed
  • deny - shell access completely blocked

Harness Events

The Agent Harness emits structured events to the event bus and JSONL log:

  • BudgetWarning - a budget dimension crossed the warning threshold
  • BudgetExhausted - a budget dimension is fully consumed
  • PolicyViolation - an agent attempted to use a blocked tool
  • RoleChanged - the active role was switched at runtime

Custom Roles

Create TOML files in .lean-ctx/roles/ (project-local) or ~/.lean-ctx/roles/ (global). Roles support inheritance via the inherits field.

[role]
name = "security-auditor"
inherits = "reviewer"
description = "Security-focused code review"
shell_policy = "deny"

[tools]
allowed = ["ctx_read", "ctx_search", "ctx_tree", "ctx_review", "ctx_session"]
denied = ["ctx_edit", "ctx_shell", "ctx_execute"]

[limits]
max_context_tokens = 100000
max_shell_invocations = 0
max_cost_usd = 2.0

Check current role with ctx_session action=role. Switch roles with ctx_session action=role value=<name>.

Activating a Role

Set the LEAN_CTX_ROLE environment variable:

export LEAN_CTX_ROLE=reviewer

Or switch at runtime via MCP:

ctx_session action=role value=debugger

Check budget status:

ctx_session action=budget