Coverage for src/keel/delegate.py: 100%

308 statements  

« prev     ^ index     » next       coverage.py v7.16.2, created at 2026-10-20 19:17 +0000

1"""How keel invokes a delegate — the pure planner behind ``keel delegate run`` (#1012). 

2 

3Nothing in keel dispatched a delegate. ``api_delegate.generate()`` had no caller; the 

4``claude``/``codex``/``agy`` argv shapes, the stdin framing, the Ollama endpoint, the 

5timeouts and the JSON return contract lived only as prose in ``ship.md`` s4/s7, so every 

6host agent re-invented them and they drifted. This module is the single answer to *how do 

7I invoke provider P for role R*, and :mod:`keel.delegaterun` is the only thing that runs 

8the answer. 

9 

10The split is keel's usual one. Everything here is **pure**: it takes a 

11:class:`keel.providers.Provider` (from #1011's registry) plus a role, and returns a frozen 

12:class:`RunPlan` — an argv, or an HTTP request description, plus the stdin framing, the 

13read-only verdict, the attribution record and any warnings. No subprocess, no network, no 

14clock, no filesystem. That is what makes "a ``review`` run never carries a write-enabling 

15flag" a property a unit test can assert per vendor instead of a sentence in a markdown 

16file nobody can execute. 

17 

18**Role policy.** ``review``/``gate``/``chair`` are read-only: the delegate reads a diff 

19and returns findings, and every mutation stays with the orchestrator. ``implement``/``fix`` 

20are tool-enabled. keel can *document* a read-only invocation for the three built-in CLIs 

21and *offer* one (``review_args``) for a configured profile; it cannot **enforce** read-only 

22for an arbitrary binary, which is why :attr:`RunPlan.read_only` reports the role's policy 

23and a warning names the case where nothing backs it. 

24 

25**Why the prompt is never in argv.** Every transport that runs a binary delivers the 

26prompt on stdin. A prompt carries the diff and the brief; an argv is world-readable in 

27``ps`` for the life of the process, and a large diff can exceed ``ARG_MAX`` outright. The 

28one exception is a profile that declares ``prompt_mode: arg`` — an operator-authored 

29choice for CLIs whose usage requires it (``cursor-agent``'s is 

30``agent [options] [command] [prompt...]``), where the plan carries ``stdin_mode: None`` and 

31the executor appends the prompt as the final argument. 

32 

33**agy's framing.** ai-jury (``src/ai_jury/adapters.py``, read-only reference) verified two 

34invocations against the shipped CLI: ``--print=<prompt>``, which takes the prompt as the 

35flag's *value* because ``--print --model X`` swallows the next flag; and 

36``--input-format stream-json --output-format stream-json``, which reads one NDJSON frame 

37per line on stdin. keel takes the **stream-json** one. Three reasons, in order: the prompt 

38stays out of ``ps`` and out of ``ARG_MAX`` (ai-jury's #287); it sidesteps the ``--print`` 

39arity trap entirely rather than working around it; and — decisively for this module — a 

40*pure* planner is handed a prompt **path**, never the prompt text, so it could not build a 

41``--print=<prompt>`` argv at all without reading a file and stopping being pure. The 

42NDJSON reply is parsed back by :func:`parse_stream_json`. 

43 

44Pure and deterministic: no wall-clock, no randomness, no I/O. Failures raise 

45:class:`DelegateError`, which carries a machine-readable ``code`` the executor turns into 

46the fail-soft ``error_code`` of the JSON contract — a traceback never reaches an operator. 

47""" 

48 

49from __future__ import annotations 

50 

51import json 

52import posixpath 

53import re 

54from dataclasses import dataclass, field 

55from typing import Any 

56 

57from . import agents 

58from . import providers as providers_mod 

59from .api_delegate import DEFAULT_MAX_TOKENS, OPENAI_COMPATIBLE 

60from .config import DEFAULT_PROMPT_MODE, DelegateProfile 

61 

62# The effort vocabulary lives in the leaf :mod:`keel.vocab` so ``keel.team`` can validate 

63# a seat's ``effort`` without importing the executor (#1050). ``EFFORT_VENDORS`` and 

64# ``supports_effort`` are re-exported under the original names, which are what the rest 

65# of the package and the tests read. 

66from .vocab import EFFORT_VENDORS as EFFORT_VENDORS 

67from .vocab import EFFORTS as EFFORTS 

68from .vocab import supports_effort as supports_effort 

69 

70#: The module's public surface, in definition order (#1070). It is declared because the 

71#: ``X as X`` re-exports above are read from *other* modules — a use CodeQL's 

72#: ``py/unused-import`` cannot see, since it counts same-module uses only. A name listed 

73#: in ``__all__`` is used by definition, so the declaration answers the scanner with the 

74#: language's own statement of intent rather than with a dismissal. Being a real 

75#: declaration it has to be the *whole* surface, not the re-exports alone; 

76#: ``tests/test_reexport_surface.py`` holds it to that in both directions. 

77__all__ = [ 

78 "EFFORT_VENDORS", 

79 "EFFORTS", 

80 "supports_effort", 

81 "ROLES", 

82 "READ_ONLY_ROLES", 

83 "TRANSPORTS", 

84 "STDIN_TEXT", 

85 "STDIN_STREAM_JSON", 

86 "DEFAULT_TIMEOUT_S", 

87 "DEFAULT_QUOTA_WAIT_S", 

88 "OLLAMA_GENERATE_URL", 

89 "AGY_STREAM_ARGS", 

90 "CLAUDE_ALLOWED_TOOLS", 

91 "CODEX_EFFORT_CONFIG", 

92 "ANTHROPIC_THINKING_BUDGET", 

93 "GOOGLE_THINKING_BUDGET", 

94 "THINKING_HEADROOM_TOKENS", 

95 "DelegateError", 

96 "Resolution", 

97 "Effort", 

98 "RunPlan", 

99 "resolve_provider", 

100 "is_safe_body_model_token", 

101 "model_reaches_argv", 

102 "model_token_issue", 

103 "is_absolute_cwd", 

104 "plan_run", 

105 "stream_json_frame", 

106 "parse_stream_json", 

107 "parse_ollama_response", 

108 "ollama_payload", 

109] 

