subagent-budget-team 0.1.0__tar.gz

subagent_budget_team-0.1.0/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

subagent_budget_team-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: subagent-budget-team
+Version: 0.1.0
+Summary: Team/CI budget control for subagent token spend: shared budget pools, per-agent quotas, overspend checks, and a kill switch.
+Author-email: hao li <haoli5933@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/subagent-budget-team
+Project-URL: Issues, https://github.com/hahahahahahahahah6/subagent-budget-team/issues
+Keywords: subagent,budget,token,cost-control,ci,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# subagent-budget-team
+
+Team/CI budget control for subagent token spend. When several agents run
+concurrently — a CI matrix, a fleet of coding agents, a team sharing one
+token pool — costs can spiral before anyone notices. `subagent-budget-team`
+gives you a **pre-spend control plane**: shared budget pools, per-agent
+quotas, overspend detection, and a kill switch that freezes spend *before*
+the next invoice.
+
+Measured context: subagents can burn ~48% of an agent's total token budget
+(see the `subagent-tax` write-up). This tool is what you deploy once you
+know that number and want to do something about it at the team level.
+
+## Install
+
+```bash
+pip install subagent-budget-team
+```
+
+Requires Python 3.9+. Zero dependencies (stdlib only).
+
+## Usage
+
+```bash
+# 1. Create a shared budget pool for a CI job or team
+subagent-budget-team pool create --name ci-nightly --limit-usd 25
+
+# 2. Give each agent its own quota inside the pool
+subagent-budget-team quota set --pool ci-nightly --agent coder-1 --limit-usd 5
+subagent-budget-team quota set --pool ci-nightly --agent reviewer-1 --limit-usd 3
+
+# 3. Record spend (call this from your agent wrapper / CI step)
+subagent-budget-team spend --pool ci-nightly --agent coder-1 --tokens 12000 --usd 1.20
+
+# 4. Check everything; exit code 1 means over budget — gate your CI on it
+subagent-budget-team check
+# or machine-readable:
+subagent-budget-team check --json
+
+# 5. Kill switch: freeze a pool (or a single agent) immediately
+subagent-budget-team kill --pool ci-nightly
+subagent-budget-team spend --pool ci-nightly --agent coder-1 --usd 1  # rejected
+subagent-budget-team release --pool ci-nightly                        # unfreeze
+
+# List pools
+subagent-budget-team pool list
+```
+
+State lives in `~/.subagent-budget-team/budgets.json` (override with
+`--state` or the `SBT_HOME` env var, handy for per-job isolation in CI).
+
+### CI example (GitHub Actions)
+
+```yaml
+- run: pip install subagent-budget-team
+- run: subagent-budget-team pool create --name pr-${{ github.event.number }} --limit-usd 10
+- run: ./run-agents.sh   # agents call `spend` as they work
+- run: subagent-budget-team check   # fails the job on overspend
+- if: failure()
+  run: subagent-budget-team kill --pool pr-${{ github.event.number }}
+```
+
+## Differentiation
+
+- **vs `subagent-tax`**: that tool is a *personal audit* lens — it measures
+  how much of *your* token budget subagents burn after the fact.
+  `subagent-budget-team` is the *team/CI control* lens: a shared budget
+  pool with per-agent quotas and a circuit breaker, designed for many
+  agents spending from one pot.
+- **vs cloud-vendor budget alerts**: those are *post-hoc alarms* — you get
+  paged after the money is spent. This is a *pre-spend circuit breaker*:
+  `kill` rejects new spend immediately and `check` can gate a pipeline
+  before the next batch of work runs.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

subagent_budget_team-0.1.0/README.md

