Merge branch 'develop'

Author: devonartis

.githooks/prepare-commit-msg

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# prepare-commit-msg — stamp Claude co-author trailer on Claude-driven commits.
+#
+# Why this exists:
+#   commit.template (.gitmessage) only fires when git opens an editor.
+#   `git commit -m "..."` and HEREDOC variants (used by Claude Code and
+#   scripts) bypass it entirely. That is why commits after 2026-03-30
+#   stopped carrying the "Co-authored-by: Claude" line even though
+#   .gitmessage still declared the intent.
+#
+#   This hook runs on every commit path, strips any existing Claude
+#   co-author line (in any historical variant — "Claude", "Claude Opus 4.6",
+#   "Claude Sonnet 4.6"), then appends the canonical trailer. Result:
+#   exactly one Claude trailer in a consistent form across the log.
+#
+# Scope:
+#   Only stamps when Claude is clearly the driver. Detection is via the
+#   CLAUDECODE=1 environment variable, which Claude Code sets in the env
+#   of every shell command it runs (including `git commit`). A commit you
+#   run yourself in your own terminal has no CLAUDECODE set and is left
+#   untouched — your solo commits stay honestly attributed to you alone.
+#
+#   This is a stronger honesty guarantee than the old .gitmessage template,
+#   which stamped every editor-driven commit regardless of who was typing.
+#
+# Skipped commit sources:
+#   - merge   : git is assembling a merge commit message; don't stamp.
+#   - squash  : git is assembling a squash message from other commits.
+#   - commit  : this is an --amend or cherry-pick reusing an existing
+#               message. The trailer is already on the source commit
+#               (if it should be). Leave it alone so amends don't mutate
+#               history unexpectedly.
+#
+# Install (one-time per clone — already set repo-wide):
+#   git config core.hooksPath .githooks
+
+COMMIT_MSG_FILE="$1"
+COMMIT_SOURCE="${2:-}"
+
+# Only stamp when Claude Code is driving this commit.
+if [[ "${CLAUDECODE:-}" != "1" ]]; then
+  exit 0
+fi
+
+case "$COMMIT_SOURCE" in
+  merge|squash|commit) exit 0 ;;
+esac
+
+TRAILER="Co-authored-by: Claude <noreply@anthropic.com>"
+
+TMP=$(mktemp)
+trap 'rm -f "$TMP"' EXIT
+
+# Strip any existing Claude co-author line. Character classes (not the /I
+# flag) because BSD sed on macOS does not support case-insensitive match.
+# Matches: "Co-authored-by: Claude", "co-authored-by:  Claude Opus 4.6",
+# "Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>", etc.
+sed -E '/^[Cc]o-[Aa]uthored-[Bb]y:[[:space:]]*Claude.*/d' "$COMMIT_MSG_FILE" > "$TMP"
+
+# Append the canonical trailer. interpret-trailers handles the blank-line
+# separator between body and trailer block per git convention. Using
+# addIfDifferent as belt-and-suspenders — we already stripped Claude lines
+# above, so this will always add ours; the flag just guards against future
+# edits to the strip regex.
+git interpret-trailers \
+  --if-exists addIfDifferent \
+  --trailer "$TRAILER" \
+  "$TMP" > "$COMMIT_MSG_FILE"

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed — Delegation framing aligned with non-strict subset behavior (2026-04-15)
+
+- Comments and docs in 9 places claimed delegation enforces strict narrowing ("strict subset", "only narrow", "narrower-scoped"). The actual `authz.ScopeIsSubset` is a non-strict containment check — equal scopes pass, and same-scope delegation is a deliberate pattern (e.g., fan-out to workers carrying the parent's full authority, verified by SDK acceptance Story 8). Wording corrected across `internal/deleg/deleg_svc.go`, `internal/authz/scope.go`, `README.md`, `docs/security-topology.md`, `docs/architecture.md`, `docs/roles.md`, `docs/common-tasks.md`, `docs/integration-patterns.md`, and the `docs/diagrams/security-topology.svg` callout label. Two source-file docstrings now carry a back-reference to issue #41 explaining why this is not a strict-subset check. Closes #41.
+
 ### Added — FAQ from community feedback (2026-04-13)
 
 - New `docs/faq.md` — real questions from practitioners evaluating AgentWrit. Covers identity vs credential exchange, OIDC (enterprise), scope model, scope drift detection (roadmap), SDK status, restart/HA behavior, demo status, and licensing.

README.md

@@ -36,11 +36,11 @@ Traditional IAM was built for humans and long-running services — not for AI ag
 | Traditional IAM for agents | AgentWrit |
 |---|---|
 | Agents get static API keys or service account credentials designed for long-running services | Each agent requests a token scoped to one task |
-| Credentials are over-permissioned because scoping per-task is manual and fragile | Scope attenuation is automatic — permissions only narrow, never expand |
+| Credentials are over-permissioned because scoping per-task is manual and fragile | Scope attenuation is automatic — permissions cannot widen, only equal or narrower |
 | Leaked credential exposes everything the service account can access | Leaked token exposes one task, already expiring in minutes |
 | Revoking a static key means rotating it everywhere it's used | Revocation is instant at 4 levels — token, agent, task, or delegation chain |
 | No visibility into which agent used which credential for which task | Every credential event is audited per-agent, per-task in a tamper-evident hash chain |
-| No native concept of agent-to-agent delegation | Delegation is built in — Agent A can delegate narrower-scoped tokens to Agent B with full chain tracking |
+| No native concept of agent-to-agent delegation | Delegation is built in — Agent A can delegate scope-attenuated tokens to Agent B (equal or narrower) with full chain tracking |
 
 > **What the audit trail covers:** The broker logs credential lifecycle events — issue, renew, revoke, delegate, release, auth failures, and scope violations. It does not see what the agent does with the token at the resource server.
 

docs/architecture.md

@@ -209,7 +209,7 @@ sequenceDiagram
 
 ### Delegation Flow
 
-Agent A delegates a narrower-scoped token to Agent B:
+Agent A delegates a scope-attenuated token to Agent B (equal or narrower scope; widening is rejected):
 
 ```mermaid
 sequenceDiagram

docs/common-tasks.md

@@ -678,7 +678,7 @@ import requests
 BROKER = "http://localhost:8080"
 
 def delegate_token(broker, my_token, delegate_agent_id, scope, ttl=60):
-    """Delegate a narrower-scoped token to another agent."""
+    """Delegate a scope-attenuated token to another agent (equal or narrower)."""
     resp = requests.post(
         f"{broker}/v1/delegate",
         headers={"Authorization": f"Bearer {my_token}"},
@@ -839,7 +839,7 @@ try {
 | Status | Meaning | Action |
 |--------|---------|--------|
 | 400 | Invalid request (bad format, missing fields) | Verify `delegate_to` is a valid SPIFFE ID and `scope` is an array |
-| 403 | Scope escalation or widening attempted | Ensure delegated scope is a strict subset of your scope |
+| 403 | Scope escalation or widening attempted | Ensure delegated scope does not widen your scope (equal or narrower is accepted) |
 | 404 | Delegate agent not found in broker | Verify the agent's SPIFFE ID is correct and it has registered |
 | 401 | Your token is invalid or expired | Renew or re-register to get a fresh token |
 

docs/diagrams/security-topology.svg

@@ -2092,7 +2092,7 @@ When implementing AgentWrit patterns, verify:
 ### Scope and Delegation
 
 - [ ] Scope ceilings are enforced at the broker level
-- [ ] Delegation always narrows scope (never escalates)
+- [ ] Delegation does not widen scope (equal or narrower)
 - [ ] Delegation depth is limited (maximum 5 hops)
 - [ ] Scope format is validated: `action:resource:identifier`
 - [ ] Wildcard scope (`*`) is used narrowly and intentionally

docs/integration-patterns.md

@@ -94,7 +94,7 @@ write:logs:agent-run-42
 | `POST /v1/token/validate` | External services check this token to decide if the agent is authorized |
 | `POST /v1/token/renew` | Extend the session — same scope, same original TTL, old token revoked first |
 | `POST /v1/token/release` | Self-revoke when the task is done |
-| `POST /v1/delegate` | Create a narrower-scoped token for another registered agent |
+| `POST /v1/delegate` | Create a scope-attenuated token (equal or narrower) for another registered agent |
 
 **What the agent cannot do:** call any admin or app endpoint. It has no `admin:*` or `app:*` scopes. The broker enforces this.
 

docs/roles.md

@@ -27,7 +27,7 @@ Scopes only move in one direction: down. Every boundary is enforced at issuance
 
 - **Challenge-response** — Ed25519 keypair per agent instance. No shared secrets at the agent level.
 - **Hash-chain audit** — tamper-evident trail with 24 event types. Each record hashes the previous.
-- **Scope attenuation** — scopes can only narrow, never escalate. Delegation preserves the original principal.
+- **Scope attenuation** — scopes cannot widen; equal or narrower is accepted. Delegation preserves the original principal.
 - **Token TTL** — default 5 minutes, max 24 hours (configurable). Per-app override available. Revocable at 4 levels.
 
 ---

docs/security-topology.md

@@ -72,7 +72,10 @@ func scopeCovers(requested, allowed string) bool {
 // least one scope in allowed. A scope is covered when its action and
 // resource match and either the identifiers are equal or the allowed
 // identifier is the wildcard "*". This enforces the attenuation rule:
-// scopes can only narrow, never expand.
+// requested scopes cannot widen allowed scopes. Equal is accepted
+// (same-scope delegation is a deliberate pattern); narrower is accepted;
+// broader is rejected. See issue #41 for why this is not a strict-subset
+// check.
 func ScopeIsSubset(requested, allowed []string) bool {
 	for _, req := range requested {
 		covered := false