Security review · Local policy · Signed decisions

What leaves your machine

AgentGuard checks supported tool calls locally. The plugin does not upload prompts, tool input, tool output, file content or receipts to AgentGuard. Here is the boundary a reviewer can inspect.

Scope: the AgentGuard plugin for Claude Code, the Codex CLI and local tasks in the ChatGPT desktop app. Your host, model provider and tools have their own network behavior.

The local boundary

The local boundary of the AgentGuard plugin On your machine the host sends each tool call to the AgentGuard hook, which checks local rules without opening a socket and signs the decision into a hash-chained ledger on disk. The call is allowed or refused; on a hook error or timeout it is allowed and the reason is recorded when local logging works. Beside the hook and outside the tool admission path, a detached worker sends identifiers and whole numbers to agentguard.run for licensing, policy sync and Team caps, the policy configuration only when you push a Solo policy, and signed Team totals only after you turn them on. The Score skill sends five answers only after you say yes. your machine the tool admission path agentguard.run the default destination the host Claude Code, Codex CLI, ChatGPT desktop local tasks tool call AgentGuard hook local rule check, no socket signs the decision signed record ledger on disk hash-chained, Ed25519 signed tool id, input hash, decision allowed the tool runs refused the call stops error or timeout fail-open: allowed, reason recorded if logging works stays here: prompts, tool input and output, file content, keys, receipts beside the hook, outside the admission path Score skill (MCP tool) five answers, report-link choice, only after you say yes to the named origin detached worker license check, seat heartbeat, policy sync, Team caps, opt-in Team totals identifiers, numbers policy on a Solo push five answers, on your yes POST /api/license/validate license key POST /api/license/seats heartbeat about every 5 min GET and PUT /api/org/policy policy sync, Solo and Team POST /api/team/reserve POST /api/team/release Team caps, Team only POST /api/team/counts POST /api/team/waste opt-in, up to plugin 0.6.1 POST /api/score the five answers only The local boundary of the AgentGuard plugin On your machine the host sends each tool call to the AgentGuard hook, which checks local rules without opening a socket and signs the decision into a hash-chained ledger on disk. The call is allowed or refused; on a hook error or timeout it is allowed and the reason is recorded when local logging works. Beside the hook and outside the tool admission path, a detached worker sends identifiers and whole numbers to agentguard.run for licensing, policy sync and Team caps, the policy configuration only when you push a Solo policy, and signed Team totals only after you turn them on. The Score skill sends five answers only after you say yes. your machine tool admission path the host Claude Code, Codex CLI, ChatGPT desktop tool call AgentGuard hook local rule check, no socket, signs the decision allowed the tool runs refused the call stops error or timeout fail-open: allowed, reason recorded if logging works signed record ledger on disk hash-chained, Ed25519: tool id, input hash, decision stays here: prompts, tool input and output, file content, keys, receipts beside the hook, outside the admission path detached worker license, seats, policy sync, Team caps Score skill (MCP tool) five answers, only after you say yes identifiers, numbers policy on a Solo push agentguard.run POST /api/license/validate · license key POST /api/license/seats · about every 5 min GET and PUT /api/org/policy · policy sync POST /api/team/reserve and /release POST /api/team/counts and /waste · to 0.6.1 POST /api/score · the five answers nothing from the ledger, policy or key
  • the tool admission path, on your machine
  • allowed
  • refused
  • hook error or timeout: allowed, reason recorded
  • worker traffic: identifiers and whole numbers; the policy only on a Solo push
Hooks never open a socket. Apart from the Score answers and the Team upload commands you run by hand, every request leaves from a detached worker that runs outside the tool admission path. Licensing and Team caps requests carry identifiers and whole numbers: a license key, a machine fingerprint, a process id, a policy hash, a member or seat id, an amount and the UTC day and month. An explicit Solo push uploads the policy configuration, and the two Team uploads, off until you turn them on, carry signed daily and weekly totals. The inventory below shows each field.

