subagent-delegation-contract

Signed, zero-dependency delegation contracts for preserving parent-to-subagent task fidelity in Python coding workflows.

Install

python -m venv .venv
. .venv/bin/activate
pip install -e .

Quick start

subagent-delegation-contract encode --task "refactor auth" \
  --scope-read "src/auth/**" --scope-write "src/auth/**" \
  --scope-forbid "*.env" --secret "$DELEGATION_SECRET" --output contract.json
subagent-delegation-contract bind --contract contract.json --subagent-id child-001 --secret "$DELEGATION_SECRET"
subagent-delegation-contract verify --contract contract.json --secret "$DELEGATION_SECRET"
subagent-delegation-contract validate pre --contract contract.json --tool write_file \
  --args '{"path":"src/auth/login.py"}' --secret "$DELEGATION_SECRET"

The package also supports python -m subagent_delegation_contract. Legacy plugin hook shims remain in plugins/subagent-delegation-contract/scripts/ and translate --mode=create|bind|verify|decode|pre|post|verify-output|audit to the package CLI.

Scope glob syntax

* and ? match within one path component; ** crosses directory separators. A bare directory pattern covers its descendants. scope.forbid takes precedence over read and write permissions. Empty read/write lists mean that mode is unconstrained.

Drift detection

validate_pre blocks forbidden tools and arguments and out-of-scope reads/writes. validate_post checks forbidden result content and output-schema types. validate_output checks the final payload. Missing and extra schema fields generate warnings; declared type mismatches are denied. JSONL audit records and a blast-radius report are available through --audit-log and audit.

Limitations

• Enforcement is in-process; callers must invoke the checks at tool boundaries.
• There is no remote attestation or distributed trust mechanism.
• HMAC-SHA256 uses a symmetric secret: both signer and verifier must know it; it is not asymmetric signing.
• This release does not provide JavaScript runtime bindings.

License

MIT; see LICENSE.