AgentOS Wave 2: hardening (H1/H2/H3) + N3 mapping + PR C-docs

[shaun0927]

Goal

Implement the Wave 2 PR queue after the Wave 1 substrate (#1132 – #1137) merged on 2026-05-20. Wave 2 covers 5 independent PRs scoped tightly inside the locked v1 boundary documents:

• docs/agentos/projection-v1-scope.md ([Feature] Define Run/Step/Artifact projections as the canonical harness vocabulary #946 v1 boundary)
• docs/agentos/workflow-ir-v1.md (Agent OS: introduce typed Workflow IR for fat-harness execution planning #956 v1 boundary)
• #939 scope-decision comment

All 5 PRs are mutually independent (touch disjoint surfaces) and may merge in any order.

Scope of Wave 2

#	Slot	Issue	Title	Risk	LOC est.
1	H1	#956	fix(persistence): guard workflow_ir aggregate type against raw append	Low	100–150
2	H2	#956	fix(orchestrator): bound workflow lifecycle reason_code/refs and nesting depth	Low	150–250
3	H3	#939	fix(plugin): block fail_closed terminal-observability hooks at dispatch	Low	200–300
4	N3	#956 / #946	docs+test(agentos): IR ↔ projection mapping contract	Low	250–400
5	PR C-docs	#939	docs(plugin): define before_tool_call/after_tool_call hook contract	Low	100–200 (docs-only)

H1–H3: 3 hardening follow-ups from Wave 1 reviewer findings

H1, H2, H3 each address a HIGH severity reviewer finding from Wave 1 (#1131 final summary). They harden defense-in-depth gaps the reviewers explicitly recommended closing before external consumers (plugin, MCP) attach to workflow_ir.

N3: IR ↔ #946 projection mapping

Locks the boundary contract between #956 Workflow IR and #946 projection vocabulary documented in docs/agentos/workflow-ir-v1.md:

The default boundary fixture must stay local and deterministic: it may pair a validated WorkflowSpec with synthetic EventStore rows to prove source-event linkage, but it must not add dispatch, cache, persistence, or projection-record embedding to the IR.

This is the v1-explicit-supported scope for N3.

PR C-docs: tool-call hook contract

Pure docs PR. Defines the before_tool_call / after_tool_call payload shape, permission scopes, failure policy, and audit event names so a future PR F (dispatch implementation) has an unambiguous target. Per the #939 scope-decision comment, PR C-docs is gated on N1 (#1134) which is now merged.

Excluded from Wave 2 (deferred — boundary decisions still pending)

• S4 StepSnapshot bounded projection view — docs/agentos/projection-v1-scope.md "Explicitly deferred" table still lists "StepSnapshot, session health, runtime handles, resume tokens — Later projection views". Needs a boundary-update PR (or canonical [Feature] Define Run/Step/Artifact projections as the canonical harness vocabulary #946 issue decision) before implementation.
• PR H on_event observation hook — subscription filter mechanism is undefined (per-hook event allowlist needs manifest schema decision; all-events fan-out is DoS-risky). Needs design decision on Agent OS plugins: standardize lifecycle hooks, permissions, and audit events #939 first.
• PR F tool-call dispatch (v0.4) — depends on PR C-docs contract being accepted + v0.4 schema introduction decision.
• PR D-docs artifact/state hook contract — write-side substrate not yet defined ([Feature] Define Run/Step/Artifact projections as the canonical harness vocabulary #946 stays read-only in v1).

---

PR 1 — Hardening H1 · workflow_ir append guard

Refs: #956 · #1134 security review HIGH #1

In-scope

• In src/ouroboros/persistence/event_store.py:append(), reject any BaseEvent whose aggregate_type == WORKFLOW_LIFECYCLE_AGGREGATE_TYPE (raise PersistenceError instructing the caller to use append_workflow_lifecycle_event()).
• In src/ouroboros/persistence/event_store.py:replay_workflow_lifecycle(), wrap each WorkflowLifecycleEvent.from_base_event() call in try/except so a single malformed row does not crash the entire replay (recommended fix from security review MEDIUM [Epic 2] Intelligent Task Routing (PAL) #3).

Out-of-scope

• ❌ Schema changes
• ❌ Any change to other aggregate types
• ❌ Behavioral change to append_workflow_lifecycle_event() itself

Files

• src/ouroboros/persistence/event_store.py
• tests/unit/persistence/test_event_store.py (or matching test file)

Acceptance

• Negative test: raw BaseEvent with aggregate_type="workflow_ir" passed to append() raises PersistenceError.
• Positive test: append_workflow_lifecycle_event() continues to work end-to-end.
• Replay-resilience test: malformed row co-located with valid rows does not blow up replay_workflow_lifecycle().

---

PR 2 — Hardening H2 · Bounded reason_code/refs and nesting depth

Refs: #956 · #1134 security review HIGH #2 + MEDIUM #4

In-scope

• Add validator on WorkflowLifecycleEvent.reason_code: len(reason_code) ≤ 1024.
• Extend _coerce_refs validator: len(refs) ≤ 64 entries, each len(ref) ≤ 512 chars.
• Add validator on WorkflowLifecycleEvent.workflow_id: len(workflow_id) ≤ 256 (security review LOW [Epic 5] Three-Stage Evaluation Pipeline #6).
• Introduce _MAX_NESTING_DEPTH = 32 and pass _depth through _normalize_json_value() recursive calls; raise ValueError on exceedance (security review MEDIUM [Epic 3] Double Diamond Execution #4).

Out-of-scope

• ❌ Schema_version bump
• ❌ Blocklist key additions (security review MEDIUM [Epic 4] Resilience & Stagnation Recovery #5 — defer to a separate small PR or normal rotation; not blocking)
• ❌ Any change to existing event consumers

Files

• src/ouroboros/orchestrator/workflow_lifecycle.py
• tests/unit/orchestrator/test_workflow_lifecycle_events.py

Acceptance

• Each bound has at least one negative test (oversized field rejected with clear ValidationError).
• Existing 21 lifecycle tests still pass without modification.
• Nesting depth test: 33-level-deep data rejected cleanly (no RecursionError).

---

PR 3 — Hardening H3 · Terminal-hook fail-open runtime guard

Refs: #939 · #1137 code review HIGH

In-scope

• In src/ouroboros/plugin/firewall.py:_run_lifecycle_hooks(), at function entry: if hook_kind in TERMINAL_OBSERVABILITY_HOOK_KINDS AND any iterated hook has failure_policy == "fail_closed":
  • Skip the hook (do not run subprocess).
  • Emit a plugin.hook.blocked audit event documenting the contract violation.
  • Do not let the skip influence the function return (terminal observability is fail-open by contract).

Out-of-scope

• ❌ Change to non-terminal hook policy (e.g., before_invocation still respects fail_closed)
• ❌ Manifest layer changes (the JSON schema + loader already prevent fail_closed for on_error/on_cancel; this is purely a runtime defense-in-depth)
• ❌ New permission scope or event family

Files

• src/ouroboros/plugin/firewall.py
• tests/unit/plugin/test_lifecycle_observability.py (or new sibling file)

Acceptance

• Test: forge a HookSpec(failure_policy="fail_closed") for on_error directly in Python (bypassing manifest validator), pass through invoke_plugin() failure path, assert original cause is preserved AND plugin.hook.blocked audit event is emitted.
• Existing 13 lifecycle observability tests still pass.
• Existing test(plugin): lock v0.3 lifecycle conformance #1119 conformance baseline still passes.

---

PR 4 — N3 · IR ↔ #946 projection mapping contract

Refs: #956 / #946 · docs/agentos/workflow-ir-v1.md

In-scope

• New doc docs/agentos/workflow-ir-projection-mapping.md defining:
  • How WorkflowNode.node_id maps to projection StepRecord.step_id / VerdictRecord.ac_id.
  • How WorkflowEdge.edge_id corresponds to projection event-pair linkage.
  • How WorkflowLifecycleEvent source IDs project into RunRecord / StageRecord / StepRecord.
• New test tests/integration/test_ir_projection_consistency.py: build a small validated WorkflowSpec, emit synthetic EventStore rows that follow the documented mapping, verify ProjectionBuilder produces records whose IDs match the IR's node_id / edge_id.

Out-of-scope (per workflow-ir-v1.md boundary)

• ❌ Schema change on either [Feature] Define Run/Step/Artifact projections as the canonical harness vocabulary #946 or Agent OS: introduce typed Workflow IR for fat-harness execution planning #956
• ❌ Live parallel_executor dispatch from IR
• ❌ Embed #946 records inside Workflow IR
• ❌ Persistence write
• ❌ New event family

Files

• docs/agentos/workflow-ir-projection-mapping.md (new)
• tests/integration/test_ir_projection_consistency.py (new)

Acceptance

• Fixture spec + synthetic events produce projection records whose step_id/ac_id/edge_id match the IR's planned identifiers.
• Mapping doc references both workflow-ir-v1.md and projection-v1-scope.md boundaries explicitly.
• 100% offline / deterministic / no credentials.

---

PR 5 — PR C-docs · Tool-call hook contract docs (pure docs)

Refs: #939 · #939 scope-decision comment

In-scope (pure docs)

• New doc docs/rfc/plugin-tool-call-hook-contract.md defining:
  • before_tool_call / after_tool_call payload shape (tool name, redacted args, bounded output ref).
  • Permission scopes: plugin:tool:intercept (mutating, fail-closed-eligible) vs plugin:tool:observe (observation, fail-open).
  • Failure policy mapping.
  • Audit event names: plugin.tool.intercept.requested / plugin.tool.intercept.completed / plugin.tool.intercept.blocked.
  • Future plugin_schema_version: "0.4" migration plan (introduction deferred to a future PR F dispatch slice; this docs PR does NOT change manifest.py or schemas).

Out-of-scope

• ❌ ANY code change (no manifest.py, no schemas/, no firewall.py)
• ❌ v0.4 schema file additions (deferred to PR F)
• ❌ Runtime dispatch behavior
• ❌ Permission scope additions in code

Files

• docs/rfc/plugin-tool-call-hook-contract.md (new, only)

Acceptance

• Markdown renders cleanly.
• Doc references docs/rfc/userlevel-plugins.md and feat(plugin): add on_error/on_cancel observability hooks (PR E) #1137 (PR E) as the observability-hook precedent.
• Doc names exactly which Wave 3+ PR will introduce v0.4 schema (PR F).

---

Common acceptance gates (apply to every Wave 2 PR)

1. Read first: each worker MUST grep / read upstream/main for the affected surface BEFORE pushing, to confirm the slot is genuinely net-new (Wave 1 lesson: S1 worker correctly refused to duplicate already-merged feat(harness): project artifact and verdict records #1061 work).
2. Schema invariant: no schema_version bump unless explicitly in the PR title.
3. Boundary doc citation: PR body names the exact section (projection-v1-scope.md, workflow-ir-v1.md, or #939 scope-decision comment) it implements.
4. Anti-action check: none of the explicit ❌ lists in the lock comments violated.
5. Test coverage: at least one negative test per acceptance criterion.
6. No --no-verify: pre-commit hooks must run.

[ouroboros-agent]

This looks like a multi-PR effort that needs design-level planning before implementation. Labeling needs-design for human planning.

Scope assessment:

• The issue bundles 5 independent PR slots (H1, H2, H3, N3, and PR C-docs) rather than a single reviewable change.
• The requested work spans multiple subsystems and boundary docs: EventStore persistence, workflow lifecycle/orchestrator behavior, plugin hook runtime policy, CLI/projection mapping, tests, and new docs.
• The current repo layout does not fully match the proposed targets yet: src/ouroboros/persistence/event_store.py and src/ouroboros/cli/commands/status.py exist, but key paths named in the issue such as src/ouroboros/orchestrator/workflow_lifecycle.py, src/ouroboros/plugin/firewall.py, and the referenced boundary docs are not present on the current branch, which increases scope and planning risk.

Suggested approach:

• Split this umbrella into the five concrete PR-sized issues already outlined in the body, each with its own acceptance gates and current-file grounding.
• Reconcile the target file paths and boundary-doc references against main before assigning implementation work.

ouroboros-agent[bot]