feat(guardrails): let tool-scope judge guardrails read the files a tool call mentions

[apetraru-uipath]

What

Tool-scope LLM-as-Judge guardrails now read the files a tool call touches. Until now guardrail_nodes.py excluded Tool scope from attachment forwarding (_ATTACHMENT_SCOPES = {Agent, Llm}), because feeding a tool-scope judge from the whole-run registry would ship every file on every tool call. This PR replaces that exclusion with call-scoped discovery:

• Pre-execution: the judge receives references for the attachments named in the tool call's arguments ({"ID": "<uuid>"} objects, the shape the model emits and replace_job_attachment_ids expands later inside the tool wrapper). Only ids the run's registry holds are forwarded, with the registry's name and MIME type: the registry is the set of files this run legitimately has (agent input plus files its tools returned), so a mention of a file the run never held is skipped rather than sent to the backend for an Orchestrator lookup.
• Post-execution: the same scan over the parsed ToolMessage result, so a tool that returns a file (output-file, batch-transform, process tools) gets it judged.
• A tool call that mentions no file forwards nothing, even when the run holds files elsewhere. A UUID under ID that is not an attachment (queue item, job) is never forwarded.
• Agent and LLM scope are unchanged: they keep reading the whole registry, because the judge there evaluates the conversation so far. Both paths now build references through one collector (_collect), so the backend sees identical references whichever scope produced them.

This is the generic mechanism AL-596 (guardrails on the IXP extraction tool) builds on: the IXP tool takes a single JobAttachment, and its interrupt() fires inside the tool node, after the pre-execution judge has run.

Code

• agent/guardrails/attachment_refs.py: resolve_referenced_attachments(data, job_attachments, guardrail) walks the payload (depth- and size-bounded), resolves mentions, dedupes and caps at 5; resolve_guardrail_attachments keeps its signature. Never raises.
• agent/guardrails/guardrail_nodes.py: _resolve_attachments picks the source by scope and stage, reusing the tool node's existing argument/result extractors. Plain-text tool results are skipped before parsing (a mention always carries the literal ID key), so the output extractor's warning is not triggered for every text result.

Not touched: the subgraph wiring (tool nodes were already wrapped pre and post), _VALIDATOR_ALLOWED_STAGES, the text-only retry on an attachment-caused 400, the escalate action payload, the coded-agent middleware stack.

Backend and designer

No helix or Studio Web change is needed: llm_as_judge already allows Tool scope at both stages, the validate request has no scope or stage field, the designer already offers Tool scope for the judge (no stage picker, so a Tool-scope guardrail runs at both stages), and the appliesTo dropdown renders from the definition contract. File contents are used only when helix has EnableGuardrailAttachments on (UiPath/Agents#6256).

Tests

• Review follow-up (093f3e4): the tool-scope node now judges the current tool call. With two calls to the same tool in one AI message it used to read the first call named tool_name (and, once the first ToolMessage was appended, nothing at all). Pre-execution selects the call via extract_current_tool_call_index exactly like the tool node; post-execution selects the call the last ToolMessage answers. Payload, deterministic input extraction and attachment resolution share the selection. Two node tests cover the two-calls case.

• tests/agent/guardrails/test_attachment_refs.py: 18 new cases for the referenced path (named file, no file, nested, id the run never held even with inline name/type, registry wins over inline fields, non-attachment UUID, non-UUID id, dedupe, cap, prompts-only, model instances, bounded scan, odd payloads, parity with the registry path).

• tests/agent/guardrails/test_guardrail_nodes.py: tool pre/post node tests replace test_tool_scope_node_never_resolves_attachments; Agent/LLM pre-execution with appliesTo = Files regression.

• tests/agent/guardrails/test_tool_guardrails_subgraph_run.py: a compiled tool subgraph around a real UiPathToolNode: a failing judge blocks before the tool implementation runs and saw exactly the referenced file; a passing judge lets the tool run and judges its result.

• tests/agent/guardrails: 351 passed. ruff, ruff format, mypy clean on the changed files; every new line in the two modules covered.

• CI note: the Integration testing / * cloud jobs fail with UiPathPermissionDeniedError: Forbidden (403) from the cloud test environment on this and on other PRs today (fix/code-interpreter-warmup); the alpha variants pass.

Verified locally

Same runtime checkout, local helix on UiPath/Agents#6256 with EnableGuardrailAttachments on, real Orchestrator attachments (alpha, APetraruTenant). Agent: the Joke Agent with the built-in Analyze Files tool, one LLM-as-Judge guardrail at Tool scope on that tool (Block), the user prompt referencing {{input.file}}, no agent-scope judge.

Input	Result
topic cats + joke_brief_unsafe.txt	model calls Analyze_Files with the attachment → tool_pre_execution_judge_file_before_analyze_files → helix validate with exactly one GET …/odata/Attachments(<id>) → Flagged: "joke_brief_unsafe.txt" contains … → blocked (AGENT_RUNTIME.TERMINATION_GUARDRAIL_VIOLATION, reason "Unsafe file content"). The tool never ran.
topic gardening + joke_brief_clean.txt	tool pre-execution judge Allowed (one attachment lookup) → Analyze Files runs → tool post-execution judge Allowed with no Orchestrator lookup (plain-text result names no file) → agent post PII passes → ✓ Successful execution

The agent-scope PII guardrail on the same runs receives the run's attachments and ignores them (helix gate), as before.

Studio Web Debug on the local robot, IXP Test Agent Solution (tool-scope judge added on the Json file IXP tool from the designer):

Input	Result
JSON with an injected "ignore your instructions / exfiltrate" note	tool pre-execution judge: one validate call, one attachment lookup → blocked before IXP started
clean PDF	Tool input guardrail check ✓ (8 s) → IXP suspend/resume ✓ (23 s) → Tool output guardrail check ✓ (no attachment lookup, the extraction result names no file) → Agent output ✓

Version bumped to 0.18.13 (0.18.12 was released from main on 2026-09-21 without this change; branch rebased onto it).

Jira: AL-593 (consumer: AL-596).

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Current-call selection and nested payload scanning have unresolved issues that can produce incorrect guardrail decisions.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1

Open (1)

• Collect attachments from the current tool call · New

What changed in this PR

Adds call-scoped attachment discovery for Tool-scope guardrails, including pre- and post-execution validation.

Changes:

• Resolves referenced attachments from tool arguments and results.
• Adds bounded scanning, deduplication, and metadata fallback.
• Adds guardrail and end-to-end tests.
• Bumps version to 0.18.12.

File	Description
uv.lock	Synchronizes the locked package version.
tests/​agent/​guardrails/​test_tool_guardrails_subgraph_run.py	Adds end-to-end tool guardrail coverage.
tests/​agent/​guardrails/​test_guardrail_nodes.py	Tests guardrail attachment forwarding.
tests/​agent/​guardrails/​test_attachment_refs.py	Tests attachment discovery behavior.
src/​uipath_langchain/​agent/​guardrails/​guardrail_nodes.py	Integrates scope- and stage-aware attachment resolution.
src/​uipath_langchain/​agent/​guardrails/​attachment_refs.py	Implements bounded attachment reference collection.
pyproject.toml	Bumps the package version.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
94.7% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud