#11858: Exec: surface skill hints on command-not-found failures
agents
stale
Cluster:
Skill and Session Management Fixes
## Summary
When the exec tool encounters exit code 127 ("command not found"), it now checks if the failed binary matches a loaded skill's requires.bins and appends a hint pointing the model to the relevant SKILL.md. This helps weaker models (e.g. Sonnet 4) self-correct when they skip skill indexing and guess at commands with typos or wrong syntax.
## Behavior Changes
- **Error-path only:** only fires when exit code is exactly 127 and the binary matches a loaded skill. Zero impact on successful commands or other failure types.
- The hint is appended to the error message the model receives, not shown to end users.
## Codebase and GitHub Search
- Searched for existing skill-exec integration: none exists. Skills are prompt-injected only; exec tool was completely skill-unaware.
- Searched for "command not found" handling: no existing post-exec hinting.
## Tests
- 20 new unit tests in `bash-tools.exec.skill-hints.test.ts`
- Tests cover: binary extraction (simple, path prefix, sudo, env vars, nohup, combined prefixes, empty, edge cases), hint building (exit 127 match, non-127 codes, missing hints, empty map, undefined map, prefix traversal)
- All 52 bash-tools tests pass (8 test files)
**Sign-Off**
- Models used: Claude claude-4.6-opus
- Submitter effort: spec + review
- Agent notes: lobster-biscuit
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR makes the `exec` tool skill-aware for the specific error path where a command fails with exit code `127` (command not found). It adds helpers to extract the invoked binary from a shell command and, when that binary matches a loaded skill’s `requires.bins`, appends a hint telling the model to read the corresponding `SKILL.md` before retrying. The hint is wired into both the local exec failure path and the node/gateway exec response path, and unit tests are added for binary extraction + hint generation.
The wiring currently builds the bin→skill hint map inside the embedded runner and passes it into `createOpenClawCodingTools` via exec defaults, so the exec tool can conditionally append the hint to the text returned to the model.
<h3>Confidence Score: 4/5</h3>
- Mostly safe to merge, but one code path likely prevents the new behavior from triggering in snapshot-based embedded runs.
- Changes are scoped to the exec error path and are covered by unit tests, but `skillBinHints` is currently derived only from `loadWorkspaceSkillEntries()` output. When a skills snapshot is present, entries are not loaded (set to `[]`), so hints won’t be generated in that common execution mode, making the feature ineffective there.
- src/agents/pi-embedded-runner/run/attempt.ts
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#9221: fix(skills): use skillKey for env config lookup in snapshots
by gavinbmoore · 2026-02-05
73.1%
#3933: fix(skills): Make skill scripts executable
by jaysonsantos · 2026-01-29
72.8%
#9516: fix(skills): detect Windows executables with extensions
by yhl10000 · 2026-02-05
72.7%
#8455: feat: add thinking/model config to skills.entries
by tsukhani · 2026-02-04
72.1%
#7251: feat(skills): Context-aware dynamic skill loading [AI-assisted]
by cheenu1092-oss · 2026-02-02
71.8%
#9215: Fix: Inject skill env vars into subagent exec commands
by vishaltandale00 · 2026-02-05
71.6%
#15115: fix: pre-load skill docs in cron sessions to prevent hallucinated syn…
by joaolcorreia · 2026-02-13
71.6%
#11250: fix: expand skills watcher ignore list and improve session repair l...
by zhangzhefang-github · 2026-02-07
71.6%
#8075: fix(skills): add --ignore-scripts to all package managers
by yubrew · 2026-02-03
71.5%
#19658: feat(skills): add overlap-check — search before filing issues or PRs
by SeMmyT · 2026-02-18
71.2%