110 

111#: Roles a delegate can be dispatched for. ``chair`` is the jury's summariser; it reads 

112#: reviews and writes nothing, so it sits with the read-only three. 

113ROLES = ("implement", "fix", "review", "gate", "chair") 

114 

115#: Roles invoked read-only / findings-only. Everything not listed here is tool-enabled. 

116READ_ONLY_ROLES = ("review", "gate", "chair") 

117 

118#: How the executor reaches a provider. ``cli`` is one of the three built-in agent CLIs, 

119#: ``profile`` any other binary (a project ``delegate_profiles`` entry or a registry 

120#: ``cli``/``local`` entry), ``api`` a hosted or OpenAI-compatible HTTP endpoint, and 

121#: ``ollama`` the built-in local vendor served on loopback. 

122TRANSPORTS = ("cli", "profile", "api", "ollama") 

123 

124#: Prompt framing on the child's stdin. ``None`` means "no stdin": the executor appends 

125#: the prompt as the final argv element (a profile's ``prompt_mode: arg``). 

126STDIN_TEXT = "text" 

127STDIN_STREAM_JSON = "stream-json" 

128 

129#: Wall-clock seconds a delegate run may take when the caller names none. Delegated 

130#: implementation is measured in tens of minutes, not in the 120 s a git call gets. 

131DEFAULT_TIMEOUT_S = 1800 

132 

133#: Default maximum seconds to back off and retry on retryable quota errors (#1549). 

134DEFAULT_QUOTA_WAIT_S = 60 

135 

136#: Ollama's local generation endpoint. A **hardcoded loopback constant**, exactly like 

137#: :data:`keel.providers.OLLAMA_TAGS_URL` and every other URL keel dials: the executor 

138#: never reaches an endpoint named by config or by the registry. 

139OLLAMA_GENERATE_URL = "http://127.0.0.1:11434/api/generate" 

140 

141#: agy's NDJSON stdin/stdout framing. See the module docstring for why keel uses it 

142#: rather than ``--print=<prompt>``. 

143AGY_STREAM_ARGS = ("--input-format", "stream-json", "--output-format", "stream-json") 

144 

145#: A Windows absolute path (``C:\\wt`` / ``C:/wt``) or a UNC share (``\\\\host\\share``). 

146#: ``posixpath.isabs`` says False for both, and a plan is a document that may be read 

147#: on a platform other than the one that wrote it. 

148_WINDOWS_ABSOLUTE = re.compile(r"^(?:[A-Za-z]:[\\/]|\\\\)") 

149 

150#: The only tools a read-only ``claude`` invocation may use. An **allow-list**: a denylist 

151#: of write tools has to be extended every time the CLI grows one, and is wrong in the 

152#: window before someone notices. Reading a diff needs no more than these three — ``Glob`` 

153#: is how the current CLI lists a directory, so there is no separate listing tool to name. 

154CLAUDE_ALLOWED_TOOLS = "Read,Grep,Glob" 

155 

156#: How ``codex`` spells reasoning effort. Not a flag on the shipped CLI (0.152.1) — it is 

157#: a config override, and an unknown key is rejected under ``--strict-config``, which is 

158#: how this spelling was verified rather than assumed. 

159CODEX_EFFORT_CONFIG = "model_reasoning_effort" 

160 

161#: ``anthropic-api`` extended-thinking budget per effort level, in tokens. 

162ANTHROPIC_THINKING_BUDGET = {"low": 2048, "medium": 8192, "high": 32768} 

163 

164#: ``google-api`` ``thinkingBudget`` per effort level, in tokens. Gemini's floor is lower 

165#: than Claude's, so ``low`` is 1024 rather than 2048. 

166GOOGLE_THINKING_BUDGET = {"low": 1024, "medium": 8192, "high": 32768} 

167 

168#: Room left for the answer *above* a thinking budget. Anthropic requires 

169#: ``max_tokens > thinking.budget_tokens``; a budget of 32768 against the default 16384 

170#: cap is rejected by the API before a token is generated. 

171THINKING_HEADROOM_TOKENS = 4096 

172 

173#: Suffixes agy spells reasoning effort with, e.g. ``gemini-3.8-flash-high``. 

174_EFFORT_SUFFIXES = tuple(f"-{level}" for level in EFFORTS) 

175 

176 

177class DelegateError(Exception): 

178 """A run that cannot be planned. ``code`` is the JSON contract's ``error_code``.""" 

179 

180 def __init__(self, code: str, message: str) -> None: 

181 super().__init__(message) 

182 self.code = code 

183 self.message = message 

184 

185 

186@dataclass(frozen=True) 

187class Resolution: 

188 """Which provider a ``--provider`` token names, and the model it carries.""" 

189 

190 provider: providers_mod.Provider 

191 #: The project ``delegate_profiles`` entry behind a ``profile``-source provider. 

192 #: :class:`keel.providers.Provider` keeps only ``review_args``, so the implementer's 

193 #: ``args`` and the ``prompt_mode`` are reachable only through the profile itself. 

194 profile: DelegateProfile | None = None 

195 #: The per-run model from ``vendor:model``, already validated. ``None`` when the 

196 #: token named no model. 

197 model: str | None = None 

198 

199 

200@dataclass(frozen=True) 

201class Effort: 

