[taras]

Why

Follow-up to #953, which merged the necessity checks for agent plans and reviews.

Those checks need a concrete security model to distinguish necessary protection from speculative defensive complexity. A trusted plugin already runs native code; treating it as an adversary can produce elaborate protocols and tests without protecting a supported boundary.

What changes

Before: necessity checks exist, but the project has no consolidated statement of the threats that justify defensive mechanisms and adversarial tests.

After: architecture.md and the approved rulebooks record the security model and the hook adapter contract agreed with the Product Owner. The Architect and Planner guides link to that model when assessing defensive mechanisms, and verification guidance requires consequential failure paths rather than speculative permutations.

The approved model states that installed native extensions and explicitly run documents are trusted programs; generated evaluation enforces the host's allowed operations; external data is validated at its owning boundary; history validation covers format and run/effect consistency without promising authenticity against deliberate local-database rewriting; and disclosure protection covers credentials and identified secrets rather than treating all paths and ordinary error details as secret. Reliability and compatibility requirements remain separate reasons for protection.

The PR also records the approved hook adapter contract:

const { expand, beforeExpand, afterExpand } =
  createHooks<"expand", TArgs, TResult>(...);

The adapter uses createApi internally without modifying it. Registration is independent and scoped; handlers receive no next or replacement return channel. Before hooks may reject by throwing. After hooks run in reverse order, including on rejection and cancellation, and receive Effection's Result<TResult> with a dedicated cancellation error. Hook failures remain visible without rewriting completed effects or causing an automatic retry.

Review guide

Start with architecture.md → Security model and Middleware and hooks. Then review the approved rules in .agents/architecture-rules.md, the evidence rule in .agents/product-verification.md, and the security-model links added to the Architect and Planner guides. The necessity-check changes from #953 are already on main.

How to verify it

• git diff --check HEAD^ HEAD passes.
• Checked the added maintained rules against the 160-character limit, the security-model links and the hook contract's final agreed shape.
• Manually checked the role-guide additions against their existing boundaries and frozen-evidence rules.
• Documentation only; runtime tests do not discriminate these changes.

Follow-up implementation and API cleanup

• Add before and after hooks for component expansion and bound commands #956 — Add before and after hooks for component expansion and bound commands. This owns createHooks and its first production consumers.
• Define middleware and hook contracts for document execution and provider APIs #957 — Define middleware and hook contracts for document execution and provider APIs. This distinguishes observation from intentional request/result transformation and provider routing before conversion.
• Simplify defensive diagnostics and tests to match the security model #958 — Simplify defensive diagnostics and tests to match the security model. This reconciles source, specifications and conformance evidence while preserving supported reliability and compatibility guarantees.

#957's contract analysis can run alongside #956. Specification and necessity assessment in #958 can also proceed independently; changes to overlapping runtime code follow the hook migration and the relevant API contract decisions.

The hook primitive is a design contract in this PR. Runtime API conversion and the conformance cleanup are separate work; this PR changes no production code or tests.

Scope confirmation

• Every changed file supports the purpose described above.
• Unrelated cleanup and formatting changes are excluded.
• No generated or mechanical changes are included.
• The description matches the final diff and verification.

[github-actions]

PR #954: Define the security model and hook API contract

5 files, +203 / -0

Scope

✅ PR scope looks good.

Structural

✅ No structural bloat detected.

Slop

✅ Slop indicators look low.

Static Analysis

✅ Oxlint found no issues.

Correctness

No extraneous code patterns detected.