feat(evaluators): add starts_with mode to list evaluator

Author: lan17

evaluators/builtin/src/agent_control_evaluators/list/config.py

@@ -19,9 +19,12 @@ class ListEvaluatorConfig(EvaluatorConfig):
     match_on: Literal["match", "no_match"] = Field(
         "match", description="Trigger rule on match or no match"
     )
-    match_mode: Literal["exact", "contains"] = Field(
+    match_mode: Literal["exact", "contains", "starts_with"] = Field(
         "exact",
-        description="'exact' for full string match, 'contains' for keyword/substring match",
+        description=(
+            "'exact' for full string match, 'contains' for keyword matching, "
+            "'starts_with' for prefix matching"
+        ),
     )
     case_sensitive: bool = Field(False, description="Whether matching is case sensitive")
 

evaluators/builtin/src/agent_control_evaluators/list/evaluator.py

@@ -18,7 +18,7 @@ class ListEvaluator(Evaluator[ListEvaluatorConfig]):
     Checks if data matches values in a list. Supports:
     - any/all logic (match any value vs match all values)
     - match/no_match trigger (trigger on match or no match)
-    - exact/contains mode (full match vs substring/keyword)
+    - exact/contains/starts_with mode (full match vs keyword vs prefix)
     - case sensitivity toggle
 
     Example configs:
@@ -50,6 +50,9 @@ def _build_regex(self) -> Any:
         if self.config.match_mode == "contains":
             # Word boundary matching for substring/keyword detection
             pattern = f"\\b({'|'.join(escaped)})\\b"
+        elif self.config.match_mode == "starts_with":
+            # Prefix matching using anchors
+            pattern = f"^({'|'.join(escaped)})"
         else:
             # Exact match using anchors
             pattern = f"^({'|'.join(escaped)})$"

evaluators/builtin/tests/list/test_list.py

@@ -33,6 +33,100 @@ def test_whitespace_only_value_rejected(self) -> None:
 class TestListEvaluator:
     """Tests for list evaluator runtime behavior."""
 
+    @pytest.mark.asyncio
+    async def test_starts_with_matches_prefix(self) -> None:
+        """Test that starts_with mode triggers on prefix matches."""
+        # Given: a starts_with evaluator config
+        evaluator = ListEvaluator(
+            ListEvaluatorConfig(
+                values=["/home/lev/agent-control", "/tmp/cache"],
+                logic="any",
+                match_on="match",
+                match_mode="starts_with",
+                case_sensitive=True,
+            )
+        )
+
+        # When: evaluating a path under an allowed prefix
+        result = await evaluator.evaluate("/home/lev/agent-control/server/src/app.py")
+
+        # Then: the prefix match triggers
+        assert result.matched is True
+        assert result.metadata["matches"] == ["/home/lev/agent-control/server/src/app.py"]
+
+    @pytest.mark.asyncio
+    async def test_starts_with_no_match_when_prefix_absent(self) -> None:
+        """Test that starts_with mode does not trigger when no prefix matches."""
+        # Given: a starts_with evaluator config
+        evaluator = ListEvaluator(
+            ListEvaluatorConfig(
+                values=["/home/lev/agent-control", "/tmp/cache"],
+                logic="any",
+                match_on="match",
+                match_mode="starts_with",
+                case_sensitive=True,
+            )
+        )
+
+        # When: evaluating a path with no configured prefix
+        result = await evaluator.evaluate("/var/log/system.log")
+
+        # Then: the evaluator does not trigger
+        assert result.matched is False
+
+    @pytest.mark.asyncio
+    async def test_starts_with_honors_case_sensitivity(self) -> None:
+        """Test that starts_with mode respects case sensitivity settings."""
+        # Given: two starts_with evaluators that differ only by case sensitivity
+        insensitive = ListEvaluator(
+            ListEvaluatorConfig(
+                values=["/HOME/LEV/AGENT-CONTROL"],
+                logic="any",
+                match_on="match",
+                match_mode="starts_with",
+                case_sensitive=False,
+            )
+        )
+        sensitive = ListEvaluator(
+            ListEvaluatorConfig(
+                values=["/HOME/LEV/AGENT-CONTROL"],
+                logic="any",
+                match_on="match",
+                match_mode="starts_with",
+                case_sensitive=True,
+            )
+        )
+
+        # When: evaluating the same lower-case path against both
+        insensitive_result = await insensitive.evaluate("/home/lev/agent-control/server")
+        sensitive_result = await sensitive.evaluate("/home/lev/agent-control/server")
+
+        # Then: only the case-insensitive evaluator matches
+        assert insensitive_result.matched is True
+        assert sensitive_result.matched is False
+
+    @pytest.mark.asyncio
+    async def test_starts_with_supports_no_match_allowlists(self) -> None:
+        """Test that starts_with works with no_match for allowlist-style controls."""
+        # Given: a starts_with evaluator configured as an allowlist
+        evaluator = ListEvaluator(
+            ListEvaluatorConfig(
+                values=["/home/lev/agent-control", "/tmp/cache"],
+                logic="any",
+                match_on="no_match",
+                match_mode="starts_with",
+                case_sensitive=True,
+            )
+        )
+
+        # When: evaluating one allowed and one disallowed path
+        allowed_result = await evaluator.evaluate("/home/lev/agent-control/server")
+        denied_result = await evaluator.evaluate("/var/log/system.log")
+
+        # Then: only the disallowed path triggers the control
+        assert allowed_result.matched is False
+        assert denied_result.matched is True
+
     @pytest.mark.asyncio
     async def test_legacy_empty_string_value_is_ignored_defensively(self) -> None:
         """Test that legacy invalid configs do not compile into a match-all regex."""

ui/src/core/evaluators/list/form.tsx

@@ -75,13 +75,14 @@ export const ListForm = ({ form }: EvaluatorFormProps<ListFormValues>) => {
         label={
           <LabelWithTooltip
             label="Match mode"
-            tooltip="Exact string match or substring (contains)"
+            tooltip="Exact string match, keyword contains, or string prefix matching"
           />
         }
         labelProps={labelPropsInline}
         data={[
           { value: 'exact', label: 'Exact (full string match)' },
-          { value: 'contains', label: 'Contains (substring match)' },
+          { value: 'contains', label: 'Contains (keyword match)' },
+          { value: 'starts_with', label: 'Starts with (prefix match)' },
         ]}
         size="sm"
         {...form.getInputProps('match_mode')}

ui/src/core/evaluators/list/types.ts

@@ -9,8 +9,8 @@ export type ListFormValues = {
   logic: 'any' | 'all';
   /** When to trigger: on match or no match */
   match_on: 'match' | 'no_match';
-  /** Match mode: exact or contains */
-  match_mode: 'exact' | 'contains';
+  /** Match mode: exact, contains, or starts_with */
+  match_mode: 'exact' | 'contains' | 'starts_with';
   /** Whether matching is case sensitive */
   case_sensitive: boolean;
 };