202 """How one ``--effort`` request landed on one vendor. 

203 

204 Returned as a record rather than a tuple because the *budget* is needed twice and in 

205 two shapes: inside the vendor's payload fragment, and again as the number 

206 ``max_tokens`` must exceed. Re-deriving it by digging back into the fragment means 

207 one parser per vendor spelling, with branches nothing can reach. 

208 """ 

209 

210 model: str | None 

211 payload: dict[str, Any] 

212 #: Thinking-token budget the fragment asks for, ``None`` when it asks for none. 

213 budget: int | None 

214 applied: bool 

215 warnings: tuple[str, ...] 

216 #: Extra argv fragment, for a vendor that spells effort on its command line. 

217 argv: tuple[str, ...] = () 

218 

219 

220@dataclass(frozen=True) 

221class RunPlan: 

222 """One fully-resolved delegate invocation. Frozen, JSON-stable, never executed here.""" 

223 

224 provider: str 

225 #: The vendor attribution names — a built-in's own token, or a profile/registry 

226 #: entry's ``vendor_label`` when it declares one (#1129). Before that field existed 

227 #: this said ``cli`` for *every* configured CLI, so two entries driving different 

228 #: makers through one binary were indistinguishable here and in the label derived 

229 #: from it. Which executor runs the plan stays in :attr:`transport` 

230 #: (``cli``/``profile``/``api``/``ollama``); a declared label costs the finer 

231 #: ``cli``-vs-``local`` split, which no caller branches on — both are run as a 

232 #: configured binary. 

233 vendor: str 

234 role: str 

235 transport: str 

236 prompt_path: str = "" 

237 model: str | None = None 

238 cwd: str | None = None 

239 timeout: int = DEFAULT_TIMEOUT_S 

240 #: The command line, **without** the prompt. Empty for ``api``/``ollama``. 

241 argv: tuple[str, ...] = () 

242 #: The HTTP call description for ``api``/``ollama``; ``None`` for the argv transports. 

243 request: dict[str, Any] | None = None 

244 #: ``text`` | ``stream-json`` | ``None`` (append the prompt as the last argv element). 

245 stdin_mode: str | None = None 

246 #: True when the role's policy is read-only. 

247 read_only: bool = False 

248 #: True when something actually **backs** that policy: a built-in CLI's documented 

249 #: read-only invocation, an operator's ``review_args``, or a transport with no tools 

250 #: at all. False means the role says read-only and nothing enforces it — the caller 

251 #: must decide whether to run at all. Split from :attr:`read_only` because a single 

252 #: flag cannot distinguish "reviewer" from "reviewer holding the implementer's write 

253 #: flags", and the second is the one that edits the checkout. 

254 read_only_backed: bool = False 

255 effort: str | None = None 

256 effort_applied: bool = False 

257 warnings: tuple[str, ...] = () 

258 attribution: dict[str, str | None] = field(default_factory=dict) 

259 prompt: str | None = None 

260 quota_wait: float = float(DEFAULT_QUOTA_WAIT_S) 

261 

262 def as_dict(self) -> dict[str, Any]: 

263 """JSON-stable record (carries no secret: ``api_key_env`` is a name).""" 

264 return { 

265 "provider": self.provider, 

266 "vendor": self.vendor, 

267 "role": self.role, 

268 "transport": self.transport, 

269 "prompt_path": self.prompt_path, 

270 "model": self.model, 

271 "cwd": self.cwd, 

272 "timeout": self.timeout, 

273 "argv": list(self.argv), 

274 "request": dict(self.request) if self.request is not None else None, 

275 "stdin_mode": self.stdin_mode, 

276 "read_only": self.read_only, 

277 "read_only_backed": self.read_only_backed, 

278 "effort": self.effort, 

279 "effort_applied": self.effort_applied, 

280 "warnings": list(self.warnings), 

281 "attribution": dict(self.attribution), 

282 "prompt": self.prompt, 

283 "quota_wait": self.quota_wait, 

284 } 

285 

286 

287def resolve_provider( 

288 config, 

289 registry: providers_mod.Registry | None, 

290 token: str, 

291) -> Resolution: 

292 """Resolve ``name`` / ``vendor:model`` against the built-ins, profiles, the registry. 

293 

294 Precedence is **built-in > project profile > registry**. A built-in vendor always 

295 wins and can never be redefined — the invariant 

296 :func:`keel.agents.resolve_delegate_profile` states and 

297 :func:`keel.config.parse_config` enforces up front, and the same rule 

298 :func:`keel.providers.registry_clashes` applies to a machine-level entry. Resolving a 

299 profile or a registry entry first would make ``claude`` mean whatever a file in 

300 ``$HOME`` said it meant, which is exactly the shadowing those two checks exist to 

301 refuse; dispatch must not be the one place the rule is inverted. 

302 

303 The model half of the token is validated before anything else looks at it: it arrives 

304 per run, on the command line (``--provider <name>:<model>`` or ``--model``), which is 

305 a lower-trust source than the operator-authored command beside it. **Which** rule 

306 applies depends on where the model lands — see :func:`model_token_issue`. 

307 """ 

308 name, model = agents.split_delegate((token or "").strip()) 

309 if not name: 

310 raise DelegateError("bad-provider", "--provider is empty; pass name or vendor:model") 

311 profiles = {} if config is None else config.knobs.delegate_profiles 

312 registry = providers_mod.Registry(path="") if registry is None else registry 

313 resolution = _lookup(name, config, profiles, registry) 

314 if resolution is None: 

315 known = ", ".join(sorted({*profiles, *registry.names(), *agents.BUILTIN_DELEGATE_VENDORS})) 

316 hint = _did_you_mean(name, profiles, registry) 

317 raise DelegateError("unknown-provider", f"unknown provider {name!r}; known: {known}{hint}") 

318 _check_model(resolution.provider, model) 

319 return Resolution(resolution.provider, resolution.profile, model) 

320 

321 

322def _did_you_mean(name: str, profiles, registry: providers_mod.Registry) -> str: 

