0015: The governance decision point¶

Status: mostly built (2026-10-27): every kind is wired (#172, #173), with events (#190) and the control-plane passport client (#174) and break-glass (KAN-33; its replay to Tower isn't built). Tower's side has the decision API (Tower#13), signed events (Tower#17), attestation receipts (Tower#18) and approver ≠ requester (Tower#19). · Date: 2026-10-16 · Builds on: 0002 (landing), 0011 (triggers and approvals), 0014 (manifest digests), #121 (one approval rule), #123 (intake posture), #129/#130 (taint and its gates) · Counterparts in Tower (a private repository for now): Tower#13 (decision API), Tower#14 (passports), Tower#16 (correlation), Tower#17 (webhooks), Tower#18 (receipts), Tower#19 (approver ≠ requester), Tower#20 (reconciliation), Tower#22 (per-run stop)

Part of a set. Ownership, cross-spec decisions and the combined build order are in docs/README.md; where this spec conflicts with that page, the page wins.

The governed workspace this spec names is Tower, the product's name since October 2026; the spec keeps the name it was written with.

1. The split¶

hangar is the Run plane: it holds sandboxes, credentials, sessions, jobs and landing, and it enforces. Tower is the Govern plane: one policy decision point (Cedar), approvals and their inbox, passports and hash-chained receipts, and it decides. hangar's approvals ask Tower instead of hangar keeping a second approval system.

Tower decides only whether a person or a policy allows something. Everything about how it happens stays in hangar:

Two rules follow. Tower never makes hangar more permissive than hangar's own enforcement: an allow lets hangar proceed with its own checks; it never skips them. Nothing that goes wrong on the way is ever an allow (§6).

2. The five decisions¶

Tool calls only reach Tower under approvals: ask and only for the calls hangar's rules flag; auto turns and unflagged calls never leave hangar, which keeps the latency budget (§5) off the common path.

3. The client interface¶

src/hangar/governance.py (built in this spike, not yet wired):

class DecisionPoint(Protocol):
    async def decide(self, req: DecisionRequest) -> Decision: ...
    async def status(self, approval_id: str, *, kind: Kind) -> Decision: ...
    async def withdraw(self, approval_id: str, reason: str) -> bool: ...

class Decision(BaseModel):
    outcome: Literal["allow", "deny", "wait"]
    reason: str; approval_id: str | None; receipt: str | None; expires_at: float | None
    status: str | None          # Tower's approval state, or "unavailable" / "local"
    rule: str | None
    source: Literal["workspace", "local", "fail_closed"]
    failure: str | None         # why it failed closed: timeout, server_error, auth, malformed, ...
    retryable: bool

The protocol differs from the issue's sketch in two places: status takes the kind (so a failure falls back to that kind's row of §6), and withdraw exists (§4.5). The request's requested_by became requester (whose work it is) plus signer (who acted), because "the approver" and "the requester" are different people and Tower must tell them apart (§4.4).

4. Wire contract: hangar.decision/v1¶

JSON over HTTPS, snake_case, times in RFC 3339 (Z or an offset). Within v1 either side only adds optional fields; anything removed or renamed is v2.

4.1 Request¶

