Delegation Hygiene

Two edges from one delegator average to one score

The public reputation fixture gives one delegator two parent and child pairs. One child copies its parent; the other narrows it on every count.

child-a keeps parent-a’s shell/exec permissions, its cap of 100 invocations, and its expiry, so its signals are 0, 0, 0. child-b takes parent-b’s net/post, removes delegation, adds a domain constraint, cuts invocations from 50 to 5, and expires earlier, so its signals are 1, 1, 1.

With the fixture’s issuance times and the default 30-day half-life, the edges weigh about 0.957398 and 0.959962. Each rate, and the mean of the three, comes to about 0.500669: the narrowing edge is slightly newer, so it weighs slightly more.

Each rate is a time-weighted share of narrowing edges

For every scored edge the weight halves every 30 days after the child’s issuance. Each rate divides the weighted positive signals by the sum of all scored-edge weights, and the score is the mean of the three rates, clamped to the unit interval.

Every rate and the score is a MetricValue: {"state":"known","value":0.5} or {"state":"unknown"}. Unknown means no edge could be scored. Known zero means edges were scored and none earned weighted credit, a different result that a policy reads differently.

Read more in the weighting recipe, with the half-life and edge cases.

The score sees children the subject issued whose parent resolves

compute_local_scorecard selects lineage records whose issuer_key is the subject and that carry a parent_capability_id. compute_delegation_hygiene then resolves that parent id against the corpus.

• Issued by the subject, parent resolves: one observation, and all three predicates run.
• A root with no parent id: outside the candidate set.
• A parent record absent from the corpus: skipped before any rate or count changes.
• No children, or every parent absent: unknown score and rates, with delegations_observed at 0.

A received capability is not an issued delegation, so a grandchild issued by another agent counts toward that intermediate agent. The local corpus builder combines snapshots the subject holds with snapshots it issued, so a parent the delegator holds resolves beside its children. The kernel derives a snapshot’s parent id from the last delegation-chain link when it records an observed capability, and writes no snapshot when no receipt store is configured.

To see the edges a delegator will be scored on, walk forward one level from a grant it holds. The fixer from Delegate Between Agents issued one child:

chio lineage query --live --seed cap-01d2…2a90 --direction forward --depth-limit 1

walk     forward from cap-01d2…2a90, depth limit 1
depth 0  cap-01d2…2a90  capability  fixer
depth 1  cap-01d2…6c13  capability  tester  delegated from cap-01d2…2a90
2 nodes, 1 edge, walk stopped at depth 1

That edge removed write, cut thirty minutes to ten, and lowered the cost ceiling from USD 2.00 to USD 0.50, so it scores 1, 1, 1.

Each predicate records that a restriction happened, whatever its size

Each edge answers three yes-or-no questions. Removing one operation and removing several earn the same credit.

1. Scope. Any child tool grant without a compatible parent grant vetoes scope credit for the edge. Otherwise the edge earns credit for fewer tool, resource, or prompt grants, or for a matching tool grant that drops operations, adds or changes constraints, or tightens a cap.
2. Expiry. The child’s absolute expires_at is strictly earlier than the parent’s. An inherited deadline earns zero even when the child was issued later, and this predicate runs whether or not tool grants match.
3. Budget. At least one matching tool grant introduces or reduces max_invocations, max_cost_per_invocation, or max_total_cost, with monetary caps in the same currency. Any match earns it, with no edge-wide veto.

A separate expansion fixture shows why a middling score needs its rates read. A parent holds fs/read_file and its child holds fs/write_file with an earlier expiry and an invocation cap of 5. The tool cannot match, so the source asserts scope 0, expiry 1, and budget 0 over one observation: a mean of one third with no narrower authority behind it.

Read more in Scope reduction, Earlier expiry, and Tighter limits.

A copied child scores 0.0 and a narrowed child 1.0

Compare a child that copies its parent's scope, quota and expiry with a child that removes delegation, reduces the quota from 100 to 1 and shortens its lifetime. Each corpus contains a resolvable parent-child pair. The binary ships in the swarm authority project, which the Rust example setup builds.

cargo run --locked --features reputation --bin hygiene