323 """``; did you mean 'grok'?`` for a profile/registry entry whose command is ``name``'s CLI. 

324 

325 People type the product (``cursor``), the binary is ``cursor-agent``, and the entry 

326 that drives it carries an operator-chosen name (``grok``). A fixed alias table would 

327 bind ``cursor`` to whatever the operator happened to name their entry, or to a CLI 

328 keel does not ship; matching on the configured *command* names the operator's own 

329 entry instead (#1509). 

330 """ 

331 needle = name.lower().removesuffix(".exe") 

332 matches = [] 

333 # Suggest only names that resolve to the entry that matched: `_lookup` prefers a 

334 # built-in, then a project profile, then the registry, so a shadowed name would run 

335 # something else. 

336 builtins = {e.name for e in providers_mod.builtin_providers()} 

337 commands = [(n, p.command) for n, p in profiles.items() if n not in builtins] 

338 commands += [ 

339 (e.name, e.command) 

340 for e in registry.providers 

341 if e.name not in builtins and e.name not in profiles 

342 ] 

343 for entry_name, command in commands: 

344 # Windows paths split on backslashes too. 

345 base = posixpath.basename((command or "").replace("\\", "/")).lower() 

346 base = base.removesuffix(".exe") 

347 if base and (base == needle or base.startswith(needle + "-")): 

348 matches.append(entry_name) 

349 if not matches: 

350 return "" 

351 return "; did you mean " + " or ".join(repr(m) for m in sorted(set(matches))) + "?" 

352 

353 

354def _lookup(name, config, profiles, registry: providers_mod.Registry) -> Resolution | None: 

355 """The provider ``name`` means, in precedence order. ``None`` when nothing claims it.""" 

356 for entry in providers_mod.builtin_providers(): 

357 if entry.name == name: 

358 return Resolution(entry, None, None) 

359 if name in profiles: 

360 return Resolution(_profile_provider(config, name), profiles[name], None) 

361 for entry in registry.providers: 

362 if entry.name == name: 

363 return Resolution(entry, None, None) 

364 return None 

365 

366 

367#: Characters a model may contain when it travels in a **JSON request body**. Wider than 

368#: :func:`keel.agents.is_safe_model_token` by ``:`` and ``/`` because real ids need both — 

369#: an Ollama tag (``qwen2.5-coder:32b``) and a gateway's namespaced id 

370#: (``deepseek/deepseek-r1``). Neither character can do anything in a JSON string value: 

371#: the body is built by :func:`json.dumps`, so there is no argv to split and no URL path 

372#: to retarget. A leading dash and ``..`` stay refused so the same token can never be 

373#: mistaken for a flag or a path if it is later logged, echoed, or reused. 

374_BODY_MODEL_OK = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._:/-") 

375 

376 

377def is_safe_body_model_token(model: str | None) -> bool: 

378 """True when ``model`` is safe as a JSON body field (``ollama``/hosted/compatible).""" 

379 if not model or model.startswith("-") or ".." in model: 

380 return False 

381 return _BODY_MODEL_OK.issuperset(model) 

382 

383 

384def model_reaches_argv(provider: providers_mod.Provider) -> bool: 

385 """Does this provider's model end up on a command line or in a URL path? 

386 

387 Two places demand the strict ``[A-Za-z0-9._-]`` token, and only two: a **subprocess 

388 argv** (``cli``/``profile``), where a stray character could read as another flag; and 

389 ``google-api``'s **URL path**, the one vendor that interpolates the model into its 

390 endpoint, where a ``/`` or a ``?`` could retarget the request or smuggle query 

391 parameters onto a URL that also carries an API key header. 

392 

393 Everywhere else the model is a JSON string value, and applying the argv rule there is 

394 not caution but breakage: it refuses ``ollama:qwen2.5-coder:32b`` and 

395 ``openrouter:deepseek/deepseek-r1``, two ids this repository's own documentation tells 

396 operators to use. 

397 """ 

398 return _transport_of(provider) in ("cli", "profile") or provider.vendor == "google-api" 

399 

400 

401def model_token_issue(provider: providers_mod.Provider, model: str | None) -> str | None: 

402 """Why ``model`` may not be used with ``provider``, or ``None`` when it may.""" 

403 if model is None: 

404 return None 

405 if model_reaches_argv(provider): 

406 if not agents.is_safe_model_token(model): 

407 return ( 

408 f"model {model!r} is not a safe token for {provider.name!r}: it reaches a " 

409 "command line or a URL path, so only [A-Za-z0-9._-] with no leading dash " 

410 "is accepted" 

411 ) 

412 return None 

413 if not is_safe_body_model_token(model): 

414 return ( 

415 f"model {model!r} is not a safe token for {provider.name!r}: a request-body " 

416 "model accepts [A-Za-z0-9._:/-] with no leading dash and no '..'" 

417 ) 

418 return None 

419 

420 

421def _check_model(provider: providers_mod.Provider, model: str | None) -> None: 

422 issue = model_token_issue(provider, model) 

423 if issue is not None: 

424 raise DelegateError("bad-model", issue) 

425 

426 

427def _profile_provider(config, name: str) -> providers_mod.Provider: 

428 """The one :class:`keel.providers.Provider` this project's profile ``name`` maps to.""" 

429 for provider in providers_mod.profile_providers(config): 

430 if provider.name == name: 

431 return provider 

432 raise DelegateError( # pragma: no cover - profile_providers covers every profile key 

433 "unknown-provider", f"profile {name!r} produced no provider record" 

434 ) 

435 

436 

437def plan_run( 

438 provider: providers_mod.Provider, 

439 role: str, 

440 prompt_path: str | None = None, 

441 cwd: str | None = None, 

442 timeout: int = DEFAULT_TIMEOUT_S, 

443 effort: str | None = None, 

444 model: str | None = None, 

445 *, 

446 profile: DelegateProfile | None = None, 

447 prompt: str | None = None, 

448 quota_wait: float | None = None, 

449) -> RunPlan: 

