Gap ledger agent-sdks: background-command limit, bounded retry watchdog, message accept scope, Agent SDK 0.2.167 - #1157

Scope

• What this PR changes, in one or two sentences: This PR closes the five ADOPT rows of the Claude Code practice gap ledger that fall on the agent-sdks layer (slot headless-sdk): B1-0006, B2-0002, B4-0001, B4-0002 and C1-0001. The command center dispatched the ledger on 2026-10-15, and each row was confirmed by a second-family gpt-6-astra re-check. Following the plan's closing rule, it is one slot-row PR for the layer page, with fail-first tests.
• Base commit: 420452059
• Lane: lane:foundation
• Owned paths touched:
  • the practice skill's slots.json and agent-sdks.md, plus the slot manifest (only sha256_when_labeled changes);
  • tools/claude-review-worker/worker.py and its README.md;
  • catalogs/foundation/upstream-surface-dispositions.json;
  • adoption/new-wsl-profile.json and .md;
  • docs/new-wsl-handbook.json and .md, regenerated with scripts/build_new_wsl_handbook.py --write, plus its receipt;
  • tests/test_native_practice_ledger_rows_agent_sdks.py (new);
  • manifests/evidence.json.

Rows:

• B2-0002 and B4-0001 (one change): in unattended runs (-p, the Agent SDK, CI) a background Bash command stops at a time limit:

  • 30 minutes, or the command's timeout up to 2 hours;
  • 10 minutes in a -p run whose prompt is text.

  The row records how to raise it and how it differs from CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS. No launcher changes: the review worker has no Bash, and the template's BASH_MAX_TIMEOUT_MS leaves the 2-hour maximum.

• C1-0001: the review worker's sandbox env sets CLAUDE_CODE_RETRY_WATCHDOG=1 with CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=900000, a third of the worker's 2700 s run timeout.

  • Key rotation on HTTP 402 or a credit-balance 400 is unchanged.
  • The watchdog retries 429 and 529 capacity errors. The 900000 ms setting caps only that wait, per request (env-vars.md:380).
  • On 2.1.199 and later the watchdog also raises the default retry count for other transient errors (server errors, timeouts, dropped connections) to 300, about three hours of backoff (env-vars.md:379). The worker's 2700 s run timeout, which ends the process group, is what bounds the whole run, those retries included.
  • The two disposition rows (upstream-surface-dispositions.json, lines 431 and 3809) move to enabled, with the worker as carrier. The second row's overturn condition was exactly this change.
  • Callers left without it, each with its reason: /skill-doctor (no model request), the capacity probes (a 429 is the reading), the gateway example, and the trading worker (that lane's call).

• B4-0002: a -p worker that must take messages from a session in the other permission-mode class needs crossSessionInbound: accept in its --settings. No launcher in this repository takes messages:

  • The review worker is --restricted and one-shot.
  • The only such worker, the 2026-10-13 overnight MCP agent, launches from outside the repository and already passes the accept.

• B1-0006: the new-WSL profile pins claude-agent-sdk 0.2.167, whose bundled CLI is 2.1.300.

  • The previous pin was 0.2.163, which bundled 2.1.286, below the 2.1.295 floor for onFailure hooks.
  • The checksum is PyPI's published sdist digest.
  • v0.2.167's install and test commands match v0.2.163's.
  • cli_path is recorded as the alternative.

SOTA sources

• Claude Code docs at client 2.1.300, fetched 2026-10-15T10:34:35Z:
  • https://code.claude.com/docs/en/tools-reference.md, lines 188 and 192-210 (sha256 32042001…);
  • https://code.claude.com/docs/en/env-vars.md, lines 191, 366 and 379-380 (54351937…);
  • https://code.claude.com/docs/en/cross-session-messaging.md, lines 203, 205, 224, 227 and 231 (7b359027…);
  • https://code.claude.com/docs/en/cli-reference.md, lines 125 and 129 (0acf910e…);
  • https://code.claude.com/docs/en/agent-sdk/python.md, line 891 (cli_path; 97dfac82…).
• anthropics/claude-code@94506ff0 CHANGELOG.md:
  • L369-371 (2.1.295 onFailure);
  • L384 (2.1.295 watchdog cap);
  • L978 (2.1.288);
  • L1280 (2.1.285).
• anthropics/claude-agent-sdk-python@c10b52c6 (tag v0.2.167): README.md:15-18, CHANGELOG.md:3-7, 40-44, .github/workflows/test.yml:27, 36.
• PyPI: https://pypi.org/pypi/claude-agent-sdk/0.2.167/json. The sdist digest is 06c9b813…e207, uploaded 2026-10-14T19:22:37Z; 0.2.167 is the latest release.
• The ledger rows and their re-checks: cc-native-practice-20261009/gap-ledger-20261015/ledger.jsonl (snapshot SNAPSHOT-20261015T104957Z.md).

Evidence-class table

Local commands run

$ python3 -m unittest tests.test_native_practice_ledger_rows_agent_sdks   # base 420452059 with only the new module
FAILED (failures=6)   e.g. AssertionError: '0.2.163' != '0.2.167'; AssertionError: None != '1'
$ python3 -m unittest tests.test_native_practice_ledger_rows_agent_sdks tests.test_claude_review_worker tests.test_new_wsl_profile
OK (skipped=1)
$ python3 -m unittest tests.test_new_wsl_handbook tests.test_new_wsl_definitive_defaults tests.test_catalog_freshness_runtime tests.test_native_practice_* (and the local-pages modules)
OK
$ python3 scripts/validate.py
rc 0; {"components": 71, "hashed_files": 12055, "profiles": 4, "receipts": 240, "status": "passed"}

tests.test_upstream_surface_watch has four CachedArtifactTests failures, identical on the base export. #1155 (open) fixes them; this module reruns after it lands.

Follow-ups

• Before landing: the regenerated handbook carries an inherited owner-quote record (docs/new-wsl-handbook.json:933, from definitive-manifest.json:1024 and consensus.json:1637). Scrub owner quotations from the new-WSL records: paraphrase the canonical inputs, regenerate, and carry a dated paraphrase in the relay contract #1161 replaces it at its source. This PR rebases onto main after Scrub owner quotations from the new-WSL records: paraphrase the canonical inputs, regenerate, and carry a dated paraphrase in the relay contract #1161 lands and regenerates the handbook and its receipt; it does not land before Scrub owner quotations from the new-WSL records: paraphrase the canonical inputs, regenerate, and carry a dated paraphrase in the relay contract #1161.
• evidence/artifacts/new-wsl-install-plan-20261002/* still pins 0.2.163; the freshness report reads that plan.
• catalogs/north-star/readiness.json was stale at base. Its builder needs a gate receipt before --write.
• examples/claude-runtime-sdk/worker.py pins claude-agent-sdk==0.2.162, the same kind of gap.
• The open practice-row PRs (Practice skill: spawn one-shot workers unnamed; shut teammates down when their result is sealed #1142, Gap ledger wave 1: route Workflow-child hooks outside project agent frontmatter; correct the TMPDIR and advisor rows #1146, Practice rows: --max-findings, marketplace autoUpdate and trust, the workflow model override, the effortLevel origin #1147, Memory maintenance: a read-only index guard reading the client's own limits; auto-dream detection; auto-memory row #1149, Keep duplicate /skill-doctor rows, refuse zero-row tables, report unused plugins; record the 2026-10-15 plugin dispositions #1153) all rewrite slots.json and sha256_when_labeled. Later ones need a manifest rebase.

Checklist

• No GitHub Actions changed.
• No workflows changed.
• No secrets are printed, logged or committed.
• No new paid hosting, subscription or billing surface.
• Peer-owned untracked files and worktrees were preserved.

🤖 Generated with Claude Code