@@ -0,0 +1,77 @@
+# subagent-budget-team
+
+Team/CI budget control for subagent token spend. When several agents run
+concurrently — a CI matrix, a fleet of coding agents, a team sharing one
+token pool — costs can spiral before anyone notices. `subagent-budget-team`
+gives you a **pre-spend control plane**: shared budget pools, per-agent
+quotas, overspend detection, and a kill switch that freezes spend *before*
+the next invoice.
+
+Measured context: subagents can burn ~48% of an agent's total token budget
+(see the `subagent-tax` write-up). This tool is what you deploy once you
+know that number and want to do something about it at the team level.
+
+## Install
+
+```bash
+pip install subagent-budget-team
+```
+
+Requires Python 3.9+. Zero dependencies (stdlib only).
+
+## Usage
+
+```bash
+# 1. Create a shared budget pool for a CI job or team
+subagent-budget-team pool create --name ci-nightly --limit-usd 25
+
+# 2. Give each agent its own quota inside the pool
+subagent-budget-team quota set --pool ci-nightly --agent coder-1 --limit-usd 5
+subagent-budget-team quota set --pool ci-nightly --agent reviewer-1 --limit-usd 3
+
+# 3. Record spend (call this from your agent wrapper / CI step)
+subagent-budget-team spend --pool ci-nightly --agent coder-1 --tokens 12000 --usd 1.20
+
+# 4. Check everything; exit code 1 means over budget — gate your CI on it
+subagent-budget-team check
+# or machine-readable:
+subagent-budget-team check --json
+
+# 5. Kill switch: freeze a pool (or a single agent) immediately
+subagent-budget-team kill --pool ci-nightly
+subagent-budget-team spend --pool ci-nightly --agent coder-1 --usd 1  # rejected
+subagent-budget-team release --pool ci-nightly                        # unfreeze
+
+# List pools
+subagent-budget-team pool list
+```
+
+State lives in `~/.subagent-budget-team/budgets.json` (override with
+`--state` or the `SBT_HOME` env var, handy for per-job isolation in CI).
+
+### CI example (GitHub Actions)
+
+```yaml
+- run: pip install subagent-budget-team
+- run: subagent-budget-team pool create --name pr-${{ github.event.number }} --limit-usd 10
+- run: ./run-agents.sh   # agents call `spend` as they work
+- run: subagent-budget-team check   # fails the job on overspend
+- if: failure()
+  run: subagent-budget-team kill --pool pr-${{ github.event.number }}
+```
+
+## Differentiation
+
+- **vs `subagent-tax`**: that tool is a *personal audit* lens — it measures
+  how much of *your* token budget subagents burn after the fact.
+  `subagent-budget-team` is the *team/CI control* lens: a shared budget
+  pool with per-agent quotas and a circuit breaker, designed for many
+  agents spending from one pot.
+- **vs cloud-vendor budget alerts**: those are *post-hoc alarms* — you get
+  paged after the money is spent. This is a *pre-spend circuit breaker*:
+  `kill` rejects new spend immediately and `check` can gate a pipeline
+  before the next batch of work runs.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

