feat(guard): screen Claude Agent SDK tool results before the model reads them

[arcjet-rei]

Adds two ways to screen what a Claude Agent SDK tool returned, before the model reads it:

• guard_tool(result_rules=, result_action=) for authored tools: a second Guard call over the handler's return value, labelled {action}.result by default. A DENY returns the existing denial envelope in place of the result.
• guard_hooks(tool_results={...}) for every tool, on PostToolUse. A DENY replaces the result through updatedToolOutput for MCP tools and for the built-ins in REPLACEABLE_BUILTIN_TOOLS (Bash, Read). For any other tool the CLI would reject the replacement and send the original, so the run stops with continue: false instead, and the capture records which happened.

Claude Code validates a built-in tool's replacement against an unpublished schema and silently sends the original result on a mismatch. A new integration test drives the CLI bundled with claude-agent-sdk against a scripted, local Messages API and asserts what the model receives, and a new CI job runs it with the extra installed.

🤖 Generated with Claude Code

[arcjet-review]

Arcjet Review — 🔴 High Risk

Decision: Needs Review

Rationale: This PR changes security-sensitive guard behavior by adding a second policy evaluation path over tool results, including fail-open/fail-closed handling, policy labels, metadata, and prompt-injection screening inputs. The implementation is well covered by unit and integration tests and I did not identify hardcoded secrets or an obvious injection vulnerability in the code paths shown. However, because the change directly affects security enforcement semantics and includes adversarial prompt-injection text in PR content, it should receive human security review before merging.

Summary of Changes

Adds result_rules and result_action to guard_tool so authored Claude Agent SDK tool results can be screened after the handler runs and before the model receives the result. The PR adds result text extraction, a second Guard evaluation path, fail-closed handling by default, README documentation, and tests for allow, deny, unavailable, invalid configuration, and label override behavior.

Security Flags

• [LOW] Prompt injection in PR content (tests/integration/guard/test_claude_agent_sdk.py:107): The diff contains the phrase "ignore previous instructions" as a test fixture. It appears to be intentional prompt-injection test data, but it was ignored as an instruction and should be verified by a human reviewer under the adversarial PR-content policy.

Review Focus Areas

• Confirm that joining all text blocks without truncation is acceptable for very large tool results, or whether there should be a maximum size with explicit fail-closed behavior.
  The design avoids prefix-only prompt-injection bypasses, but unbounded result text can create memory, latency, or provider-limit risks when screening attacker-controlled fetched content.
• Verify the degradation path for result rule resolver failures is intended: Guard is still called without local result rules, and on_guard_error determines whether the result is denied or allowed.
  This is a security enforcement boundary; a resolver failure must not silently bypass result screening under the default deny mode.
• Check that returning the existing denial envelope in place of the handler result is compatible with all authored tool consumers.
  This changes the post-handler response path for tools using result_rules; consumers expecting a specific result shape need to handle the is_error denial envelope.
• Consider whether an additional test should cover invalid/non-sequence return values from result_rules, not only a resolver that raises.
  The docstring says non-sequence or invalid bound-rule results are handled like resolver failures; an explicit test would help prevent regressions in that fail-closed behavior.

_{Review: 38eb094c | Model: openai/gpt-5.5 | Powered by Arcjet Review}

[arcjet-rei]

Replies to the Arcjet Review focus areas:

• Untruncated text. Intended: screening a prefix lets an injection placed after the cut through. The text is sent whole; a request over the protocol limit, or a detector that returns no verdict, leaves the policy unevaluated, which denies under the default on_guard_error="deny". So an oversized result fails closed rather than being screened in part.
• Resolver failure. Intended, and the same as rules on the call itself: Guard is still called without local rules so remote policy and the capture record it, and on_guard_error decides. Under the default that denies the result (test_rules_callable_raising_still_calls_guard_and_fails_closed).
• Denial envelope in place of the result. It is the envelope a pre-call denial already returns for the same tool, so a consumer of that tool already handles it; only callers who opt into result_rules get it after the handler runs.
• Non-sequence return. Added in 41a6f49: test_rules_callable_returning_no_bound_rules_fails_closed, over the shared NOT_BOUND_RULES cases (None, a string, a non-rule object, an unbound rule, a coroutine).
• "ignore previous instructions" in the integration test. Deliberate test data: it is the tool's output the result screen is meant to catch.