Metadata-Version: 2.4
Name: subagent-delegation-contract
Version: 0.1.0
Summary: Canonical delegation contract schema + enforcement hooks for parent->subagent fidelity in AI coding workflows.
Author: repo-factory
License: MIT
Project-URL: Homepage, https://github.com/prasad-a-abhishek/subagent-delegation-contract
Keywords: agent,subagent,delegation,contract,hmac,scope,audit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# subagent-delegation-contract

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

## Install

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

## Quick start

```bash
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](LICENSE).
