4141import io .github .agentic .ai .agent .interceptor .authorization .ToolAuthorizationPolicy ;
4242import io .github .agentic .ai .agent .result .StructuredOutputFinalizer ;
4343import io .github .agentic .ai .agent .tool .patch .ToolContextPatchPolicy ;
44+ import io .github .agentic .ai .agent .tool .patch .strict .StateIsolation ;
45+ import io .github .agentic .ai .agent .tool .patch .strict .StrictPatchAdmission ;
46+ import io .github .agentic .ai .agent .tool .patch .strict .ToolUpdateUnit ;
4447import io .github .agentic .ai .agent .tool .patch .ToolContextPatchValidator ;
4548import io .github .agentic .ai .agent .tool .patch .ToolContextPatchViolationException ;
4649import io .github .agentic .ai .agent .validation .ToolArgumentValidator ;
@@ -79,6 +82,8 @@ public final class ReActAgent implements Agent {
7982
8083 private final ToolContextPatchPolicy patchPolicy ;
8184
85+ private final boolean strictToolState ;
86+
8287 private final BusinessOutcomeMapperRegistry outcomeMappers ;
8388
8489 private final HumanInTheLoop humanInTheLoop ;
@@ -101,6 +106,7 @@ private ReActAgent(Builder builder) {
101106 "authorizationPolicy must not be null" );
102107 this .validateToolArguments = builder .validateToolArguments ;
103108 this .patchPolicy = builder .patchPolicy ;
109+ this .strictToolState = builder .strictToolState ;
104110 this .outcomeMappers = Objects .requireNonNull (builder .outcomeMappers , "outcomeMappers must not be null" );
105111 this .humanInTheLoop = builder .humanInTheLoop ;
106112 this .outputFinalizer = builder .outputFinalizer ;
@@ -135,6 +141,8 @@ public static final class Builder {
135141
136142 private ToolContextPatchPolicy patchPolicy ;
137143
144+ private boolean strictToolState ;
145+
138146 private BusinessOutcomeMapperRegistry outcomeMappers = BusinessOutcomeMapperRegistry .empty ();
139147
140148 private HumanInTheLoop humanInTheLoop ;
@@ -178,6 +186,24 @@ public Builder patchPolicy(ToolContextPatchPolicy patchPolicy) {
178186 return this ;
179187 }
180188
189+ /**
190+ * Opt-in strict tool-state mode. Tools then receive a read-only view of the
191+ * invocation state instead of the live map (writes escape only through the
192+ * {@link ToolContextPatchProvider} patch channel), and a failed call's patch is
193+ * always discarded regardless of {@code discardPatchOnFailedResult}. Merging
194+ * stays sequential last-write-wins, deliberately diverging from the graph path's
195+ * KeyStrategy-honoring strict merges: the ReAct state is an invocation-local
196+ * output map rather than the shared graph blackboard, and tool execution is
197+ * sequential, so the result is already deterministic w.r.t. completion order.
198+ * Default {@code false}: legacy behavior.
199+ * @param strict true to enable strict tool-state semantics
200+ * @return this builder
201+ */
202+ public Builder strictToolState (boolean strict ) {
203+ this .strictToolState = strict ;
204+ return this ;
205+ }
206+
181207 public Builder outcomeMappers (BusinessOutcomeMapperRegistry outcomeMappers ) {
182208 this .outcomeMappers = Objects .requireNonNull (outcomeMappers , "outcomeMappers must not be null" );
183209 return this ;
@@ -492,7 +518,9 @@ private ToolStep executeTool(ToolCall call, List<ChatMessage> messages, Map<Stri
492518 return new ToolStep (false , null );
493519 }
494520 }
495- CompletableFuture <ToolResult > future = availableTools .execute (call , new ToolContext (state )).toCompletableFuture ();
521+ Map <String , Object > toolVisibleState = strictToolState ? StateIsolation .readOnlyView (state ) : state ;
522+ CompletableFuture <ToolResult > future = availableTools .execute (call , new ToolContext (toolVisibleState ))
523+ .toCompletableFuture ();
496524 toolOperation .set (future );
497525 try (AutoCloseable ignored = context .control ().onLoss (() -> future .cancel (true ))) {
498526 ToolResult result ;
@@ -530,6 +558,16 @@ private void admitPatch(String toolName, ToolResult result, Map<String, Object>
530558 if (patch == null || patch .isEmpty ()) {
531559 return ;
532560 }
561+ if (strictToolState ) {
562+ // Hard rule: a failed call's patch is always discarded, independent of
563+ // discardPatchOnFailedResult; the shared admission also applies the policy
564+ // validation, so both paths enforce identical rules.
565+ if (StrictPatchAdmission .admit (patchPolicy ,
566+ new ToolUpdateUnit (toolName , !result .error (), patch ))) {
567+ state .putAll (patch );
568+ }
569+ return ;
570+ }
533571 if (patchPolicy != null && result .error () && patchPolicy .discardPatchOnFailedResult ()) {
534572 return ;
535573 }
0 commit comments