passthrough: {"score":{"state":"known","value":0.0},"delegations_observed":1,"scope_reduction_rate":{"state":"known","value":0.0},"ttl_reduction_rate":{"state":"known","value":0.0},"budget_reduction_rate":{"state":"known","value":0.0}}
narrowed: {"score":{"state":"known","value":1.0},"delegations_observed":1,"scope_reduction_rate":{"state":"known","value":1.0},"ttl_reduction_rate":{"state":"known","value":1.0},"budget_reduction_rate":{"state":"known","value":1.0}}

You should see one observation per history, every rate known, and scores of 0.0 and 1.0. The scoring API reads lineage snapshots; establish where those records came from before an issuance or passport decision relies on the score.

Known hygiene feeds the composite, issuance tiers, and passport floors

Delegation hygiene has a default weight of 0.15 in the eight-metric scorecard. Only known metrics contribute their weighted value and their weight, so unknown hygiene drops out of both sides instead of counting as zero. A weight of 0.15 is exactly 15% only when the contributing weights total 1.0; read effective_weight_sum for the actual share.

• Local issuance tier. The effective composite, under any probationary ceiling, resolves to a configured tier, which enforces its max_scope. With max_delegation_depth set to 0 a tool grant containing Delegate is refused; with constraints_required an unconstrained tool grant is refused.
• Passport verifier policy. PassportVerifierPolicy can require minDelegationHygiene against the scorecard a ReputationCredential carries in credentialSubject.metrics. Unknown hygiene adds the reason “delegation_hygiene is unknown but policy requires a minimum,” even at a minimum of zero; a low known score adds its value and the minimum.
• Marketplace feed tier. tier_from_deltas derives its tier from ScoreDelta feed inputs and reads no local hygiene field. The guard-market CLI passes an explicit parsed tier to its tenant context and uses the trusted fiscal service.

Tune the weight through extensions.reputation.scoring.weights.delegation_hygiene; validation requires a finite value in [0, 1], and the weights need not sum to one. The public passport example sets its floor to 0.70, a value each verifier chooses. Reasons accumulate across the policy checks, and the credential’s signature authenticates its issuer’s statement, so assess that issuer and its evidence.

Read more in Reputation Scoring and Agent Passport.

The score describes recorded behavior; provenance comes from its caller

The pure scoring function is deterministic over the corpus, time, and configuration it receives. Assembling the database and deciding whom to trust belong to its caller, and the metric reads snapshot fields as given, leaving capability signatures, parent-chain authenticity, and complete attenuation to the verifiers that check them.

A boolean credit shows that a recognized reduction occurred, not that the child held only the authority it needed. Zero observed looks the same whether nothing was delegated or the lineage was unavailable. Caps describe authority; spend and settlement live in the budget store. Sub-Agent Budgets covers enforcement once the child uses its grant.

chio reputation compare compares the composed hygiene score, so equal totals can hide changed scope, expiry, and budget rates. Portable normalization rounds known values to nine decimal places and keeps the three rates and the observation count. Portable Reputation explains the exported statement.

Fields, predicates, and diagnostics

chio --format json \
  --receipt-db ./receipts.db \
  reputation local --agent fixer

age = max(now - child.issued_at, 0)
weight = 2 ^ (-age / half_life_seconds)
rate = sum(signal * weight) / sum(weight)
score = (scope + expiry + budget) / 3

{
  "weights": {
    "boundary_pressure": 0.2,
    "resource_stewardship": 0.1,
    "least_privilege": 0.15,
    "history_depth": 0.1,
    "tool_diversity": 0.05,
    "delegation_hygiene": 0.15,
    "reliability": 0.15,
    "incident_correlation": 0.1
  },
  "delegation_hygiene": {
    "score": {
      "state": "unknown"
    },
    "delegations_observed": 0,
    "scope_reduction_rate": {
      "state": "unknown"
    },
    "ttl_reduction_rate": {
      "state": "unknown"
    },
    "budget_reduction_rate": {
      "state": "unknown"
    }
  },
  "effective_weight_sum": 0.0,
  "composite_score": {
    "state": "unknown"
  }
}

Next: carry the score into reputation