POST {tower}/v1/decisions, headers Authorization: Bearer <credential> (§9), Idempotency-Key: <key> (same as the body's), traceparent (§10).

{
  "v": "hangar.decision/v1",
  "kind": "hangar.job.release",
  "idempotency_key": "hangar:job:j-4143a542:release",
  "requester": {"external": "github:9912345"},
  "subject": {"job": "j-4143a542", "repo": "acme/api", "environment": "hangar-jobs"},
  "action": {"detail": "Fix the flaky retry test in tests/test_client.py"},
  "context": {"untrusted_source": "github:9912345", "tainted": true},
  "correlation": {"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01", "job": "j-4143a542"},
  "deadline": "2026-10-17T14:05:00Z"
}

A tool call relayed from an ask turn:

{
  "v": "hangar.decision/v1",
  "kind": "hangar.tool.call",
  "idempotency_key": "hangar:session:s-77:tool:ap-1a2b3c4d5e6f",
  "requester": {"person": "p-12", "email": "dev@acme.test"},
  "subject": {"job": "j-9", "session": "s-77", "turn": 3, "run": "r-5d1", "repo": "acme/api",
              "environment": "hangar-jobs", "harness_digest": "sha256:9f2c", "model": "claude-opus-4-5-20251101"},
  "action": {"tool": "Bash", "args_hash": "0f40a5cddf23051ff00817f5a7674212fa48257ff339c86f0fbedfc2503e88f7",
             "detail": "git push origin HEAD:main", "risky": "git push to a protected branch"},
  "context": {"tainted": true},
  "correlation": {"traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-a1b2c3d4e5f60718-01", "job": "j-9",
                  "session": "s-77", "turn": 3, "run": "r-5d1", "tool_call_id": "toolu_01ABC"},
  "deadline": "2026-10-16T15:10:00Z"
}

4.2 Response¶

200 with:

{"v": "hangar.decision/v1", "decision": "wait", "approval": "A-123", "expires_at": "2026-10-17T14:05:00Z",
 "status": "waiting", "rule": "release-untrusted-job",
 "reason": "Waiting for Dana or Lee (maintainers) to sign A-123: an untrusted job needs a maintainer.",
 "poll": "/v1/decisions/A-123"}

{"v": "hangar.decision/v1", "decision": "allow", "approval": "A-123", "receipt": "RC-104", "status": "approved",
 "rule": "release-untrusted-job", "reason": "Signed by Dana (A-123)."}

How hangar reads deny: status blocked or denied is the policy or a person saying no (a job is rejected with the reason, a tool call denied, a landing not armed, a request denied). expired and withdrawn mean nobody decided: hangar treats them like its own expiry (the job's expire_approvals path, a landing waiting for the next approval) rather than a rejection.

HTTP status codes and what hangar does:

4.3 Idempotency¶

One approval per thing a person decides on, keyed as in §2. The rules:

1. The same key returns the same approval while it waits.
2. A settled deny (blocked, denied) keeps returning that deny for the approval's ttl: an agent retrying a declined call is told no again.
3. job.release and landing.approve keep returning their settled allow (with its receipt) for the ttl, so hangar can replay after a restart.
4. A tool.call allow is single use (Tower's claim_clearance): the first answer that carries it consumes it, and the key is spent. A retry of the same HTTP request after a lost response gets the same answer (Tower keys its response cache on the idempotency key for 10 minutes).
5. expired and withdrawn approvals don't bind the key: the next request opens a new approval.

The key never includes anything a caller controls beyond hangar's own ids. A new PR head is a new landing key, and hangar withdraws the old one.

4.4 Signatures from hangar surfaces¶

A person can act in hangar (/hangar approve on GitHub or Jira, hangar job approve, MCP approve_job, answer_approval, a PR review) or in Tower (Slack, Teams, the web inbox). Both reach the same approval:

• In Tower: Tower records the signature itself and pushes approval.decided (§12).
• In hangar: hangar first runs its own local check (approvals.can_decide: never your own work, #121), then sends decide with the same idempotency key and a signer. Tower counts it as a signature only if its own rules let that person sign: in the approver group, not the requester (Tower#19, across every platform id), the self-approval annotation for low-risk packets, multi-signature counts. It records proof: "hangar:<via>". The answer is allow (rule satisfied, with receipt), wait (needs more signatures), or deny with status: denied and the reason when the signer may not sign or verdict was reject.

A signer Tower can't map to a user (no verified email) is not a signature: the answer is wait with a reason saying so, and hangar tells the person to sign in Tower.

4.5 Status and withdraw¶

GET /v1/decisions/{approval} returns the §4.2 shape, for approvals of the calling agent only (anything else is 404). It is the source of truth: hangar acts on it, never on an event's payload (§12).

POST /v1/decisions/{approval}/withdraw with {"v": "hangar.decision/v1", "reason": "..."} closes a waiting approval nobody needs any more: hangar expired the job (expire_approvals), the job was cancelled, a push replaced the PR's head, the turn ended before an answer. Tower closes its cards and writes a withdrawn receipt (its existing Governor.withdraw).

4.6 Dry run¶

dry_run: true evaluates the rules for shadow mode (§7) and answers what it would decide: decision, rule, reason, and no approval, cards or receipt. It doesn't count toward the agent's hourly budget.

5. Timeouts and waiting¶

No call blocks while a person decides. decide answers wait at once; hangar keeps the thing pending in its own state and follows the approval:

• job.release: the job stays awaiting_approval with job.approval.workspace_approval_id (#172). An approval.decided event, or the 60 s poll of waiting jobs, re-reads the status; allow queues the job, deny rejects it.
• landing.approve: landing.note says who must sign; the landing is re-evaluated on the event, the next push, or the poll.
• egress.request, secret.request: the request stays pending with the approval id; the owner sees where to sign.
• tool.call: the turn's pending approval shows Tower's approval id and link. Then:
• With events on and a harness that can checkpoint, once the call has waited suspend_after (60 s; #190 owns the value) hangar denies it with "Paused for approval A-9; this turn resumes when it's signed", lets the turn end at that tool boundary, checkpoints, and releases the sandbox. The session is awaiting_approval.
• On approval.decided hangar re-reads the status. allow resumes the session from its checkpoint and pre-clears that one call in the driver: hangar passes (tool, args_hash, receipt), and the driver allows the first matching call once, records the receipt on the approval, and asks as usual for anything else. The resumed turn doesn't ask Tower again, so Tower's run id changing with the turn number doesn't matter. deny leaves the session idle with the reason as an event (#190).
• Without events, or for a harness that can't checkpoint, the turn waits as ask turns do today, up to the driver's own deadline, then the driver denies. This replaces the hook's fixed 540 s poll for hangar sandboxes; it isn't another one.

6. Fail closed¶

What each kind does when Tower can't answer. retryable failures are retried in the background (the 60 s poll for pending things; within the driver's deadline for a tool call); none of them ever becomes an allow.

Self-approval is refused locally before any of this (#121, #160): Tower being down never turns a refused self-approval into a pending one.

7. Modes and break-glass¶

HANGAR_GOVERNANCE=off|shadow|enforce sets the default; HANGAR_GOVERNANCE_MODES overrides per kind (tool.call=shadow,landing.approve=enforce or JSON). The default is off.

A disagreement is any different outcome. Local allow against remote wait ("Tower would have asked someone") is the common one while policies are tuned.

Break-glass. hangar governance local --until <time> --reason <text>, by an admin, confirmed by a second admin, at most 24 hours, audited governance.break_glass (start, confirm, end). While active, kinds in enforce are decided by the local rules; each such decision is queued and replayed to Tower as a record once it answers again (an open item for Tower, §16), so its receipts have no gap. Break-glass never applies to off or shadow kinds (they're local already) and ends on its own.

hangar refuses to start with shadow or enforce and no HANGAR_GOVERNANCE_URL, and hangar doctor checks the URL, the credential and the webhook secret.

8. Offline and cluster down¶

9. Identity¶

Control-plane calls (every kind in §2 is asked by hangar's control plane, not by a sandbox):

1. Phase 1, a service key. HANGAR_GOVERNANCE_CREDENTIAL names a secret in hangar's vault; Tower stores its hash for an agent of kind hangar, scoped to /v1/decisions* (Tower#13). It can assert any requester and signer, so it is as powerful as hangar's admin token and is rotated like one.
2. Phase 2, a passport (#174, Tower#14). hangar mints itself a token (iss = hangar's OIDC issuer, sub: hangar:control-plane, aud = Tower's /oauth/token, 5 minutes; a new CloudCreds method, since mint needs a sandbox today), exchanges it (RFC 8693) for a 15-minute passport, caches it until 60 s before expiry, and re-exchanges on a 401 (Credential.token(fresh=True)). Tower trusts that issuer for agent hangar with claims: {sub: "hangar:control-plane"}. The service key goes.

The requester and signer still come from the body, signed by hangar's TLS-authenticated identity; they are accepted only from the hangar agent.

Sandbox calls are a different path: an environment with a governance: block installs a hangar-owned Claude Code hook that exchanges the sandbox's token (sub: hangar:env:<env>) for a passport naming the person, and calls /hooks/claude-code directly (#174, #175, Tower#14). A turn uses exactly one path. With the managed hook, Tower sees every call through /hooks, and hangar's driver answers only from its local deny-risky rules as a guard rail, never relaying to Tower as well; without it, the driver relays flagged ask calls as tool.call (§5). Otherwise one call would raise two approvals.

10. Correlation¶

Every request carries hangar's ids and the W3C trace context of the span that asked:

• the traceparent header and correlation.traceparent: for a tool call, the turn's invoke_agent span (the same TRACEPARENT the agent runs with, fleet.py); for a release or landing, the job's span;
• correlation: job, session, turn, run (hangar's run id), tool_call_id (the harness's id for the call: Claude Code's tool_use_id).

Tower stores them on its run and receipts (corr, Tower#16; its run id becomes R-h-<session>-<turn>, or R-h-job-<job> for a release with no session) and echoes corr in events. hangar records each decision as a governance.decide span with hangar.governance.kind, .mode, .outcome, .approval, .receipt, .source and .failure, and puts the receipt on the approval's span so reconciliation can match exactly (#176, Tower#20).

args_hash is the one value both sides compute: lowercase hex SHA-256 of json.dumps(input, sort_keys=True, separators=(",", ":"), default=str) over the harness's tool input as the harness sent it, before any clipping. hangar sends it; Tower records it on the receipt for hangar.tool.call (it doesn't recompute it from detail, which is clipped); hangar's exported execute_tool span carries the same value as gen_ai.tool.call.arguments.hash.

11. Receipts¶

In enforce, an allow without a receipt is refused (§4.2). hangar keeps the id where the decision lives and shows it:

For job.release and landing.approve hangar also sends subject.harness_digest, environment_digest and the concrete model from the turn's manifest (0014), and context.checks with trusted set for hangar's own verification, so Tower's receipt carries the attestation envelope (aw.attest/v1, Tower#18). hangar links to GET /v1/receipts/{id}/attestation; it doesn't verify the chain itself. Local, shadow and break-glass decisions carry no receipt (break-glass decisions get one when replayed).

12. Events from Tower¶

One inbound route, POST /api/governance/events, for everything Tower pushes (it replaces the separate /api/governance/decisions callback #172 sketched; #190 builds it):

• Signature (Tower#17): X-AW-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, t + "." + body)>, X-AW-Event-Id. The secret is HANGAR_GOVERNANCE_WEBHOOK_SECRET in hangar's vault, one per subscription. Rejected and audited: no or bad signature, t more than 300 s off, an event id seen before (ids are kept 48 h, past Tower's 24 h retry window), a malformed body.
• Approval events are hints. approval.created and approval.decided only make hangar re-read GET /v1/decisions/{approval} with its own credential and act on that answer. A forged, replayed, stale or reordered event can at most cause a status read, so out-of-order delivery ("decided" before "created") needs no special handling.
• run.stop (Tower#22) interrupts the run through hangar's existing interrupt path, is audited with who stopped it, and marks the session so that no later approval.decided resumes it. It only removes capability, so it is acted on once its signature checks out. Tower never holds a hangar admin token for this.
• Events that arrive during the power-down are applied to hangar's state at once; anything that needs a sandbox waits for power-up.

{"id": "ev-01HF3", "kind": "approval.decided", "at": "2026-10-16T15:02:11Z",
 "approval": {"id": "A-123", "status": "approved", "idempotency_key": "hangar:job:j-4143a542:release",
              "decided_by": "dana@acme.test", "receipt": "RC-104", "expires_at": "2026-10-17T14:05:00Z"},
 "corr": {"source": "hangar", "job": "j-4143a542", "session": null, "turn": null}}

13. Security notes¶

• The hangar agent's credential can assert requesters and signers. Phase 1 scopes the key to /v1/decisions*; phase 2 replaces it with a 15-minute passport. Either way it never reaches a sandbox.
• A signer asserted by hangar is only as good as hangar's front door: GitHub numeric ids, linked accounts (people.py), never logins. Tower records proof: hangar:<via> so an auditor can tell those signatures from ones made in Tower.
• action.detail is content (a command, a file path). It is redacted (broker.redact), clipped to 2000 characters with both ends kept (driver.shown), shown on the approval card, and forgotten by Tower once decided (its AD-6). Receipts keep only args_hash. Events carry ids and hashes only.
• hangar posts Tower's reason on public issues; it is redacted on the way out like any other text hangar writes there.

14. Rollout¶

Any phase rolls back by setting the kind back to shadow or off; nothing is migrated, and receipts already written stay.

15. Where Tower's API differs from what hangar needs¶

Each item is proposed as a comment on the Tower issue that owns it.

16. Open items¶

• Break-glass replay (§7, item 21): the record request's shape is agreed only in outline.
• Approval ttl for landings: Tower's merge_pull_request ttl is 3 days; hangar has no landing deadline today. hangar sends none for now.
• Who signs in Tower for a team job (no person): requester is empty and only context.untrusted_source is set; maintainers sign. Fine for release; for landing, the policy approvers decide in hangar today, so their mapping to a Tower group needs agreeing per repo.
• Multi-signature from hangar surfaces: two /hangar approve comments by different people each add a signature; the second gets the allow. Tested on Tower's side once Tower#13 lands.

17. What the contract tests pin¶

tests/test_governance.py, against a fake Tower (httpx.MockTransport):

• each row of §6 for every kind: unreachable, timeouts, 500/502/503 (including 503 {"decision":"deny"}), 429, 401 after a refresh, 403, 400, a malformed body, an allow without a receipt, an open circuit: none is ever allow;
• the 401 retry with a fresh token; the circuit opening and closing;
• wait followed by status polling until allow, a webhook waking the waiter, and the deadline failing closed;
• shadow never changing the outcome and reporting disagreements; enforce using Tower; break-glass needing two admins and 24 h at most;
• args_hash equal to Tower's own function;
• the JSON examples in this document parse with the client's models, and an event signed as Tower#17 specifies verifies (stale, replayed and tampered ones don't).