[AIG-868] Wire guardrails into review-loop + expose as Hook

[blackms]

[AIG-868] Wire dei guardrails nel review-loop + esposizione come Hook

Il motore guardrails (src/guardrails/) era implementato e testato ma orfano: non agganciato al review-loop ne esportato dalla public API. Questa PR lo collega come gate effettivo e ne documenta l'uso come hook nativo di Claude Code.

Cosa cambia

1. Gate nel review-loop (src/coordination/review-loop.ts)

   • Nuovo metodo privato runGuardrailGate(payload, direction).
   • INPUT gate: i requisiti del task passano dai validatori PRIMA che il coder venga eseguito (su violazione bloccante il coder non parte).
   • OUTPUT gate: l'output del coder passa dai validatori PRIMA di arrivare al reviewer / essere persistito, sia sulla generazione iniziale sia su ogni iterazione di fix.
   • Su violazione bloccante: status failed, failure registrate in state.guardrailFailures, audit log, e throw new ReviewLoopGuardrailError(direction, outcome). Nessun proseguimento silenzioso.
   • Fail-closed: nomi guardrail sconosciuti in config fanno throw; un guardrail viene eseguito solo nella direzione che dichiara.

2. Public API (src/index.ts): esportati motore (runGuardrails, withGuardrails, initGuardrails), built-in (secretsGuardrail, piiGuardrail, promptInjectionGuardrail, zodSchemaGuardrail), registry e i tipi principali; piu ReviewLoopGuardrailError (anche da src/coordination/index.ts).

3. Config opt-in (src/types.ts, src/utils/config.ts): estesa GuardrailsConfig in modo additivo con input, output, aggregateTimeoutMs, outputNonBlocking (schema zod aggiornato). Disattivata di default (enabled: false) -> nessun impatto sulle installazioni esistenti.

4. Documentazione (docs/GUARDRAILS.md): nuova sezione sul gate del review-loop e su come usare i guardrail come hook PreToolUse di Claude Code (script + config .claude/settings.json). Riusa il sistema hook nativo, non lo duplica.

5. Test d'integrazione (tests/integration/guardrails-gate.test.ts): blocco su secret e PII (carta LUHN-valida) in OUTPUT, blocco su prompt-injection in INPUT (coder mai invocato), no-op a gate disabilitato, percorso outputNonBlocking, e caso pulito che non blocca.

Note

• Pass di sicurezza OWASP: fail-closed su crash/timeout/typo, filtro per direzione, budget aggregato che non scarta il risultato di un fallimento high-severity.
• Draft PR per far girare la CI (AC Implement consensus checkpoints for high-stakes tasks #5). Da NON mergiare: lasciata in review umana.

Closes AIG-868

Summary by CodeRabbit

• New Features

  • Guardrails enforced as real gates in the review loop, validating input and output and failing the loop on blocking violations.
  • Guardrails exposed as a public feature (runnable and configurable) and a dedicated error type for handling violations.
  • Support for reusing guardrails from external tool hooks to screen tool calls.

• Configuration

  • Configurable via aistack.config.json with direction-specific rules, timeouts, kill-switch, aggregate timeout, and non-blocking output option.

• Documentation

  • Added comprehensive guide and sample hook integration.

• Tests

  • Added integration tests covering guardrail gate behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5807253f-f016-4193-bec9-7f0a708d9da0

📥 Commits

Reviewing files that changed from the base of the PR and between 485c1af and 03bf9cf.

📒 Files selected for processing (1)

• src/coordination/review-loop.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/coordination/review-loop.ts

---

📝 Walkthrough

Walkthrough

This PR integrates guardrail validation gates into the review loop (AIG-868). The loop now validates configured input requirements before code generation and validates generated outputs before proceeding, with configurable fail-closed input behavior and optional non-blocking output violations. The implementation includes configuration extensions, core gating logic, public API exports, comprehensive tests, and user documentation.

Changes

Guardrail Gate Integration

Layer / File(s)	Summary
Configuration and state tracking src/types.ts, src/utils/config.ts	GuardrailsConfig gains per-direction input/output arrays, aggregateTimeoutMs budget, and outputNonBlocking flag; ReviewLoopState adds guardrailFailures array for violation recording.
Guardrail gate core implementation src/coordination/review-loop.ts	Coordinator gains ReviewLoopGuardrailError, guardrail resolution, lazy initialization (ensureGuardrailsInitialized), shared agent-task wrapper (executeAgentTask), and gate executor (runGuardrailGate); input gates on requirements and fix instructions block execution, output gates on coder response support non-blocking mode.
Public API exports src/coordination/index.ts, src/index.ts	ReviewLoopGuardrailError and guardrails engine surface (functions, built-ins, registry, types) are re-exported from package root and coordination module.
Integration tests tests/integration/guardrails-gate.test.ts	Nine test cases verify input/output blocking, non-blocking output mode, custom guardrails, and disabled gates using mocked spawner/memory to assert error types, failure recording, and agent execution counts.
Documentation docs/GUARDRAILS.md	Gate behavior, fail-closed semantics, configuration, and complete PreToolUse hook example showing guardrails API usage with registry resolution and tool-call denial on violations.

Sequence Diagram(s)

sequenceDiagram
  participant ReviewLoop as Review Loop
  participant InputGate as Input Gate
  participant Coder as Coder Agent
  participant OutputGate as Output Gate
  participant Adversarial as Adversarial Agent
  participant State as Loop State

  ReviewLoop->>InputGate: validate requirements
  alt input violation
    InputGate->>State: record failure, mark failed
    InputGate-->>ReviewLoop: throw GuardrailError
  else input pass
    InputGate-->>Coder: proceed
    Coder->>Coder: generate code
    Coder-->>OutputGate: return response
    OutputGate->>OutputGate: validate output
    alt output violation
      alt outputNonBlocking
        OutputGate->>State: record failure
        OutputGate-->>Adversarial: proceed
      else blocking
        OutputGate->>State: record failure, mark failed
        OutputGate-->>ReviewLoop: throw GuardrailError
      end
    else output pass
      OutputGate-->>Adversarial: proceed
    end
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• blackms/aistack#45: Overlaps src/coordination/review-loop.ts changes—tracing instrumentation touches the same coordinator lifecycle phases that this PR modifies for guardrail gating.
• blackms/aistack#1: Introduced the base review-loop coordinator and adversarial review/fix flow extended here with guardrail gates and status-transition refactoring.

Poem

A rabbit hops through review gates with care, 🐰
Checking inputs before coders dare,
Secrets blocked and prompts screened tight,
The loop runs guarded, day and night!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 66.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main changes: integrating guardrails into the review-loop and exposing them as a Hook, with the ticket reference.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch pm-agent/AIG-868-guardrails-wire

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}