feat(kdo): integrate H5-R3B active guarded tool pipeline

[TheHalfMoon]

Implements canonical KDO-H5-R3B — ACTIVE MONOTONIC GUARDED TOOL PIPELINE plus canonical C1 plan-module boundary correction from main@b76da457eab307904841d1097ff5a1cbcab6eaa7.

This is a Draft pre-ledger diagnostic candidate. The evidence ledger is absent and forbidden until a fresh exact-head pre-ledger PASS.

Current implementation paths

• packages/kodac-runtime/src/agent/guarded-tool-plan.ts — new pure serialized plan companion; all actual narrowing/block/rewrite fold goes through canonical R3A.
• packages/kodac-runtime/src/model/turn.ts — filtered H2/provider tool exposure, defensive provider-call normalization, R3A evaluation, immutable trusted-host veto seam, effective-call execution/history.
• packages/kodac-runtime/src/agent/loop.ts — propagates one static guardPlanJson; existing hard duplicate/R2B observation sees effective post-rewrite calls.
• packages/kodac-runtime/src/protocol/event.ts — adds tool.guard.evaluated and tool.guard.execution_observed structural events.
• packages/kodac-runtime/test/kdo-h5-r3b-active-guarded-tool-pipeline.test.ts — focused active-integration proof.

Historical regression reconciliations authorized by R3B are not yet committed; they will be applied only after current TypeScript/runtime diagnostics identify the final active blobs. The ledger remains absent.

Core invariants under test

PROVIDER_VISIBLE_TOOLS ⊆ REGISTERED_TOOLS
PROVIDER REQUEST TOOLS == H2 SNAPSHOT TOOLS
PROVIDER-ORIGIN MUTABLE CALL != EXECUTION OBJECT
R3A BLOCK -> NO TRUSTED HOOK / NO ORCHESTRATOR
R3A REWRITE -> SAME TOOL/CAPABILITY + NEW CALL IDENTITY
HARD LOOP GUARD / R2B -> EFFECTIVE REWRITTEN INPUT
BEFORE-TOOL RETURN VALUE -> IGNORED
BEFORE-TOOL MUTATION -> CANNOT ALTER EXECUTION
POST-TOOL EVIDENCE -> STRUCTURAL ONLY / NO OUTPUT OR RECEIPT REWRITE

Explicit boundaries

No dynamic/workspace hook discovery, shell/command hooks, plugin/user module execution, Agentica runtime import, K2/approval/confinement override, free-form H2 guard feedback, result/receipt rewrite, H5-R1 pruning integration, subagents/delegation/worktrees/background jobs/writable memory, Done Gate override, H5 completion, or H6 readiness.

No auto-merge.

---

Summary by cubic

Integrates the H5‑R3B active guarded tool pipeline to hide non‑permitted tools and execute only guard‑approved, JSON‑normalized tool calls, and records its pre‑ledger evidence. Previously all registry tools were exposed and provider call objects could pass through; now a pure plan preflights via R3A, filters exposure, can rewrite inputs, blocks disallowed/unknown calls, and emits structured guard evidence.

• New pure guarded-tool-plan module: canonicalizes JSON, enforces limits, validates exact name/capability pairs, preflights exposure and per‑call rules through R3A, and returns stable plan/tool‑set identities.
• AgentTurnRunner: accepts optional guardPlanJson; rejects invalid/stale plans before request snapshot/provider invocation; filters provider‑visible tools without mutating registry; normalizes provider responses; freezes beforeToolCall; preflights batches and aborts if any call is blocked; emits tool.guard.evaluated and tool.guard.execution_observed; throws GuardedToolCallBlockedError (unknown_tool, guard_blocked); returns only effective calls.
• BoundedAgentLoop: forwards guardPlanJson; duplicate detection and R2B advisories use effective rewritten inputs.
• Protocol: adds tool.guard.evaluated and tool.guard.execution_observed.
• Docs: adds a pre‑ledger R3B evidence ledger; merge still requires a fresh post‑ledger pass.

Migration

• Treat beforeToolCall as read‑only; its return value is ignored.
• Update sinks/routers to handle tool.guard.evaluated and tool.guard.execution_observed; missing the execution observation fails the turn.
• Handle GuardedToolCallBlockedError; unknown provider tools now fail with code unknown_tool.
• Use the runner’s effective toolCalls or provider stream events; do not rely on provider‑original inputs or the unfiltered tool set.
• Ensure guard plans reference exact registered name/capability pairs; R3A preflight rejects mismatches.

^{Written for commit 09298a9. Summary will update on new commits.}

