Skip to content

feat(guardrails): guardrail events reach the platform with fleet counts, and credentials in tool output are hidden from the model (abilityai/trinity-enterprise#165) - #4425

Draft
AndriiPasternak31 wants to merge 62 commits into
devfrom
AndriiPasternak31/ent165-guardrail-events
Draft

AndriiPasternak31 wants to merge 62 commits into
devfrom
AndriiPasternak31/ent165-guardrail-events

Conversation

@AndriiPasternak31

@AndriiPasternak31 AndriiPasternak31 commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Closes abilityai/trinity-enterprise#165 (GUARD-004 and GUARD-005). This PR carries the issue's whole scope. The keyword names another tracker, so it does not move the issue's status; that is set by hand after merge.

Draft until the manual UI sign-off is given. The two new UI surfaces (the Guardrails card on Operations › Health and Recent events in Settings › Guardrails) have not been visually accepted in a browser, in either theme. This PR stays a draft until that sign-off.

Order and couplings.

Why

The guardrail hooks wrote every decision (a Bash or file deny, a turn-tier refusal) only to /logs/guardrails.jsonl inside the agent container. Nothing read that file, it is lost on recreate, and it is readable only while the container runs. So the platform could not say that a run was refused, or that an agent had stopped reporting: #4281 is the concrete case, 78 hook denials over about 25 hours while every execution read success.

The PostToolUse output scanner only logged a credential match. The model still received the value, and from there it could reach a reply, a commit or the next tool call.

This PR makes guardrail decisions a platform record with an honest fleet view, and turns the scanner into an enforcing control: a credential in tool output reaches the model as a placeholder.

What changes

Guardrail events: a versioned record in the agent, forwarded under the agent's own key

  • Spool record (hooks/lib.py). log_event adds v, event_id (uuid4), kind and hook (derived through one frozen table), code (defaults to the legacy event name), execution_id (read once from the parent process's TRINITY_EXECUTION_ID), and the CLI's conversation and tool-use ids. The derived fields win over a caller's, and a fault in the derivation still writes the legacy record. Existing fields are unchanged (additive only). Public enums: EVENT_KINDS, EVENT_HOOKS, SPOOL_SCHEMA_VERSION.
  • A stable code at every deny site: bash (bash_deny_pattern, bash_agent_rule), file (protected_path, path_agent_rule), read-only (read_only_path), turn-tier (shell_owner_only, shell_visitor_off, mcp_owner_only, mcp_visitor_off, owner_only_path, owner_only_search, tier_unreachable), skill gate (skill_refused, skill_check_unreachable). The bash, file and read-only denies also pass rule=, so a forwarded deny says which baseline row fired; turn-tier-guard.py passes the turn's kind as turn_kind=. An AST guard fails any hook call that passes a reserved field (kind, v, event_id, hook, execution_id) or a deny without code=.
  • Forwarder (agent_server/guardrail_events.py, wired in main.py the way the heartbeat is). It tails the spool with a persisted offset, projects each record to an allowlist (no command text, traceback or error is ever sent), sanitizes rule/path, and posts batches of ≤500 events and ≤255 KiB with Authorization: Bearer <TRINITY_MCP_API_KEY>.
    • Flush within 2 s of an append; a keepalive every 5 minutes carrying runtime, so a reachable agent never crosses the platform's 15-minute stale window (pinned: keepalive + max backoff < 900 s).
    • 413 halves the batch; 422 drops and counts it; 429 waits Retry-After (clamped 1 s–1 h); 401/403/404 keep the spool, log once and retry hourly; 5xx and transport errors back off from 2 s to 5 minutes and keep the data.
    • The spool rotates at 5 MiB with a 2 s grace for writers holding the old descriptor; a second rotation waits out the first one's grace; a cut-short last line in the rotated file is counted and skipped; records without v are skipped. A lone surrogate becomes U+FFFD (an id holding one is dropped) and a timestamp outside float range is counted as dropped, so no single line can stall the queue.
    • With no TRINITY_MCP_API_KEY or TRINITY_BACKEND_URL the loop does not start and logs "disabled". Runtimes other than Claude Code run no hooks and send keepalives only.

Guardrail events on the platform: store, own-key ingest, owner read

  • Table guardrail_events on both migration tracks (Invariant Fix git pushing bug #9): SQLite migration guardrail_events_table and Alembic 0124_guardrail_events, plus db/schema.py and db/tables.py. UNIQUE(agent_name, event_id); indexes on (agent_name, occurred_at), (execution_id) and (received_at); execution_id carries no foreign key.
  • Store db/guardrail_events.py with database.py facade methods. The insert is on_conflict_do_nothing(...).returning(id), so accepted and duplicate counts are exact on both dialects. Reads page by keyset on (occurred_at, id). Service services/guardrail_event_service.py, router routers/guardrail_events.py (# mcp: none header), models in models.py.
  • POST /api/agents/{agent_name}/guardrail-events accepts the agent's own TRINITY_MCP_API_KEY only (a sibling agent's key, a user key and a connector key get 403). Body {"schema":1,"runtime":…,"events":[≤500],"dropped":n}, ≤256 KiB. Answers 200 {accepted, duplicates, rejected}, 413 over the caps, 422 for a malformed envelope only, 429 with Retry-After past 60 posts per minute per agent.
    • One bad event never fails the batch: an unknown kind or hook is stored as other with the raw value kept; a malformed event is counted in rejected; an over-long execution_id is nulled; rule and path go through the credential sanitizer; a NUL or lone surrogate in a display field is stored as U+FFFD, and an id holding one is dropped, so one unstorable character can neither fail the batch nor break the owner's later read.
    • The own-key check runs again once the body has been read, so a post still uploading when the agent is deleted or renamed writes nothing under the retired name.
    • An event dated in the future is stored at its receive time, with the agent's value kept in details.occurred_at_reported; it is never rejected, so a skewed agent clock loses nothing.
  • GET /api/agents/{agent_name}/guardrail-events, owner tier through OwnedAgentByName (uniform 404, SEC: User and Agent Enumeration via differential API responses #186). Filters kind, since/until, limit (≤200), keyset cursor.
  • Reporting state on every read: {state: reporting|stale|never, last_report_at, first_report_at, runtime, dropped_total}. stale after 15 minutes without a report. first_report_at is the receive time of the agent's first accepted report (first write wins in Redis; the oldest stored row is the fallback; capped at last_report_at), so a consumer can tell "before this agent was covered" from "covered and clean". A lost Redis moves it later, never earlier, and the create path clears a recycled name's reporter state so a new agent never inherits a predecessor's start.
  • count_by_execution(agent_name, execution_ids), the read-time seam A schedule created by a non-owner-tier person silently loses the shell on every run, and the run still reports success #4281 uses: {reporting, executions: {id: {by_kind, by_hook_code}}}, reading the reporting state before the counts and filtering by the authenticated agent.
  • Lifecycle and retention. Rows CASCADE with the agent and follow a rename (AGENT_REFS); the reporter key is cleared on teardown (CLEARED_KEYSPACES). Retention is 90 days on received_at (so an agent-reported date cannot keep a row forever), through the guarded prune (guardrail_event_retention_days in OPS_SETTINGS_DEFAULTS, bounds 0–3650).
  • Censuses: the POST is tier self in agent_route_tiers.json and AGENT_CALLABLE_ANY in _route_census.py; the GET is owner tier; FROZEN_BASELINE_COUNT is unchanged. The fleet-reach guard (test_ent872_fleet_reach.py) lists the fleet read's roster function, guardrail_event_service.fleet_agent_names, in its allowlist with the reason: its one caller is the require_person route below, which decides the fleet-wide roster with dependencies.is_fleet_admin.

Fleet counts and two UI surfaces

  • GET /api/ops/guardrail-stats?hours= (ops_router). Gate Depends(require_person): a browser login or the person's own user key; agent, system, ops, connector and portal-delegate keys get 403, and a Workspace-only person is refused by the operator floor. An admin sees every live agent; anyone else sees the agents they own, not those shared with them. hours is 1–2160 (the retention window), checked in the route and again in the service.
  • fleet_stats returns {hours, since, events, by_kind, coverage: {reporting, stale, never, no_hooks}, agents: [...]}. Every agent in scope is a row, with or without events, loudest first; coverage is no_hooks when the container's runtime label is not Claude Code, otherwise the reporting state. reporting_states(names) is a batch read (one Redis pipeline plus one grouped MIN/MAX(received_at) fallback query) built on the same helper as the single-agent read, so the two cannot drift. Models GuardrailStatsAgent and GuardrailStatsResponse.
  • Operations › Health: a "Guardrails (24 h)" card (GuardrailStatsCard.vue, admin tab): the total and a badge per kind (the total reads —, with the reason, when no agent reports), a tally per coverage state, and a bounded, scrolling list of agents with events or without coverage, each opening that agent's Settings › Guardrails. The tab's 30 s refresh reloads it in place.
  • Agent › Settings › Guardrails: "Recent events" (GuardrailEventsSection.vue, owner tier): one coverage notice, then up to 50 rows from the last 24 h (kind badge, hook · code, tool and path/rule/patterns, time).
  • The empty states are the same on both surfaces and never read silence as a clean zero: "No guardrail events in the last 24 h" (only while the agent reports), "This agent isn't reporting guardrail events (older image)", "Not reporting since ", "Guardrail hooks run on the Claude Code runtime only".
  • stores/guardrailEvents.js (fleet and per-agent state with their own loaded and error flags; a late read for a previous agent is dropped) and utils/guardrailEvents.js. A skeleton on the first load only (no bare loading gate), LoadFailed on a failed first read, the stale banner on a failed refresh (which keeps the data). Both surfaces sit last in their container, so their variable-height lists move nothing above them. Design-system tokens only; the new files carry zero raw palette classes.

The output scanner hides credentials from the model

  • Bash (hooks/output-scanner.py, rewritten). On a successful call it returns a shape-preserving updatedToolOutput: every string leaf (lists and structuredContent included) is scanned and each match becomes [REDACTED:<shape>]. Clean output prints nothing and is byte-identical.
    • One matcher, with a first-character lookahead. All shapes compile into one matcher behind the left boundary. When every shape shows the character it starts with (all shipped shapes do), a lookahead on those characters follows the boundary, so a position no shape can start at fails at one test instead of trying all fourteen. The matches are the same; a shape whose text does not show its first character (an optional first character, a top-level |, a comment, flag or conditional group) turns the lookahead off. This keeps escape-dense output cheap: 8 MiB of backslashes took 10.9 s of CPU on a CI runner before it; in process it drops from 1.4 s to 0.5 s, and ESC [ from about 2 s to 0.7 s.
    • Large output: when the CLI saved the output to a tool-results file, the file is redacted in place (temp file + os.replace), only for a regular file under /home/developer reached without a symlink. Over 8 MiB, or when the rewrite fails, the file is cut to a notice.
    • Fail closed: unparseable input, unloadable shapes, an exception or more than 8 MiB of text withholds every model-facing string with a notice. The hook exits 0, never 2.
    • Failed calls: on CLI 2.1.281 a failed Bash call fires the managed PostToolUse as well as PostToolUseFailure, with the response as an error string. The scanner rewrites that string as a Bash object ({stdout, stderr, interrupted}), which the CLI accepts. The cost: the model receives that result without its error flag (the text still starts Error: Exit code N). A new PostToolUseFailure registration adds a warning to the model and records credential_unredacted.
    • CLI pin: OUTPUT_SCANNER_CLI_VERIFIED = "2.1.281" with a pin guard and the list of CLI facts to re-check on a bump.
    • Events: credential_redacted, credential_unredacted, scanner_error, scanner_oversize, with shape names only, never a value.
  • Read, Grep, WebFetch and owner MCP tools (managed-settings.json). PostToolUse on Read|Grep|WebFetch, PostToolUse on ^mcp__, and PostToolUseFailure on ^mcp__, in the same exec form. On CLI 2.1.281 (read from the binary) a matcher of only letters, digits, _ and | is an exact list of names and anything else is an unanchored regex; so the exact list cannot reach NotebookRead, ReadMcpResourceTool or similar, and the MCP matcher is anchored. A test pins both.
    • Platform MCP tools are exempt, through the same is_platform_mcp_tool predicate the turn-tier guard uses (a test checks the two agree), because some of them hand the agent a credential on purpose.
    • Binary payloads (base64, image_data, a data key beside type: base64) are never rewritten and do not count toward the 8 MiB cap, so images and PDFs pass untouched.
    • A withhold keeps the shape of the tool that produced it, with the number types its output schema requires (a schema-breaking rewrite would be dropped by the CLI): Read becomes a text read whose content is the notice, Grep returns content mode with the notice, WebFetch keeps its numbers and puts the notice in result, MCP keeps its list or string form. Event codes are per tool (read_output, grep_output, webfetch_output, mcp_output, mcp_failure_output, and the Bash ones).
  • Shapes. guardrails-baseline.json credential_patterns holds 14 shapes: the vendor-prefix part of SECRET_VALUE_PATTERNS without Bearer/Basic and without any KEY=value heuristic. One shared credential_boundary decides where a key may start, and all shapes compile into one matcher, so the leftmost key wins in a single pass.
    • A key does not start after a letter, a digit or -, so pod/task-runner-deployment-…, flask-…, disk-… and ?sig= share links are untouched. It does start after _, after a literal \n/\r/\t in JSON text, after a %XX URL escape, and after an ANSI escape (CSI or a short escape, raw or written as \^[/\x1b/\033/\e); the escape is kept in the output. The Slack forms need 20+ characters after the prefix, so short placeholders in fixtures and docs pass.
    • Trinity MCP keys are matched whole, - and _ included: 43 URL-safe characters (what token_urlsafe(32) mints) that end there, or the older alphanumeric form. The same shape is used in both copies of SECRET_VALUE_PATTERNS (backend and agent log sanitizers) and in the Workspace composer guard; in SECRET_VALUE_PATTERNS it moved first, so a log line never keeps part of a key that happens to contain another shape's prefix.
    • A key that colour codes split is redacted whole. When the text holds ESC or a backslash, a second look strips every run of escape sequences (what a terminal shows), runs the shapes again, keeps only matches with an escape run strictly inside them, and maps them back onto the original text. The scanner merges these spans with its first look; both sanitizer copies replace split keys before their per-pattern pass; the failure-path warning uses the same spans. Only the key's own characters go: the escapes it held are written back after the placeholder, in order, so coloured output stays well-formed. The escape grammar is one credential_escape baseline entry, equal to ESCAPE_SEQUENCE in both sanitizers, and _split_keys is AST-identical in all three files (pinned by tests). Plain text skips the second look.
    • The Google API key shape (AIza…) joins SECRET_VALUE_PATTERNS in both copies and the composer guard (google).
  • Write-back guard. file-guardrail.py refuses new content holding [REDACTED: (Write, Edit, MultiEdit, NotebookEdit) and bash-guardrail.py refuses a command holding it, both with code="redaction_writeback_refused", so the placeholder never replaces a real value on disk. The message tells the model to Edit only the lines it needs rather than rewrite the whole file. Write and Edit to .env, .env.*, .mcp.json, .credentials.enc and the CLI's credentials file stay refused by the existing path guard whatever the content (now pinned by a test); an Edit of another line matches against the real file, so the real key stays byte-identical.
  • Image-build smoke (guard002-smoke.py) now requires a deny record carrying v/event_id/kind/hook/code, and checks the scanner's rewrite payload, the absence of the test key on stdout and stderr, the failed-call object, the persisted file, the failure warning, a split sk key redacted whole, Read and MCP redaction, the platform tool left alone, the refusal rows, and (through the matcher rule) that the scanner reaches Read, Grep, WebFetch, MCP and both Bash events.

Docs

requirements/security.md §28.2 (spool and forwarder; the "logged to Vector" line corrected), §28.4 (GUARD-004, status 🚧: fail-safe table, coverage and what it does not reach) and §28.5 (GUARD-005, status 🚧: the event contract, fleet read and empty states); architecture/agent-runtime.md, backend.md, api-endpoints.md, database.md, frontend.md; the guardrails, monitoring, settings and credential-in-chat feature flows; the user docs agents/agent-guardrails.md (what the scanner does and does not cover) and operations/monitoring.md. GUARD-005 stays 🚧 because the requirement text also promises a blocked/allowed ratio, top patterns, notifications and export, which are outside this issue's acceptance criteria (listed under follow-ups).

The issue's acceptance criteria

Criterion Where
Credential matches redacted before the model sees them; shape names logged, never values The output scanner on Bash, Read, Grep, WebFetch and owner MCP tools; events carry shape names only
Guardrail events surfaced platform-side, per agent The forwarder (a pushed equivalent of guardrails.jsonl), the ingest and the owner-tier GET
Fleet counts in the Operations UI with an honest empty state GET /api/ops/guardrail-stats and the Health card; silence reads as never/stale/no_hooks, never as 0
Fail-safe posture defined and documented Withhold on any scanner fault, exit 0; the fail-safe table in §28.4
Redaction does not corrupt legitimate output The shared left boundary; a benign corpus (pod, package and branch names, Slack fixtures, .env.example placeholders, ?sig= links, coloured lines) stays byte-identical; shapes reuse SECRET_VALUE_PATTERNS
Runtime coverage stated honestly Hooks run on Claude Code only; the fleet read reports no_hooks; the user doc says what other runtimes get
Docs §28.2, §28.4, §28.5, the guardrails flow and the user docs above

Tests

New files: test_ent165_guardrail_event_store.py (real rows on SQLite and PostgreSQL), test_ent165_guardrail_event_route.py (the real router over a real DB, only the key lookup stubbed), test_ent165_guardrail_event_retention.py, test_ent165_guardrail_event_contract.py (the backend's kind and hook enums against the hooks' EVENT_KINDS/EVENT_HOOKS), test_ent165_guardrail_spool.py (89), test_ent165_guardrail_forwarder.py (37; the test backend encodes bodies with httpx's own encoder, so tests see the real wire), test_ent165_guardrail_stats.py (the real router over a real DB with fakeredis, single-vs-batch reporting parity on the Redis and the fallback path), test_ent165_output_scanner.py (290), test_ent165_scanner_other_tools.py (62; each case runs the hook only if a port of the CLI's matcher rule says the managed registration selects it), and the frontend specs guardrailEventsSection.mount.spec.js, guardrailStatsCard.mount.spec.js, guardrailEventsUtils.spec.js (mounted over the real store with api stubbed). Updated: test_ent787_guardrail_exec_form.py, test_guardrails.py.

  • Every scanner case runs the hook under its registered env -i … python3 -I -S invocation. Coverage includes the benign corpus with a precondition proving the untightened shapes would damage it; a three-class partition test that fails when SECRET_VALUE_PATTERNS gains a shape not classified here; withhold on a forced exception without exit 2; 2000 minted MCP keys found whole; an 8 MiB case well inside the 30 s hook timeout; and keys split by colour codes (at the prefix, mid-key, every N characters, every -/_, only at the end) for the sk, GitHub, Google, AWS, Slack and MCP shapes in GNU grep, the image's grep, rg and tput styles, raw and JSON-written, through the scanner and both sanitizers; 49 coloured benign lines stay unchanged.
  • Red before: against the unchanged hooks the spool suite is 63 failed / 20 passed (the 20 are additive-only and reserved-field checks, true on both sides by design). Against the tree before the split-key change the scanner tests are 111 failed / 152 passed (the 152 are earlier tests and benign lines that must pass on both), and the image smoke fails with "a key that colour codes split was not redacted whole". On dev's scanner the scanner set is red for behaviour (no rewrite printed, guards absent). On the Bash-only scanner, 47 of 61 first-draft other-tools tests fail, and 25 still fail with only the registration applied, so they are red for the scanner's behaviour, not only the matcher.
  • Mutation runs, each from a scratch copy restored byte-identical and each turning named tests red. Store and ingest: unknown kind rejected instead of stored as other; no ON CONFLICT; any valid key accepted; counts not filtered by agent; GET at accessor tier; prune on occurred_at; sweep not in the cleanup cycle; retention default lowered; the AGENT_REFS entry removed; no rate or byte cap; path and rule not sanitized; no receive-time clamp; first_report_at last-wins, read from the newest row or dropped from the model; the create-path clear removed (red in test_1484); the unstorable-character handling removed; the second own-key check removed. Forwarder and spool: command_prefix allowlisted, sanitize removed, 3 s debounce, no rotation grace, rotation loss not counted, 413 never splits, 404 backs off, offset committed on failure, no keepalive, 422 not counted, no backoff growth, records without v forwarded, Retry-After ignored, 401/403 falling into the 5xx backoff, a caller overriding a derived field, a constant event_id, a deny losing its code, the smoke's record check skipped. Fleet read and UI: a non-admin sees every agent (7 red); shared agents included (5); require_person replaced by get_current_user (5); coverage ignores runtime (4); only agents with events listed (8); the batch read drops the fallback (2); the empty copy shown whatever the coverage (3); stale read as never (3); a failed first read shown as loaded; the skeleton on every fetch; a failed refresh blanks the card. Scanner: no left boundary; withhold keeps stderr; no symlink check; exception not caught; no persisted redaction; no failed-call Bash object; no write-back guard; the MCP shape back to alphanumeric in the baseline or either sanitizer copy or the composer guard; the old pattern order; _, \n/\t, %XX or the escape lead dropped; shapes run one after another; no second look (56 red); the split step not called in either sanitizer (18 each); escapes not written back (55); the start not mapped back (32); spans not merged (1); the agent copy of _split_keys drifting (parity); no platform exemption (5); no binary skip (6); unanchored mcp__ matcher (22); Read dropped from the matcher (18); Read withhold numbers as strings (2). Lookahead: none built for the shipped shapes (2); a top-level | (3), an optional first character (3), any group form (2) or a class whose first member is an escape (1) read as a first character.

Validation: each area was re-run on dev at 13d32e22f before the areas were merged into this branch — the event store, ingest and retention tests with seeds 11, 22 and 4242: 103 passed, 1 skipped (the contract test, which needs the agent half), and with the fleet read 137 passed, 1 skipped, each time; the forwarder, spool and neighbour set (test_agent_heartbeat.py, test_3106_agent_server_fastapi_telemetry.py, test_2114_subscription_shadow_guard.py, test_2338_journey_catalog.py) 219 passed at the same seeds; the hook suites 2059 passed; test_ent165_* plus the credential-sanitizer suites 383 passed (Bash scanner) and 445 passed (other tools); the guards (#2996 ×5, ent#926 ×3, #1560 ×2, test_agent_cleanup_parity, schema parity, 186, 1310 ×2, models-centralized, 297, cleanup sweeps, 1644, 2085, 1638, retention floor, test_1484, 293, 2323, 837 floor) 1897 passed; frontend specs plus the raw-colour, loading-gate and source-text ratchets 65 passed with no baseline change; npm run check:tokens and npm run build pass; check_alembic_heads.py one head; check_alembic_parity.py pass; a real alembic upgrade head on PostgreSQL reached the revision (then numbered 0123_guardrail_events) with all indexes, and a downgrade and re-upgrade rebuilt them. test_ent926_turn_tier_hook.py fails 39 cases on macOS only (/home resolves under /System/Volumes/Data), identically on untouched dev; it passed 163/163 in a Linux container (Python 3.13). The enum contract test, which needs the agent and backend halves on one tree and skips otherwise, runs and passes on this branch (2 passed). The merges into this branch conflicted only in docs, tests/registry.json and guard002-smoke.py (both the deny-record and the scanner checks kept). After merging dev at 97a86f1dc (conflicts in file-guardrail.py — dev's .env denial sentence and the write-back refusal both kept — db/migrations.py and tests/registry.json): check_alembic_heads.py one head (0124_guardrail_events), check_alembic_parity.py and check_sqlite_upgrade_parity.py pass; schema parity, the Alembic guards, the test_ent165_* suites, the file-guardrail and guardrail-registration suites and dev's ent#1158 and ent#1202 suites 1041 passed, 2 skipped; the scanner suites and the files that read the guardrails flow 716 passed. dev at b99c23f6e (#4447, tests only) was merged after that without conflicts.

CodeQL flags guard002-smoke.py (clear-text storage): the build smoke writes its own synthetic key ("sk-ant-api03-" + "A" * 93, named SECRET) into a temp file it deletes, to prove the scanner redacts a persisted output file. The query tags the value by its variable name only; no credential is involved.

Mutation: n/a — not a fix

Unverified: the split-key change on a live agent (proven by the tests and the image-build smoke only; the live run found the case and predates the change); rg output (not installed in the agent image); WebFetch live (the CLI refuses a dotless host and upgrades plain HTTP to TLS, and no TLS page holding a test key was available; unit-tested with the shape captured from the CLI); Grep live (the pinned CLI ships no Grep tool; the shape comes from the binary's output schema); a PDF Read (unit only); a lone surrogate written by the real CLI (unit-tested through httpx's encoder); an agent-server restart within 2 s of a rotation; a real turn on the other non-Claude runtime (its CLI reached the provider, which refused the test account); Python 3.13 and the full unit suite (CI); the UI look (pending sign-off below); the scanner's first-character lookahead in an agent container (unit-tested and measured in process only). The live run predates the merge of dev at 97a86f1dc and the renumbering to 0124; the PostgreSQL upgrade under the new number is CI's pg-migrations job.

Verified on a live stack

Production images built from one tree holding these changes together with the public ent#863 and #4281 changes on the dev of that time, on the prod compose stack (PostgreSQL 16, Redis with ACL users, two backend workers), with real agent containers on Claude Code CLI 2.1.281. The first pass used a scripted model endpoint (CLI, hooks, agent server and platform real; every request the CLI sent was logged); the scanner cases were then run again with real model turns through a pass-through logging proxy that recorded every tool result the model received. Also checked: the stored stream-json, the tool-results files, the transcripts and the agent's guardrail log.

  • Migration: recorded on an upgrade of a database made by the dev image and on a fresh SQLite install; the real init_database on PostgreSQL moved from 0122 to the guardrail revision (then 0123_guardrail_events, now 0124 on 0123_agent_ownership_default_model) with one head and the table and indexes present.
  • Ingest and read: own key 200; sibling agent key, owner user key and owner JWT 403; a resend counts as duplicates. The owner and an admin read rows and state; a shared non-owner gets a 404 byte-identical to a missing agent's. A NUL in tool stored as U+FFFD on PostgreSQL; a surrogate in path does not break the GET. Cleanup cycles ran the sweep with no prune error; rows followed a rename; the hard purge left no rows and no reporter key. An event sent three days ahead was stored at its receive time; first_report_at stayed put across later reports, a Redis restart (AOF on) and a backend restart; after a real FLUSHALL the database fallback gave the oldest row's receive time; a same-name recreate got its own start.
  • Forwarder: guard002-smoke.py and skill-gate.py --self-test passed in the image build. A Bash deny landed as a row with hook=bash_guardrail, code=bash_deny_pattern and the execution id about 1.2 s after the hook fired; a shared person's turn landed shell_owner_only with turn_kind: person; no command text in the stored row or the posted body. About 5 s after start the agent read reporting (runtime claude-code); a Gemini agent sent keepalives only; an agent without forwarder settings logged "disabled" and never posted; an agent on an older image stayed never. Against a 404 backend: one INFO line, spool kept; after a restart against a 200 backend the backlog was delivered. docker restart resumed at the same offset with no resend; a recreate started a fresh spool; the spool rotated past 5 MiB with no gap; a stop right after a deny still delivered it within the 10 s grace.
  • Fleet read: the route is in OpenAPI. An admin sees every agent with coverage; a creator sees only their own (an agent only shared with them is absent); the system key, the ops key and an agent key get 403; hours=0 and hours=2161 get 422; a Workspace-only user gets 403 workspace_only. A Gemini agent reads no_hooks; an agent stopped 14.5 minutes still read reporting and at 15.8 minutes stale. The grouped fallback and fleet_stats ran on PostgreSQL; after a real FLUSHALL the fleet read gave the same first_report_at as the per-agent read.
  • Scanner: every agent started with no GUARDRAILS: ERROR and guardrails_registration: ok; rm -rf / still denied, ls ran. A key on stdout read [REDACTED:sk], on stderr [REDACTED:github]; a 39 KB output's persisted file was redacted; an exit-3 call read [REDACTED:sk] with the warning and a credential_unredacted record. The agent's own MCP key (with -/_ in its first 16 characters) read Bearer [REDACTED:trinity_mcp] through cat and Read of ~/.mcp.json, with no fragment of it anywhere on record; Read of .env → [REDACTED:sk]; a background command's output read back from its tasks file was redacted; an owner MCP result and error were redacted (the error with the warning). grep --color=always output kept its colour codes around the placeholder; the JSON \n/\t, %3D, KEY_ and prefix_ cases were redacted; the CLI accepted every rewrite. A model-typed key in a command was stored as ***REDACTED*** in both copies of the execution log. mcp__trinity__list_agents untouched; a real share_file link kept its ?sig=; pod/task-runner-… passed byte-identical. Read → Edit kept the real key on disk; a whole-file Write of [REDACTED:sk] was refused with the placeholder message. In a shared person's turn, Bash, the owner MCP tool and the .env path were refused by the turn-tier guard and an allowed Read still redacted. 8 MiB through the managed hook in a 1-CPU agent container: 2.1 s for 8 MiB of ESC[, 0.6 s for log text, 1.5 s for backslashes (before the split-key change; in-process that change moves ESC[ from 1.80 to 2.05 s and backslashes from 1.26 to 1.37 s, and leaves log text at 0.40 s). A Gemini agent started and ran a real turn (no hooks on that runtime, as documented).

Pending

  • Manual UI sign-off of the Operations › Health card and Settings › Guardrails › Recent events: both themes, phone width, the four empty states, the stale banner, the bounded list scrolling inside the card, and that nothing above either surface moves. Not driven in a browser yet. The PR stays a draft until it is given.

Unfiled follow-ups

  • Retention window in the Settings UI and user docs — guardrail_event_retention_days is not in retentionFields.js or the monitoring retention table.
  • An MCP tool for guardrail events — the read is UI/REST only.
  • Show dropped_total on Recent events and the Health card — lost events are counted but not shown.
  • Timestamp reported drops — dropped_total is cumulative with no time, so a consumer cannot tell which runs a drop may cover.
  • last_report_at is last-write-wins — a delayed report can move it earlier, so an agent can read stale early.
  • Bound the coverage start by the agent's creation time — for Redis being down during both a teardown and the next create under the same name.
  • Recent events refreshes on neither a timer nor focus — a pane left open past 15 minutes keeps its last reporting state until reload.
  • Paging or a wider window in Recent events — the API already pages with a cursor.
  • Admit the ops key to the fleet read, if the ops agent should read guardrail counts (a reviewed scope grant).
  • The rest of GUARD-005 as the requirement words it — blocked/allowed ratio, top patterns, notifications (see spike: Rippletide integration for agent evaluation and persistent memory #141), export.
  • SIGTERM trap in startup.sh — let the agent server flush on stop instead of being killed after the grace.
  • Persist the rotation time — so a late hook write in the rotated file is counted across an agent-server restart inside the 2 s grace.
  • Bound _count_events by the line limit — a line far beyond any hook record is read whole on the event loop.
  • Isolate a batch that draws the same 5xx repeatedly — so one event a backend bug chokes on does not hold up the agent's whole record (visible today as stale).
  • Conversation and tool-use ids on skill-gate records — the skill gate parses its own stdin.
  • Forward from the system agent — it has no TRINITY_BACKEND_URL, so its coverage always reads never.
  • Post soon after a turn ends — shortens the window in which A schedule created by a non-owner-tier person silently loses the shell on every run, and the run still reports success #4281's refusal reading reads pending.
  • Extend split-key recognition in the scanner to the two escape layouts the guardrails flow lists as limits — one needs an approach that still leaves ordinary grep --color output of task-runner-… names untouched.
  • Match a known .env value split by colour codes in the agent log sanitizer.
  • Narrow the sk- and xoxb- shapes — /var/cache/sk-learn-…, an sk-gateway-… host, long placeholders and the AWS docs example key read as keys; the _/escape boundary extends this to my_sk-learn-….
  • Narrow the Workspace composer guard's sk shape — it refuses ordinary text such as a message naming a task-runner-… pod.
  • Let the write-back guard tell a mention from a write-back — code, tests and docs containing [REDACTED:, and a grep for it, are refused.
  • Record credential_unredacted only when the failed call was not also redacted — it overstates counts.
  • Keep the error flag on a rewritten failed call — the model sees a success-shaped result whose text starts with Error:.
  • Bring the frontend display scrub (utils/scrub.js) onto the whole-key MCP shape.
  • Align mcp_validator's literal-secret list with SECRET_VALUE_PATTERNS — its comment no longer claims they mirror.
  • requirements/security.md still says GUARD-004 is not started in one summary line outside §28.4.
  • Extend scanner coverage to Glob, WebSearch, MCP resource reads and the results of agent-spawning tools (Agent/Task).
  • Scan container logs returned through get_agent_logs — either narrow the platform-MCP exemption to the credential-delivering tools or sanitize /api/agents/{name}/logs.
  • Steer a Write that would drop a credential the target file holds to Edit.
  • Make the withhold builders non-recursive with a last-resort notice in the error path (hardening; deep nesting is not reachable through the pinned CLI's WebFetch shape).
  • Redact the original file content that Edit/Write results carry in the stored stream and transcript (the model is not shown it).

Journey Impact

Journey Impact: none: adds guardrail event forwarding, storage and reads, an Operations card and a settings list, and credential redaction in tool output; tool calls run as before and no catalog promise covers guardrail events

… its store (Abilityai/trinity-enterprise#165)

One row per guardrail event an agent reported, unique per (agent, event_id) so a
resend is idempotent (ON CONFLICT DO NOTHING ... RETURNING on both dialects).
SQLite migration plus Alembic 0123 chained after 0122 (one head), DDL in
schema.py/tables.py, indexes for the per-agent read, the per-execution counts and
the retention sweep. execution_id carries no FK. Rows follow the agent through
AGENT_REFS (CASCADE: renamed with it, purged with its hard delete).
…/trinity-enterprise#165)

POST /api/agents/{name}/guardrail-events takes a batch from the agent's own key
only (the heartbeat predicate, outside get_current_user): 413 past 500 events or
256 KiB, 422 only for a malformed envelope, 429 + Retry-After past the per-agent
cap. Each event is validated on its own: an unknown kind or hook is stored as
'other' with the raw value, code is an open string, a malformed event is counted
in 'rejected' and never fails the batch, an over-long execution_id is nulled.
Only allowlisted fields are kept, free text sanitized and bounded.

GET is owner tier with the uniform 404 and returns events newest first, a keyset
cursor and the reporting state (never / reporting / stale) kept in Redis and
cleared on teardown. count_by_execution and count_by_agent are the seams the
execution-status and fleet consumers call. Both route censuses list the routes.
…us guard (Abilityai/trinity-enterprise#165)

guardrail_event_retention_days (default 90, 0 disables) is a registered
retention window: validated write path, reported by GET /api/settings/retention,
not a community-floor key. The cleanup cycle prunes rows past it by the server
receive time (an agent-reported timestamp must not make a row immortal), behind
its own _guard_allows site, in bounded chunks.
…cycle harness (Abilityai/trinity-enterprise#165)

The happy-path harness mocks db wholesale, so a new sweep's prune count must be
a real int or the WAL-checkpoint sum raises. Same shape as the ent#433 and
ent#478 sweeps; the test now also asserts the guardrail prune is reached.
…ls its batch or the owner's read (Abilityai/trinity-enterprise#165)

A NUL in a raw-stored field made psycopg2 refuse the whole multi-row insert,
and a lone surrogate did the same on SQLite: the batch 500ed on every retry and
the forwarder stalled behind it. Inside details a surrogate was stored
JSON-escaped and then made every later GET of that agent's events fail while
the response was encoded.

Display text (tool, verb, tier, turn_kind, rule, path) now carries U+FFFD in
place of such a character; an id (execution_id, session_id, tool_use_id) that
holds one is dropped, like an over-long one.
…dy is in (Abilityai/trinity-enterprise#165)

Auth was decided before the body was read, so a body streamed slowly could
outlive an agent delete or rename: its rows landed under the retired name after
the cascade, and its report re-marked that name as reporting after the
reporter was cleared, so a later agent of the same name would read as covered.
The key rows follow the agent (cascaded on delete, re-keyed on rename), so the
second check refuses the write with the same 403.
…e time, not counted in every window (Abilityai/trinity-enterprise#165)

An agent whose clock runs ahead sent events whose occurred_at sat after
every rolling-window cutoff until the row was pruned, so the 24 h counts
(and any since-read) kept counting them. Ingest now clamps occurred_at to
received_at when the agent's ts is later, and keeps the agent's own value
in details.occurred_at_reported. The event is never rejected: a skewed
clock must not cost the agent its record.
…ed, so history before it is not read as clean (Abilityai/trinity-enterprise#165)

A consumer of reporting could not tell a run from before the agent's
first report (never covered) from a covered run with no events: both read
as zero. The reporter hash now records first_report_at with HSETNX (first
write wins), and reporting carries it: the stored value, else the oldest
stored row's received_at when the fast store lost it, else the last
report. Every fallback is at or after the true first report, so a lost
fast store only moves coverage later, the safe direction. It is null
exactly when the state is never. The response model carries the field so
the GET does not drop it.
… after the last report, and is read before the counts (Abilityai/trinity-enterprise#165)

Three gaps a second review found in first_report_at, each proven by a
test that failed first:

- A recycled name inherited its predecessor's reporter record when the
  teardown's fail-open Redis clear failed, or an ingest in flight wrote it
  back, so a new agent's unreported history read as covered. The create
  path now clears it beside the #1560 breakers, before the container.
- Two racing reports could leave the start after a later-dated last
  report. The start is capped at last_report_at: the agent did report
  then, so the earlier value is still at or after the truth.
- count_by_execution read the counts before the coverage, so an agent's
  first batch landing between the two reads paired a clean 0 with the
  coverage that batch set up. Coverage is now read first.
…ilityai/trinity-enterprise#165)

The guardrail hooks' records never left the container: §28.2 said they
were logged to Vector, which reads container stdout only. State what
the spool record carries, what leaves the container, how the forwarder
delivers, and the loss window and authenticity limits. Also corrects
the hook file names (.py, not .sh) and the scanner's pattern claim.
…y deny (Abilityai/trinity-enterprise#165)

lib.log_event now adds v, event_id, a derived kind and hook, the turn's
execution_id (read from the claude process's launch environment), and
the hook input's session and tool-use ids. kind and hook are closed sets
owned by lib.py and derived through one frozen table, so later hook
events need no lib.py edit. The existing record fields are unchanged.

Every deny call site passes a stable code. The turn-tier guard records
the turn's kind as turn_kind, since kind is now the record's own field.
The image smoke checks a deny record carries the contract, and the
skill gate's log comment no longer claims Vector reads the file.
…e agent's own key (Abilityai/trinity-enterprise#165)

A new agent-server loop tails /logs/guardrails.jsonl from a persisted
offset and posts an allowlisted, sanitized projection of each guardrail
event: never the command text, a traceback, error text or the deny prose.

Delivery is debounced to within 2 s of an append, since no shutdown
flush runs (bash is PID 1 and has no SIGTERM handler). Batches are
bounded by count and bytes; 413 halves the batch, 422 drops and counts
it, 429 honours Retry-After, 404/401/403 keep the spool and retry
hourly, 5xx backs off with jitter. An empty batch every 5 minutes is a
keepalive. The spool rotates at 5 MiB and stays bounded while the
platform is unreachable, with the overflow reported as dropped. Gated
on the heartbeat's rule: no agent key, no loop. Fails open.
… the forwarder (Abilityai/trinity-enterprise#165)

A hook input can carry an escaped lone surrogate, for example in a
model-written file path. It survives the spool's json round trip, but httpx
encodes the request body as strict UTF-8, so the POST raised before it was
sent, on every attempt. The batch holding that record never left, the records
after it never did either, and the keepalives stopped with them.

The projection now replaces a lone surrogate with U+FFFD in text and drops an
id that holds one, the rule the platform's ingest applies. The test fake
encodes bodies with httpx's own encoder, so the suite sees the real wire.
…nted, not retried forever (Abilityai/trinity-enterprise#165)

A JSON integer too large for a float made math.isfinite raise OverflowError
in the projection, outside every guard, so the forwarder step failed on the
same line every few seconds and nothing after it was delivered. The check now
sits inside the guard, and the line is counted in `dropped` like any other
record that does not parse into an event.
…ated spool (Abilityai/trinity-enterprise#165)

Two corner cases of the spool rotation:

- A hook write cut short (a full disk, a kill mid-write) left a line with no
  newline at the end of `.1`. Nothing appends to `.1` once its grace is over,
  so the forwarder waited there, delivering none of the live spool until the
  next 5 MiB rotation, while its keepalives kept the agent reading as
  reporting. Past the grace that line is now counted in `dropped` and the
  forwarder moves on.
- A second rotation inside the first one's 2 s grace replaced `.1` while a
  hook could still be appending to it, so that write landed in an unlinked
  file, neither delivered nor counted. Rotation now waits out the grace.
…ord check (Abilityai/trinity-enterprise#165)

- 401/403 keep the spool and retry hourly. Only 404 was pinned, so a 403 that
  fell through to the 5xx backoff stayed green. The platform answers 403 to a
  key that is not the agent's own and to one revoked while the body uploads.
- The image smoke's deny-record check is called from main() after the bash
  rows, and it fails a record missing any one of v, event_id, kind, hook or
  code. Before, dropping the call or the kind check stayed green.
… Recent events in Settings > Guardrails, with honest empty states (Abilityai/trinity-enterprise#165)
…its output schema requires (Abilityai/trinity-enterprise#165)

The CLI drops a hook rewrite that fails the tool output schema and shows the
original output, so a withhold with the wrong field types fails open. The
Read withhold tests checked field names only, and nothing exercised the
WebFetch number fix-up; both now fail when those fields stop being integers.
…what the server returns (Abilityai/trinity-enterprise#165)

The scanner skips every mcp__trinity__ tool. The docs said that output is
platform-authored and sanitized by the backend; get_agent_logs returns an
agent's raw container logs, so that is not true for every tool. The real reason
for the skip is that some tools hand the agent a credential on purpose.
…165-guardrail-events

# Conflicts:
#	docs/memory/feature-flows.md
…165-guardrail-events

# Conflicts:
#	docker/base-image/hooks/guard002-smoke.py
#	docs/memory/feature-flows.md
#	docs/memory/feature-flows/agent-guardrails.md
#	tests/registry.json
…bilityai/trinity-enterprise#165)

GET /api/ops/guardrail-stats is require_person and picks the fleet-wide
roster with is_fleet_admin, so an agent key never reaches
fleet_agent_names. List it in the fleet-reach guard's allowlist with that
reason.
… agent's own key (Abilityai/trinity-enterprise#165)

POST /api/agents/{name}/guardrail-events reads the bearer itself and
accepts only the agent's own key, like the heartbeat. List it with that
reason and drive it in the door sweep: the ops_write key gets the own-key
403, the agent's key gets 200.
… not wall time (Abilityai/trinity-enterprise#165)

A shared CI runner stalled the 8 MiB backslash case to 11.3 s of wall
time for a scan that takes about 2.7 s of CPU. Measure the hook process's
CPU so the bound tests the scanner, not the runner.
@vybe

vybe commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Heads-up from an automated build chain (trinity-pm): #4431 also adds an Alembic revision on 0122_channel_client_blocks — 0123_agent_ownership_default_model beside this PR's 0123_guardrail_events. Whichever of the two merges second needs to renumber to 0124 (and #4427, stacked here, follows this branch). Merge order is the operator's call; nothing to do until one of them lands.

@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

⚠️ Alembic head fork if this PR is merged into dev.

dev has advanced since this PR's checks last ran. GitHub recomputes the merge ref when the base moves but does not re-trigger workflows, so a green schema-parity here can describe a base that no longer exists (#2533).

scripts/ci/check_alembic_heads.py against dev + this PR, merged in memory
alembic-heads: FAIL — src/backend/migrations/versions resolves to 2 heads across 126 revision(s); exactly 1 is required.
  • 0124_execution_continues_execution_id  (0124_execution_continues_execution_id.py)
  • 0124_guardrail_events  (0124_guardrail_events.py)

They fork at: 0123_agent_ownership_default_model  (0123_agent_ownership_default_model.py)

`alembic upgrade head` is singular and resolves its target BEFORE applying anything,
so this graph applies ZERO revisions — every revision since the fork stops arriving,
not only the one that forked. Fix by chaining the newer revision off the real head,
or — if the forked revision may already be applied somewhere — by adding a merge
revision (`alembic merge -m "…" <head-a> <head-b>`), whose tuple `down_revision`
converges the line from any starting state. See Architectural Invariant #3.
alembic-heads: src/backend/enterprise/backend/migrations/versions — version directory absent (submodule not initialised) — skipped.

Evaluated on the version line only — this PR also conflicts with dev in 4 unrelated file(s), which do not change this verdict but must be resolved before merge:

docs/memory/architecture/agent-runtime.md
docs/memory/feature-flows.md
docs/user-docs/agents/agent-guardrails.md
src/backend/db/migrations.py

Fix: rechain this PR's revision off 0124_execution_continues_execution_id (the current dev head), or — if the forked revision may already be applied somewhere — add a merge revision (alembic merge -m "…" 0124_execution_continues_execution_id 0124_guardrail_events), whose tuple down_revision converges the line from any starting state. See Architectural Invariant #3.

Push the fix and schema-parity re-checks it against the merge ref immediately; this comment clears on the next push to dev touching src/backend/migrations/versions/**.

Advisory — this check does not block merge. · head_sha: 68bb9cd82651fd2c682674b849fdceb289a6aa72 · run

@github-actions

Copy link
Copy Markdown

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

@github-actions

Copy link
Copy Markdown

⚠️ Live-instance suite skipped — merge conflict against dev.

Resolve by merging dev locally and pushing the result; the next nightly re-tests.

dev now carries 0123_agent_ownership_default_model on
0122_channel_client_blocks, so the guardrail event store's revision moves
to 0124_guardrail_events, chained after it, and the version-line keeps one
head. The SQLite entry follows dev's agent_ownership_default_model.

Conflicts kept both sides: file-guardrail.py has dev's .env denial
sentence and the placeholder write-back refusal; tests/registry.json
holds both sets of entries.
…pe can start (Abilityai/trinity-enterprise#165)

Output that is all backslashes or `ESC [` passes the left boundary at
every position, so the one matcher tried all fourteen shapes eight
million times on an 8 MiB result. On a CI runner that hook took 10.9 s
of CPU, against a 30 s registered timeout and the test's 10 s bound; the
previous change to CPU time had assumed a stalled runner, and the CPU
figure shows the cost was the scan.

When every shape shows the character it starts with, a lookahead on
those characters now follows the boundary. No shape can match anywhere
else, so the matches are unchanged; a position that starts none of them
fails at one test. The reader is conservative: an optional first
character, a top-level `|`, or a comment, flag or conditional group
reads as "not shown", and then the matcher has no lookahead.

In process, 8 MiB of backslashes drops from 1.4 s to 0.5 s and `ESC [`
from about 2 s to 0.7 s; the whole hook on backslashes from 2.8 s to
0.9 s of CPU. Tests pin the lookahead for the shipped shapes, the reader
on each trap with a counterexample the engine matches, the fallback
without it, and identical spans with and without it.
@AndriiPasternak31

Copy link
Copy Markdown
Contributor Author

Thanks — #4431 landed first, so this PR moved: dev is merged in at cd155218a, and the revision is now 0124_guardrail_events on 0123_agent_ownership_default_model, with the SQLite entry after agent_ownership_default_model. check_alembic_heads.py reports one head; the Alembic and SQLite upgrade parity checks pass. #4427 carries the same revision through this branch.

Brings #4447 (httpcore pinned against a sys.modules split). No conflicts.
…65-guardrail-events

# Conflicts:
#	docs/memory/feature-flows.md
…SK (Abilityai/trinity-enterprise#165)

CodeQL read the variable name SECRET as sensitive data and flagged the
persisted-output check, which writes that made-up key into a temp file the
smoke deletes. The value and every check are unchanged.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants