dsh-plugin-prompt-tool 0.3.0 → 0.4.0

package/preset/skill-search.mjs

@@ -0,0 +1,142 @@
+/**
+ * skill-search — on-demand skill discovery and loading, replacing
+ * `dsh-tool-skill`'s full-catalog injection.
+ *
+ * WHY: the available-skills reminder (`<available_skills>`, ~9KB with many
+ * skills) is injected into the first step by dsh-tool-skill and again after
+ * every promotion/compaction. That large injected block perturbs the
+ * trajectory (issue #6: 0/9 anchored with the catalog present vs ~81%
+ * without). We remove the catalog injection entirely and expose two small
+ * tools instead — the Claude tool-search pattern:
+ *
+ *  - `skill_search` — list skills whose name/description match a query
+ *    (summaries only, bounded; no bodies). The model discovers what exists
+ *    without a 9KB dump.
+ *  - `skill_load` — load ONE skill's full instructions by exact name and
+ *    inject them for the NEXT request via `agent.inject` (the non-waking
+ *    next-step inbox). The model (or the user) calls this only when the
+ *    skill is actually needed.
+ *
+ * Discovery reads `ctx.skills` scoped to the calling agent, exactly like
+ * dsh-tool-skill. If skills are unavailable the tools answer with a short
+ * message instead of throwing.
+ *
+ * NOTE: this plugin REPLACES the `dsh-tool-skill` row in the composition —
+ * the composition must NOT mount both, or the catalog injection returns.
+ */
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'skill-search'
+
+/** The agent, tools, and skills services must exist before these tools can register. */
+export const inject = ['agents', 'tools', 'skills']
+
+const MAX_RESULTS = 20
+
+/** Minimal JSON schema compiler for tool parameters (zero dependencies). */
+function toJsonSchema(spec) {
+  const properties = {}
+  const required = []
+  for (const [key, meta] of Object.entries(spec || {})) {
+    const prop = { type: meta.type }
+    if (meta.description) prop.description = meta.description
+    properties[key] = prop
+    if (meta.required) required.push(key)
+  }
+  return { type: 'object', properties, required, additionalProperties: false }
+}
+
+/** Register the two on-demand skill tools. */
+export function apply(ctx) {
+  /** Normalize a query into lowercase tokens for simple substring matching. */
+  const tokens = (text) => (text || '').toLowerCase().split(/[^a-z0-9_-]+/).filter(Boolean)
+
+  ctx.tools.register({
+    name: 'skill_search',
+    description: 'Search the available skills by keyword and return matching skill names with short descriptions. This session keeps NO skill catalog in the prompt — if a task looks like it matches a skill (document conversion, image processing, game reviews, markdown, PDF, spreadsheets, …), call skill_search FIRST to find it, then skill_load to activate it. Do NOT assume skill names from memory.',
+    parameters: toJsonSchema({
+      query: { type: 'string', required: true, description: 'search keywords (e.g. "pdf", "obsidian", "game review")' },
+    }),
+    output: {
+      schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string' } }, required: ['text'] },
+      render: (_a, v) => [{ type: 'text', text: v.text }],
+    },
+    async execute(args, exec) {
+      const wanted = tokens(args.query)
+      const scope = exec?.agent ?? ctx
+      try {
+        const all = await ctx.skills.list({
+          scope,
+          cwd: exec?.agent?.session?.header?.cwd,
+          signal: exec?.signal,
+        })
+        const matches = all.filter((skill) => {
+          if (wanted.length === 0) return true
+          const haystack = tokens(`${skill.name} ${skill.description ?? ''} ${skill.whenToUse ?? ''}`).join(' ')
+          return wanted.every((token) => haystack.includes(token))
+        })
+        const head = matches.slice(0, MAX_RESULTS)
+        const lines = head.map((skill) => {
+          const desc = (skill.description || '').split('\n')[0]
+          return `- ${skill.name}: ${desc}`
+        })
+        if (lines.length === 0) return { text: `No skills match "${args.query}". Use skill_search with other keywords.` }
+        const extra = matches.length > MAX_RESULTS ? `\n…(${matches.length - MAX_RESULTS} more)` : ''
+        return { text: `Matching skills (${matches.length}):\n${lines.join('\n')}${extra}\n\nLoad one with skill_load (exact name).` }
+      } catch (error) {
+        return { text: `skill_search unavailable: ${String((error && error.message) || error)}` }
+      }
+    },
+  })
+
+  ctx.tools.register({
+    name: 'skill_load',
+    description: 'Load the full instructions of ONE skill by its exact name (from skill_search results) and inject them for the next request. Call this before acting on a task that matches the skill.',
+    parameters: toJsonSchema({
+      name: { type: 'string', required: true, description: 'exact skill name (kebab-case, from skill_search)' },
+    }),
+    output: {
+      schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string' } }, required: ['text'] },
+      render: (_a, v) => [{ type: 'text', text: v.text }],
+    },
+    async execute(args, exec) {
+      try {
+        const agent = exec?.agent
+        if (agent === undefined) return { text: 'skill_load requires an agent context.' }
+        const skill = await ctx.skills.get(args.name, {
+          scope: agent,
+          cwd: agent.session.header.cwd,
+          signal: exec?.signal,
+        })
+        if (skill === undefined) {
+          return { text: `No skill named "${args.name}". Run skill_search to list available skills.` }
+        }
+        const body = extractSkillBody(skill)
+        if (body.length === 0) {
+          return { text: `Skill "${args.name}" has no loadable body.` }
+        }
+        // Queue the skill content as a non-waking next-step context message,
+        // exactly like dsh-tool-skill's invocation injection.
+        agent.inject({
+          id: `skill-load-${args.name}-${Date.now()}`,
+          role: 'user',
+          content: [{ type: 'text', text: body }],
+          source: { kind: 'skill-invocation', name: args.name, form: 'instructions' },
+        })
+        return { text: `Skill "${args.name}" loaded; its instructions will be injected for the next request.` }
+      } catch (error) {
+        return { text: `skill_load failed: ${String((error && error.message) || error)}` }
+      }
+    },
+  })
+}
+
+/** Extract the model-facing body of a loaded skill definition. */
+function extractSkillBody(skill) {
+  const content = skill?.content ?? skill?.instructions ?? skill?.body
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    return content.map((part) => (typeof part === 'string' ? part : JSON.stringify(part))).join('\n')
+  }
+  return ''
+}

package/preset/tool-bootstrap.mjs

@@ -0,0 +1,282 @@
+/**
+ * Anchored tool bootstrap — keep the FIRST model request on the Minimal
+ * preset's REAL tool schema (persistent `bash` + `str_replace_editor`), then
+ * keep the assembled catalog once the session has produced its first durable
+ * promotion signal; `usePtcMode` optionally switches the wire presentation to
+ * Code Mode (PTC). Injected-context control lives in the companion
+ * `context-gate` plugin, not here.
+ *
+ * The phase is derived from durable session events, so resume and reload
+ * preserve it. By default (`promoteOn: 'either'`) a session promotes after the
+ * first `tool/call` OR the first `assistant/message`, whichever comes first:
+ * request #1 always sees the bootstrap catalog and later requests keep the
+ * assembled catalog. The original `'tool-call'` mode is kept for compatibility,
+ * but it can trap a session in bootstrap forever when the first model reply
+ * makes no tool call — the `'either'` default removes that trap while keeping
+ * the first-request anchor intact.
+ *
+ * First-request conditions established by the reproduction work (issues #6
+ * and #11, 2026-08-15):
+ *
+ *  1. Tool schema. The API-visible first-request catalog decides whether the
+ *     session anchors on the Minimal trajectory. At the adapter-default
+ *     maxTokens (256000 on the official endpoint) the Minimal tool pair —
+ *     persistent `bash` + `str_replace_editor` — anchored 5/5 runs with zero
+ *     `let me` first-lines, while every standard-family schema (pwsh/read,
+ *     pwsh only, sandboxed bash/read) fell into standard-like behavior
+ *     (11/11). Bootstrap therefore exposes exactly the Minimal pair, not
+ *     Standard's `pwsh`/`read`.
+ *
+ *  2. Output budget. On the official endpoint the first request's `max_tokens`
+ *     also dominated the trajectory anchor at 1024 (`We need` style in 26/32
+ *     runs against 0/5 at 256000, independent of tool descriptions). The
+ *     Minimal tool schema, however, anchors at 256000 WITHOUT any cap, and the
+ *     cap's delivery depends on the profile package's `prepareCall` behavior
+ *     (it reaches the request on the 0.1.0-rc.5 source checkout; a prebuilt
+ *     rc.6-reporting profile package observed in issue #11 overwrote it with
+ *     `adapterDefaults.maxTokens`). `bootstrapMaxTokens` is therefore OPT-IN:
+ *     leave it unset to run the Minimal schema at the adapter default, or set
+ *     it to cap the first request. When set, the cap is stripped after
+ *     promotion — the next request's seed proposal carries the previous
+ *     header's maxTokens forward, so the release must be explicit.
+ *
+ *  3. Injected context is NOT this plugin's concern: the companion
+ *     `context-gate` plugin (shared/context-gate.mjs, mounted as the FIRST
+ *     row) owns the unified injection control — runtime-context suppression
+ *     on the assembly path and a claimed-baseline deny on the pre-step
+ *     waterfall, both keyed to the same epoch-aware promotion phase. Mount it
+ *     separately for context control alone; this file narrows only the tool
+ *     catalog (plus the optional output cap below).
+ *
+ * SUBAGENTS: by default subagents (delegationDepth > 0) are always promoted
+ * (assembled catalog from their first request). `includeSubagents: true`
+ * makes them follow the same bootstrap phase — their first request also sees
+ * the bootstrap pair, and their own first reply or tool call promotes them.
+ * Keep this flag in sync with the context-gate row's flag.
+ *
+ * POST-PROMOTION CATALOG (prompt-tool patch): after promotion both modes
+ * keep the assembled catalog. `usePtcMode` switches the wire presentation
+ * to Code Mode (PTC, single run_code) instead of narrowing the resident set.
+ * The controlled phase below still narrows the catalog before promotion and
+ * after compaction.
+ * COMPACTION (local addition): a compaction rewrites the whole surface, so the
+ * first post-compaction request is a "second first request". Promotion is
+ * epoch-aware (see compaction-epoch.mjs): after `compaction/end` the session
+ * falls back to the controlled phase — the bootstrap pair plus
+ * `compactionTools` (a core work set, default none) — until a NEW durable
+ * promotion signal exists past that boundary. The model is mid-task and needs
+ * to keep working, but still faces a small catalog instead of the full
+ * Standard set.
+ *
+ * Robustness:
+ *  - Promotion decisions are memoized per session id for this process; the
+ *    durable event scan runs once per session per process, then O(1).
+ *  - Subagents (delegationDepth > 0) are always promoted (assembled catalog)
+ *    unless `includeSubagents: true`.
+ *  - A missing bootstrap tool degrades to the full catalog with a one-time
+ *    warning instead of throwing, so a composition drift can never brick
+ *    every request of a session.
+ *  - Invalid config (bad tool lists, unknown `promoteOn`, malformed flags,
+ *    non-positive `bootstrapMaxTokens`) fails at apply time, i.e. at preset
+ *    mount, where it is visible and fixable.
+ */
+
+import { createEpochPromotion } from './compaction-epoch.mjs'
+import { booleanOption, createWarnOnce, parsePromoteOn, validateConfig } from './shared.mjs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'anchored-tool-bootstrap'
+
+/**
+ * Deliberately NO inject list: the listeners only touch services at event
+ * time. Keep this row right AFTER the context-gate row in agent.cordis.yml:
+ * waterfall after-next transforms apply in reverse registration order, so the
+ * tool filter here must register before any plugin that touches the same
+ * assembly. The optional budget listener registers with `prepend: true` so a
+ * later listener can never override the first-round cap after we set it.
+ */
+export const inject = []
+
+/** Every config key this plugin accepts — anything else is a typo. */
+const ALLOWED_KEYS = new Set(['bootstrapTools', 'promoteOn', 'bootstrapMaxTokens', 'compactionTools', 'includeSubagents', 'usePtcMode'])
+
+
+/**
+ * The default first-request catalog: the OFFICIAL Minimal preset's exact tool
+ * pair — the persistent `bash` shell and `str_replace_editor`. Issue #11
+ * measured this schema anchoring 5/5 at the adapter-default maxTokens while
+ * every standard-family schema failed 11/11.
+ */
+const DEFAULT_BOOTSTRAP_TOOLS = ['bash', 'str_replace_editor']
+
+/** Non-empty string list config validator. */
+function stringList(value, field) {
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== 'string' || item.length === 0)) {
+    throw new TypeError(`${name}: ${field} must be a non-empty array of non-empty strings`)
+  }
+  return [...new Set(value)]
+}
+
+function stringListOrEmpty(value, field) {
+  if (value === undefined) return []
+  return stringList(value, field)
+}
+
+
+/**
+ * Validate the optional first-request output cap. `undefined` means NO cap:
+ * the Minimal tool schema anchors at the adapter-default maxTokens, and the
+ * cap's delivery is profile-package dependent (see the header note), so it is
+ * opt-in rather than the default.
+ */
+function optionalPositiveInt(value, field) {
+  if (value === undefined) return undefined
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name}: ${field} must be a positive safe integer`)
+  }
+  return value
+}
+
+/** Register the per-session bootstrap filters. */
+export function apply(ctx, config) {
+  const source = validateConfig(name, config, ALLOWED_KEYS)
+  const bootstrapTools = stringList(source.bootstrapTools, 'bootstrapTools')
+  const promoteEvents = parsePromoteOn(name, source.promoteOn)
+  const bootstrapMaxTokens = optionalPositiveInt(source.bootstrapMaxTokens, 'bootstrapMaxTokens')
+  const includeSubagents = booleanOption(name, source.includeSubagents, 'includeSubagents', false)
+  const usePtcMode = booleanOption(name, source.usePtcMode, 'usePtcMode', true)
+  // Core work set exposed after a compaction, before re-promotion. Empty
+  // means "no compaction recovery catalog": the session stays on the
+  // bootstrap pair until a new promotion signal.
+  const compactionTools = stringListOrEmpty(source.compactionTools, 'compactionTools')
+
+  const promotion = createEpochPromotion(promoteEvents, { includeSubagents })
+
+  // prompt-tool patch: optional Code Mode (PTC) wire presentation after promotion.
+  const presentationBySession = new WeakMap()
+  const agentBySession = new WeakMap()
+  const presentationState = (session) => {
+    let state = presentationBySession.get(session)
+    if (state === undefined) {
+      state = { applied: false, disposer: undefined }
+      presentationBySession.set(session, state)
+    }
+    return state
+  }
+  const applyCodePresentation = (agent) => {
+    const session = agent?.session
+    if (session === undefined) return
+    const state = presentationState(session)
+    if (state.applied) return
+    const tools = agent.ctx?.tools
+    if (tools === undefined || typeof tools.presentAs !== 'function') return
+    state.disposer = tools.presentAs('code')
+    state.applied = true
+  }
+  const releaseCodePresentation = (session) => {
+    const state = presentationBySession.get(session)
+    if (state === undefined) return
+    if (typeof state.disposer === 'function') {
+      try { state.disposer() } catch { /* never brick the session */ }
+    }
+    state.disposer = undefined
+    state.applied = false
+  }
+  ctx.on('session/event', (session, event) => promotion.observe(session, event))
+
+  ctx.on('session/event', (session, event) => {
+    if (!usePtcMode) return
+    if (event.type === 'compaction/end') {
+      releaseCodePresentation(session)
+      return
+    }
+    if (event.type !== 'step/end' && event.type !== 'turn/end') return
+    const agent = agentBySession.get(session)
+    if (agent !== undefined && promotion.status(agent).promoted) applyCodePresentation(agent)
+  })
+
+  const warnOnce = createWarnOnce(ctx, name)
+
+  /** Narrow the assembled catalog to a keep-set; validate required names. */
+  const keepTools = (assembled, keep, missingAllowsFullCatalog) => {
+    const available = new Set(assembled.tools.map((tool) => tool.name))
+    const missing = [...keep].filter((toolName) => !available.has(toolName))
+    if (missing.length > 0) {
+      warnOnce(
+        `${name}: expected every phase tool; missing=${JSON.stringify(missing)} — `
+        + (missingAllowsFullCatalog ? 'bootstrap disabled, full catalog exposed' : 'continuing with what is available'),
+      )
+      if (missingAllowsFullCatalog) return assembled
+    }
+    return {
+      ...assembled,
+      tools: assembled.tools.filter((tool) => keep.has(tool.name)),
+    }
+  }
+
+  ctx.on('system-prompt/assemble', async (_assembly, context, next) => {
+    // Downstream errors propagate untouched; only this filter's own logic is guarded.
+    const assembled = await next()
+    try {
+      const agent = context.agent
+      if (agent === undefined) return assembled
+      // prompt-tool patch: subagents skip catalog narrowing and use assembled tools directly.
+      // Callers (such as dsh-mnemon) already filter assembled.tools through their own whitelists.
+      // New plugin tools with any prefix therefore appear in the subagent first session automatically.
+      agentBySession.set(agent.session, agent)
+      if ((agent.session?.header?.delegationDepth ?? 0) > 0) {
+        if (usePtcMode) applyCodePresentation(agent)
+        return assembled
+      }
+      const status = promotion.status(agent)
+      if (status.promoted) {
+        // prompt-tool patch: both modes keep the assembled catalog after promotion.
+        // usePtcMode switches the wire presentation instead of narrowing resident tools.
+        if (usePtcMode) applyCodePresentation(agent)
+        return assembled
+      }
+      // Controlled phase: the bootstrap pair; after a compaction, plus the
+      // compaction work set so mid-task work can continue. Context control is
+      // NOT here: the companion `context-gate` plugin owns it (see the header
+      // note), so this filter touches only the tool catalog.
+      const { boundary } = status
+      const keep = new Set(bootstrapTools)
+      if (boundary >= 0) for (const toolName of compactionTools) keep.add(toolName)
+      return keepTools(assembled, keep, true)
+    } catch (error) {
+      // A filter bug must never brick a session: degrade to the full catalog.
+      warnOnce(`${name}: bootstrap filter failed, exposing the full catalog: ${String((error && error.message) || error)}`)
+      return assembled
+    }
+  })
+
+  // Optionally cap the first model request's output budget while bootstrapping.
+  // Unset (`bootstrapMaxTokens` omitted) means the adapter default flows — the
+  // Minimal tool schema anchors at 256000 without a cap (issue #11).
+  if (bootstrapMaxTokens !== undefined) {
+    // Same registration discipline as the pre-step strip below: `prepend`
+    // keeps this listener the OUTERMOST transform of the agent/request
+    // waterfall for the same registration-order reasons (loader row
+    // application is concurrent; row order alone does not decide listener
+    // order — see issue #6 and upstream PR #13), so a later listener can
+    // never override the first-round budget after we set it.
+    ctx.on('agent/request', async (payload, next) => {
+      const resolved = await next()
+      const agent = payload.agent
+      if (promotion.status(agent).promoted) {
+        // The next request's seed proposal carries the previous header's
+        // maxTokens forward, so the injected cap must be stripped explicitly —
+        // otherwise it would persist for the whole session.
+        if (resolved.maxTokens === bootstrapMaxTokens) {
+          const { maxTokens: _bootstrap, ...rest } = resolved
+          return rest
+        }
+        return resolved
+      }
+      return {
+        ...resolved,
+        maxTokens: bootstrapMaxTokens,
+      }
+    }, { prepend: true })
+  }
+}

package/upstream/dsh-anchored-standard/REVISION

@@ -1 +1 @@
-ba7a27cf92f80ef3a73a16a05b9df46a20ebbb2a
+25f21aefaf8ddc414da54d2e581e43740d977c6e

package/upstream/dsh-anchored-standard/preset/agent.cordis.yml

@@ -149,12 +149,19 @@
   name: '@deepseek-ai/dsh-tool-pwsh'
   disabled: !!js process.platform !== 'win32'
 
-# The Minimal preset's shell: a PTY-backed persistent bash, byte-identical in
-# configuration to the official `minimal` preset's `persistent-shell` group so
-# the first request exposes exactly Minimal's real `bash` schema. The PTY
-# registry is an agent-owned service, so it lives in an entry-local realm; the
-# backend still consumes the host sandbox policy and subprocess implementation,
-# while the tool registers into this agent's scoped catalog.
+# The Minimal preset's shell: a PTY-backed persistent bash, schema-identical
+# to the official `minimal` preset's `persistent-shell` group so the first
+# request exposes exactly Minimal's real `bash` schema. ONE deliberate config
+# difference: an adaptive `shellPath` — the terminal-bash plugin default
+# `/bin/bash` where that absolute path exists (every host that ships it keeps
+# the previous behavior), otherwise a bare `bash` resolved through the same
+# scrubbed PATH the other harness tools use. The fallback exists because
+# `/bin/bash` does not exist on NixOS and other hosts that keep bash
+# elsewhere; there `execvp("/bin/bash")` exits during PTY startup ("PTY shell
+# exited during startup") and every bash call fails. The PTY registry is an
+# agent-owned service, so it lives in an entry-local realm; the backend still
+# consumes the host sandbox policy and subprocess implementation, while the
+# tool registers into this agent's scoped catalog.
 #
 # DISABLED ON WINDOWS: DSH's PTY backend is linux/darwin-only, so the
 # persistent shell cannot serve win32. The `custom-bash` row below registers
@@ -172,6 +179,7 @@
     - id: terminal-bash
       name: '@deepseek-ai/dsh-terminal-bash'
       config:
+        shellPath: !!js "process.getBuiltinModule?.('node:fs')?.existsSync('/bin/bash') ? '/bin/bash' : 'bash'"
         timeoutMs: 300000
 
     - id: persistent-bash
@@ -191,15 +199,18 @@
 # Windows-only `bash` tool (see custom-bash.mjs): registers the SAME
 # tool name as the persistent shell with a Minimal-compatible description, but
 # executes through the ordinary cross-platform subprocess seam (`bash -c`)
-# instead of a PTY. `bashPath` defaults to `bash` on PATH; point it at Git
-# Bash explicitly when the WSL shim would otherwise be picked up. No OS
+# instead of a PTY. The shell is resolved WITHOUT a hardcoded install path
+# (issue #24): `bashPath` unset probes the `git` executable's install root,
+# then the well-known Git-for-Windows roots (Program Files(/x86), per-user
+# LOCALAPPDATA, scoop's `current` junction), then plain `bash` on PATH — set
+# `bashPath` explicitly only to pin a shell that probing cannot find. No OS
 # sandbox confinement on Windows (landlock is linux-only); the tool
-# description says so.
+# description says so. When no bash exists at all the tool errors with
+# guidance instead of switching shells — pwsh stays its own tool in the
+# promoted catalog.
 - id: custom-bash
   name: ./custom-bash.mjs
   disabled: !!js process.platform !== 'win32'
-  config:
-    bashPath: 'C:\Program Files\Git\bin\bash.exe'
 
 # ── filesystem ──────────────────────────────────────────────────────────────
 

package/upstream/dsh-anchored-standard/preset/custom-bash.mjs

@@ -13,9 +13,27 @@
  * the ordinary (cross-platform) subprocess seam keeps the schema anchor
  * without the PTY dependency.
  *
- * Executable resolution (config `bashPath`):
- *  - explicit absolute path (e.g. `C:\Program Files\Git\bin\bash.exe`), or
- *  - `bash` resolved through `ctx.subprocess.resolveExecutable` (PATH lookup).
+ * Executable resolution (config `bashPath`, issue #24 — no hardcoded install
+ * path): an explicit non-empty `bashPath` wins unconditionally. Unset, the
+ * Git Bash executable is INFERRED, in probe order:
+ *  1. the `git` executable on PATH — its install root carries `bin\bash.exe`
+ *     one level up from `cmd\`, beside `bin\`, or two levels up from
+ *     `mingw64\bin\` (the standard installer, choco, and winget all resolve
+ *     here; a scoop SHIM does not — its directory is the shims root, not the
+ *     app — which is what step 2 covers);
+ *  2. the well-known Git-for-Windows roots derived from environment variables
+ *     (`ProgramFiles`, `ProgramFiles(x86)`, per-user `LOCALAPPDATA\Programs
+ *     \Git`, scoop's `~\scoop\apps\git\current` junction);
+ *  3. plain `bash` through `ctx.subprocess.resolveExecutable` (PATH lookup —
+ *     last resort, since on Windows that may pick the WSL shim; WSL bash is
+ *     still true bash, only the filesystem paths shift to /mnt/…).
+ *
+ * If NOTHING resolves, the tool fails with an actionable error naming the
+ * remedies — it does NOT silently execute under a different shell: the
+ * schema above promises `bash -c` semantics, and pwsh/cmd are different
+ * command languages. PowerShell stays available as its OWN tool (`pwsh`,
+ * present in the promoted catalog on Windows, unlockable via
+ * dev_tool_search).
  *
  * Semantics mirror the official bash tool: `bash -c <command>` in a fresh
  * process, bounded output, non-zero exit reported not thrown. No sandbox
@@ -24,6 +42,9 @@
  * `str_replace_editor` (Minimal's two tools).
  */
 
+import { access } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'custom-bash'
 
@@ -33,6 +54,34 @@ export const inject = ['subprocess', 'tools']
 const DEFAULT_TIMEOUT_MS = 120000
 const DEFAULT_MAX_OUTPUT_BYTES = 64000
 
+/**
+ * Git Bash candidate paths, in probe order (see the header): the `git`
+ * executable's install root first, then the well-known env-derived roots.
+ * Exported for tests; pure — existence probing happens at the call site.
+ */
+export function bashCandidates(env, gitExe) {
+  const candidates = []
+  // git at <root>\cmd\git.exe (installer/scoop) or <root>\bin\git.exe →
+  // <root>\bin\bash.exe; <root>\mingw64\bin\git.exe (portable) → two up.
+  // A bare relative name means `git` did not actually resolve to a path.
+  if (typeof gitExe === 'string' && /[/\\]/.test(gitExe)) {
+    const dir = dirname(gitExe)
+    const root = dirname(dir)
+    candidates.push(
+      join(root, 'bin', 'bash.exe'),
+      join(dir, 'bash.exe'),
+      join(dirname(root), 'bin', 'bash.exe'),
+    )
+  }
+  if (env.ProgramFiles) candidates.push(join(env.ProgramFiles, 'Git', 'bin', 'bash.exe'))
+  if (env['ProgramFiles(x86)']) candidates.push(join(env['ProgramFiles(x86)'], 'Git', 'bin', 'bash.exe'))
+  if (env.LOCALAPPDATA) candidates.push(join(env.LOCALAPPDATA, 'Programs', 'Git', 'bin', 'bash.exe'))
+  if (env.USERPROFILE) candidates.push(join(env.USERPROFILE, 'scoop', 'apps', 'git', 'current', 'bin', 'bash.exe'))
+  // Layouts overlap (a `bin` git.exe derives the same bash twice) — probe
+  // order survives the dedupe, insertion order is preserved.
+  return [...new Set(candidates)]
+}
+
 /** Tool parameter schema for the model-facing command. */
 const commandSchema = {
   type: 'object',
@@ -52,10 +101,54 @@ const commandSchema = {
 
 /** Register the model-facing `bash` tool. */
 export function apply(ctx, config) {
-  const bashPath = typeof config?.bashPath === 'string' && config.bashPath.length > 0 ? config.bashPath : 'bash'
+  const explicitBashPath = typeof config?.bashPath === 'string' && config.bashPath.length > 0 ? config.bashPath : undefined
   const timeoutMs = Number.isSafeInteger(config?.timeoutMs) && config.timeoutMs > 0 ? config.timeoutMs : DEFAULT_TIMEOUT_MS
   const maxOutputBytes = Number.isSafeInteger(config?.maxOutputBytes) && config.maxOutputBytes > 0 ? config.maxOutputBytes : DEFAULT_MAX_OUTPUT_BYTES
 
+  // The inferred executable is memoized per plugin instance: candidate probing
+  // walks the filesystem, and the answer cannot change within a mount. A
+  // failed inference is NOT memoized — the plain `bash` fallback resolves
+  // fresh on every execute until some probe succeeds.
+  let inferredShell
+  const exists = (path) => access(path).then(() => true, () => false)
+  const resolveShell = async (signal) => {
+    if (explicitBashPath !== undefined) {
+      // A misconfigured explicit path must fail as itself, not as a
+      // discovery miss — the raw resolution error says which path failed.
+      return ctx.subprocess.resolveExecutable(explicitBashPath, undefined, signal)
+    }
+    if (inferredShell !== undefined) {
+      return ctx.subprocess.resolveExecutable(inferredShell, undefined, signal)
+    }
+    let gitExe
+    try {
+      gitExe = await ctx.subprocess.resolveExecutable('git', undefined, signal)
+    } catch {
+      // git unresolvable → the env-derived candidates below still apply
+    }
+    for (const candidate of bashCandidates(process.env, gitExe)) {
+      if (!(await exists(candidate))) continue
+      try {
+        inferredShell = await ctx.subprocess.resolveExecutable(candidate, undefined, signal)
+        return inferredShell
+      } catch {
+        // Exists but unresolvable (EPERM, a broken scoop junction): keep
+        // probing — one bad root must not block the rest of the chain, and
+        // nothing is memoized so later executes can still find a good one.
+        continue
+      }
+    }
+    try {
+      return await ctx.subprocess.resolveExecutable('bash', undefined, signal)
+    } catch (error) {
+      // Total discovery failure (no Git Bash root, no env root, no bash on
+      // PATH): name the remedies instead of leaking a raw ENOENT. Never
+      // fall back to pwsh/cmd here — the schema promises `bash -c`
+      // semantics; a different shell would silently break every command.
+      throw new Error(`bash executable not found — install Git for Windows, expose a bash on PATH, or set the custom-bash \`bashPath\` config (${String((error && error.message) || error)})`)
+    }
+  }
+
   ctx.tools.register({
     name: 'bash',
     description: [
@@ -81,7 +174,7 @@ export function apply(ctx, config) {
       render: (_args, value) => [{ type: 'text', text: value.text }],
     },
     async execute(args, exec) {
-      const shell = await ctx.subprocess.resolveExecutable(bashPath, undefined, exec?.signal)
+      const shell = await resolveShell(exec?.signal)
       const workdir = typeof args.workdir === 'string' && args.workdir.length > 0
         ? args.workdir
         : exec?.agent?.session?.header?.cwd