[coderabbitai]

Warning

Review limit reached

@TheHalfMoon, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 17 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 3ea72894-7326-4202-bbd2-54018af2a5ee

📥 Commits

Reviewing files that changed from the base of the PR and between b76da45 and 09298a9.

📒 Files selected for processing (11)

• docs/planning/KODAC_KDO_H5_R3B_ACTIVE_MONOTONIC_GUARDED_TOOL_PIPELINE_EVIDENCE_2026-08-15.md
• packages/kodac-runtime/src/agent/guarded-tool-plan.ts
• packages/kodac-runtime/src/agent/loop.ts
• packages/kodac-runtime/src/model/turn.ts
• packages/kodac-runtime/src/protocol/event.ts
• packages/kodac-runtime/test/kdo-h2-r2-event-derived-history.test.ts
• packages/kodac-runtime/test/kdo-h5-r1a-tool-result-pruning.test.ts
• packages/kodac-runtime/test/kdo-h5-r2a-repeat-call-signal.test.ts
• packages/kodac-runtime/test/kdo-h5-r3a-monotonic-guarded-tool-pipeline.test.ts
• packages/kodac-runtime/test/kdo-h5-r3b-active-guarded-tool-pipeline.test.ts
• packages/kodac-runtime/test/model-turn.test.ts

✨ 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 feat/kdo-h5-r3b-active-guarded-tool-pipeline

---

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

[qodo-code-review]

PR Summary by Qodo

Integrate H5-R3B active guarded tool pipeline with serialized plan enforcement

✨ Enhancement 🐞 Bug fix 🧪 Tests 🕐 40+ Minutes

AI Description

• Add R3B serialized guard plan to filter provider-visible tools and evaluate tool calls.
• Normalize tool calls and enforce immutable, non-mutable hook/execution boundaries.
• Emit guard evidence/observation events and add focused active-integration test coverage.

Diagram

