fix: cyclic arguments fail closed instead of hanging (#33)

argumentsDepth/_arguments_depth re-enqueued container children without tracking identities, so a self-referential arguments object looped forever in ToolGuard.check. Track visited containers and return -1 on cycle detection; both call sites (Python check/_parse_tool_arguments, TS parseToolArguments) fail closed on negative depth. Verified: cyclic direct+wrapper paths return blocked GuardResults in both languages, acyclic args still pass, 212 pytest passed, black clean, tsc clean, taint 0.

Author: rahuldass19

npm/src/guards.ts

@@ -368,11 +368,15 @@ export class ToolGuard extends BaseGuard {
 
     private static MAX_ARGS_JSON_DEPTH = 128;
 
-    /** Non-recursive max container nesting depth of a value. */
+    /**
+     * Non-recursive max container nesting depth of a value.
+     * Returns -1 when a container cycle is detected (fail closed).
+     */
     private static argumentsDepth(obj: any): number {
         if (obj === null || typeof obj !== 'object') return 0;
         let max = 0;
         const stack: Array<[any, number]> = [[obj, 1]];
+        const seen = new Set<any>([obj]);
         while (stack.length > 0) {
             const pair = stack.pop()!;
             const node = pair[0];
@@ -383,6 +387,8 @@ export class ToolGuard extends BaseGuard {
                 : Object.values(node);
             for (const child of children) {
                 if (child !== null && typeof child === 'object') {
+                    if (seen.has(child)) return -1;
+                    seen.add(child);
                     stack.push([child, depth + 1]);
                 }
             }
@@ -402,7 +408,9 @@ export class ToolGuard extends BaseGuard {
         if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) {
             // Bound structural depth before JSON.stringify can overflow the
             // stack on deeply nested objects (Greptile P1, mirror of Python).
-            if (ToolGuard.argumentsDepth(raw) > ToolGuard.MAX_ARGS_JSON_DEPTH) {
+            // A negative depth means a cycle — fail closed on that too.
+            const argsDepth = ToolGuard.argumentsDepth(raw);
+            if (argsDepth < 0 || argsDepth > ToolGuard.MAX_ARGS_JSON_DEPTH) {
                 return { ok: false };
             }
             return { ok: true, value: raw };

src/qwed_open_responses/guards/tool_guard.py

@@ -269,8 +269,10 @@ def check(
                     },
                 )
 
-            # Check for dangerous patterns in arguments
-            if ToolGuard._arguments_depth(arguments) > ToolGuard._MAX_ARGS_JSON_DEPTH:
+            # Check for dangerous patterns in arguments. A negative depth
+            # means a cycle was detected — fail closed on it too.
+            args_depth = ToolGuard._arguments_depth(arguments)
+            if args_depth < 0 or args_depth > ToolGuard._MAX_ARGS_JSON_DEPTH:
                 return self.fail_result(
                     "BLOCKED: Tool arguments exceed maximum nesting depth.",
                     details={"tool": tool_name},
@@ -361,18 +363,23 @@ def _arguments_depth(obj: Any) -> int:
 
         Used to fail closed on deeply-nested dict arguments before
         ``str(arguments)`` / json.dumps can raise RecursionError (Greptile P1).
-        Uses an explicit stack, so it never recurses itself.
+        Uses an explicit stack, so it never recurses itself. Returns -1 when
+        a container cycle is detected, so callers fail closed (Greptile P1).
         """
         if not ToolGuard._is_container(obj):
             return 0
         max_depth = 0
         stack = [(obj, 1)]
+        seen = {id(obj)}
         while stack:
             node, depth = stack.pop()
             if depth > max_depth:
                 max_depth = depth
             for child in ToolGuard._container_children(node):
                 if ToolGuard._is_container(child):
+                    if id(child) in seen:
+                        return -1
+                    seen.add(id(child))
                     stack.append((child, depth + 1))
         return max_depth
 
@@ -388,7 +395,8 @@ def _parse_tool_arguments(raw: Any) -> Tuple[bool, Any]:
         if raw is None or (isinstance(raw, str) and not raw.strip()):
             return True, {}
         if isinstance(raw, dict):
-            if ToolGuard._arguments_depth(raw) > ToolGuard._MAX_ARGS_JSON_DEPTH:
+            depth = ToolGuard._arguments_depth(raw)
+            if depth < 0 or depth > ToolGuard._MAX_ARGS_JSON_DEPTH:
                 return False, None
             return True, raw
         if isinstance(raw, str):

tests/test_guard_envelope_coverage.py

@@ -506,6 +506,27 @@ def test_deeply_nested_dict_arguments_fail_closed(self):
         r2 = guard.check({"type": "function_call", "name": "f", "arguments": deep_obj})
         assert r2.passed is False
 
+    # ------------------------------------------------------------------
+    # Cyclic (self-referential) arguments must fail closed, never hang
+    # in the depth traversal (Greptile P1).
+    # ------------------------------------------------------------------
+
+    def test_cyclic_arguments_fail_closed_no_hang(self):
+        cyclic = {"a": 1}
+        cyclic["self"] = cyclic
+        guard = ToolGuard()
+        # Depth traversal itself terminates with the cycle marker.
+        assert ToolGuard._arguments_depth(cyclic) == -1
+        # direct tool_call path
+        r1 = guard.check({"type": "function_call", "name": "f", "arguments": cyclic})
+        assert r1.passed is False
+        # OpenAI wrapper path
+        r2 = guard.check({"function": {"name": "f", "arguments": cyclic}})
+        assert r2.passed is False
+        # Acyclic arguments remain valid.
+        ok = guard.check({"type": "function_call", "name": "f", "arguments": {"a": {"b": 1}}})
+        assert ok.passed is True
+
     # ------------------------------------------------------------------
     # Multiple top-level tool collections are ambiguous - rejected, not
     # double-counted (Sentry LOW)