450 """Plan one delegate invocation. Pure; raises :class:`DelegateError` on bad input. 

451 

452 ``model`` is the per-run override (``--model``, or the ``vendor:model`` half of the 

453 provider token) and wins over the provider's configured ``model``, matching the 

454 precedence ship.md s4 documents. ``profile`` supplies the project profile behind a 

455 ``profile``-source provider — see :attr:`Resolution.profile`. 

456 """ 

457 if role not in ROLES: 

458 raise DelegateError("bad-role", f"unknown role {role!r}; valid: {', '.join(ROLES)}") 

459 if effort is not None and effort not in EFFORTS: 

460 raise DelegateError("bad-effort", f"unknown effort {effort!r}; valid: {', '.join(EFFORTS)}") 

461 if timeout <= 0: 

462 raise DelegateError( 

463 "bad-timeout", f"timeout must be a positive number of seconds: {timeout!r}" 

464 ) 

465 if prompt is not None and prompt_path: 

466 raise DelegateError("no-prompt", "pass either --prompt or --prompt-file, not both") 

467 if not prompt_path and not prompt: 

468 raise DelegateError("no-prompt", "--prompt or --prompt-file is required") 

469 if prompt is not None and not prompt.strip(): 

470 raise DelegateError("no-prompt", "--prompt cannot be empty") 

471 effective_quota_wait = float(DEFAULT_QUOTA_WAIT_S if quota_wait is None else quota_wait) 

472 if effective_quota_wait < 0: 

473 raise DelegateError("bad-timeout", f"quota-wait must be non-negative: {quota_wait!r}") 

474 # Normalised once, here, because a :class:`RunPlan` is a frozen JSON document: a 

475 # ``Path`` reaching this far would pass every predicate, land in ``cwd`` and in the 

476 # ``--add-dir`` argv, and then raise ``TypeError: Object of type PosixPath is not 

477 # JSON serializable`` out of ``as_dict`` — at the point where the contract is 

478 # printed rather than where the wrong type entered. Found by the gate review of 

479 # #1134. 

480 cwd = None if cwd is None else str(cwd) 

481 effective = model or provider.model 

482 _check_model(provider, effective) 

483 read_only = role in READ_ONLY_ROLES 

484 transport = _transport_of(provider) 

485 effort, warnings = _effective_effort(provider, effort) 

486 applied = _apply_effort(provider.vendor, transport, effort, effective) 

487 effective = applied.model 

488 warnings = warnings + applied.warnings 

489 argv: tuple[str, ...] = () 

490 request: dict[str, Any] | None = None 

491 stdin_mode: str | None = None 

492 backed = read_only 

493 if transport == "cli": 

494 argv, stdin_mode = _builtin_argv( 

495 provider, 

496 read_only=read_only, 

497 model=effective, 

498 effort_args=applied.argv, 

499 cwd=cwd, 

500 timeout=timeout, 

501 ) 

502 if cwd and not is_absolute_cwd(cwd) and provider.name == "agy": 

503 warnings = warnings + ( 

504 f"cwd {cwd!r} is relative; agy resolves --add-dir against the directory " 

505 "it is started in, so it would name a path inside the worktree instead of " 

506 "the worktree. The flag is omitted and agy will edit its own scratch copy " 

507 "(#1134) — pass an absolute path.", 

508 ) 

509 elif transport == "profile": 

510 argv, stdin_mode, backed, profile_warnings = _profile_argv( 

511 provider, profile, read_only=read_only, model=effective 

512 ) 

513 warnings = warnings + profile_warnings 

514 else: 

515 request = _request(provider, transport, model=effective, timeout=timeout, effort=applied) 

516 return RunPlan( 

517 provider=provider.name, 

518 vendor=provider.label_vendor(), 

519 role=role, 

520 transport=transport, 

521 prompt_path=str(prompt_path) if prompt_path else "", 

522 model=effective, 

523 cwd=cwd, 

524 timeout=timeout, 

525 argv=argv, 

526 request=request, 

527 stdin_mode=stdin_mode, 

528 read_only=read_only, 

529 read_only_backed=backed, 

530 effort=effort, 

531 effort_applied=applied.applied, 

532 warnings=warnings, 

533 attribution=_attribution(provider, profile, effective), 

534 prompt=prompt, 

535 quota_wait=effective_quota_wait, 

536 ) 

537 

538 

539def _effective_effort( 

540 provider: providers_mod.Provider, effort: str | None 

541) -> tuple[str | None, tuple[str, ...]]: 

542 """``--effort`` if given, else the provider's own configured default. 

543 

544 ``Provider.effort`` exists so an operator can say "this entry is my high-effort seat" 

545 once, in the registry or the profile, instead of on every dispatch. A per-run 

546 ``--effort`` still wins. An unrecognised configured value is a **warning, not an 

547 error**: the registry is fail-soft everywhere else in #1011, and a typo in a file in 

548 ``$HOME`` should not make every run of an otherwise usable provider fail. 

549 """ 

550 if effort is not None or not provider.effort: 

551 return effort, () 

552 if provider.effort in EFFORTS: 

553 return provider.effort, () 

554 return None, ( 

555 f"{provider.name}: ignoring configured effort {provider.effort!r}; " 

556 f"valid: {', '.join(EFFORTS)}", 

557 ) 

558 

559 

560def _transport_of(provider: providers_mod.Provider) -> str: 

561 """Which executor path a provider record lands on. 

562 

563 :class:`keel.providers.Provider` records the *shape* of a provider (``cli``/``api``/ 

564 ``local``); this is the finer question of which code runs it. The built-in ``ollama`` 

565 vendor gets its own HTTP path, while a registry ``local`` entry names an arbitrary 

566 binary and is run exactly like a configured CLI — keel does not dial an address a 

567 file names, so a local entry's only reachable surface is its command. 

568 """ 