Fail-open means loss of protection can allow an action. It is an availability choice, not evidence that the action was safe. Host permission checks still apply. A timeout or failure allows the call and records a reason when local logging is available; a dead worker, full disk or inaccessible directory can leave a gap.

A receipt you can inspect

The example below comes from a synthetic local command processed by the real plugin. It contains decision metadata and a cryptographic signature, without the command arguments or output text.

Synthetic local benchmark receipt. No customer session. The example records an allow decision for Bash. Download the receipt and public key.

local record · sequence 0allow
decision
allow · tool_policy_allowed
tool
Bash · capability tier data_write
input
sha256 e4f9dad9…b68ef6 · 32 bytes · 1 key
what is absent
the command, its output, the prompt
policy
agentguard-codex v1 · enforce
time
2026-09-20T19:31:20.651Z
previous hash
0000…0000 (first entry)
entry hash
4cb1b599…4da907
signature
Ed25519 7ddb87ee…35be808
signer
3d0245b28ea0e960 · key 1587ee82…9ea51b
the signed JSON and verification keyVerify it at /verify
{
  "note": "Synthetic local benchmark receipt. No customer session.",
  "public_key_hex": "1587ee82dcd2d77fd62f0fb37f6c45d4e62e384f678cb70dfd7578ef459ea51b",
  "receipt": {
    "sequence": 0,
    "decision": {
      "actor": {
        "tenantId": "synthetic-overhead",
        "agentId": "synthetic-overhead",
        "sessionId": "synthetic-overhead",
        "provider": "codex"
      },
      "decisionId": "363be4ac-1ef5-46d4-963b-64211b59c8b8",
      "timestamp": "2026-09-20T19:31:20.651Z",
      "action": "allow",
      "triggeredCap": null,
      "triggeredScopeKey": null,
      "projectedCents": 0,
      "windowSpendBefore": 0,
      "windowSpendAfter": 0,
      "provider": "codex",
      "modelRequested": "Bash",
      "modelResolved": "Bash",
      "policyId": "agentguard-codex",
      "policyVersion": 1,
      "enforcementMode": "enforce",
      "reasons": [
        "tool_policy_allowed"
      ],
      "costBasis": {
        "inputCentsPerKtok": 0,
        "outputCentsPerKtok": 0,
        "rateSource": "override:manual"
      },
      "plugin": {
        "host": "codex",
        "schema": "agentguard.codex.v1",
        "requestId": "c71005d5-510d-49ed-8e1e-187630065d32",
        "gate": "spend",
        "toolName": "Bash",
        "toolUseId": "overhead-warmup",
        "sessionId": "synthetic-overhead",
        "inputSha256": "e4f9dad917af7e49307be421d1743f1c5eb5f2e44810357d150721d659b68ef6",
        "inputBytes": 32,
        "inputKeys": 1,
        "startedAt": "2026-09-20T19:31:20.552Z",
        "event": "decision",
        "capabilityTier": "data_write",
        "unitCostCents": 0,
        "chargedCents": 0,
        "chargedWindows": [],
        "license": {
          "paid": true,
          "tier": "startup",
          "seatsUsed": null,
          "seatLimit": 10,
          "expiresAt": "2026-09-21T19:31:20.508Z",
          "mode": "enforce",
          "reason": null,
          "offlineGrace": false
        }
      }
    },
    "previousHash": "0000000000000000000000000000000000000000000000000000000000000000",
    "entryHash": "4cb1b599f8a51605850bc111406235457008f85eb565cedbc5ff7a386e4da907",
    "signature": "7ddb87ee4f5d597c20e81817606820c5b524ac0ea60db527d96f4712b47819a3bf7a1c58a413fc4e0dce8eee8ee96ef8ce6e50aed187a97a1eae813b135be808",
    "signerFingerprint": "3d0245b28ea0e960",
    "publicKeyHex": "1587ee82dcd2d77fd62f0fb37f6c45d4e62e384f678cb70dfd7578ef459ea51b"
  }
}

