Skip to content

feat(guardrails): tool-access profiles — one choice sets read-only mode and the tools an agent can't use (abilityai/trinity-enterprise#341) - #4232

Merged
vybe merged 3 commits into
devfrom
feature/341-tool-access-profiles
Nov 4, 2026
Merged

vybe merged 3 commits into
devfrom
feature/341-tool-access-profiles

Conversation

@webmixgamer

Copy link
Copy Markdown
Contributor

Summary

  • One "Tool access" choice per agent in Settings › Guardrails: Full access (default), Workspace-only, Read-only + report, Strict read-only, and Custom. A profile is a fixed bundle that sets the read-only layer and the disallowed_tools list together, so the two can no longer disagree. Each card states in plain language what the agent can and cannot do, plus one coverage line for the agent's runtime.
  • Read-only mode is the Strict read-only profile. The header and Dashboard-list Read-only toggle is its shortcut. It shows ON for Strict only. OFF returns the agent to the profile it had before. Both toggles now go through the agents store (the raw fetch / direct axios calls are gone). The General pane's read-only row moved into Tool access.
  • The send block is refused by Trinity, not only hidden. The nine backend routes behind the seven send tools (send_message, send_group_message, send_notification, send_voice_reply, call_user, post_to_room, share_file) and report refuse an agent-scoped caller whose enforced list names the tool. The same refusal applies to the agent a route sends as. It works on every runtime, whatever path the call took (shell, an aliased MCP entry). The tool-list removal stays as a second layer.
  • Nothing changes on upgrade. There's no migration and no base-image change. An agent with no stored profile has it derived from what it already enforces. An agent that was read-only reads Strict read-only · send block not applied, with an Apply button.
  • No MCP surface. No tool reads or writes a profile.
Profile Read-only layer Tools removed Codex --sandbox
Full access (default) off none danger-full-access
Workspace-only off the 7 send tools danger-full-access
Read-only + report on the 7 send tools read-only
Strict read-only on the 7 send tools + report read-only
Custom owner's switch owner's list (≤50 entries, 1–256 chars each) per the switch

How it works

  • Storage. guardrails_config.disallowed_tools and the read-only columns stay exactly what is enforced, so env injection, write-runtime-config.py and the drift check's inputs are unchanged. guardrails_config.tool_access records the choice: the profile, Custom's remembered settings, and where the shortcut returns. The drift check ignores it next to visitor_shell.
  • Writers.
    • The three writers share one compare-and-set over the guardrails blob and the read-only columns: PUT /tool-access (new), PUT /read-only (the shortcut), and PUT /guardrails (keeps the stored profile).
    • A lost race is a 409. Racing live applies converge to the row, and every change writes an audit row with the before and after state.
    • The toggle never loosens silently: ON from a list that removes tools Strict allows is a 409 naming them.
  • Auth.
    • The write gate is the one the two composed routes already use: a person, or another agent holding agents.manage, never the agent on itself. The system agent is refused.
    • GET /tool-access is owner tier. GET /guardrails now shows only the profile id.
    • Both new routes are classified in the human-only census and the agent-route tier table.
  • Code.
    • services/tool_access_profiles.py: the pure policy.
    • services/agent_service/tool_access.py: reads and writers.
    • services/tool_access_guard.py: the send check.
    • agent-settings/ToolAccessSection.vue.
  • Also in this PR.

Stated limits

  • A failed live read-only apply is reported only by the save that tried it (read_only_applied: false, restart_required: true). A later read does not remember it. The next agent start re-syncs the read-only file from the row.

  • Agent-to-agent asks aren't sends. chat_with_agent, fan_out, call_a2a_agent, emit_event and ask_operator are not removed by any profile. So a blocked agent can ask another agent to send, which then sends under its own identity and its own profile.

  • Codex and Gemini enforce what the coverage lines say.

    Claude Code Codex Gemini
    Read-only layer file tools can't write code/config; shell commands aren't covered sandbox blocks every shell command, reads included not enforced
    Send block refused by Trinity + removed from the tool list refused by Trinity refused by Trinity
    Other removed tools (Custom) removed from the tool list not enforced not enforced