569 if provider.transport == "api": 

570 return "api" 

571 if provider.vendor == "ollama": 

572 return "ollama" 

573 if provider.source == "builtin": 

574 return "cli" 

575 return "profile" 

576 

577 

578def is_absolute_cwd(cwd: str | None) -> bool: 

579 """Is ``cwd`` a path agy's ``--add-dir`` can be given? (pure — no filesystem) 

580 

581 The child is started **inside** ``cwd`` — :func:`keel.delegaterun._run_argv` passes it 

582 to the runner — so agy resolves a relative ``--add-dir`` against that directory: 

583 ``--cwd worktrees/foo`` would name ``<root>/worktrees/foo/worktrees/foo``, and the 

584 real worktree would go untouched exactly as it did before #1134. ``--add-dir .`` is 

585 not a way out; it was measured, and the run ended on agy's timeout with the tree 

586 unchanged, the same as passing no flag at all. 

587 

588 So the path has to be absolute, and this module cannot make it so: ``abspath`` reads 

589 the *host's* working directory into a :class:`RunPlan` that is frozen, JSON-stable and 

590 may be executed somewhere else. The CLI resolves it; this refuses what is left, and 

591 :func:`plan_run` says why in a warning. Found by the gate review of #1134. 

592 

593 Both separators are accepted, because a plan built on one platform is a document that 

594 may be read on another. 

595 """ 

596 # ``str(cwd)`` rather than ``cwd``: the annotation says ``str | None``, but 

597 # ``posixpath.isabs`` accepts a ``PathLike`` while ``re.match`` does not, so a 

598 # *relative* ``Path`` would fall through the first test and raise ``TypeError`` out of 

599 # the second while an absolute one short-circuited to ``True``. A predicate that 

600 # answers for half its inputs and crashes for the other half is worse than one that 

601 # refuses both. Found by the gate review of #1134. 

602 text = "" if cwd is None else str(cwd) 

603 return bool(text) and (posixpath.isabs(text) or _WINDOWS_ABSOLUTE.match(text) is not None) 

604 

605 

606def _builtin_argv( 

607 provider: providers_mod.Provider, 

608 *, 

609 read_only: bool, 

610 model: str | None, 

611 effort_args: tuple[str, ...] = (), 

612 cwd: str | None = None, 

613 timeout: int = DEFAULT_TIMEOUT_S, 

614) -> tuple[tuple[str, ...], str]: 

615 """The argv + stdin framing for one of the three built-in agent CLIs. 

616 

617 **claude's read-only invocation is an allow-list, and carries no permission bypass.** 

618 The first cut paired ``--disallowed-tools Edit,Write,NotebookEdit,Bash`` with 

619 ``--dangerously-skip-permissions``, on the reasoning that a denylist wins over the 

620 bypass. That is a denylist of four names against a tool surface that grows with every 

621 release — ``WebFetch``, an MCP server's tools, whatever ships next — and it hands the 

622 bypass to everything it failed to enumerate. ``--allowed-tools`` inverts the default: 

623 anything not named is refused, so a new tool is refused on the day it appears rather 

624 than on the day someone remembers this list. With no tool outside the read set 

625 reachable there is nothing left for a permission prompt to ask about, so the bypass is 

626 dropped as well. Flag spelling verified against ``claude --help`` 

627 (``--allowedTools, --allowed-tools <tools...>``). 

628 

629 ``agy`` keeps ``--sandbox`` plus ``--dangerously-skip-permissions``: it exposes no 

630 allow-list, the sandbox is the only read-only mechanism it documents, and without the 

631 skip flag an unattended reviewer stops at an approval prompt. This is the same pairing 

632 ai-jury's ``privilege.enforce_read_only`` uses for the vendor, and the reason 

633 :attr:`RunPlan.read_only_backed` reports what backs the promise rather than asserting 

634 that writes are impossible. 

635 """ 

636 command = provider.command or provider.name 

637 if provider.name == "claude": 

638 argv = [command, "-p"] 

639 if read_only: 

640 argv += ["--output-format", "text"] 

641 if model: 

642 argv += ["--model", model] 

643 if read_only: 

644 argv += ["--allowed-tools", CLAUDE_ALLOWED_TOOLS] 

645 else: 

646 argv += ["--dangerously-skip-permissions"] 

647 return tuple(argv), STDIN_TEXT 

648 if provider.name == "codex": 

649 sandbox = "read-only" if read_only else "workspace-write" 

650 argv = [command, "exec", "-s", sandbox, "--skip-git-repo-check"] 

651 if model: 

652 argv += ["-m", model] 

653 argv += list(effort_args) 

654 return tuple(argv), STDIN_TEXT 

655 # agy — the only remaining built-in CLI vendor (agents.CLI_VENDORS). 

656 argv = [command] 

657 if read_only: 

658 argv += ["--sandbox"] 

659 argv += ["--dangerously-skip-permissions", *AGY_STREAM_ARGS] 

660 if model: 

661 argv += ["--model", model] 

662 # `--add-dir` is what makes the working directory keel named the one agy edits 

663 # (#1134). Without it agy works in `~/.gemini/antigravity-cli/scratch/<basename>` — 

664 # its own copy — so an `implement` run returned prose about files it had changed 

665 # while the worktree keel handed it stayed clean, and the first thing downstream 

666 # would have seen is a pull request with no diff. Measured, not inferred: three 

667 # runs of one prompt against a standalone clone, a linked worktree, and a linked 

668 # worktree with this flag. Only the third edited the real file, and only it made 

669 # no scratch copy — the other two never touched the directory at all and ended on 

670 # agy's own print timeout. 

