Adapter contract

Note

Specification: accepted. Implemented in part in the source build. Remaining requirements and external validation are not complete.

Version: shiin.adapter-contract/v1-draft.1.

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

An adapter connects a host to Shiin. An adapter intercepts proposed actions, builds action requests, and enforces the resulting decision using the host’s own protocol. Adapters never make decisions (ADR-0025, ADR-0026).

Interception

[ADP-001] An adapter MUST intercept proposed actions before the host executes them.

[ADP-002] An adapter MUST normalize the host payload into an action request (AR-001).

[ADP-003] An adapter MUST NOT classify an action more permissively than the host payload allows. Anything the adapter cannot classify MUST become an opaque effect (ADR-0018).

Enforcement

[ADP-004] An adapter MUST enforce the decision using the host’s own protocol.

[ADP-005] An adapter MUST return allow only when the decision is allow.

[ADP-006] An adapter MUST return deny when the decision is deny.

[ADP-007] For a pending decision, an adapter MUST either wait for an approver, use the host’s native prompt, or deny with a ticket (ADR-0028).

With the local daemon configured, pending actions are denied with an approval ticket on all three adapters. Daemonless Codex and Cursor still deny pending actions without a ticket when native holding behavior is unsupported or unverified. The full approval workflow requires the configured local service; daemonless operation does not fully satisfy ADP-007.

[ADP-008] An adapter MUST produce deny on any error, timeout, or crash (ADR-0013).

Enforcement level

[ADP-009] Every adapter MUST declare an enforcement level: L1 cooperative, L2 mediated, or L3 OS-enforced (ADR-0033).

[ADP-010] An adapter’s documentation MUST state what it cannot see.

Audit

[ADP-011] An adapter MUST write an audit event before a non-read action is allowed to proceed.

[ADP-012] An adapter MUST record every decision, approval, and grant.

Hosts

Revision history

• Accepted on 2026-10-12. Accepted: the contract matches the hook behavior verified for Claude Code, Codex CLI, and Cursor on 2026-09-14.
• v1-draft.1 (2026-10-01): Initial draft.