[Draft] feat: Delegation depth tracking — max_delegation_depth (Phase 2)

[watari-ai]

Status: Draft

This is a design draft for Phase 2 of delegation-aware effects.
Phase 1 (delegation=explicit + grants) is tracked in #107.

Feedback and design discussion welcome — nothing is frozen here.

---

Motivation

Phase 1 introduces a static friction mechanism: callers must explicitly declare grants to invoke delegation=explicit effects. This stops silent propagation at one hop.

But in long delegation chains (A→B→C→D), an explicit grant at each hop still allows the permission to travel arbitrarily far. For highly sensitive or irreversible effects, you may want to limit how many hops a permission can travel, regardless of explicit grants.

This is the dynamic complement to Phase 1's static mechanism.

---

Proposed Addition

Add optional max_delegation_depth to EffectQualifier:

{
  "op": "NET:http_post",
  "reversible": false,
  "delegation": "explicit",
  "max_delegation_depth": 1
}

Semantics:

• depth=0: only the declaring module may invoke this effect directly
• depth=1: the declaring module + one level of delegation
• No field (default): unlimited depth (current behavior)

---

Open Design Questions

1. Static or dynamic?

The core challenge: delegation depth is often determined at runtime (which agent calls which), not at compile time.

• Static approach: define "depth" as the number of module boundaries crossed in the static call graph. Checkable by L2 at compile time, but may be too conservative — a module that conditionally delegates would always be counted.
• Dynamic approach: thread a delegation_context through runtime execution. More precise, but requires runtime support (executor, or mcp-fw enforcement layer).
• Hybrid: static checker warns, runtime enforces.

2. Who enforces it?

• NAIL checker (static): can detect obvious violations at compile time
• mcp-fw (runtime): can track actual delegation chain length per call

This is the primary reason Phase 2 is deferred — the enforcement boundary between NAIL (language) and mcp-fw (runtime) needs to be decided first.

3. Interaction with grants

Does max_delegation_depth=1 mean:

• (a) grants can only be declared at depth ≤ 1, or
• (b) the effect can only be executed within depth ≤ 1 of its origin?

These have different implications for the checker and the runtime.

---

Relationship to mcp-fw

mcp-fw already sits in the delegation chain between Claude and MCP servers. Phase 2 would likely be primarily enforced there — tracking delegation_chain per request and blocking calls that exceed max_delegation_depth.

See: https://github.com/zyom45/mcp-fw

---

References

• arXiv:2602.11865 — Section 2.3 "Zone of Indifference", "Authority Gradient"
• Phase 1: feat: Effect Qualifiers — delegation-aware type system (Phase 1) #107

[watari-ai]

Design Notes (External Review)

The following is a summary of design feedback from an external AI review session, recorded here as input for future discussion — not a spec decision.

---

Overall Direction: Hybrid is Right

The "Hybrid: static warns, runtime enforces" option in the Open Design Questions is the correct path.

• Static depth enforcement would produce too many false positives (call graphs are conservative)
• NAIL checker → warn/hint only
• mcp-fw → runtime enforcement (the primary authority)

---

Three Points Worth Adding Before Closing the Draft

1. Define "what counts as +1 hop"

The issue says "hops from origin" but doesn't define where the counter increments. Two realistic options for mcp-fw:

• Agent-hop (preferred): depth increments when the delegating agent identity changes. A→B→C = depth 2.
• Proxy-hop: counts mcp-fw boundary crossings. In practice this is always 1, making max_delegation_depth useless.

Suggested wording: depth is tracked as delegation_context.chain_length, incrementing each time the delegating agent identity changes.

2. Fix max_delegation_depth to meaning (b)

Q3 in the issue raises (a) vs (b). Recommendation: lock to (b) — "the effect may only be executed within N hops of its origin."

• (a) "grants can only be declared at depth ≤ N" mixes static and dynamic, making both harder
• (b) "execution is blocked beyond depth N" is runtime-complete and maps cleanly to mcp-fw enforcement
• Even if grants are repeated at every hop, depth limit still stops execution

3. Identify "origin" by identity, not module

The current depth=0: declaring module only wording breaks if the same tool is deployed on multiple servers.

Suggested: origin = {server_identity, tool_id} (fc_ir side provides tool_id, mcp-fw provides server_identity). This survives replication and multi-server deployments.

---

Minimum delegation_context for mcp-fw (sketch)

{
  "chain": [
    {"agent": "A", "policy_hash": "abc123"},
    {"agent": "B", "policy_hash": "def456"}
  ],
  "depth": 1,
  "origin": {"server": "filesystem-server", "tool_id": "write_file"},
  "grant_evidence": []
}

This structure makes the delegation chain auditable and directly maps to the accountability requirements in arXiv:2602.11865.

---

These three points (hop definition, (b) semantics, origin identity) are the minimum needed to unblock Phase 2 design when the time comes.