coding-guardrails 0.2.0__tar.gz → 0.3.0__tar.gz

{coding_guardrails-0.2.0 → coding_guardrails-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-guardrails
-Version: 0.2.0
+Version: 0.3.0
 Summary: Safe, reliable local coding agent backend. Forge + coding-specific guardrails.
 Author: Stawils
 License-Expression: MIT

{coding_guardrails-0.2.0 → coding_guardrails-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coding-guardrails"
-version = "0.2.0"
+version = "0.3.0"
 description = "Safe, reliable local coding agent backend. Forge + coding-specific guardrails."
 requires-python = ">=3.12"
 license = "MIT"

{coding_guardrails-0.2.0 → coding_guardrails-0.3.0}/src/coding_guardrails/cli.py

@@ -32,6 +32,7 @@ def main() -> None:
 @click.option("--no-rescue", is_flag=True, help="Disable Forge rescue parsing")
 @click.option("--no-guardrails", is_flag=True, help="Disable Layer 2 guardrails (Forge only)")
 @click.option("--serialize", is_flag=True, help="Serialize requests (single-GPU)")
+@click.option("--timeout", default=600, type=float, help="Backend request timeout in seconds (default: 600)")
 @click.option("--verbose", "-v", is_flag=True, help="Verbose logging")
 def serve(
     backend_url: str,
@@ -43,6 +44,7 @@ def serve(
     no_rescue: bool,
     no_guardrails: bool,
     serialize: bool,
+    timeout: float,
     verbose: bool,
 ) -> None:
     """Start the coding-guardrails proxy server."""
@@ -69,6 +71,7 @@ def serve(
             rescue_enabled=not no_rescue,
             guardrails_enabled=not no_guardrails,
             serialize=serialize,
+            timeout=timeout,
         ))
     except KeyboardInterrupt:
         click.echo("\nStopped.")
@@ -84,9 +87,10 @@ async def _run_proxy(
     rescue_enabled: bool,
     guardrails_enabled: bool,
     serialize: bool,
+    timeout: float = 600.0,
 ) -> None:
     """Async proxy startup and run loop."""
-    from forge.clients.llamafile import LlamafileClient
+    from coding_guardrails.proxy.client import SafeLlamafileClient
     from forge.context.manager import ContextManager
     from forge.context.strategies import TieredCompact
     from coding_guardrails.proxy.server import GuardrailProxyServer
@@ -97,10 +101,12 @@ async def _run_proxy(
     if not base.endswith("/v1"):
         base = base + "/v1"
 
-    client = LlamafileClient(
+    client = SafeLlamafileClient(
         gguf_path=model,
         base_url=base,
         mode="native",
+        timeout=timeout,
+        default_max_tokens=8192,
     )
 
     # Auto-detect context budget from backend

{coding_guardrails-0.2.0 → coding_guardrails-0.3.0}/src/coding_guardrails/middleware.py

@@ -61,7 +61,13 @@ class CodingGuardrails:
         prereq_cfg = config.get("prerequisites", {})
         if prereq_cfg.get("enabled", True):
             rules["prerequisites"] = PrerequisiteRule(
-                rules=prereq_cfg.get("rules", None),
+                edit_tools=tuple(prereq_cfg.get("edit_tools", (
+                    "edit", "write", "create",
+                ))),
+                read_tools=tuple(prereq_cfg.get("read_tools", (
+                    "read", "cat", "head", "tail", "less",
+                ))),
+                match_arg=prereq_cfg.get("match_arg", "path"),
                 max_violations=prereq_cfg.get("max_violations", 2),
             )
 
@@ -98,7 +104,14 @@ class CodingGuardrails:
         seq_cfg = config.get("sequencing", {})
         if seq_cfg.get("enabled", True):
             rules["sequencing"] = SequenceRule(
-                rules=seq_cfg.get("rules", None),
+                trigger_prefixes=tuple(seq_cfg.get("trigger_tools", (
+                    "edit", "write", "create",
+                ))),
+                suggest_prefixes=tuple(seq_cfg.get("suggest_tools", (
+                    "bash", "shell", "run", "exec",
+                ))),
+                strength=seq_cfg.get("strength", "soft"),
+                nudge=seq_cfg.get("nudge", "Consider running tests to verify your changes."),
                 cooldown=seq_cfg.get("cooldown", 3),
             )
 

coding_guardrails-0.3.0/src/coding_guardrails/proxy/client.py

@@ -0,0 +1,51 @@
+"""Extended Forge client that passes max_tokens through to the backend.
+
+Forge's LlamafileClient._apply_sampling() only handles its own field list
+(temperature, top_p, etc.) — it deliberately ignores max_tokens. This
+subclass extends it to also forward max_tokens / n_predict, which prevents
+runaway model generation.
+
+This is the only place we extend Forge behavior without modifying the
+installed package. Everyone gets the fix just by pip-installing our package
+and Forge — no manual edits required.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from forge.clients.llamafile import LlamafileClient
+
+
+class SafeLlamafileClient(LlamafileClient):
+    """LlamafileClient that forwards max_tokens to the backend.
+
+    Adds max_tokens, max_completion_tokens, and n_predict to the sampling
+    pipeline so the backend always receives an output cap.
+
+    The default_max_tokens constructor arg is injected when the caller
+    doesn't provide one — acts as a safety net against runaway generation.
+    """
+
+    _EXTRA_SAMPLING_FIELDS = ("max_tokens", "n_predict")
+
+    def __init__(self, *args: Any, default_max_tokens: int = 8192, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._default_max_tokens = default_max_tokens
+
+    def _apply_sampling(
+        self, body: dict[str, Any], sampling: dict[str, Any] | None = None,
+    ) -> None:
+        # Let Forge handle its own fields first
+        super()._apply_sampling(body, sampling)
+
+        # Forward our extra fields (max_tokens, n_predict)
+        for field in self._EXTRA_SAMPLING_FIELDS:
+            override = (sampling or {}).get(field)
+            if override is not None:
+                body[field] = override
+                break  # First match wins (max_tokens preferred over n_predict)
+
+        # Safety net: if nobody set any cap, inject a default
+        if "max_tokens" not in body and "n_predict" not in body:
+            body["max_tokens"] = self._default_max_tokens

{coding_guardrails-0.2.0 → coding_guardrails-0.3.0}/src/coding_guardrails/proxy/handler.py

@@ -12,6 +12,7 @@ from __future__ import annotations
 
 import json
 import logging
+import time
 from typing import Any
 
 from forge.clients.base import LLMClient
@@ -34,7 +35,36 @@ from coding_guardrails.rules.base import ToolCall as GuardrailToolCall
 
 logger = logging.getLogger("coding_guardrails.proxy")
 
+# ── Banner helpers ──────────────────────────────────────────────────────────
+
+_BANNER_WIDTH = 60
+
+
+def _banner(label: str, char: str = "─") -> str:
+    pad = _BANNER_WIDTH - len(label) - 4
+    left = pad // 2
+    right = pad - left
+    return f"{char * left} ▸ {label} ◂ {char * right}"
+
+
+def _short(msg: str, width: int = 80) -> str:
+    if len(msg) <= width:
+        return msg
+    return msg[:width - 3] + "..."
+
+
+def _fmt_tools(calls: list[ToolCall]) -> str:
+    parts = [f"{tc.tool}({','.join(f'{k}={_short(str(v),20)}' for k, v in list(tc.args.items())[:3])})" for tc in calls]
+    return " | ".join(parts)
+
+
+def _fmt_elapsed(seconds: float) -> str:
+    if seconds < 1.0:
+        return f"{seconds * 1000:.0f}ms"
+    return f"{seconds:.1f}s"
+
 # OpenAI-compatible top-level body fields plumbed from inbound to client.
+# Note: max_tokens / n_predict are handled by SafeLlamafileClient, not here.
 _SAMPLING_FIELDS = (
     "temperature", "top_p", "top_k", "min_p",
     "repeat_penalty", "presence_penalty", "seed",
@@ -45,6 +75,15 @@ _SAMPLING_FIELDS = (
 def _extract_sampling(body: dict[str, Any]) -> dict[str, Any] | None:
     """Pull recognized sampling fields from the inbound request body."""
     extracted = {f: body[f] for f in _SAMPLING_FIELDS if f in body}
+    # Also forward max_tokens variants — SafeLlamafileClient handles them
+    for field in ("max_tokens", "max_completion_tokens", "n_predict"):
+        if field in body:
+            extracted[field] = body[field]
+    # Normalize: max_completion_tokens → max_tokens
+    if "max_completion_tokens" in extracted and "max_tokens" not in extracted:
+        extracted["max_tokens"] = extracted.pop("max_completion_tokens")
+    else:
+        extracted.pop("max_completion_tokens", None)
     return extracted or None
 
 
@@ -141,16 +180,23 @@ async def handle_chat_completions(
 
     # No tools → plain chat completion, pass through
     if not tool_specs:
-        logger.info("No tools, passing through to backend")
+        logger.info("💬 Plain text (no tools)")
+        t0 = time.monotonic()
         api_format = getattr(client, "api_format", "ollama")
         api_messages = fold_and_serialize(messages, api_format)
         response = await client.send(api_messages, tools=None, sampling=sampling)
+        elapsed = time.monotonic() - t0
         text = response.content if isinstance(response, TextResponse) else ""
+        logger.info("✅ Text response (%s, %d chars)", _fmt_elapsed(elapsed), len(text))
         if is_stream:
             return text_to_sse_events(text, model=model_name)
         return text_response_to_openai(text, model=model_name)
 
-    # ── Layer 1: Forge guardrails (rescue, validate, retry) ──
+    # ── Layer 1: Forge (rescue, validate, retry) ──
+    logger.info(_banner("LAYER 1 · Forge"))
+    logger.info("🔧 Calling model (%d tools, %d msgs, max %d retries)", len(tool_names), len(messages), max_retries)
+    t0 = time.monotonic()
+
     validator = ResponseValidator(tool_names, rescue_enabled=rescue_enabled)
     error_tracker = ErrorTracker(max_retries=max_retries)
 
@@ -166,12 +212,16 @@ async def handle_chat_completions(
         )
     except ToolCallError as exc:
         raw = exc.raw_response or ""
-        logger.warning("Layer 1 retries exhausted: %.120s", raw)
+        logger.warning("❌ Layer 1 failed after %d retries (%s)", max_retries, _short(raw, 80))
         if is_stream:
             return text_to_sse_events(raw, model=model_name)
         return text_response_to_openai(raw, model=model_name)
 
+    elapsed_l1 = time.monotonic() - t0
+    retries_used = error_tracker.attempt if hasattr(error_tracker, 'attempt') else 0
+
     if result is None:
+        logger.info("⚠️  Model returned empty")
         if is_stream:
             return text_to_sse_events("", model=model_name)
         return text_response_to_openai("", model=model_name)
@@ -184,37 +234,50 @@ async def handle_chat_completions(
 
     if respond_calls and not other_calls:
         text = respond_calls[0].args.get("message", "")
-        logger.info("Stripping respond(), returning as text")
+        logger.info("📝 Model responded with text (%s)", _fmt_elapsed(elapsed_l1))
         if is_stream:
             return text_to_sse_events(text, model=model_name)
         return text_response_to_openai(text, model=model_name)
 
     if not other_calls:
+        logger.info("⚠️  No actionable tool calls")
         if is_stream:
             return text_to_sse_events("", model=model_name)
         return text_response_to_openai("", model=model_name)
 
+    logger.info("✅ Layer 1 complete (%s, %d tool calls: %s)",
+                _fmt_elapsed(elapsed_l1), len(other_calls), _fmt_tools(other_calls))
+
     # ── Layer 2: Coding guardrails ──
+    logger.info(_banner("LAYER 2 · Guardrails"))
+    t1 = time.monotonic()
+
     guardrail_calls = [_forge_call_to_guardrail_call(tc) for tc in other_calls]
     guardrail_result = guardrails.check(guardrail_calls)
 
     # Record executed calls (for stateful rules like prerequisites)
     if guardrail_result.allowed:
         guardrails.record(guardrail_result.allowed)
+        for call in guardrail_result.allowed:
+            logger.info("  ✅ %s — allowed", call.tool)
 
-    # Log what happened
+    # Log blocks
     if guardrail_result.has_blocks:
         for block in guardrail_result.blocked:
-            logger.info(
-                "LAYER 2 BLOCK: tool=%s reason=%s",
-                block.tool, block.reason or block.nudge,
-            )
+            logger.info("  🚫 %s — BLOCKED [%s]", block.tool, block.reason or "policy violation")
+            logger.info("     ↳ %s", _short(block.nudge or "", 60))
+
+    # Log nudges
     if guardrail_result.has_nudges:
         for nudge in guardrail_result.nudges:
-            logger.info("LAYER 2 NUDGE: tool=%s", nudge.tool)
+            logger.info("  ⚠️  %s — nudged [%s]", nudge.tool, nudge.reason or "advisory")
+            logger.info("     ↳ %s", _short(nudge.nudge or "", 60))
+
+    elapsed_l2 = time.monotonic() - t1
 
     # If any call was hard-blocked, return block responses
     if guardrail_result.has_blocks:
+        logger.info("⛔ Request BLOCKED by Layer 2 (%s)", _fmt_elapsed(elapsed_l2))
         # Return the first block as the response with all nudges appended
         block = guardrail_result.blocked[0]
         nudge_text = block.nudge or "Action blocked by guardrails."
@@ -230,10 +293,8 @@ async def handle_chat_completions(
         # Return a block response — the agent sees this as guidance
         return _make_block_response(block.tool, nudge_text, model=model_name)
 
-    # All clear — return validated tool calls
-    # If there are nudges, log them (agent doesn't see them unless we inject)
-    # For now, nudges are advisory — we could inject them as system messages
-    # in a future iteration. For v0.1, they're logged only.
+    # All clear
+    logger.info("✅ Request PASSED (%s)", _fmt_elapsed(elapsed_l2))
 
     if is_stream:
         return tool_calls_to_sse_events(other_calls, model=model_name)

{coding_guardrails-0.2.0 → coding_guardrails-0.3.0}/src/coding_guardrails/proxy/server.py

@@ -180,9 +180,29 @@ class GuardrailProxyServer:
 
     async def _handle_models(self, writer: asyncio.StreamWriter) -> None:
         """GET /v1/models — returns model info."""
+        model_info: dict[str, Any] = {
+            "id": self._model_name,
+            "object": "model",
+            "owned_by": "coding-guardrails",
+        }
+
+        # Proxy the backend's model metadata (includes n_ctx)
+        try:
+            import httpx
+            async with httpx.AsyncClient(timeout=5.0) as http:
+                resp = await http.get(f"{self._client.base_url}/models")
+                if resp.status_code == 200:
+                    data = resp.json()
+                    for m in data.get("data", []):
+                        if "meta" in m:
+                            model_info["meta"] = m["meta"]
+                            break
+        except Exception:
+            pass
+
         body = json.dumps({
             "object": "list",
-            "data": [{"id": self._model_name, "object": "model"}],
+            "data": [model_info],
         })
         await self._send_json(writer, 200, body)
 
@@ -201,10 +221,11 @@ class GuardrailProxyServer:
         is_stream = body.get("stream", False)
         msg_count = len(body.get("messages", []))
         tool_count = len(body.get("tools", []))
-        logger.info(
-            "   stream=%s msgs=%d tools=%d model=%s",
-            is_stream, msg_count, tool_count, body.get("model", "?"),
-        )
+        logger.info("")
+        logger.info("━" * 60)
+        logger.info(">> POST /v1/chat/completions")
+        logger.info("   msgs=%d tools=%d stream=%s model=%s",
+                    msg_count, tool_count, is_stream, body.get("model", "?"))
 
         if self._serialize:
             item = _QueueItem(body=body)

{coding_guardrails-0.2.0 → coding_guardrails-0.3.0}/src/coding_guardrails/rules/commands.py

@@ -1,7 +1,7 @@
 """Destructive command blocking.
 
 Blocks shell commands that could cause irreversible damage:
-rm -rf /, fork bombs, pipe-to-shell, format disks, etc.
+rm -rf /, fork bombs, pipe-to-shell, format disks, sudo, etc.
 """
 
 from __future__ import annotations
@@ -24,67 +24,78 @@ class CommandSafetyRule:
         command_args: Argument names that contain shell commands.
         blocked: Exact command prefixes that are always blocked.
         blocked_patterns: Regex patterns for dangerous commands.
-        require_confirmation: Commands that should trigger a confirmation nudge.
+        require_confirmation: Commands that trigger a confirmation nudge.
     """
 
     command_args: list[str] = field(default_factory=lambda: ["command", "cmd", "script"])
 
     blocked: list[str] = field(default_factory=lambda: [
+        # Filesystem destruction
         "rm -rf / ",
         "rm -rf /*",
         "rm -rf ~",
-        "rm -rf /*",
         "rm -rf ~/*",
         "dd if=",
         "mkfs.",
         ":(){ :|:& };:",
+        # Privilege escalation
+        "sudo ",
+        "sudo(",
+        "su -",
+        "su root",
+        # Service manipulation
+        "systemctl stop",
+        "systemctl disable",
+        "systemctl restart",
+        "systemctl mask",
+        "service stop",
+        "shutdown",
+        "reboot",
+        "init 0",
+        "init 6",
+        # Disk/device access
+        "> /dev/sd",
     ])
 
     blocked_patterns: list[str] = field(default_factory=lambda: [
+        # Permission escalation
         r"chmod\s+777\s+/",
+        r"chmod\s+666\s+/",
+        # Download + execute (pipe to shell)
         r"curl\s+.*\|\s*(ba)?sh",
         r"wget\s+.*\|\s*(ba)?sh",
+        # Download + execute (two-step)
+        r"curl\s+.*-o\s+\S+.*&&\s*(ba)?sh\s",
+        r"wget\s+.*-O\s+\S+.*&&\s*(ba)?sh\s",
+        # Eval/execute fetched content
+        r"eval\s+['\"]?\$?\(",
+        r"bash\s+-c\s+['\"]?\$?\(",
+        r"source\s+<\(",
+        r"\.\s+<\(",                            # dot-source via process substitution
+        r"exec\s+<\(",
+        # Disk/device redirect
         r">\s*/dev/sd[a-z]",
+        # Root filesystem removal (exact end)
         r"rm\s+-rf\s+/\s*$",
+        # Git destructive operations
+        r"git\s+clean\s+-fdx?",
+        r"git\s+reset\s+--hard",
+        r"git\s+checkout\s+--\s+\.",
+        r"git\s+branch\s+-[dD]\s+(main|master)",
+        r"git\s+push\s+.*--force",
+        # Credential theft
+        r"cat\s+/etc/shadow",
+        r"cat\s+/root/.ssh",
+        r"cp\s+/etc/shadow",
     ])
 
     require_confirmation: list[str] = field(default_factory=lambda: [
         "rm -rf",
-        "git push --force",
         "DROP TABLE",
+        "DELETE FROM",
+        "TRUNCATE",
     ])
 
-    _DEFAULTS_BLOCKED: ClassVar[list[str]] = [
-        "rm -rf / ",
-        "rm -rf /*",
-        "rm -rf ~",
-        "rm -rf /*",
-        "rm -rf ~/*",
-        "dd if=",
-        "mkfs.",
-        ":(){ :|:& };:",
-    ]
-    _DEFAULTS_PATTERNS: ClassVar[list[str]] = [
-        r"chmod\s+777\s+/",
-        r"curl\s+.*\|\s*(ba)?sh",
-        r"wget\s+.*\|\s*(ba)?sh",
-        r">\s*/dev/sd[a-z]",
-        r"rm\s+-rf\s+/\s*$",
-    ]
-    _DEFAULTS_CONFIRM: ClassVar[list[str]] = [
-        "rm -rf",
-        "git push --force",
-        "DROP TABLE",
-    ]
-
-    def __post_init__(self) -> None:
-        if self.blocked is None:
-            object.__setattr__(self, 'blocked', list(self._DEFAULTS_BLOCKED))
-        if self.blocked_patterns is None:
-            object.__setattr__(self, 'blocked_patterns', list(self._DEFAULTS_PATTERNS))
-        if self.require_confirmation is None:
-            object.__setattr__(self, 'require_confirmation', list(self._DEFAULTS_CONFIRM))
-
     @property
     def name(self) -> str:
         return "command_safety"

coding_guardrails-0.3.0/src/coding_guardrails/rules/prerequisites.py

@@ -0,0 +1,95 @@
+"""Read-before-edit prerequisite enforcement.
+
+Tracks which files the agent has read. Blocks edit/write operations
+on files that haven't been read first.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+from coding_guardrails.rules.base import Action, RuleResult, ToolCall
+
+
+# Tool name matching: prefix-based so 'edit' matches 'edit', 'edit_file',
+# 'Edit', etc. Covers Pi (edit/read/bash), Claude Code (Edit/Read),
+# Aider, OpenCode, and generic agents.
+_DEFAULT_EDIT_TOOLS = ("edit", "write", "create")
+_DEFAULT_READ_TOOLS = ("read", "cat", "head", "tail", "less")
+
+
+def _tool_matches(tool: str, prefixes: tuple[str, ...]) -> bool:
+    """Check if a tool name matches any prefix (case-insensitive)."""
+    tool_lower = tool.lower()
+    return any(tool_lower.startswith(p) for p in prefixes)
+
+
+@dataclass
+class PrerequisiteRule:
+    """Enforce read-before-edit for file operations.
+
+    Uses prefix matching so tool names like 'edit', 'edit_file', 'Edit'
+    all match. Covers Pi, Claude Code, Aider, OpenCode, and generic agents.
+
+    Attributes:
+        edit_tools: Tool name prefixes that require a prior read.
+        read_tools: Tool name prefixes that satisfy the read requirement.
+        match_arg: Argument name containing the file path.
+        max_violations: Block after this many consecutive violations.
+    """
+
+    edit_tools: tuple[str, ...] = _DEFAULT_EDIT_TOOLS
+    read_tools: tuple[str, ...] = _DEFAULT_READ_TOOLS
+    match_arg: str = "path"
+    max_violations: int = 2
+
+    _read_paths: set[str] = field(default_factory=set, repr=False)
+    _violation_count: int = field(default=0, repr=False)
+
+    @property
+    def name(self) -> str:
+        return "prerequisites"
+
+    def check(self, call: ToolCall) -> RuleResult:
+        if not _tool_matches(call.tool, self.edit_tools):
+            return RuleResult.allow(call.tool)
+
+        path = call.args.get(self.match_arg, "")
+        if not path:
+            return RuleResult.allow(call.tool)
+
+        # Normalize: expand user, strip trailing slashes
+        normalized = os.path.normpath(os.path.expanduser(path))
+
+        if normalized not in self._read_paths:
+            self._violation_count += 1
+            if self._violation_count >= self.max_violations:
+                return RuleResult.block(
+                    call.tool,
+                    nudge=f"You must read {path} before editing it. "
+                    f"Read the file first.",
+                    reason=f"edit without read: {path}",
+                )
+            return RuleResult.nudge(
+                call.tool,
+                message=f"Consider reading {path} before editing. "
+                f"Read the file first.",
+            )
+
+        # No prerequisite violated — reset counter
+        self._violation_count = 0
+        return RuleResult.allow(call.tool)
+
+    def record(self, calls: list[ToolCall]) -> None:
+        """Record which files have been read."""
+        for call in calls:
+            if _tool_matches(call.tool, self.read_tools):
+                path = call.args.get(self.match_arg, "")
+                if path:
+                    normalized = os.path.normpath(os.path.expanduser(path))
+                    self._read_paths.add(normalized)
+
+        # Reset violation counter on successful execution
+        self._violation_count = 0

coding_guardrails-0.3.0/src/coding_guardrails/rules/sequencing.py

@@ -0,0 +1,85 @@
+"""Workflow sequencing — soft nudges for test-after-change.
+
+Suggests running tests after code edits. Soft by default (nudge, not block).
+Uses prefix matching so it works with any agent's tool naming convention.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from coding_guardrails.rules.base import Action, RuleResult, ToolCall
+from coding_guardrails.rules.prerequisites import _tool_matches
+
+# Default trigger/suggest prefixes covering all major agents.
+_DEFAULT_EDIT_PREFIXES = ("edit", "write", "create")
+_DEFAULT_SUGGEST_PREFIXES = ("bash", "shell", "run", "exec")
+
+
+@dataclass
+class SequenceRule:
+    """Suggest workflow steps after certain tool calls.
+
+    Uses prefix matching: trigger_prefixes="edit" matches 'edit',
+    'edit_file', 'Edit', etc.
+
+    Attributes:
+        trigger_prefixes: Tool name prefixes that trigger the suggestion.
+        suggest_prefixes: Tool name prefixes that satisfy the suggestion.
+        strength: "soft" (nudge) or "hard" (block until done).
+        nudge: Nudge message shown to the agent.
+        cooldown: Minimum number of calls between repeated nudges.
+    """
+
+    trigger_prefixes: tuple[str, ...] = _DEFAULT_EDIT_PREFIXES
+    suggest_prefixes: tuple[str, ...] = _DEFAULT_SUGGEST_PREFIXES
+    strength: str = "soft"
+    nudge: str = "Consider running tests to verify your changes."
+    cooldown: int = 3
+
+    _calls_since_nudge: int = field(default=0, repr=False)
+    _pending: bool = field(default=False, repr=False)
+
+    @property
+    def name(self) -> str:
+        return "sequencing"
+
+    def check(self, call: ToolCall) -> RuleResult:
+        # Trigger: agent just edited/wrote a file
+        if _tool_matches(call.tool, self.trigger_prefixes):
+            self._pending = True
+            self._calls_since_nudge = 0
+
+            if self.strength == "hard":
+                return RuleResult.block(
+                    call.tool,
+                    nudge=self.nudge,
+                    reason=f"hard sequence: {call.tool} → test",
+                )
+
+            return RuleResult.allow(call.tool)
+
+        # Satisfaction: agent is running a command (might be tests)
+        if self._pending and _tool_matches(call.tool, self.suggest_prefixes):
+            self._pending = False
+            self._calls_since_nudge = 0
+            return RuleResult.allow(call.tool)
+
+        # Cooldown nudge: agent hasn't run tests after edits
+        if self._pending:
+            self._calls_since_nudge += 1
+            if self._calls_since_nudge >= self.cooldown:
+                self._calls_since_nudge = 0
+                return RuleResult.nudge(
+                    call.tool,
+                    message=self.nudge,
+                )
+
+        return RuleResult.allow(call.tool)
+
+    def record(self, calls: list[ToolCall]) -> None:
+        """Track if suggested follow-up was executed."""
+        for call in calls:
+            if self._pending and _tool_matches(call.tool, self.suggest_prefixes):
+                self._pending = False
+                self._calls_since_nudge = 0