PathReader — How It Works

PathReader evaluates agent actions against your workspace's policy documents before they execute — converting PDF policies into deterministic, auditable rules.

Core Workflow

  1. Upload a policy document — Go to Documents, upload a PDF. PathReader extracts the text and uses an LLM to propose rules automatically.
  2. Review rule candidates — Each candidate shows the proposed rule, severity (block or escalate), and the source quote from your document. Approve or reject each one.
  3. Activate a policy version — Go to Policies, open a policy, open a version, click Activate. PathReader compiles the approved rules and makes them live.
  4. Evaluate agent actions — Use the Evaluate page to manually test, or wire the agent hook so every tool call is checked automatically.

Workspace → Department → Policy

Policies are organized in a hierarchy: your Workspace contains one or more Departments, each of which owns Policies. A policy can have multiple versions — only one is active at a time. Activating a new version retires the previous one.

Decisions

allowNo rules fired — action is permitted.
blockA rule with severity block fired. The agent hook exits non-zero; the tool call is cancelled and PathReader shows the violated rule with its policy citation.
escalateOnly escalate-severity rules fired. In OBSERVE mode the action proceeds with a warning. In ENFORCE mode the action is blocked.

OBSERVE vs ENFORCE Mode

Each service account has a mode:

  • OBSERVE (default) — All decisions are logged. Block actions are always blocked; escalate actions are logged but allowed through. Good for rolling out PathReader without disrupting existing workflows.
  • ENFORCE — Both block and escalate actions are blocked. The agent cannot proceed and must find an alternative. Toggle this in Settings → Service Accounts.

Agent Hook (Claude Code / Cursor)

PathReader ships a scripts/pathreader-agent-hook.sh that plugs into the PreToolUse hook of Claude Code (and Cursor). Every tool call — Bash command, file read, web fetch — is sent to PathReader's evaluate API before it executes.

See docs/integration-guide.md for the full setup guide including the settings.json snippet and action request schema.

The hook is fail-open by default: network errors and server errors allow the action through so a connectivity blip does not halt the agent. Set PATHREADER_HOOK_LOG=/tmp/pathreader.log for debug output.

Service Accounts

Create service accounts in Settings → Service Accounts. Each account gets a unique API key (shown once at creation) that agents use to authenticate with the evaluate API. Revoke an account to immediately stop all agents using that key.

Roles

OwnerFull access: manage members, service accounts, webhooks, policies, and org settings.EditorUpload documents, review and approve rule candidates, create and manage policy versions.ViewerRead-only: view policies, evaluations, analytics, coverage, and rule effectiveness.

Analytics & Observability

  • Analytics — violation rates, daily trends, attribution by caller and agent, and mean evaluation latency.
  • Policy Coverage — fields that appear in recent evaluations but aren't checked by any active rule.
  • Rule Effectiveness — per-rule trigger counts; flags dead rules (never triggered) and overly-broad rules (>30% trigger rate).
  • Near-miss detection — evaluations where a THRESHOLD_LIMIT rule passed within 5% of the threshold are flagged in the analytics page as near-misses.
  • Change impact analysis — on any DRAFT or APPROVED version, click “Change impact analysis” to see how historical evaluations would have changed under the new rules before you activate.

Current Limits

  • Candidate extraction analyzes the first ~12,000 characters of extracted text.
  • Extraction rate limit: 10 requests per hour per user.
  • Only text-based PDFs are supported (no scanned/image PDFs).
  • Maximum PDF file size: 10 MB.
  • Evaluation history shows the most recent 100 transactions per query.