Test plan

  • Eyeball passed on 0dab359af. Covered: a legacy read-only agent reading as Strict with Apply, all five profiles and their toasts, Customize → Custom with Bash, the 51-line error, and the header and Dashboard-list toggle round trips. Those include Read-only + report and the 409 naming Bash. Also covered: the Codex and Gemini coverage lines, the restart banner, and both themes. A live check before the restart got the 403 send_notification is blocked by this agent's tool access (Workspace-only)…. After the restart the agent's tool list went 174 → 167, and of the send set only report remained. The dev merge (64c315ce5) and the toast move (dcaae7121) came after the eyeball. The toast is covered by agentListToastPlacement.mount.spec.js, not re-eyeballed.
  • Backend unit:
    • New: test_ent341_tool_access_profiles.py, test_ent341_tool_access_routes.py (compare-and-set race, mutation-proved) and test_ent341_send_block.py (all nine routes driven through their real routers, plus an AST pin).
    • Updated: the census, grants and owner-config suites.
    • Before the merge, the full unit suite ran 35,324 passed with 1 failure, a sys.modules lint hit on the new test file, fixed since. After the merge I re-ran every unit file touching the changed modules: 9,753 passed.
    • The only reds were 39 in test_ent926_turn_tier_hook.py, host-only. Its inputs are byte-identical to dev, and it anchors paths at /home/developer, which macOS lacks.
  • Frontend unit:
    • New mount specs: toolAccessSection, readOnlyShortcut, guardrailsToolAccess, agentListToastPlacement. New plain specs: toolAccess, toolAccessStore. Updated: agentHeaderIdentityEdit.
    • Full suite on the merge: 7,050 passed. 4 spec files fail host-only (they need @vue/compiler-sfc or @vue/compiler-core, or depend on the installed DOMPurify version) and touch nothing in this diff.
    • The token check and the production build pass.
  • /verify-local --skip-agent, on 64c315ce5 with TRINITY_DEFAULT_SYSTEM_MANIFEST=disabled:
    • First run: the unit stage stopped it, with 36,745 passed and 42 host-only failures:
      • 39 in test_ent926_turn_tier_hook.py (above);
      • 3 in test_3262, which the manifest export trips.
    • Re-run with --skip-unit: pass. Build + import smoke, boot + health and test-preflight are OK. Integration: 74 passed, 13 skipped (0 infra-broken), 2 deselected per the known-false-fails registry.
    • Not run: the agent stage (the eyeball covered a live agent), and tests/test_read_only_mode.py, a live root-tier file outside tests/integration.
  • /cso --diff: 0 findings at the gate. The report is in docs/security-reports/cso-diff-2026-11-03-ent341-tool-access-profiles.md.
  • Live integration test updated. tests/test_read_only_mode.py asserted the old toggle messages.

No migration (SQLite or PostgreSQL) and no base-image rebuild needed.

Fixes abilityai/trinity-enterprise#341

🤖 Generated with Claude Code

webmixgamer and others added 3 commits November 3, 2026 18:21
…de and the tools an agent can't use (Abilityai/trinity-enterprise#341)

Settings › Guardrails gains a Tool access section: Full access (default),
Workspace-only, Read-only + report, Strict read-only and Custom. A profile is a
fixed bundle that sets the read-only layer and `disallowed_tools` together, so
the two can no longer disagree; read-only mode IS the Strict profile, and the
header and Dashboard-list Read-only toggle is its shortcut (ON for Strict only,
OFF returns to the profile it came from), now sent through the agents store.