graph TD
  A["Bounded loop"] --> B["Turn runner"] --> C{{"Model provider"}}
  B --> D["Guard plan (R3B)"] --> E["R3A pipeline"] --> F{"Blocked?"}
  F -->|"no"| G["Orchestrator invoke"] --> H[("Event sink")]
  F -->|"yes"| H
  subgraph Legend
    direction LR
    _svc["Component"] ~~~ _ext{{"External"}} ~~~ _dec{"Decision"} ~~~ _db[("Event store")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Schema-validate with JSON.parse + Ajv/Zod

• ➕ Much less custom parsing/canonicalization code to maintain
• ➕ Clearer schema evolution and error reporting
• ➕ Likely faster iteration for future plan versions
• ➖ JSON.parse accepts duplicate keys; matching current strictness would require extra handling
• ➖ Harder to guarantee canonical, deterministic plan identity without additional canonicalization steps
• ➖ May diverge from the explicit security posture of rejecting ambiguous JSON inputs

2. Move enforcement to a central tool execution gateway

• ➕ Single enforcement point for all tool invocations (even non-agent callers)
• ➕ Reduces chances of bypass if new call paths are added later
• ➖ Does not address provider-visible tool exposure filtering at request construction time
• ➖ Requires broader refactor across runtime boundaries and could be more disruptive

3. Use CBOR/MessagePack + canonical encoding for plan/call

• ➕ Avoids JSON duplicate-key ambiguity by construction
• ➕ Potentially simpler deterministic identity computation
• ➖ Adds encoding/decoding complexity and interoperability overhead
• ➖ Requires new tooling and migration plan for plan authorship/fixtures

Recommendation: Keep the current approach for this integration: the strict parsing (duplicate-key rejection), canonicalization, and explicit plan/call boundaries align with the security invariants being asserted, and it cleanly reuses the existing R3A pipeline without adding ambient authority to the plan layer. Revisit a library-based validator only if a shared, battle-tested canonical JSON parser is adopted repo-wide.

Files changed (9) +1160 / -17

Enhancement (4) +683 / -8

guarded-tool-plan.tsAdd pure R3B serialized guard plan reducer wrapping R3A pipeline +543/-0

Add pure R3B serialized guard plan reducer wrapping R3A pipeline

• Introduces a strict, deterministic JSON plan format (tool decisions + per-tool call rules), including duplicate-key rejection, bounded sizes, and canonical JSON serialization for stable planIdentity. Exposes helpers to (1) reduce provider-visible tool exposure and (2) evaluate/possibly rewrite or block specific tool calls by delegating to the existing R3A guarded-tool-pipeline.

packages/kodac-runtime/src/agent/guarded-tool-plan.ts

loop.tsPropagate optional guardPlanJson through the agent loop +2/-0

Propagate optional guardPlanJson through the agent loop

• Extends AgentLoopInput with guardPlanJson and forwards it into each AgentTurnRunner invocation so the loop observes effective post-guard tool calls (including rewrites) consistently.

packages/kodac-runtime/src/agent/loop.ts

turn.tsIntegrate R3B guard plan into tool exposure, call evaluation, and execution +136/-8

Integrate R3B guard plan into tool exposure, call evaluation, and execution

• Filters provider-visible tools via reduceGuardedToolExposure when guardPlanJson is present and rejects invalid plans before snapshot/provider invocation. Normalizes provider tool calls, blocks unknown tools, evaluates guard decisions (block/rewrite) via reduceGuardedToolCallWithPlan, and executes only an immutable effective call; beforeToolCall now receives Readonly input and can no longer mutate execution. Emits tool.guard.evaluated and tool.guard.execution_observed events and returns effective toolCalls in the turn result/history.

packages/kodac-runtime/src/model/turn.ts

event.tsAdd guard evaluation and execution observation event types +2/-0

Add guard evaluation and execution observation event types

• Extends KodacEventType with tool.guard.evaluated and tool.guard.execution_observed to support structured guard evidence and post-execution observation reporting.

packages/kodac-runtime/src/protocol/event.ts

Tests (5) +477 / -9

kdo-h2-r2-event-derived-history.test.tsUpdate protected-surface expectations for turn.ts changes +0/-1

Update protected-surface expectations for turn.ts changes

• Adjusts the H2-R2 protected authority surface fixture by removing the previous turn.ts blob pin now that turn execution logic has evolved under R3B integration.

packages/kodac-runtime/test/kdo-h2-r2-event-derived-history.test.ts

kdo-h5-r1a-tool-result-pruning.test.tsAssert turn.ts does not introduce tool-result pruning hooks +3/-1

Assert turn.ts does not introduce tool-result pruning hooks

• Adds explicit assertions that turn.ts does not reference pruning logic and updates protected blob fixtures accordingly.

packages/kodac-runtime/test/kdo-h5-r1a-tool-result-pruning.test.ts

kdo-h5-r2a-repeat-call-signal.test.tsAlign repeat-call-signal protected fixtures after turn.ts evolution +0/-1

Align repeat-call-signal protected fixtures after turn.ts evolution

• Updates the protected blob list by dropping the previous turn.ts hash, keeping the test focused on non-superseded authority surfaces.

packages/kodac-runtime/test/kdo-h5-r2a-repeat-call-signal.test.ts

kdo-h5-r3a-monotonic-guarded-tool-pipeline.test.tsReframe R3A purity test to account for R3B integration boundary +24/-6

Reframe R3A purity test to account for R3B integration boundary

• Renames and extends the test to assert R3A remains byte-identical and pure while R3B integration occurs only through the new pure plan companion. Adds checks ensuring loop/turn/events include guard wiring without introducing forbidden confinement/hook imports, and updates protected boundary messaging.

packages/kodac-runtime/test/kdo-h5-r3a-monotonic-guarded-tool-pipeline.test.ts

kdo-h5-r3b-active-guarded-tool-pipeline.test.tsAdd active integration proof for H5-R3B guarded tool pipeline +450/-0

Add active integration proof for H5-R3B guarded tool pipeline

• Adds end-to-end tests covering plan determinism and trap resistance, provider-visible tool filtering, stale-plan rejection before request snapshot, rewrite propagation to immutable beforeToolCall and execution, blocking behavior preventing hook/orchestrator execution, loop duplicate detection using effective rewritten input, and guard event emission/robustness under sink failures.

packages/kodac-runtime/test/kdo-h5-r3b-active-guarded-tool-pipeline.test.ts

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📜 Skill insights (0)

1. Later block hides execution ✓ Resolved 🐞 Bug ☼ Reliability

Description

Guard validation and execution are interleaved, so an allowed call can complete before a later call
in the same provider response is blocked. The block throws before AgentTurnResult is returned,
leaving the loop to append only failure recovery while the earlier side effect has already occurred
and may be repeated by a subsequent model turn.

Code

packages/kodac-runtime/src/model/turn.ts[R328-331]

+      const effectiveCall = immutableEffectiveCall({ id: call.id, name: call.name, value: effectiveInput })
+      await hooks.beforeToolCall?.(effectiveCall)
+      const executionInput = materializeJson(effectiveCall.input)
+      const output = await this.orchestrator.invoke<unknown, unknown>(effectiveCall.name, executionInput, { signal: input.signal })

Relevance

●●● Strong

Team previously accepted making turns atomic by preflighting all outputs to avoid partial
persistence/side effects.

PR-#49

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The new loop invokes each call immediately after evaluating it, while a later blocked call throws
from the same loop before the return statement. BoundedAgentLoop handles that throw as a failed
turn and appends a recovery message; successful assistant/tool-result history is constructed only
when a complete result is returned.

packages/kodac-runtime/src/model/turn.ts[280-347]
packages/kodac-runtime/src/model/turn.ts[350-356]
packages/kodac-runtime/src/agent/loop.ts[437-461]
packages/kodac-runtime/src/agent/loop.ts[470-499]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
A later guard block can discard the normal result/history representation of earlier calls that already executed in the same response.

## Issue Context
Normalize, resolve, and guard-evaluate the entire provider call batch before invoking the first tool. If any call is unknown, malformed, or blocked, execute none of the calls; retain the current immutable hook and execution ordering after successful batch preflight.

## Fix Focus Areas
- packages/kodac-runtime/src/model/turn.ts[280-347]
- packages/kodac-runtime/src/agent/loop.ts[437-461]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Replacement inputs skip preflight ✓ Resolved 🐞 Bug ☼ Reliability

Description

normalizeDecision freezes replace_input values without enforcing R3A's input depth and item
limits, and exposure preflight never submits call-rule decisions to R3A. An invalid replacement
therefore permits a provider request and fails only during post-response guard reduction for a
matching call.

Code

packages/kodac-runtime/src/agent/guarded-tool-plan.ts[R328-330]

+  if (kind === "replace_input") {
+    return Object.freeze({ ...base, kind, input: freezeJson(copyJson(record.input as JsonValue)) })
+  }

Relevance

●●● Strong

Team often enforces strict boundary validation/limits; missing preflight for replace_input likely
fixed.

PR-#56

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The companion parser only copies/freezes replacement JSON. R3A later invokes canonicalInput for
replacements, enforcing depth and aggregate item bounds, but exposure passes only toolDecisions;
AgentTurnRunner uses that incomplete exposure result as its sole pre-provider plan check.

packages/kodac-runtime/src/agent/guarded-tool-plan.ts[328-330]
packages/kodac-runtime/src/agent/guarded-tool-plan.ts[495-509]
packages/kodac-runtime/src/agent/guarded-tool-pipeline.ts[330-364]
packages/kodac-runtime/src/agent/guarded-tool-pipeline.ts[479-488]
packages/kodac-runtime/src/model/turn.ts[165-193]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Call-rule replacement inputs are not checked against the canonical R3A input constraints during plan preflight.

## Issue Context
Apply equivalent R3A validation before accepting exposure, or preflight each rule through R3A with a bounded synthetic call, so malformed plans fail before request snapshot/provider invocation.

## Fix Focus Areas
- packages/kodac-runtime/src/agent/guarded-tool-plan.ts[305-330]
- packages/kodac-runtime/src/agent/guarded-tool-plan.ts[495-509]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Combined decisions exceed R3A 🐞 Bug ≡ Correctness

Description

A matching call may combine up to 128 tool decisions with 128 rule decisions, but R3A rejects any
pipeline over 128 decisions. Such a plan passes exposure preflight and reaches the provider, then
deterministically fails matching calls during guard reduction.

Code

packages/kodac-runtime/src/agent/guarded-tool-plan.ts[R417-418]

+    const decisions = normalizeDecisionArray(rule.decisions as JsonValue, `${label}.decisions`, KDO_H5_R3B_PLAN_LIMITS.maxRuleDecisions)
+    totalDecisions += decisions.length

Relevance

●●● Strong

Deterministic limit mismatch causing guaranteed failure usually gets addressed with stricter
preflight bounds.

PR-#56

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The plan parser independently allows 128 global decisions and 128 decisions per rule, then
concatenates both arrays. The unchanged R3A reducer caps the resulting decision array at 128, while
turn preflight evaluates only global tool decisions before contacting the provider.

packages/kodac-runtime/src/agent/guarded-tool-plan.ts[390-420]
packages/kodac-runtime/src/agent/guarded-tool-plan.ts[535-541]
packages/kodac-runtime/src/agent/guarded-tool-pipeline.ts[508-518]
packages/kodac-runtime/src/model/turn.ts[165-193]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
R3B accepts plans whose applicable global and rule decisions exceed R3A's 128-decision pipeline limit, causing post-provider reduction failures.

## Issue Context
Validate each rule against the number of global tool decisions so every possible combined pipeline accepted by the plan parser is valid for the canonical R3A reducer.

## Fix Focus Areas
- packages/kodac-runtime/src/agent/guarded-tool-plan.ts[390-420]
- packages/kodac-runtime/src/agent/guarded-tool-plan.ts[535-541]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Unknown-tool block lacks guard evidence event ✗ Dismissed 🐞 Bug ◔ Observability

Description

When a provider tool call names a tool absent from the registry, AgentTurnRunner.run throws
GuardedToolCallBlockedError('unknown_tool') immediately without emitting a 'tool.guard.evaluated'
(or equivalent) structural event, unlike the guard-blocked path which emits full pipeline evidence
before throwing. This creates an inconsistent evidence trail for two conceptually similar block
outcomes, making it harder to reconstruct why a turn failed from the event stream alone.

Code

packages/kodac-runtime/src/model/turn.ts[R292-293]

+      const registered = registeredTools.find((tool) => tool.name === call.name)
+      if (registered === undefined) throw new GuardedToolCallBlockedError("unknown_tool")

Relevance

●● Moderate

Inconsistent event trail noted, but adding emissions on unknown-tool path is a design choice;
uncertain.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The unknown_tool branch throws before any session.emit call, whereas the guard_blocked branch a few
lines later emits tool.guard.evaluated with planIdentity, pipelineResultIdentity, blockCode, etc.
before throwing GuardedToolCallBlockedError('guard_blocked', ...). Both are legitimate 'blocked
call' outcomes per the PR's invariant 'R3A BLOCK -> NO TRUSTED HOOK / NO ORCHESTRATOR', yet only one
produces structural evidence.

packages/kodac-runtime/src/model/turn.ts[292-324]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
When a provider tool call references a tool name that is not in the registered tool set, `AgentTurnRunner.run` throws `GuardedToolCallBlockedError("unknown_tool")` without emitting any structural event, unlike the `guard_blocked` path which emits `tool.guard.evaluated` first.

## Issue Context
This inconsistency means the event/evidence stream (session events) cannot distinguish/explain an unknown-tool rejection the same way it can for a guard-plan rejection, hurting downstream diagnostics and audit trails.

## Fix Focus Areas
- packages/kodac-runtime/src/model/turn.ts[292-293]
- packages/kodac-runtime/src/model/turn.ts[306-324]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

5. Guard plan rejection event omits validation detail ✗ Dismissed 🐞 Bug ◔ Observability

Description

When reduceGuardedToolExposure throws during plan parsing/validation (e.g. stale plan referencing a
removed tool), the runner emits a 'model.failed' event with only the generic string 'guard plan
rejected', discarding the specific validation error message available on the caught exception. This
limits the usefulness of the emitted event for operators diagnosing guard-plan authoring bugs from
the event log alone.

Code

packages/kodac-runtime/src/model/turn.ts[R171-178]

+      } catch (error) {
+        await this.session.emit("model.failed", {
+          provider: provider.name,
+          stage: "tool_guard_plan",
+          error: "guard plan rejected",
+        })
+        throw error
+      }