subagent_budget_team-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "subagent-budget-team"
+version = "0.1.0"
+description = "Team/CI budget control for subagent token spend: shared budget pools, per-agent quotas, overspend checks, and a kill switch."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "hao li", email = "haoli5933@gmail.com" }]
+keywords = ["subagent", "budget", "token", "cost-control", "ci", "agents"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+[project.urls]
+Homepage = "https://github.com/hahahahahahahahah6/subagent-budget-team"
+Issues = "https://github.com/hahahahahahahahah6/subagent-budget-team/issues"
+
+[project.scripts]
+subagent-budget-team = "subagent_budget_team.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

subagent_budget_team-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

subagent_budget_team-0.1.0/src/subagent_budget_team/__init__.py

@@ -0,0 +1,8 @@
+"""subagent-budget-team: team/CI budget control for subagent token spend.
+
+A stdlib-only CLI that manages shared token-budget pools, per-agent
+quotas, pre-spend circuit breaking (kill switch), and overspend checks.
+"""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

subagent_budget_team-0.1.0/src/subagent_budget_team/cli.py

@@ -0,0 +1,188 @@
+"""Command-line interface for subagent-budget-team."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .core import BudgetError, Store, default_state_path
+
+EXIT_OK = 0
+EXIT_OVER_BUDGET = 1
+EXIT_USAGE = 2
+
+
+def _store(args: argparse.Namespace) -> Store:
+    path = Path(args.state) if getattr(args, "state", None) else default_state_path()
+    return Store(path).load()
+
+
+def cmd_pool_create(args: argparse.Namespace) -> int:
+    try:
+        _store(args).create_pool(args.name, args.limit_usd, args.limit_tokens)
+    except BudgetError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    print(f"pool '{args.name}' created")
+    return EXIT_OK
+
+
+def cmd_pool_list(args: argparse.Namespace) -> int:
+    pools = _store(args).list_pools()
+    if args.json:
+        print(json.dumps(pools, indent=2))
+        return EXIT_OK
+    if not pools:
+        print("no pools yet; create one with: pool create --name NAME --limit-usd X")
+        return EXIT_OK
+    for p in pools:
+        status = "KILLED" if p["killed"] else "active"
+        lim = []
+        if p["limit_usd"] is not None:
+            lim.append(f"${p['limit_usd']:.2f}")
+        if p["limit_tokens"] is not None:
+            lim.append(f"{p['limit_tokens']} tokens")
+        print(f"{p['name']}: limit {' + '.join(lim)} | "
+              f"spent ${p['spent_usd']:.4f} / {p['spent_tokens']} tokens | "
+              f"{status} | agents: {len(p['agents'])}")
+    return EXIT_OK
+
+
+def cmd_quota_set(args: argparse.Namespace) -> int:
+    try:
+        _store(args).set_quota(args.pool, args.agent,
+                               args.limit_usd, args.limit_tokens)
+    except BudgetError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    print(f"quota set: agent '{args.agent}' in pool '{args.pool}'")
+    return EXIT_OK
+
+
+def cmd_spend(args: argparse.Namespace) -> int:
+    try:
+        _store(args).record_spend(args.pool, args.agent,
+                                  args.tokens, args.usd)
+    except BudgetError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    print(f"recorded: agent '{args.agent}' +{args.tokens} tokens "
+          f"+${args.usd:.4f} in pool '{args.pool}'")
+    return EXIT_OK
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    violations = _store(args).check()
+    if args.json:
+        print(json.dumps([v.to_dict() for v in violations], indent=2))
+    elif violations:
+        print(f"OVER BUDGET: {len(violations)} violation(s)")
+        for v in violations:
+            print(f"  - {v.detail}")
+    else:
+        print("OK: all pools and quotas within budget")
+    return EXIT_OVER_BUDGET if violations else EXIT_OK
+
+
+def cmd_kill(args: argparse.Namespace) -> int:
+    try:
+        _store(args).kill(args.pool, args.agent)
+    except BudgetError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    target = f"agent '{args.agent}' in " if args.agent else ""
+    print(f"kill switch engaged: {target}pool '{args.pool}'")
+    return EXIT_OK
+
+
+def cmd_release(args: argparse.Namespace) -> int:
+    try:
+        _store(args).release(args.pool, args.agent)
+    except BudgetError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    target = f"agent '{args.agent}' in " if args.agent else ""
+    print(f"released: {target}pool '{args.pool}'")
+    return EXIT_OK
+
+
+def _add_limit_opts(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--limit-usd", type=float, default=None,
+                   help="budget limit in USD (e.g. 25.50)")
+    p.add_argument("--limit-tokens", type=int, default=None,
+                   help="budget limit in tokens")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="subagent-budget-team",
+        description="Team/CI budget control for subagent token spend: "
+                    "shared budget pools, per-agent quotas, overspend checks, "
+                    "and a kill switch.",
+    )
+    ap.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    ap.add_argument("--state", default=None,
+                    help="path to state file (default: ~/.subagent-budget-team/budgets.json)")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    # pool create / pool list
+    pool_p = sub.add_parser("pool", help="manage budget pools")
+    pool_sub = pool_p.add_subparsers(dest="pool_command", required=True)
+    pc = pool_sub.add_parser("create", help="create a budget pool")
+    pc.add_argument("--name", required=True, help="pool name")
+    _add_limit_opts(pc)
+    pc.set_defaults(func=cmd_pool_create)
+    pl = pool_sub.add_parser("list", help="list budget pools")
+    pl.add_argument("--json", action="store_true", help="JSON output")
+    pl.set_defaults(func=cmd_pool_list)
+
+    # quota set
+    quota_p = sub.add_parser("quota", help="manage per-agent quotas")
+    quota_sub = quota_p.add_subparsers(dest="quota_command", required=True)
+    qs = quota_sub.add_parser("set", help="set an agent's quota inside a pool")
+    qs.add_argument("--pool", required=True, help="pool name")
+    qs.add_argument("--agent", required=True, help="agent id")
+    _add_limit_opts(qs)
+    qs.set_defaults(func=cmd_quota_set)
+
+    # spend
+    sp = sub.add_parser("spend", help="record token/USD spend")
+    sp.add_argument("--pool", required=True)
+    sp.add_argument("--agent", required=True)
+    sp.add_argument("--tokens", type=int, default=0)
+    sp.add_argument("--usd", type=float, default=0.0)
+    sp.set_defaults(func=cmd_spend)
+
+    # check
+    ch = sub.add_parser("check", help="detect overspend (exit 1 if over budget)")
+    ch.add_argument("--json", action="store_true", help="JSON output")
+    ch.set_defaults(func=cmd_check)
+
+    # kill / release
+    k = sub.add_parser("kill", help="engage the kill switch (freeze a pool or agent)")
+    k.add_argument("--pool", required=True)
+    k.add_argument("--agent", default=None, help="omit to kill the whole pool")
+    k.set_defaults(func=cmd_kill)
+    r = sub.add_parser("release", help="release a kill switch")
+    r.add_argument("--pool", required=True)
+    r.add_argument("--agent", default=None, help="omit to release the whole pool")
+    r.set_defaults(func=cmd_release)
+
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except BudgetError as exc:  # pragma: no cover - defensive
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

subagent_budget_team-0.1.0/src/subagent_budget_team/core.py

@@ -0,0 +1,214 @@
+"""Core budget-pool logic. Pure stdlib: JSON state file, no dependencies."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def default_state_path() -> Path:
+    base = os.environ.get("SBT_HOME") or os.path.expanduser("~")
+    return Path(base) / ".subagent-budget-team" / "budgets.json"
+
+
+@dataclass
+class BudgetError(Exception):
+    message: str
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        return self.message
+
+
+@dataclass
+class Violation:
+    kind: str  # "pool_over" | "agent_over" | "killed"
+    pool: str
+    agent: str | None = None
+    detail: str = ""
+
+    def to_dict(self) -> dict:
+        return {"kind": self.kind, "pool": self.pool,
+                "agent": self.agent, "detail": self.detail}
+
+
+@dataclass
+class Store:
+    path: Path = field(default_factory=default_state_path)
+    data: dict = field(default_factory=lambda: {"pools": {}})
+
+    # ---- persistence -------------------------------------------------
+    def load(self) -> "Store":
+        if self.path.exists():
+            try:
+                self.data = json.loads(self.path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError) as exc:
+                raise BudgetError(f"cannot read state file {self.path}: {exc}")
+        self.data.setdefault("pools", {})
+        return self
+
+    def save(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(self.data, indent=2, sort_keys=True),
+                       encoding="utf-8")
+        os.replace(tmp, self.path)
+
+    # ---- helpers -----------------------------------------------------
+    def _pool(self, name: str) -> dict:
+        pool = self.data["pools"].get(name)
+        if pool is None:
+            raise BudgetError(f"pool '{name}' does not exist")
+        return pool
+
+    @staticmethod
+    def _check_positive(name: str, value: float | int | None) -> None:
+        if value is not None and value <= 0:
+            raise BudgetError(f"{name} must be positive, got {value}")
+
+    # ---- pool management ---------------------------------------------
+    def create_pool(self, name: str, limit_usd: float | None = None,
+                    limit_tokens: int | None = None) -> None:
+        if not name or not name.strip():
+            raise BudgetError("pool name must not be empty")
+        if name in self.data["pools"]:
+            raise BudgetError(f"pool '{name}' already exists")
+        self._check_positive("limit_usd", limit_usd)
+        self._check_positive("limit_tokens", limit_tokens)
+        if limit_usd is None and limit_tokens is None:
+            raise BudgetError("at least one of --limit-usd / --limit-tokens "
+                              "is required")
+        self.data["pools"][name] = {
+            "limit_usd": limit_usd,
+            "limit_tokens": limit_tokens,
+            "killed": False,
+            "spent_usd": 0.0,
+            "spent_tokens": 0,
+            "agents": {},
+        }
+        self.save()
+
+    def list_pools(self) -> list[dict]:
+        out = []
+        for name, pool in sorted(self.data["pools"].items()):
+            out.append({
+                "name": name,
+                "limit_usd": pool.get("limit_usd"),
+                "limit_tokens": pool.get("limit_tokens"),
+                "killed": pool.get("killed", False),
+                "spent_usd": pool.get("spent_usd", 0.0),
+                "spent_tokens": pool.get("spent_tokens", 0),
+                "agents": sorted(pool.get("agents", {})),
+            })
+        return out
+
+    # ---- quotas ------------------------------------------------------
+    def set_quota(self, pool_name: str, agent: str,
+                  limit_usd: float | None = None,
+                  limit_tokens: int | None = None) -> None:
+        pool = self._pool(pool_name)
+        if not agent or not agent.strip():
+            raise BudgetError("agent name must not be empty")
+        self._check_positive("limit_usd", limit_usd)
+        self._check_positive("limit_tokens", limit_tokens)
+        if limit_usd is None and limit_tokens is None:
+            raise BudgetError("at least one of --limit-usd / --limit-tokens "
+                              "is required")
+        agents = pool.setdefault("agents", {})
+        entry = agents.get(agent, {"spent_usd": 0.0, "spent_tokens": 0})
+        entry["limit_usd"] = limit_usd
+        entry["limit_tokens"] = limit_tokens
+        agents[agent] = entry
+        self.save()
+
+    # ---- spend -------------------------------------------------------
+    def record_spend(self, pool_name: str, agent: str, tokens: int = 0,
+                     usd: float = 0.0) -> None:
+        pool = self._pool(pool_name)
+        if pool.get("killed"):
+            raise BudgetError(f"pool '{pool_name}' is killed: spend rejected")
+        if tokens < 0 or usd < 0:
+            raise BudgetError("tokens and usd must be non-negative")
+        pool["spent_tokens"] = pool.get("spent_tokens", 0) + tokens
+        pool["spent_usd"] = pool.get("spent_usd", 0.0) + usd
+        agents = pool.setdefault("agents", {})
+        entry = agents.setdefault(agent,
+                                  {"spent_usd": 0.0, "spent_tokens": 0,
+                                   "limit_usd": None, "limit_tokens": None})
+        entry["spent_tokens"] = entry.get("spent_tokens", 0) + tokens
+        entry["spent_usd"] = entry.get("spent_usd", 0.0) + usd
+        if entry.get("killed"):
+            raise BudgetError(f"agent '{agent}' in pool '{pool_name}' is "
+                              "killed: spend rejected")
+        self.save()
+
+    # ---- kill switch -------------------------------------------------
+    def kill(self, pool_name: str, agent: str | None = None) -> None:
+        pool = self._pool(pool_name)
+        if agent is None:
+            pool["killed"] = True
+        else:
+            entry = pool.get("agents", {}).get(agent)
+            if entry is None:
+                raise BudgetError(f"agent '{agent}' has no quota in pool "
+                                  f"'{pool_name}'")
+            entry["killed"] = True
+        self.save()
+
+    def release(self, pool_name: str, agent: str | None = None) -> None:
+        pool = self._pool(pool_name)
+        if agent is None:
+            pool["killed"] = False
+        else:
+            entry = pool.get("agents", {}).get(agent)
+            if entry is None:
+                raise BudgetError(f"agent '{agent}' has no quota in pool "
+                                  f"'{pool_name}'")
+            entry["killed"] = False
+        self.save()
+
+    # ---- check -------------------------------------------------------
+    def check(self) -> list[Violation]:
+        violations: list[Violation] = []
+        for name, pool in self.data["pools"].items():
+            if pool.get("killed"):
+                violations.append(Violation(
+                    "killed", name,
+                    detail=f"pool '{name}' is killed (circuit breaker open)"))
+                continue
+            limit_usd = pool.get("limit_usd")
+            spent_usd = pool.get("spent_usd", 0.0)
+            limit_tokens = pool.get("limit_tokens")
+            spent_tokens = pool.get("spent_tokens", 0)
+            if limit_usd is not None and spent_usd > limit_usd:
+                violations.append(Violation(
+                    "pool_over", name,
+                    detail=f"pool '{name}': spent ${spent_usd:.4f} > "
+                           f"limit ${limit_usd:.4f}"))
+            if limit_tokens is not None and spent_tokens > limit_tokens:
+                violations.append(Violation(
+                    "pool_over", name,
+                    detail=f"pool '{name}': spent {spent_tokens} tokens > "
+                           f"limit {limit_tokens}"))
+            for agent, entry in pool.get("agents", {}).items():
+                if entry.get("killed"):
+                    violations.append(Violation(
+                        "killed", name, agent,
+                        detail=f"agent '{agent}' in pool '{name}' is killed"))
+                    continue
+                a_usd = entry.get("limit_usd")
+                a_spent_usd = entry.get("spent_usd", 0.0)
+                a_tokens = entry.get("limit_tokens")
+                a_spent_tokens = entry.get("spent_tokens", 0)
+                if a_usd is not None and a_spent_usd > a_usd:
+                    violations.append(Violation(
+                        "agent_over", name, agent,
+                        detail=f"agent '{agent}' in pool '{name}': spent "
+                               f"${a_spent_usd:.4f} > limit ${a_usd:.4f}"))
+                if a_tokens is not None and a_spent_tokens > a_tokens:
+                    violations.append(Violation(
+                        "agent_over", name, agent,
+                        detail=f"agent '{agent}' in pool '{name}': spent "
+                               f"{a_spent_tokens} tokens > limit {a_tokens}"))
+        return violations

subagent_budget_team-0.1.0/src/subagent_budget_team.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: subagent-budget-team
+Version: 0.1.0
+Summary: Team/CI budget control for subagent token spend: shared budget pools, per-agent quotas, overspend checks, and a kill switch.
+Author-email: hao li <haoli5933@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/subagent-budget-team
+Project-URL: Issues, https://github.com/hahahahahahahahah6/subagent-budget-team/issues
+Keywords: subagent,budget,token,cost-control,ci,agents
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# subagent-budget-team
+
+Team/CI budget control for subagent token spend. When several agents run
+concurrently — a CI matrix, a fleet of coding agents, a team sharing one
+token pool — costs can spiral before anyone notices. `subagent-budget-team`
+gives you a **pre-spend control plane**: shared budget pools, per-agent
+quotas, overspend detection, and a kill switch that freezes spend *before*
+the next invoice.
+
+Measured context: subagents can burn ~48% of an agent's total token budget
+(see the `subagent-tax` write-up). This tool is what you deploy once you
+know that number and want to do something about it at the team level.
+
+## Install
+
+```bash
+pip install subagent-budget-team
+```
+
+Requires Python 3.9+. Zero dependencies (stdlib only).
+
+## Usage
+
+```bash
+# 1. Create a shared budget pool for a CI job or team
+subagent-budget-team pool create --name ci-nightly --limit-usd 25
+
+# 2. Give each agent its own quota inside the pool
+subagent-budget-team quota set --pool ci-nightly --agent coder-1 --limit-usd 5
+subagent-budget-team quota set --pool ci-nightly --agent reviewer-1 --limit-usd 3
+
+# 3. Record spend (call this from your agent wrapper / CI step)
+subagent-budget-team spend --pool ci-nightly --agent coder-1 --tokens 12000 --usd 1.20
+
+# 4. Check everything; exit code 1 means over budget — gate your CI on it
+subagent-budget-team check
+# or machine-readable:
+subagent-budget-team check --json
+
+# 5. Kill switch: freeze a pool (or a single agent) immediately
+subagent-budget-team kill --pool ci-nightly
+subagent-budget-team spend --pool ci-nightly --agent coder-1 --usd 1  # rejected
+subagent-budget-team release --pool ci-nightly                        # unfreeze
+
+# List pools
+subagent-budget-team pool list
+```
+
+State lives in `~/.subagent-budget-team/budgets.json` (override with
+`--state` or the `SBT_HOME` env var, handy for per-job isolation in CI).
+
+### CI example (GitHub Actions)
+
+```yaml
+- run: pip install subagent-budget-team
+- run: subagent-budget-team pool create --name pr-${{ github.event.number }} --limit-usd 10
+- run: ./run-agents.sh   # agents call `spend` as they work
+- run: subagent-budget-team check   # fails the job on overspend
+- if: failure()
+  run: subagent-budget-team kill --pool pr-${{ github.event.number }}
+```
+
+## Differentiation
+
+- **vs `subagent-tax`**: that tool is a *personal audit* lens — it measures
+  how much of *your* token budget subagents burn after the fact.
+  `subagent-budget-team` is the *team/CI control* lens: a shared budget
+  pool with per-agent quotas and a circuit breaker, designed for many
+  agents spending from one pot.
+- **vs cloud-vendor budget alerts**: those are *post-hoc alarms* — you get
+  paged after the money is spent. This is a *pre-spend circuit breaker*:
+  `kill` rejects new spend immediately and `check` can gate a pipeline
+  before the next batch of work runs.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

subagent_budget_team-0.1.0/src/subagent_budget_team.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/subagent_budget_team/__init__.py
+src/subagent_budget_team/cli.py
+src/subagent_budget_team/core.py
+src/subagent_budget_team.egg-info/PKG-INFO
+src/subagent_budget_team.egg-info/SOURCES.txt
+src/subagent_budget_team.egg-info/dependency_links.txt
+src/subagent_budget_team.egg-info/entry_points.txt
+src/subagent_budget_team.egg-info/top_level.txt
+tests/test_smoke.py

subagent_budget_team-0.1.0/src/subagent_budget_team.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

subagent_budget_team-0.1.0/src/subagent_budget_team.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+subagent-budget-team = subagent_budget_team.cli:main

subagent_budget_team-0.1.0/src/subagent_budget_team.egg-info/top_level.txt

@@ -0,0 +1 @@
+subagent_budget_team

subagent_budget_team-0.1.0/tests/test_smoke.py

@@ -0,0 +1,126 @@
+"""Smoke tests for subagent-budget-team. stdlib only (unittest)."""
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+CLI = [sys.executable, "-m", "subagent_budget_team.cli"]
+SRC = Path(__file__).resolve().parent.parent / "src"
+
+
+def _env(tmp: Path) -> dict:
+    env = dict(os.environ)
+    env["SBT_HOME"] = str(tmp)
+    env["PYTHONPATH"] = str(SRC) + os.pathsep + env.get("PYTHONPATH", "")
+    return env
+
+
+class SmokeTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp(prefix="sbt-test-"))
+        self.env = _env(self.tmp)
+
+    def run_cli(self, *args: str):
+        return subprocess.run(CLI + list(args), capture_output=True,
+                              text=True, env=self.env)
+
+    def test_01_pool_create_and_list(self):
+        r = self.run_cli("pool", "create", "--name", "ci-nightly",
+                         "--limit-usd", "25")
+        self.assertEqual(r.returncode, 0, r.stderr)
+        r = self.run_cli("pool", "list")
+        self.assertEqual(r.returncode, 0, r.stderr)
+        self.assertIn("ci-nightly", r.stdout)
+
+    def test_02_quota_set(self):
+        self.run_cli("pool", "create", "--name", "team", "--limit-usd", "100")
+        r = self.run_cli("quota", "set", "--pool", "team",
+                         "--agent", "coder-1", "--limit-usd", "10")
+        self.assertEqual(r.returncode, 0, r.stderr)
+        r = self.run_cli("pool", "list", "--json")
+        pools = json.loads(r.stdout)
+        self.assertIn("coder-1", pools[0]["agents"])
+
+    def test_03_spend_within_budget_check_ok(self):
+        self.run_cli("pool", "create", "--name", "p", "--limit-usd", "50")
+        r = self.run_cli("spend", "--pool", "p", "--agent", "a",
+                         "--tokens", "1000", "--usd", "2.50")
+        self.assertEqual(r.returncode, 0, r.stderr)
+        r = self.run_cli("check")
+        self.assertEqual(r.returncode, 0, r.stdout + r.stderr)
+        self.assertIn("OK", r.stdout)
+
+    def test_04_pool_overspend_check_fails(self):
+        self.run_cli("pool", "create", "--name", "p", "--limit-usd", "5")
+        self.run_cli("spend", "--pool", "p", "--agent", "a", "--usd", "6.01")
+        r = self.run_cli("check")
+        self.assertEqual(r.returncode, 1)
+        self.assertIn("OVER BUDGET", r.stdout)
+
+    def test_05_agent_quota_overspend_check_fails(self):
+        self.run_cli("pool", "create", "--name", "p", "--limit-usd", "100")
+        self.run_cli("quota", "set", "--pool", "p", "--agent", "a",
+                     "--limit-usd", "1")
+        self.run_cli("spend", "--pool", "p", "--agent", "a", "--usd", "1.50")
+        r = self.run_cli("check")
+        self.assertEqual(r.returncode, 1)
+        self.assertIn("agent_over", r.stdout + self.run_cli(
+            "check", "--json").stdout)
+
+    def test_06_kill_switch_breaks_check(self):
+        self.run_cli("pool", "create", "--name", "p", "--limit-usd", "50")
+        self.run_cli("spend", "--pool", "p", "--agent", "a", "--usd", "1")
+        r = self.run_cli("check")
+        self.assertEqual(r.returncode, 0)
+        r = self.run_cli("kill", "--pool", "p")
+        self.assertEqual(r.returncode, 0, r.stderr)
+        r = self.run_cli("check")
+        self.assertEqual(r.returncode, 1)
+        self.assertIn("killed", r.stdout.lower())
+
+    def test_07_kill_rejects_new_spend(self):
+        self.run_cli("pool", "create", "--name", "p", "--limit-usd", "50")
+        self.run_cli("kill", "--pool", "p")
+        r = self.run_cli("spend", "--pool", "p", "--agent", "a", "--usd", "1")
+        self.assertNotEqual(r.returncode, 0)
+
+    def test_08_release_restores_ok(self):
+        self.run_cli("pool", "create", "--name", "p", "--limit-usd", "50")
+        self.run_cli("kill", "--pool", "p")
+        self.run_cli("release", "--pool", "p")
+        r = self.run_cli("check")
+        self.assertEqual(r.returncode, 0)
+
+    def test_09_duplicate_pool_rejected(self):
+        self.run_cli("pool", "create", "--name", "p", "--limit-usd", "1")
+        r = self.run_cli("pool", "create", "--name", "p", "--limit-usd", "1")
+        self.assertNotEqual(r.returncode, 0)
+        self.assertIn("already exists", r.stderr)
+
+    def test_10_negative_limit_rejected(self):
+        r = self.run_cli("pool", "create", "--name", "p",
+                         "--limit-usd", "-5")
+        self.assertNotEqual(r.returncode, 0)
+        self.assertIn("positive", r.stderr)
+
+    def test_11_check_json_output(self):
+        self.run_cli("pool", "create", "--name", "p", "--limit-tokens", "100")
+        self.run_cli("spend", "--pool", "p", "--agent", "a", "--tokens", "150")
+        r = self.run_cli("check", "--json")
+        self.assertEqual(r.returncode, 1)
+        data = json.loads(r.stdout)
+        self.assertEqual(data[0]["kind"], "pool_over")
+        self.assertEqual(data[0]["pool"], "p")
+
+    def test_12_version(self):
+        r = self.run_cli("--version")
+        self.assertEqual(r.returncode, 0)
+        self.assertIn("0.1.0", r.stdout)
+
+
+if __name__ == "__main__":
+    unittest.main()