contracts

hawk-core-contracts

Shared contracts for the hawk ecosystem.

This repo holds stable cross-repo type definitions used by every engine and hawk itself: severity levels, findings, tool contracts, event models, policy verdicts, review results, verification reports, and agent session state.

Tagline: Shared contracts for the hawk ecosystem.

Install

go get github.com/GrayCodeAI/hawk-core-contracts

Quick Reference

Architecture

hawk-core-contracts (stdlib only)
├── types/     Severity, Finding, FindingSlice — the core vocabulary
├── tools/     ToolCall, ToolResult — provider-neutral tool contracts
├── events/    ToolEvent, TraceEvent — normalized event contracts
├── policy/    Risk, PermissionVerdict — governance contracts
├── review/    Result, Finding, Comment — review result contracts
├── verify/    Report, Finding — verification report contracts
└── sessions/  Phase, CostAccumulator — session state contracts

Scope

Allowed here

• shared enums (severity levels, risk levels, phases)
• shared structs (findings, tool calls, events, verdicts, reports)
• event models (tool events, trace events, usage info)
• finding/result models (severity, confidence, status)
• engine request/response contracts
• policy and tool contracts

Not allowed here

• CLI code (commands, flags, shell output)
• provider implementations
• runtime logic
• storage implementations
• product orchestration
• anything that belongs in a single consuming repo

Engines should depend on this repo only when they produce or consume a shared cross-repo contract. Contract-free engines (e.g., eyrie, yaad, trace) should not add the dependency just for consistency.

If a type is only used inside one repo, it should stay in that repo.

Migration History

The legacy github.com/GrayCodeAI/hawk/shared/types package has been removed. All shared finding and severity definitions now live here. Migration is complete:

1. Severity and finding definitions migrated from hawk/shared/types
2. sight and inspect migrated to import this repo
3. Tool, event, and policy contracts added
4. Review and verification result contracts added
5. Sessions package added for cross-repo session state

Ecosystem

hawk-core-contracts is a foundation repo in the hawk-eco mono-ecosystem:

hawk and all engines import hawk-core-contracts when they share a real cross-repo contract; the repo itself never imports back.

Ecosystem Boundaries

Rules that keep this repo at the foundation layer:

• Zero hawk-eco dependencies. This repo imports only the Go standard library. make boundaries (also run in CI) enforces this with scripts/check-ecosystem-boundaries.sh.
• Implementation-free. See Scope above — no CLI code, provider implementations, runtime logic, storage, or orchestration.
• Consumers, not dependents. hawk and engines import this repo when they share a real cross-repo contract; it never imports them back.

If a change here would require importing anything outside the standard library, that type does not belong in this repo.

Package Ownership

License

MIT — see LICENSE.