fix: parameter guidance, shell-reflex interception, and output contracts in tool descriptions

[jkyberneees]

Summary

Second adversarial pass on native tool descriptions, targeting the principal's two observed failure modes in real agent runs: models missing behavior-changing parameters (getting default/mush output, then falling back to shell) and models switching to shell for jobs the zero-fork tools do better. Three sequential reviewers (parameter neglect / shell-reflex interception / output-contract clarity; 5-6 code-verified findings each) + a fourth verifier on the final diff: APPROVE, 0 code defects (2 text nits fixed).

Highlights (17 findings across 6 files)

Parameter guidance (silent-truncation theme)

• head_tail: default 10 / max 100 now stated in the description — "a peek, not the file"; compare to total_lines.
• tree: deeper entries are silently cut at max_depth (3/10) — pass 10 before concluding absence.
• search_files / multi_grep / glob: limit params now disclose the default, the cap, and that the walk stops silently (50/500, 50/pattern, 50/1000) — raise before trusting completeness.
• bg_start.timeout_seconds: set it for anything that can loop/poll/listen forever; 0/absent = runs until session end, never notifies.
• delegate_tasks.trust_level: the omission default is now stated accurately — omitted = untrusted (the safe choice); trusted only for fully internal content.

Shell-reflex interception — descriptions now name the exact reflexes they replace: read_file (cat / sed -n / head), multi_grep (grep -rn / rg), glob (find), count_lines/word_count (wc), diff (diff/cmp), file_info (stat/du/ls -l). Family note added where it wins hardest: json_query/base64/checksum work inside the sandbox where jq/xxd/sha256sum may not even exist.

Output contracts (description-vs-code drift)

• tr and sort: descriptions now state the hard truth — the source file is NEVER modified; results come back in the response (persist with write_file/patch). Previously "operates on a file" implied in-place mutation.
• glob: output envelope documented as {"matches":[…]} with empty = {"matches":null} — zero matches is not an error.
• browser: runtime error strings no longer reference phantom browser_navigate/browser_snapshot tools (follow-up from fix: polish native tool descriptions for discoverability and turn efficiency #178) — they now point at the real action contract.

One code fix: batch_patch early-stop enforced

The tool description (since before v1.41.1) promised "at the first failing edit the remaining edits are skipped (early-stop)" — the code actually continued past failures, and one test pinned the undocumented side. Docs-as-contract: the loop now enforces early-stop (later edits report skipped: an earlier patch failed (early-stop), never touch disk; earlier-applied edits are kept). RED-first: new TestBatchPatchEarlyStopOnFirstFailure failed against the old loop; TestBatchPatch_ContinueOnError rewritten as TestBatchPatch_EarlyStop to pin the documented contract.

Verification

• 4th verifier sub-agent on the final diff: APPROVE — every numeric claim re-checked against constants/clamps (10/100, 3/10, 50/500, 50/1000, trust-omitted→untrusted), early-stop gate confirmed ahead of all per-patch work incl. the sandbox write branch, no max-10-cap interaction.
• go build, go vet, full cmd/odek + internal/memory suites green (-count=1).

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	odek	2ed1ca8	Commit Preview URL Branch Preview URL	Sep 03 2026, 07:43 AM