Glossary

Note

Reference: draft. This is the only place Shiin terms are defined. Every other page links here instead of redefining a term.

Terms are listed alphabetically. Each entry gives a definition, what the term is easily confused with, and where its precise rules live. To propose a new term or change a definition, open a pull request that edits this page and every page that uses the term.

Action

An operation an agent attempts that has an effect outside the agent itself, such as reading a file, running a command, or contacting a host. The action is Shiin’s unit of authorization.

• Not to be confused with: a tool call, which is a host’s name for how an agent invokes a capability. One tool call can contain several actions.
• Rules: Action types.

Action request

The normalized, host-independent description of one proposed action. An adapter builds it and the engine evaluates it.

• Rules: Action request.

Action type

A dotted identifier that classifies an action, such as fs.write or shell.exec. Policies refer to action types, never to host tool names.

• Rules: Action types.

Adapter

The component that 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.

• Rules: Adapter contract.

Agent

Software that uses a model to propose actions on a person’s behalf, such as Claude Code or Codex CLI. Shiin treats every agent as untrusted.

• Not to be confused with: the host, which is the application the agent runs in. For many products the agent and host ship together.

Agent identity

The identifier of the agent that proposed an action, together with its assurance level.

• Not to be confused with: approver identity, which identifies the human resolving an approval request.
• Rules: Identity.

Allow

The decision value meaning the action may proceed. Only policy rules and grants can produce allow.

• Rules: Decision, Evaluation.

Approval channel

A route by which approval requests reach approvers, such as the command-line approver or a webhook.

• Rules: Approval protocol.

Approval request

A pending decision waiting for an approver to resolve it.

• Rules: Approval protocol.

Approver

A human authorized to resolve approval requests. An approver approves or denies; the resulting decision is allow or deny.

Assurance level

How strongly an agent identity is established. The levels, weakest first, are asserted, attested-local, attested-os-user, and attested-crypto (reserved for the future).

• Rules: Identity.

Audit event

One record in the audit log, such as a received request, a decision, or an approval resolution.

• Rules: Audit events.

Audit log

An append-only JSON Lines file of audit events linked by a hash chain. The audit log is tamper-evident, not tamper-proof.

• Rules: Audit events.

Built-in protected resource

A resource that no policy can make allowable for agents, such as Shiin’s own state, keys, and audit log, host hook configuration, and approval commands.

• Rules: Policy model, ADR-0016.

Capability

A coarse permission for an agent to attempt a whole class of actions at all, for example “may run shell commands”. The capability stage is a gate.

• Not to be confused with: object capabilities (unforgeable tokens), which Shiin does not use.

Checkpoint

A signed statement of the audit log’s head hash at a given position.

• Rules: Audit events, Cryptography.

Classifier

Deterministic code that derives action types and effects from what a host reports. Classifiers only ever make decisions stricter: anything they cannot classify becomes an opaque effect.

• Rules: Action request, ADR-0018.

Constraint

A machine-checkable limit inside a task declaration. The closed set of constraint kinds is scope.paths, forbid.action_types, allow.hosts, limits, expires_at, and require_pending_for.

• Rules: Intent binding.

Decision

The engine’s answer to an action request: allow, deny, or pending, with a reason code.

• Rules: Decision.

Default decision

The decision made when no rule matches. It is deny, can be configured to pending, and can never be allow.

• Rules: Evaluation.

Deny

The decision value meaning the action must not proceed. A deny from any stage wins over every other result, including grants.

Deny-with-ticket

How pending is expressed to a host that cannot wait for an approver: the adapter denies the action now and returns an approval ticket. If the agent retries after an approver approves, the retry consumes a single-use grant.

• Rules: Approval protocol, ADR-0028.

Developer

The person using an agent to do work. Often the same person as the operator and the approver, but the roles are distinct.

Effect

A concrete consequence of an action, such as a path written or a host contacted, recorded with a confidence of exact, inferred, or opaque.

• Rules: Action request.

Enforcement level