- Storage is materialized: `disallowed_tools` and the read-only columns stay
  exactly what is enforced, so env injection, the drift check's inputs and the
  base image are unchanged. `guardrails_config.tool_access` records the choice
  (and Custom's remembered settings); the drift check ignores it. No migration.
- Nothing changes on upgrade: an agent with no stored profile has it derived;
  a read-only agent reads "Strict read-only · send block not applied" + Apply.
- Three writers (PUT /tool-access, PUT /read-only, PUT /guardrails) share one
  compare-and-set over the guardrails blob and the read-only columns (409 on a
  lost race); racing live applies converge to the row; every change is audited
  with the before and after state.
- The send block is refused by the backend, not only hidden: the nine routes
  behind the seven send tools and report refuse an agent-scoped caller (or the
  agent it sends as) whose enforced list names the tool, on every runtime.
- The toggle never loosens silently: ON from a list that removes tools Strict
  allows is a 409 naming them.
- Per-runtime coverage on every card; GET /guardrails shows the profile id only.
- No MCP surface: no tool reads or writes a profile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nt and the view switch (#1953)

The Dashboard list was the last toast on `fixed top-20 right-4`, where it covered
Create Agent and the Timeline/Grid/List buttons; the tool-access toggle's longer
sentences made it cover more. Same placement as AgentDetail.vue and FilesPanel.vue
(`bottom-24` clears the help FAB). Pinned by agentListToastPlacement.mount.spec.js.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Resolutions:
- check_guardrails_env_matches: the drift check ignores both live keys,
  ent#926's visitor_shell and this branch's tool_access.
- tests/registry.json: both sides' new entries kept (additive).
- agent_route_tiers.json: owner-tier rows for GET/PUT /tool-access.
- GuardrailsPanel: the ent#926 visitor-shell toggle's stored copy also leaves
  out tool_access and disallowed_tools once a profile is stored (spec added).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@webmixgamer webmixgamer added the ui PR touches the frontend UI — triggers Playwright e2e tests label Nov 4, 2026

@vybe vybe left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

merge-train: batch validated on train/20261104-2048 (train PR #4244, all Tier 1 + Tier 2 gates green)

@vybe
vybe merged commit ff69a63 into dev Nov 4, 2026
32 of 34 checks passed
@vybe

vybe commented Nov 4, 2026

Copy link
Copy Markdown
Contributor

merge-train (2026-11-04): merged at 64c315ce5 on train train/20261104-2048 (all gates green; nine real routers driven, CAS and allowlist mutations red). Notes that ride as follow-ups: (1) routers/agent_config.py:165 GET /tool-access is OwnedAgentByName, which admits the agent itself, so an agent key can read its own profile, before_strict and the Custom list over REST — the issue says "cannot see or change", the PR body narrows it to "no MCP surface"; writes are correctly agent-proof. A one-line ruling on ent#341 settles the wording. (2) Bar 11: no docs/user-docs/ page for tool-access profiles and no docs issue named. (3) feature-flows/agent-guardrails.md lacks the Side Effects / Error Handling / Security / Testing headings. (4) tool access / guardrails tier is not on record in OSS_VS_ENTERPRISE.md.

vybe pushed a commit that referenced this pull request Nov 4, 2026
…4243) — train decision at Gate 1, see the PR note

#4232 (trinity-enterprise#341) landed on dev after this PR's last dev merge and
added the send block, services/tool_access_guard.py::assert_tool_allowed, in
front of nine send routes. It is a per-agent tool restriction, never a grant,
so the ent#719 scan lists it under NOT_GRANT_GUARDS with the nine routes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@webmixgamer
webmixgamer deleted the feature/341-tool-access-profiles branch November 5, 2026 15:10
vybe pushed a commit that referenced this pull request Nov 11, 2026
…ited, the saved-token fork takes a session, and no grant rests on an agent-only check (#4243)

* fix(auth): human-only MCP tools follow their routes, refusals are audited, the saved-token fork takes a session, and no grant rests on an agent-only check

- MCP listing: each tool whose route needs a person or a signed-in session is
  listed through one shared predicate, so no key is shown a tool its scope can
  never call; within a listed scope the route still decides. The descriptions
  state each route's rule.
- MCP refusal reasons: a backend 403 whose detail is the person_required
  object, or the signed-in-session sentence, maps to the human-only answer.
- Audit: the human-only primitives raise HumanOnlyRefused, and an app handler
  records one row per refused attempt, bounded per principal and route, with
  no request body; the response is unchanged and an audit failure still
  answers 403.
- Agent creation: the arm that spends the creator's saved token as the new
  agent's is a credential bind and takes a signed-in session.
- A static scan fails any grant route that rests on an agent-only check alone;
  it lists one reviewed deferral. The feature-flows index carries one row for
  the issue.

Part of Abilityai/trinity-enterprise#719

* fix(mcp): inject_credentials and set_agent_github_pat are listed to a person's key

On dev, writing a credential the caller supplies into its own agent takes a
person (the ruled exception in requirements/auth.md §2.8):
POST .../credentials/inject and PUT .../github-pat are require_person. The
listing still treated inject as a signed-in-session bind (shown to no key)
and said setting a per-agent PAT needed a session, so a person's own user
key was hidden a tool its route admits. Both now take the person predicate;
the visibility tests follow (3 + 14 + 13 refusals, 10 person/interactive
rows, 10 user-listed tools on a fresh install).

Part of Abilityai/trinity-enterprise#719

* docs(mcp): a fork through create_agent is refused for every key

The create_agent fork block (ent#1007) relies on the backend spending the
caller's saved GitHub token. That arm makes the token the new agent's own,
a credential bind, so it runs only from a signed-in session, and an MCP
call never is one. The tool description and the docs that said the tool
spends the saved token now say a fork made through it is refused
FORK_PAT_REQUIRED for every key and is created from the web UI.

Part of Abilityai/trinity-enterprise#719

* fix(auth): the autonomy dial's owner writes take a person

The Workspace door admits the system key for the Workspace's uses, and it
resolves to the admin who owns the install, so the dial's owner check alone
let it release a person's held class and rewrite the guard cap (both 200
before this). Releasing is a grant in the route's own words. Both writes
now refuse a caller that is not a person first, as the readiness,
canvas-pin and seat-decision writes beside them do.

The grant scan found both, and the agent's own seat-decision record: its
two agent-only checks narrow an agent key to its running turn and grant
nothing, so they are listed as reviewed non-grants.

Mutation: with the two person checks removed, four system-key cases in
test_ent719_workspace_autonomy_person_only.py go red and the scan reports
both routes.

Part of Abilityai/trinity-enterprise#719

* docs(auth): the deferred grant and the remaining baseline point at their follow-up

The scan's one deferral and the census baseline's remaining entries are
tracked in trinity-enterprise#985, the follow-up filed for this issue.

Part of Abilityai/trinity-enterprise#719

* docs(mcp): the credential and PAT tool lines say a person's key reaches inject and a PAT set

Follows the listing change: inject_credentials and setting a per-agent PAT
take a person on dev, so the lines that said they take a signed-in session,
or that a user key can only clear a PAT, now say a person's own user key
reaches both.

Part of Abilityai/trinity-enterprise#719

* test(mcp): the fetch stubs compare the backend origin, not a URL prefix

CodeQL reads url.startsWith(BACKEND) as an incomplete URL check. In these
stubs it only routes a stubbed fetch, but comparing the origin says the
same thing exactly and clears the alert. 70/70 pass in both files.

Part of Abilityai/trinity-enterprise#719

* merge-train: list assert_tool_allowed as a reviewed non-grant guard (#4243) — train decision at Gate 1, see the PR note

#4232 (trinity-enterprise#341) landed on dev after this PR's last dev merge and
added the send block, services/tool_access_guard.py::assert_tool_allowed, in
front of nine send routes. It is a per-agent tool restriction, never a grant,
so the ent#719 scan lists it under NOT_GRANT_GUARDS with the nine routes.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* test(auth): drop the two seat-decision NOT_GRANT_GUARDS entries #4204 made stale

#4204 (ent#1062) made the seat-decision doors agent-only, so the person path
these entries described is gone and the scan reports them stale.

* test(auth): list the room-wake and Continue routes dev added under NOT_GRANT_GUARDS

On the merged tree the grant scan reported six routes resting on an
agent-only check alone. None is a grant:

- trinity-enterprise#1135 returns an ended ask to its room on the agent's
  next start, so start, chat, task result and system deploy/restart now reach
  the room wake, and through the engine's reply post, `tagger_for`. That post
  carries no tags (`post_message` asks for a tagger only for a sender's own
  tags), so the check never runs there.
- trinity#4302's Continue reaches `tagger_for` the same way, and calls
  `assert_tool_allowed` for parity with `/messages`. Its person check is
  `_is_room_person` in the service.

---------

Co-authored-by: trinity-ability <309458136+trinity-ability@users.noreply.github.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ui PR touches the frontend UI — triggers Playwright e2e tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants