docs: add subagent tool-budget guardrails for MCP tasks (Closes #259)

Document default tool-call and wall-time budgets for deterministic MCP
work, forbid subagent commit delegation when gitea_commit_files is
available, and pin the rules in runbooks, portable skill, operator guide,
and doc-contract tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

docs/llm-workflow-runbooks.md

@@ -285,6 +285,39 @@ explicit control-checkout repair.
 
 Portable wording: [`skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md).
 
+## Subagent Tool-Budget Guardrails
+
+General-purpose subagents tasked with **deterministic MCP work** (for example a
+single `gitea_commit_files` call) have expanded to 100–122 tool calls,
+WebFetch/Playwright fallbacks, and throwaway helper-script generation instead of
+calling the native MCP tool once (observed during #152 closure, issue #259).
+
+**Default budgets** (fail closed when exceeded):
+
+| Task class | Max tool calls | Max wall time |
+|------------|----------------|---------------|
+| Single-step MCP mutation (`commit_files`, `create_pr`, `lock_issue`) | 15 | 5 minutes |
+| Review / merge queue inspection | 40 | 15 minutes |
+| Exploration / codebase search (non-mutating) | 60 | 20 minutes |
+
+**Required behavior:**
+
+1. **Main session first.** When the active author profile allows
+   `gitea.repo.commit` and `gitea_commit_files` is visible, the main session
+   must call it directly — do not delegate commit authority to a subagent
+   (see #260).
+2. **Native MCP before fallback.** After a shell spawn failure (#258), attempt
+   the native MCP tool once before any alternate path. Shell unavailability
+   never authorizes WebFetch, Playwright, or manual base64 encoding.
+3. **No retry spirals.** Never resume a failed subagent into a larger retry
+   loop or spawn a second subagent for the same deterministic step. Stop and
+   emit a recovery report instead.
+4. **Forbidden detours** when `gitea_commit_files` is available: WebFetch,
+   Playwright/browser automation, manual LLM-generated base64, and ad-hoc
+   `_encode_*` / `_emit_*` helper scripts left in the repo.
+
+Doc-contract tests: `tests/test_subagent_tool_budget_docs.py`.
+
 ## Branch worktree isolation
 
 All LLM implementation and review work happens in an isolated branch worktree