[ketchupz1999]

By opening this pull request you agree to the Contributor License Agreement. On your first pull request a bot asks you to sign it with a one-line comment.

Closes #217.

When child_session_create or child_session_create_many was refused at admission (full fleet queue, spend allowance, sandbox minutes, or a release closing admission), the agent got a generic failure or only an error code, so it could not tell whether to wait, retry or stop.

• childSessionRefusalResult in child-session-tools.ts maps those four known errors to one tool error: the existing user-facing message plus code and the numbers behind it (limit, spent/allowance, used/cap, retryable). Both create tools use it; unknown errors keep their current behaviour.
• The internal route returns the same mapping, and the restricted gateway bridge keeps the control plane's message and its other structured fields instead of collapsing a 429 into the error code.

Tests, each failing against the old sources:

• a real full fleet queue and a real spend account on Postgres, for create and create_many
• the release and sandbox-minute mappings
• the delegated 429 path through the restricted gateway bridge

bun test --max-concurrency=1 --timeout 30000 src/knowledge/gateway/child-session-tools.test.ts src/knowledge/gateway/child-session-delegation.test.ts: 15 pass. Root bun run typecheck, bun test scripts/agent-docs.test.ts (5 pass) and the ratchet and persisted-names guards pass. Locally the full bun run test gives 3547 pass and 8 fail, all in files this change does not touch (macOS tooling: spawn ENOENT, missing gfind, file URL encoding, loopback fetch).

This change was prepared with AI assistance and reviewed by me.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[ketchupz1999]

I have read the CLA Document and I hereby sign the CLA

[ketchupz1999]

recheck