feat(agent): add task completion hook with bounded exits and explicit terminal states (T36)

argi-agent-framework/src/main/java/io/github/agentic/ai/graph/agent/action/ActionReasonCodes.java

@@ -19,9 +19,8 @@
 /**
  * Short, stable reason codes carried by {@link ActionDecision}.
  *
- * <p>Reason codes are operational labels, never private model reasoning. Additional
- * codes for routing and bounded-exit policies arrive with later slices of the action
- * decision work.</p>
+ * <p>Reason codes are operational labels, never private model reasoning. Codes cover tool
+ * selection outcomes and the bounded-exit policies of the task completion work.</p>
  */
 public final class ActionReasonCodes {
 
@@ -41,6 +40,30 @@ public final class ActionReasonCodes {
 	 */
 	public static final String TOOL_SELECTION_MODEL_FAILED = "TOOL_SELECTION_MODEL_FAILED";
 
+	/**
+	 * Required tasks are still unfinished and the bounded re-ask budget is exhausted, so
+	 * the run terminates with an explicit state instead of a plain success.
+	 */
+	public static final String UNFINISHED_REQUIRED_TASKS = "UNFINISHED_REQUIRED_TASKS";
+
+	/**
+	 * The bounded re-ask budget is exhausted and every no-tool answer in the sequence was
+	 * identical: the run is not making progress.
+	 */
+	public static final String NO_PROGRESS = "NO_PROGRESS";
+
+	/**
+	 * The same decision fingerprint (identical tool calls or identical final answer)
+	 * repeated for too many consecutive model turns.
+	 */
+	public static final String REPEATED_DECISION = "REPEATED_DECISION";
+
+	/**
+	 * More tool calls to unresolvable tool names occurred in this run than the configured
+	 * bound allows.
+	 */
+	public static final String UNKNOWN_TOOL = "UNKNOWN_TOOL";
+
 	private ActionReasonCodes() {
 	}
 

argi-agent-framework/src/main/java/io/github/agentic/ai/graph/agent/hook/taskcompletion/TaskCompletionExceededException.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2025-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.github.agentic.ai.graph.agent.hook.taskcompletion;
+
+import io.github.agentic.ai.graph.agent.action.ActionDecision;
+
+/**
+ * Thrown by {@link TaskCompletionHook} in {@link TaskCompletionHook.ExitBehavior#ERROR}
+ * mode when a bounded exit is reached. The terminal {@link ActionDecision} is available
+ * via {@link #getDecision()}.
+ */
+public class TaskCompletionExceededException extends RuntimeException {
+
+	private final ActionDecision decision;
+
+	/**
+	 * Creates the exception carrying the terminal decision.
+	 * @param decision the terminal decision, must not be {@code null}
+	 */
+	public TaskCompletionExceededException(ActionDecision decision) {
+		super(decision.reasonCode() + (decision.detail() == null ? "" : ": " + decision.detail()));
+		this.decision = decision;
+	}
+
+	/**
+	 * Returns the terminal decision that triggered this bounded exit.
+	 * @return the terminal decision
+	 */
+	public ActionDecision getDecision() {
+		return decision;
+	}
+
+}