671 # Absolute only — see :func:`is_absolute_cwd`. The caller makes it absolute; a plan 

672 # that reached here with a relative one carries the warning instead of an argv the 

673 # child would resolve against itself. 

674 if is_absolute_cwd(cwd): 

675 # ``str`` by the time it reaches here — :func:`plan_run` normalises it — and 

676 # spelled again because this helper is reachable from a test with any value, and 

677 # ``RunPlan.argv`` is ``tuple[str, ...]``. 

678 argv += ["--add-dir", str(cwd)] 

679 # And `--print-timeout` is why keel's own `--timeout` used to mean nothing here: 

680 # agy's print mode defaults to 5m and stops on its own, so `--timeout 900` against 

681 # a real brief died at 298s with agy's `timeout waiting for response` — keel's 

682 # bound never reached the process it was bounding. Go duration spelling, per 

683 # `agy --help` ("default 5m0s"). 

684 # 

685 # Unconditional, because :func:`plan_run` refuses a non-positive timeout before 

686 # reaching here — a guard on it would be a branch no input can take, which the 

687 # 100 % coverage bar reports as exactly what it is. Found by the gate review. 

688 argv += ["--print-timeout", f"{timeout}s"] 

689 return tuple(argv), STDIN_STREAM_JSON 

690 

691 

692def _profile_argv( 

693 provider: providers_mod.Provider, 

694 profile: DelegateProfile | None, 

695 *, 

696 read_only: bool, 

697 model: str | None, 

698) -> tuple[tuple[str, ...], str | None, bool, tuple[str, ...]]: 

699 """The argv + framing + read-only backing for an operator-configured binary. 

700 

701 The dangerous case is a profile that has ``args`` and no ``review_args``: 

702 :meth:`keel.config.DelegateProfile.role_args` **falls back to ``args``**, which is the 

703 implementer's flag set — ``aider``'s ``--yes-always``, ``cursor-agent``'s ``--force``. 

704 A reviewer invoked with those can edit the checkout it was asked to read. 

705 

706 So the question asked here is *"did the operator configure a read-only invocation?"* — 

707 ``profile.review_args is None`` — and **not** *"is the argv empty?"*. The first cut 

708 asked the second, so exactly the dangerous case produced a full implementer argv, 

709 ``read_only: true``, and no warning at all: the fallback made ``role_args`` non-empty, 

710 which read as "configured". A profile whose ``review_args`` is an explicit empty list 

711 is a deliberate choice — "this CLI needs no flags to be a reviewer" — and is backed. 

712 """ 

713 command = provider.command 

714 if not command: 

715 raise DelegateError("bad-provider", f"provider {provider.name!r} names no command") 

716 if profile is not None: 

717 role_args = profile.role_args(review=read_only) 

718 configured = profile.review_args is not None 

719 prompt_mode = profile.prompt_mode 

720 else: 

721 # A registry entry's `args` are the implementer's flags (#1508): applied to a 

722 # write role only, and never as a fallback for `review_args`, so an empty 

723 # review_args still reads as "nothing configured" rather than a fallback in disguise. 

724 role_args = provider.review_args if read_only else provider.args 

725 configured = bool(provider.review_args) 

726 prompt_mode = DEFAULT_PROMPT_MODE 

727 argv = [command, *role_args] 

728 if model and provider.model_arg: 

729 argv += [provider.model_arg, model] 

730 warnings: tuple[str, ...] = () 

731 backed = read_only and configured 

732 if read_only and not configured: 

733 shared = " it is running with the implementer's own args" if role_args else "" 

734 warnings = ( 

735 f"{provider.name}: no read-only invocation is configured (review_args), so" 

736 f"{shared or ' the command runs with its default permissions'} — keel cannot " 

737 "enforce read-only for an arbitrary CLI. Set review_args, treat this " 

738 "reviewer's output as advisory, and re-check the worktree is clean afterwards", 

739 ) 

740 stdin_mode = STDIN_TEXT if prompt_mode == DEFAULT_PROMPT_MODE else None 

741 return tuple(argv), stdin_mode, backed, warnings 

742 

743 

744def _request( 

745 provider: providers_mod.Provider, 

746 transport: str, 

747 *, 

748 model: str | None, 

749 timeout: int, 

750 effort: Effort, 

751) -> dict[str, Any]: 

752 """The HTTP call description for the ``api`` and ``ollama`` transports.""" 

753 if not model: 

754 raise DelegateError( 

755 "no-model", 

756 f"provider {provider.name!r} generates text over HTTP and names no model; " 

757 "pass --model or provider:model", 

758 ) 

759 if transport == "ollama": 

760 # Hardcoded loopback constant, never provider.endpoint: the tag listing #1011 

761 # probes and the generation endpoint are two paths on the same fixed origin. 

762 return { 

763 "vendor": "ollama", 

764 "model": model, 

765 "endpoint": OLLAMA_GENERATE_URL, 

766 "timeout": timeout, 

767 } 

768 max_tokens = DEFAULT_MAX_TOKENS 

769 if effort.budget is not None: 

770 # Anthropic rejects max_tokens <= thinking.budget_tokens before generating a 

771 # token, and Gemini's answer shares the output cap with its thinking. 

772 max_tokens = max(max_tokens, effort.budget + THINKING_HEADROOM_TOKENS) 

773 return { 

774 "vendor": provider.vendor, 

775 "model": model, 

776 "endpoint": provider.endpoint, 

777 "api_key_env": provider.api_key_env, 

778 "max_tokens": max_tokens, 

779 "timeout": timeout, 

780 "extra_payload": effort.payload, 

781 } 

782 

783 

784def _apply_effort(vendor: str, transport: str, effort: str | None, model: str | None) -> Effort: 