How strongly a Shiin decision is enforced for a given adapter. At L1 Cooperative, the host honors the decision through its hook mechanism, which can be disabled. At L2 Mediated, Shiin sits in the data path, as the MCP proxy does. At L3 OS-enforced (future), the operating system or a sandbox enforces the decision.

• Rules: Enforcement levels, ADR-0033.

Engine

The pure, synchronous component that evaluates an action request against a policy snapshot and returns a decision. It performs no I/O.

• Rules: Evaluation, ADR-0010.

Fail-closed

The rule that any failure (an error, a timeout, an unreadable policy) results in deny.

• Rules: Security model, ADR-0013.

Gate

An evaluation stage that can return deny, pending, or pass, but never allow. The identity, capability, intent, and risk stages are gates.

• Rules: Evaluation.

Grant

A stored authorization created when an approver resolves an approval request.

• A single-use grant is bound to the digest of one action request.
• A scoped grant covers an agent, action types, a resource pattern, and a workspace, and expires.

A grant can satisfy only a grantable pending result. It never overrides deny.

• Rules: Approval protocol, ADR-0027.

Hash chain

The construction in which each audit event includes the hash of the event before it, so removing or altering an event is detectable.

Hook

A host mechanism that runs an external program before or after the agent uses a tool, and that can accept a decision back. Hooks are the interception point for L1 adapters.

Host

The application that runs an agent and exposes an interception mechanism, such as Claude Code, Codex CLI, Cursor, or an MCP client.

Intent binding

Checking an action against the constraints of the active task declaration. Natural-language descriptions of intent are recorded but never evaluated.

• Rules: Intent binding, ADR-0020.

Opaque effect

An effect Shiin cannot determine before the action runs, such as what python cleanup.py will do. Opaque effects lead to pending by default.

Operator

The person who installs and configures Shiin and writes its policy.

Outcome verification

A reserved concept: checking after an action runs that its real effects matched what was authorized. It is not yet specified.

• Not to be confused with: receipt verification.

Pending

The decision value meaning the action must wait for an approver. A pending decision that is never resolved expires as deny; it never becomes allow on its own.

Policy

The complete set of rules, capabilities, defaults, and risk configuration that applies to an evaluation, drawn from every policy layer.

• Rules: Policy model.

Policy layer

One source of policy. Layers, in order, are built-in, user, and workspace. An organization layer is reserved for the future. A workspace layer can only restrict unless the operator trusts it by hash.

• Rules: Policy model, ADR-0015.

Policy snapshot

The immutable input to one evaluation: compiled policy, grants, active tasks, and counters, identified by a snapshot hash.

• Rules: Evaluation.

Reason code

A stable, machine-readable code that explains a decision, such as deny.policy.

• Rules: Decision.

Receipt

A signed statement that attests a decision was made, using a DSSE envelope and an Ed25519 signature.

• Rules: Receipts, ADR-0031.

Receipt verification

Checking that a receipt’s signature and contents are valid. It proves who signed a statement about a decision, not that the action’s real outcome was correct.

Replay

Re-evaluating recorded action requests against their recorded policy snapshots, or against a different policy to answer “what if”.

Requirement ID

A stable identifier, such as EVAL-007, for one normative requirement in a specification.

Resolution

An approver’s answer to an approval request: allow_once, allow_always, or deny.

Risk signal

A discrete, deterministic property of an action request, such as bulk_delete or secret_path, that can escalate a decision. Shiin does not use numeric risk scores.

• Rules: Risk signals.

Rule

A policy element that matches action requests and produces allow, deny, or pending.

Session

One run or conversation of a host, identified by the host’s session ID.

Shiin

The project. shiin is the command-line binary and shiind is the daemon.

Stage

One step of evaluation. The stages, in order, are identity, capability, policy, intent, and risk. Later stages can only restrict the result of earlier ones.

• Rules: Evaluation, ADR-0012.

Task declaration

A structured, human-confirmed statement of what an agent is working on: a description, constraints, and an expiry. Also called a task.

• Rules: Intent binding.

Trace

The record of each stage’s result for one decision, produced in explain mode and used by replay.

Workspace

The project directory an agent works in, and the root of the workspace policy layer.

Avoided terms