coding-guardrails 0.7.2__tar.gz → 0.7.4__tar.gz

coding_guardrails-0.7.4/CLAUDE.md

@@ -0,0 +1,174 @@
+# Coding Guardrails
+
+An LLM proxy with safety guardrails, built on [Forge](https://github.com/antoinezambelli/forge) (vendored at `.vendors/forge/`).
+
+## Quick Start
+
+```bash
+source .venv/bin/activate
+pytest tests/unit/ -q          # 233 tests, ~0.1s
+uv pip install -e ".[dev]"     # refresh editable install
+```
+
+## Architecture
+
+Two-layer proxy between agent and LLM:
+
+```
+Agent → :8081 (our proxy)
+          ├── Layer 1: Forge (rescue, validate, retry, thinking capture)
+          ├── Layer 2: Coding Guardrails (11 rules)
+          └── → :8080 (llama-server / LLM backend)
+```
+
+### Request Flow
+
+1. Agent sends OpenAI-compatible request to `:8081`
+2. **Preprocessing**: empty user messages fixed, stale assistant text stripped
+3. **Tool enforcement**: for real coding agents (bash/read/edit/write tools), inject guidance
+4. **Layer 1 (Forge)**: run inference with rescue + retry + thinking capture
+5. **Layer 2 (Guardrails)**: check tool calls against 11 rules
+6. **Response**: blocked calls return text nudge to agent; allowed calls pass through
+
+### Key Modules
+
+| File | Purpose |
+|------|---------|
+| `proxy/handler.py` | Request pipeline: preprocessing → L1 → L2 → response |
+| `proxy/layer1.py` | Instrumented Forge wrapper with thinking capture |
+| `proxy/client.py` | `SafeLlamafileClient` — thinking tokens, max_tokens |
+| `proxy/server.py` | Asyncio HTTP server, `/v1/chat/completions` |
+| `middleware.py` | Composes all rules, `check()` / `record()` API |
+| `cli.py` | `coding-guardrails serve` CLI |
+| `rules/` | 11 guardrail rules |
+
+### Guardrail Rules
+
+| Rule | Action | Purpose |
+|------|--------|---------|
+| `prerequisites` | block | Read-before-edit |
+| `path_safety` | block | Path traversal |
+| `command_safety` | block | Destructive commands |
+| `network` | block | Network access |
+| `sensitive_files` | block | Protect sensitive files |
+| `secrets` | block/mask | Secret detection |
+| `loop_detection` | nudge→block | Repeated identical calls (3 nudge, 5 block) |
+| `session_budget` | nudge | File/command budgets |
+| `thoroughness` | nudge | Premature terminal submission |
+| `sequencing` | nudge | Test-after-change |
+| `tool_resolution` | nudge | Empty/error results |
+
+## Production Rules
+
+### Block Response Design
+
+When Layer 2 blocks a tool call, the proxy returns a **text response** (not an empty tool call).
+
+**Why**: Returning an empty tool call with the blocked tool name confuses agents — they see a tool call, execute it with empty args, get nothing, and retry the same call. Returning text makes the nudge visible to the agent and the model, providing a clear escape path.
+
+**Loop detection blocks specifically** tell the model: "If the task is done, call respond() with your final answer. Otherwise try a completely different approach." This gives the model an explicit exit instead of vague guidance.
+
+### Tool Enforcement
+
+Only injected for **real coding agents** (requests that include bash/read/edit/write tools). The enforcement says:
+
+> "Respond by calling tools. If the task is complete, call respond(). If unsure, call bash with 'echo ready'."
+
+**Never** say "NEVER respond with plain text" — the model needs to finish tasks. The `respond()` tool is the proper terminal action.
+
+### For eval/workflow requests (no coding tools)
+
+No enforcement, no injection, no modification. The proxy is a transparent pass-through.
+
+### Thinking Capture & Injection
+
+Layer 1 captures thinking tokens from the model's response. On retry (failed validation), the thinking is injected into the retry nudge so the model doesn't re-think from scratch.
+
+### Nudges vs Blocks
+
+- **Nudge**: advisory — the call proceeds, message is logged. Only visible if the agent's runner supports nudge injection (Forge does for its own evals). For streaming agents (Pi), nudges are silently logged.
+- **Block**: hard stop — the call is NOT passed through. The proxy returns a text response to the agent explaining why. This is the only reliable way to change model behavior mid-conversation.
+
+## Running the Proxy
+
+### tmux Sessions
+
+| Session | Purpose | Port |
+|---------|---------|------|
+| `llm-server` | `llama-server` with model | :8080 |
+| `guardrails` | `coding-guardrails serve` | :8081 |
+
+```bash
+# Start proxy
+source .venv/bin/activate
+coding-guardrails serve \
+  --backend-url http://localhost:8080 \
+  --model Qwen3.5-9B-UD-Q4_K_XL \
+  --port 8081 -v
+```
+
+### Client Quirks
+
+- `SafeLlamafileClient` needs `gguf_path` (stem = model name): use `/tmp/Qwen3.5-9B-UD-Q4_K_XL.gguf`
+- `recommended_sampling=False` — model not in Forge's registry
+
+## Testing
+
+```bash
+pytest tests/unit/ -q              # All 233 tests
+pytest tests/unit/ -q -k "loop"    # Specific rule
+```
+
+All 233 tests must pass before committing.
+
+## Eval
+
+```bash
+# Full Forge 30-scenario benchmark (proxy mode)
+python eval/scripts/run_forge_eval.py --mode proxy --runs 5
+
+# Direct vs proxy comparison
+python eval/scripts/run_forge_eval.py --mode both --runs 5
+
+# Specific scenarios
+python eval/scripts/run_forge_eval.py --mode proxy --scenario data_gap_recovery_extended
+
+# Layer 2 guardrails
+python eval/scripts/run_layer2_eval.py
+```
+
+Results go to `eval/runs/<timestamp>/` (gitignored).
+
+**Best result: 93% (140/150)** on Forge 30-scenario eval, +9pp over Forge's 84% baseline.
+
+## Development Guidelines
+
+- **Do NOT hack Forge source** — extend via public API, subclassing, wrapping
+- All 233 unit tests must pass
+- No hardcoded scenario-specific logic
+- Block responses must return **text**, not empty tool calls
+- Enforcement prompts must mention `respond()` as the exit tool
+- No injection/modification for non-coding-agent requests
+
+## Versioning & Releases
+
+SemVer: `MAJOR.MINOR.PATCH`
+
+- **PATCH**: Bug fixes, no new features
+- **MINOR**: New features, new rules, backward-compatible
+- **MAJOR**: Breaking API changes
+
+### Release Process
+
+1. Update `version` in `pyproject.toml`
+2. Update README/CLAUDE.md if needed
+3. `pytest tests/unit/ -q` — all 233 must pass
+4. `git commit -m "vX.Y.Z: description" && git push`
+5. `git tag vX.Y.Z && git push origin vX.Y.Z`
+6. GitHub Actions: test → build → verify CLI → publish to PyPI
+
+### CI Pipeline
+
+- Push to `main`: tests + lint
+- Tag `v*`: build → verify → publish to PyPI (trusted publishing, no tokens)
+- Refresh local: `uv pip install -e ".[dev]" && coding-guardrails --version`

{coding_guardrails-0.7.2 → coding_guardrails-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coding-guardrails
-Version: 0.7.2
+Version: 0.7.4
 Summary: Safe, reliable local coding agent proxy. Forge (rescue, retry, thinking capture) + 11 composable guardrail rules. 93% on Forge eval (Qwen3.5-9B).
 Project-URL: Homepage, https://github.com/stawils/coding-guardrails
 Project-URL: Repository, https://github.com/stawils/coding-guardrails

{coding_guardrails-0.7.2 → coding_guardrails-0.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "coding-guardrails"
-version = "0.7.2"
+version = "0.7.4"
 description = "Safe, reliable local coding agent proxy. Forge (rescue, retry, thinking capture) + 11 composable guardrail rules. 93% on Forge eval (Qwen3.5-9B)."
 requires-python = ">=3.12"
 license = "MIT"

{coding_guardrails-0.7.2 → coding_guardrails-0.7.4}/src/coding_guardrails/proxy/handler.py

@@ -221,8 +221,9 @@ async def handle_chat_completions(
 
     if _REAL_AGENT_TOOLS & tool_names_lower:
         enforcement = (
-            "CRITICAL: You MUST always respond by calling bash, read, edit, or write. "
-            "Never respond with plain text. "
+            "IMPORTANT: Respond by calling tools (bash, read, edit, write). "
+            "If you have completed the task and need to give a final answer, "
+            "call the respond tool. "
             "If unsure what to do, call bash with 'echo ready'."
         )
         if openai_messages:
@@ -313,11 +314,15 @@ async def handle_chat_completions(
     other_calls = [tc for tc in tool_calls if tc.tool != RESPOND_TOOL_NAME]
 
     if respond_calls and not other_calls:
+        # Convert respond() to text — most agents (Pi, Cline, etc.)
+        # don't have a respond tool. The model is saying "I'm done."
+        msg = respond_calls[0].args.get("message", respond_calls[0].args.get("answer", ""))
         attempts_tag = f"[%d attempt%s]" % (attempts, "s" if attempts != 1 else "") if attempts > 1 else ""
-        logger.info("✅ Layer 1 done %s (%s, respond: %s)",
-                    attempts_tag, _fmt_elapsed(elapsed_l1),
-                    _short(respond_calls[0].args.get("message", respond_calls[0].args.get("answer", "")), 60))
-        return tool_calls_to_openai(respond_calls, model=model_name)
+        logger.info("✅ Layer 1 done %s (%s, respond → text: %s)",
+                    attempts_tag, _fmt_elapsed(elapsed_l1), _short(msg, 60))
+        if is_stream:
+            return text_to_sse_events(msg, model=model_name)
+        return text_response_to_openai(msg, model=model_name)
 
     if not other_calls:
         logger.info("⚠️  No actionable tool calls")
@@ -375,7 +380,9 @@ async def handle_chat_completions(
 
         if is_stream:
             return text_to_sse_events(nudge_text, model=model_name)
-        return _make_block_response(block.tool, nudge_text, model=model_name)
+        # Return as text so the agent sees the nudge directly.
+        # Empty-args tool-call blocks confuse agents into retrying.
+        return text_response_to_openai(nudge_text, model=model_name)
 
     # All clear
     logger.info("✅ Request PASSED (%s)", _fmt_elapsed(elapsed_l2))

{coding_guardrails-0.7.2 → coding_guardrails-0.7.4}/src/coding_guardrails/rules/loop_detection.py

@@ -78,7 +78,9 @@ class LoopDetectionRule:
             return RuleResult.block(
                 call.tool,
                 nudge=f"You've called {call.tool} with the same arguments "
-                f"{count + 1} times. This isn't working — try a different approach.",
+                f"{count + 1} times. This isn't working. "
+                f"If the task is done, call respond() with your final answer. "
+                f"Otherwise, try a completely different approach.",
                 reason=f"loop detected: {call.tool} repeated {count + 1}x",
             )
 
@@ -86,7 +88,9 @@ class LoopDetectionRule:
             return RuleResult.nudge(
                 call.tool,
                 message=f"You've tried {call.tool} {count + 1} times with "
-                "the same arguments. Consider trying a different approach.",
+                "the same arguments. If the task is complete, "
+                "call respond() with your answer. "
+                "Otherwise try a different approach.",
             )
 
         # ── Check 2: Stagnation (cycling same few tools, different args) ──

coding_guardrails-0.7.2/CLAUDE.md

@@ -1,189 +0,0 @@
-# Coding Guardrails
-
-An LLM proxy with safety guardrails, built on [Forge](https://github.com/antoinezambelli/forge) (vendored at `.vendors/forge/`).
-
-## Quick Start
-
-```bash
-# Activate venv
-source .venv/bin/activate
-
-# Run tests
-pytest tests/unit/ -q          # 233 tests, ~0.1s
-
-# Install editable
-pip install -e .
-```
-
-## Architecture
-
-Two-layer proxy sitting between agent and LLM:
-
-```
-Agent → :8081 (our proxy)
-          ├── Layer 1: Forge (rescue, validate, retry, thinking capture)
-          ├── Layer 2: Coding Guardrails (11 rules)
-          └── → :8080 (llama-server / LLM backend)
-```
-
-### Key Modules
-
-| File | Purpose |
-|------|---------|
-| `src/coding_guardrails/proxy/handler.py` | Request pipeline: preprocessing → L1 (Forge) → L2 (guardrails) → response |
-| `src/coding_guardrails/proxy/layer1.py` | Instrumented wrapper around Forge's `run_inference()` with thinking capture |
-| `src/coding_guardrails/proxy/client.py` | `SafeLlamafileClient` — thinking token capture, max_tokens forwarding |
-| `src/coding_guardrails/proxy/server.py` | Asyncio HTTP server, OpenAI-compatible `/v1/chat/completions` |
-| `src/coding_guardrails/middleware.py` | Composes all guardrail rules, provides `check()` / `record()` API |
-| `src/coding_guardrails/cli.py` | `coding-guardrails serve` CLI with `--backend-url`, `--model`, `--port`, `--log-file` |
-| `src/coding_guardrails/rules/` | 11 guardrail rules (see below) |
-
-### Guardrail Rules (Layer 2)
-
-| Rule | Action | What it does |
-|------|--------|-------------|
-| `prerequisites` | block | Enforce read-before-edit |
-| `path_safety` | block | Path traversal blocking |
-| `command_safety` | block | Destructive command blocking |
-| `network` | block | Network access control |
-| `sensitive_files` | block | Protect sensitive files |
-| `secrets` | block/mask | Secret detection |
-| `loop_detection` | nudge/block | Stagnation detection (≤2 unique tools over 14+ calls) |
-| `session_budget` | nudge | File/command/read budget limits |
-| `thoroughness` | block | Premature terminal submission (low tool exploration ratio) |
-| `sequencing` | nudge | Test-after-change suggestions |
-| `tool_resolution` | nudge | Empty/error result handling |
-
-## Running the Proxy
-
-### tmux Sessions
-
-Four tmux sessions are used:
-
-| Session | Purpose | Port |
-|---------|---------|------|
-| `llm-server` | `llama-server` with Qwen3.5-9B-UD-Q4_K_XL | :8080 |
-| `guardrails` | `coding-guardrails serve` proxy | :8081 |
-| `skills-master` | General workspace | — |
-| `pi` | Pi coding agent | — |
-
-```bash
-# Start llama-server (in tmux: llm-server)
-llama-server -m /path/to/Qwen3.5-9B-UD-Q4_K_XL.gguf --port 8080 --host 0.0.0.0
-
-# Start proxy (in tmux: guardrails)
-source .venv/bin/activate
-coding-guardrails serve --backend-url http://localhost:8080 --model Qwen3.5-9B-UD-Q4_K_XL --port 8081 -v
-```
-
-### Important Client Quirks
-
-- `SafeLlamafileClient` needs `gguf_path` for model identity (stem = model name), not `model` — file doesn't need to exist: use `/tmp/Qwen3.5-9B-UD-Q4_K_XL.gguf`
-- `recommended_sampling=False` required — Qwen3.5-9B-UD-Q4_K_XL not in Forge's MODEL_SAMPLING_DEFAULTS registry
-
-## Testing
-
-```bash
-source .venv/bin/activate
-pytest tests/unit/ -q              # All 233 unit tests
-pytest tests/unit/ -q -k "loop"    # Specific rule tests
-```
-
-All 233 tests must pass before committing.
-
-## Eval
-
-### Forge 30-Scenario Eval
-
-```bash
-source .venv/bin/activate
-
-# Proxy mode (5 runs × 30 scenarios = 150 calls)
-python eval/scripts/run_forge_eval.py --mode proxy --runs 5
-
-# Direct mode (bypass proxy, LLM only)
-python eval/scripts/run_forge_eval.py --mode direct --runs 5
-
-# Both modes (direct vs proxy comparison)
-python eval/scripts/run_forge_eval.py --mode both --runs 5
-
-# Specific scenarios
-python eval/scripts/run_forge_eval.py --mode proxy --scenario data_gap_recovery_extended argument_transformation
-
-# Verbose (shows tool calls, thinking, results)
-python eval/scripts/run_forge_eval.py --mode proxy --runs 1 -v
-```
-
-### Run Folder Structure
-
-Each run creates `eval/runs/<timestamp>/`:
-
-```
-eval/runs/2026-05-31_204247Z/
-├── run.json          # Run metadata (mode, model, timestamps)
-├── eval.log          # Forge's verbose trace (tee'd from stdout)
-├── proxy.log         # Proxy's logging module output
-├── proxy.jsonl       # Per-scenario JSON results
-├── proxy_summary.txt # Human-readable summary table
-├── comparison.md     # Direct vs proxy comparison (both mode)
-└── direct.jsonl      # Direct mode results (both mode)
-```
-
-### Layer 2 Guardrails Eval
-
-```bash
-python eval/scripts/run_layer2_eval.py    # 17 JSON scenarios
-```
-
-### Compare Direct vs Proxy
-
-```bash
-python eval/scripts/compare.py eval/runs/<timestamp>/direct.jsonl eval/runs/<timestamp>/proxy.jsonl
-```
-
-### Benchmark Results
-
-Latest run: `eval/runs/2026-05-31_204247Z/` — **93% accuracy** (140/150), 100% completion.
-Forge's published benchmark: ~84% accuracy. Our proxy: +9pp with zero regressions.
-
-## Development Guidelines
-
-- **Do NOT hack Forge source** — extend via public API, subclassing, or wrapping only
-- Changes must survive upstream Forge updates (vendored at `.vendors/forge/`)
-- All 233 unit tests must pass
-- No hardcoded scenario-specific logic — guardrails must be general purpose
-- Use `edit` for targeted changes, `write` for new files or complete rewrites
-- Keep the proxy clean: no injection/annotation of messages for non-coding-agent requests
-
-## Versioning & Releases
-
-Uses [SemVer](https://semver.org/): `MAJOR.MINOR.PATCH`
-
-- **PATCH** (0.7.1): Bug fixes, no new features or API changes
-- **MINOR** (0.8.0): New features, new rules, backward-compatible
-- **MAJOR** (1.0.0): Breaking API changes
-
-### Release Process
-
-1. Update `version` in `pyproject.toml`
-2. Update README if needed (eval results, new rules, new features)
-3. Update CLAUDE.md if architecture changed
-4. Ensure all 233 tests pass: `pytest tests/unit/ -q`
-5. Commit: `git commit -m "vX.Y.Z: description"`
-6. Push: `git push`
-7. Tag: `git tag vX.Y.Z && git push origin vX.Y.Z`
-8. GitHub Actions auto-builds, tests, and publishes to PyPI
-
-### CI Pipeline
-
-- On every push to `main`: runs tests + lint
-- On tag `v*`: builds wheel, verifies CLI (`coding-guardrails --version`), publishes to PyPI
-- PyPI uses trusted publishing (OIDC), no API tokens needed
-
-### Refresh Local Install
-
-```bash
-source .venv/bin/activate
-uv pip install -e ".[dev]"
-coding-guardrails --version  # verify
-```