785 """Map ``--effort`` onto the vendor's own spelling. 

786 

787 Every vendor spells reasoning effort differently and several cannot spell it at all; 

788 an unsupported request is a warning plus ``applied: False``, never a silent no-op — a 

789 caller that asked for ``high`` and got the default must be able to see that from the 

790 JSON it parses. 

791 """ 

792 if effort is None: 

793 return Effort(model, {}, None, False, ()) 

794 if vendor == "agy": 

795 return _agy_effort(effort, model) 

796 if vendor == "codex": 

797 # A config override rather than a flag: `codex exec` takes `-c key=value`, and 

798 # `model_reasoning_effort` is the key it recognises (verified by round-tripping a 

799 # real and a bogus key through `--strict-config`). 

800 return Effort(model, {}, None, True, (), ("-c", f"{CODEX_EFFORT_CONFIG}={effort}")) 

801 if vendor == "anthropic-api": 

802 budget = ANTHROPIC_THINKING_BUDGET[effort] 

803 payload = {"thinking": {"type": "enabled", "budget_tokens": budget}} 

804 return Effort(model, payload, budget, True, ()) 

805 if vendor in ("openai-api", OPENAI_COMPATIBLE): 

806 return Effort(model, {"reasoning_effort": effort}, None, True, ()) 

807 if vendor == "google-api": 

808 budget = GOOGLE_THINKING_BUDGET[effort] 

809 payload = {"generationConfig": {"thinkingConfig": {"thinkingBudget": budget}}} 

810 return Effort(model, payload, budget, True, ()) 

811 return Effort( 

812 model, 

813 {}, 

814 None, 

815 False, 

816 ( 

817 f"--effort {effort} is not supported by {vendor} over the {transport} " 

818 "transport; the run used the provider's default reasoning effort", 

819 ), 

820 ) 

821 

822 

823def _agy_effort(effort: str, model: str | None) -> Effort: 

824 """agy spells effort as a model suffix (``gemini-3.8-flash-high``), not as a flag.""" 

825 if not model: 

826 return Effort( 

827 model, 

828 {}, 

829 None, 

830 False, 

831 ( 

832 f"--effort {effort} needs a model for agy, which spells effort as a " 

833 "model suffix; pass --model or provider:model", 

834 ), 

835 ) 

836 for suffix in _EFFORT_SUFFIXES: 

837 if model.endswith(suffix): 

838 if suffix == f"-{effort}": 

839 return Effort(model, {}, None, True, ()) 

840 return Effort( 

841 model, 

842 {}, 

843 None, 

844 True, 

845 ( 

846 f"model {model!r} already selects effort {suffix[1:]!r}; the model's " 

847 f"own suffix wins over --effort {effort}", 

848 ), 

849 ) 

850 return Effort(f"{model}-{effort}", {}, None, True, ()) 

851 

852 

853def _attribution( 

854 provider: providers_mod.Provider, 

855 profile: DelegateProfile | None, 

856 model: str | None, 

857) -> dict[str, str | None]: 

858 """The attribution record, computed by :mod:`keel.agents` so a host cannot drift. 

859 

860 A configured provider also records **which** entry ran under ``delegate_profile``, 

861 never ``profile``: the ship run record already means the workflow profile 

862 (``standard``/``compound``) by that name, and writing the CLI's name there would 

863 silently overwrite it. 

864 

865 A registry entry names its **label vendor** (#1129): ``vendor`` there is the 

866 transport the schema requires — ``cli`` for every local coding-agent CLI — so two 

867 entries driving Grok and GPT through the same binary both reported ``agent:cli``, 

868 and ``review-vendor-distinctness``, which is the rule keel most depends on, could 

869 not tell them apart. ``vendor_label`` is how an entry says which maker it reaches; 

870 unset, it stays the generic token, which is what every built-in already is. 

871 """ 

872 if profile is not None: 

873 return agents.profile_attribution(provider.name, profile, model) 

874 record = agents.attribution(provider.label_vendor(), model) 

875 if provider.source != "builtin": 

876 record["delegate_profile"] = provider.name 

877 return record 

878 

879 

880def stream_json_frame(prompt: str) -> str: 

881 """One NDJSON user frame for agy's ``--input-format stream-json`` stdin. 

882 

883 Shape ported from ai-jury's ``AgyAdapter._stdin_for``, verified there against 

884 agy 1.1.22. 

885 """ 

886 return json.dumps({"event": "user", "message": {"role": "user", "content": prompt}}) + "\n" 

887 

888 

889def parse_stream_json(raw: str) -> str: 

890 """The response text out of agy's NDJSON stdout, falling back to the raw stream. 

891 

892 Falls back rather than returning empty: a truncated stream must surface as output an 

893 operator can read, not as a silent abstention. An empty review counts as a review, 

894 and a review read as an approval is the expensive failure (ai-jury #625). 

895 """ 

896 response, saw_result = None, False 

897 for line in (raw or "").splitlines(): 

898 line = line.strip() 

899 if not line: 

900 continue 

901 try: 

902 event = json.loads(line) 

903 except ValueError: 

904 continue 

905 if isinstance(event, dict) and event.get("event") == "result": 

906 saw_result = True 

907 result = event.get("result") 

908 if isinstance(result, dict): 

909 response = result.get("response") 

910 if saw_result and isinstance(response, str): 

911 return response 

912 return raw 

913 

914 

915def parse_ollama_response(data: Any) -> str | None: 

916 """The completion out of an Ollama ``/api/generate`` payload (``None`` if malformed).""" 

917 if not isinstance(data, dict): 

918 return None 

919 text = data.get("response") 

920 return text if isinstance(text, str) and text else None 

921 

922 

923def ollama_payload(model: str, prompt: str) -> dict[str, Any]: 

924 """The ``/api/generate`` body. ``stream: false`` — keel wants one document, not NDJSON.""" 

925 return {"model": model, "prompt": prompt, "stream": False}