Relevance

●● Moderate

Observability improvement; could be accepted, but team may avoid leaking detailed internal errors in
events.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

parsePlan/validatePlanReferences in guarded-tool-plan.ts throw specific TypeError/RangeError
messages (e.g. 'guardPlan call rule must reference an exact registered tool name/capability pair'),
but the catch block in turn.ts replaces this with a fixed 'guard plan rejected' string in the
emitted event payload; the original error is still thrown to the caller, so this only affects
event-stream-only consumers.

packages/kodac-runtime/src/model/turn.ts[165-179]
packages/kodac-runtime/src/agent/guarded-tool-plan.ts[459-472]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The `model.failed` event emitted when a guard plan is rejected only carries a fixed string `"guard plan rejected"` instead of the specific validation failure reason.

## Issue Context
Consumers that only observe the session event stream (not the thrown exception) lose the actionable detail about which part of the guard plan/tool set mismatch caused the rejection.

## Fix Focus Areas
- packages/kodac-runtime/src/model/turn.ts[171-178]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context

Review mode: 🧠 Deep: This is a security-sensitive runtime pipeline with substantial new parsing, policy, execution, event, and loop logic across many independent paths, creating a high density of subtle defects that benefits from redundant review passes.

Tip of the day

💡 Did you know, you can turn on the rule miner and Qodo learns your standards from review history

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