Receipts include a tool identifier, input SHA-256, encoded byte counts, actor identifiers and decision or outcome fields. Outcome rows link to the earlier decision. Missing host success evidence stays unknown. A valid signature shows that the signed bytes match the key; it does not prove that the host executed the tool or that every action was recorded.

The network inventory

Hooks never open a socket. The detached worker performs licensing, configuration and Team requests outside the tool admission path. Its requests are listed here: policy sync when you add a Solo key, Team caps on a Team license, and two Team uploads that stay off until you turn them on. One request lives outside the worker: the five AgentGuard Score answers and your report-link choice, sent by the MCP tool only after you say yes to the named origin.

DestinationWhat is sentWhen and why
POST /api/license/validateLicense key.The worker checks license eligibility at session start or explicit activation.
POST /api/license/seatslicense_key, machine_fingerprint, process_id, org_policy_sha256 or null. On a Team license, member_id as well when one is entered.Registration, then a heartbeat about every five minutes while the session is live.
GET /api/org/policyLicense key in the Authorization Bearer header. No request body.Separate configuration lookup at session start and every fifth heartbeat. Solo receives its personal policy; Team receives its admin-published policy. Unpublished policies receive no content.
PUT /api/org/policySolo license key in the Authorization Bearer header; Content-Type: application/json; body {"policy":{...}} containing only validated policy configuration. Maximum 64 KB. No key inside the body.Only when you run node runtime/policy-cli.cjs push. The detached worker uploads it. The response is the same version, publication time, SHA256 and policy envelope as the GET.
POST /api/team/reservelicense_key in the body; member_id when one is entered, otherwise seat_id, a SHA-256 of the license key and the machine fingerprint; kind, tokens or usd_cents; amount, a whole number; windows, the current UTC day and month.Team licenses only, with nothing to turn on. The worker reserves a block of the team's shared allowance at session start and again in the background when its cached block runs low. While the team has no cap for a kind, it asks again at most every 15 minutes. Each request has a two second deadline; a hook never waits on one.
POST /api/team/releaselicense_key in the body; member_id or seat_id as for a reserve; grant_id; unused, a whole number.Team licenses only. Returns the unused part of each block the worker holds: when the last live session ends, at the UTC day change, when the owner changes the caps, when the worker stops and when a kind turns out to have no cap.
POST /api/team/countsLicense key in the Authorization Bearer header. Body: payload, publicKey and signature, signed with this machine's receipt key. The payload is schema, date, seatId (the SHA-256 above), counts (launches, allowed, asked, saidYes, stopped, shadow, unrecorded, unresolvedAsked) and tokens, the day's token total.Off by default. Only with AGENTGUARD_TEAM_COUNTS=1, after you run node runtime/counts-sync.cjs on, on a paid, registered Team seat. One request per completed UTC day, sent after a session's closing receipt is written and at most once a minute. node runtime/counts-sync.cjs off stops it. Removed in plugin 0.6.2: only 0.6.1 and earlier can send it, and agentguard.run has no endpoint for it, so nothing sent was stored.
POST /api/team/wasteLicense key in the Authorization Bearer header. Body at most 4 KB: payload, publicKey and signature, signed the same way. A week payload is schema, weekStart, seatId and the Burn week figures kept by node runtime/counts-sync.cjs week: tokens and usdMicros (total, useful, waste, unattributed; dollars null when unpriced), causes, reloadsByCause, subagentTokens, wrongModel, topCause and basis. A share payload is schema, seatId, share (off, totals or seat) and setAt.Off by default. Only with AGENTGUARD_TEAM_WASTE=1, your choice of waste totals or waste seat in node runtime/counts-sync.cjs, a paid, registered Team seat, and a completed UTC week you opened with its week command. The worker sends your share choice first, then at most one week per request. waste off sends a signed off choice for a seat that shared before, from the command itself. Removed in plugin 0.6.2: only 0.6.1 and earlier can send it, and agentguard.run has no endpoint for it, so nothing sent was stored.
POST /api/scoreFive questionnaire answers, report-link choice.Only when you run the score skill and say yes.

The default destination is https://agentguard.run. An operator can override only the license-validation base URL with AGENTGUARD_LICENSE_ENDPOINT; seat and org-policy endpoints stay fixed, and so do the four Team endpoints. Free sessions without a license key make no licensing fetch. The license and seat POSTs carry identifiers only; the Score POST carries the five answers and nothing from the ledger, policy or key. Policy GET and PUT share a third endpoint. The Team caps POSTs carry the identifiers, kind, whole numbers and UTC dates listed above. The counts and waste POSTs carry signed totals, never ledger rows, paths, tool names or arguments. Policy requests are limited to 120 per IP per minute, with 60 GETs and 10 PUTs per license per minute. Failed Solo sync requests select the local policy and do not cause a tool denial. The license key is a credential and should be kept private. HTTP connections also expose ordinary connection metadata such as source IP. A matching policy hash reports a loaded version; it does not attest enforcement.

Stays on your machine

Tool arguments and output, prompts, file content, provider keys, signing keys, signed decisions, input hashes and byte counts are not sent by these requests. Guard Pack matching uses arguments in memory and records rule IDs, not the arguments.

Synced configuration is server-held

The dashboard stores the org policy your admin publishes, machine labels, revocation state and invite addresses. Solo stores the policy configuration you explicitly push. The upload selects allowed policy fields from the local configuration; it does not upload local files, the license key or unrelated settings. Free users have local presets and customization without a network request. The policy uses a strict field allowlist; custom prompt or document fields are rejected.

Installation can download packages from registries. Your host still calls its model provider, and an allowed tool can make its own requests. This inventory describes the plugin's runtime, not every program on the machine.

Measured on this plugin

Local hook overhead: p50 98.869 ms; p95 105.765 ms. Added inference tokens: 0.

Measured 2026-09-20 on Mac14,6 (Apple M2 Max, darwin), Node v22.17.1 arm64, using 1,000 synthetic tool-hook invocations after one excluded worker warmup. Wall time includes Node startup, local rule checks, file IPC and a signed decision. The separate Burn hook and session startup are not measured. Read the benchmark record and samples. Its authored synthetic commands describe the test; they are not customer session content.

False positives on 356 benign commands: 0.

Measured 2026-09-20 on Apple M2 Max (darwin), Node v22.17.1 arm64. Static command strings were scanned, not executed. Hard-reset examples use an explicit feature-branch context. This result covers the named corpus, not arbitrary commands. Read the corpus measurement.

Cost exposure, with limits

CostWhat to inspectLimit
Hook overheadMeasured local latency in the benchmark above.A machine-specific observation, not a latency guarantee for every host or cold start.
Model gradingLocal rules use no inference tokens.Host and tool model usage remains separate and can still incur charges.
Configured tool chargeA policy may assign a unit cost and apply scoped caps.An unpriced tool defaults to zero configured charge; that does not make the tool free.
Provider usageYour provider's usage record and invoice. Burn can explain local recorded token usage.API list-price equivalents are not a subscription bill or a promise of avoided cost.

Free Enforce on one machine, Solo at $19 per month or $190 per year for up to three machines, and Team at $19.90 per seat per month or $199 per seat per year, starting at three seats; provider usage is billed separately.

Read plans and trial terms.

Facts for the reviewer

Coverage depends on the host

Rules cover tool calls the host sends to trusted hooks. Disabled hooks, unsupported host paths and tools outside that boundary are not governed. Protect policy and hook configuration when they are organizational controls.

Metadata can still be sensitive

Actor IDs, tool names, input hashes and local paths can reveal context even without content. Restrict access to local ledgers and signing keys. Export only to a destination you choose.

Failures are visible when storage works

A timeout or failure allows the call and records a reason when local logging is available. A dead worker, full disk or inaccessible directory can leave a gap. An absent receipt does not prove an action did not happen.

Rule checks have a defined scope

Guard Pack rules use fixed built-in IDs and stop, warn or off modes. They are not a complete shell interpreter, a malware detector or a proof that allowed code is safe. Review the rules and the benign test corpus.