dsh-plugin-prompt-tool 0.1.0

package/vendor/dsh-anchored-standard/preset/compaction-epoch.mjs

@@ -0,0 +1,74 @@
+/**
+ * Epoch-aware promotion tracker shared by the bootstrap and baseline-gate
+ * plugins of the anchored presets.
+ *
+ * A compaction rewrites the model-visible surface: the pre-compaction
+ * conversation collapses into one synthetic summary message, and the
+ * workspace-instruction baseline is re-injected from scratch. The first
+ * post-compaction request is therefore a "second first request" — the same
+ * first-token conditions the anchored presets exist to control. Promotion is
+ * epoch-aware: only a durable promotion signal (`tool/call` and/or
+ * `assistant/message`, per the caller's `promoteEvents`) recorded AFTER the
+ * last `compaction/end` boundary counts as promoted. Before any compaction
+ * the boundary is -1, which preserves the original one-shot semantics.
+ *
+ * State is memoized per session id and maintained incrementally through
+ * `observe()`; a cold session scans its durable log once (so resume and
+ * reload reconstruct the same phase), then O(1).
+ */
+
+/** Build one epoch-aware promotion tracker. */
+export function createEpochPromotion(promoteEvents) {
+  const promote = new Set(promoteEvents)
+  /** sessionId -> { boundary, promoted } */
+  const state = new Map()
+
+  /** Scan a session's durable log from scratch (cold start / resume). */
+  const scan = (session) => {
+    let boundary = -1
+    let promoted = false
+    for (const event of session.events) {
+      const seq = event.seq ?? 0 // events without a seq are treated as post-boundary
+      if (event.type === 'compaction/end') {
+        boundary = seq
+        promoted = false
+        continue
+      }
+      if (promote.has(event.type) && seq > boundary) promoted = true
+    }
+    const entry = { boundary, promoted }
+    state.set(session.id, entry)
+    return entry
+  }
+
+  return {
+    /**
+     * Current phase of the agent's session.
+     * @param agent - the assembly/pre-step agent, or undefined outside an agent.
+     * @returns { boundary, promoted } — `boundary` is the last compaction/end
+     *   seq (-1 before any compaction); `promoted` is true when a durable
+     *   promotion signal exists after that boundary.
+     */
+    status(agent) {
+      if (agent === undefined) return { boundary: -1, promoted: true }
+      const session = agent.session
+      if (session === undefined) return { boundary: -1, promoted: true }
+      // Subagents keep the full catalog from their very first request.
+      if ((session.header?.delegationDepth ?? 0) > 0) return { boundary: -1, promoted: true }
+      return state.get(session.id) ?? scan(session)
+    },
+    /** Incremental feed: call on every `session/event`. */
+    observe(session, event) {
+      const entry = state.get(session.id)
+      if (entry === undefined) return
+      const seq = event.seq ?? 0
+      if (event.type === 'compaction/end') {
+        state.set(session.id, { boundary: seq, promoted: false })
+        return
+      }
+      if (promote.has(event.type) && seq > entry.boundary && !entry.promoted) {
+        state.set(session.id, { ...entry, promoted: true })
+      }
+    },
+  }
+}

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

@@ -0,0 +1,126 @@
+/**
+ * custom-bash — a Windows-capable `bash` tool that registers under the SAME
+ * name (`bash`) as the official persistent bash, with a Minimal-compatible
+ * description, but executes through `ctx.subprocess.spawn` instead of a PTY.
+ *
+ * WHY: DeepSeek's first-request trajectory anchor keys on the tool SCHEMA
+ * matching the RL training distribution (issue #11: persistent
+ * bash + str_replace_editor anchored 5/5 at maxTokens=256000, pwsh/read
+ * 8/8 standard-like). The official persistent bash uses a PTY, and DSH's PTY
+ * backend is linux/darwin-only — `subprocess-local` throws "terminal
+ * inspection is unsupported on platform win32". A custom tool that presents
+ * the same name and a Minimal-like description but spawns Git Bash through
+ * 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).
+ *
+ * Semantics mirror the official bash tool: `bash -c <command>` in a fresh
+ * process, bounded output, non-zero exit reported not thrown. No sandbox
+ * confinement on Windows (the sandbox backend is linux-only); the tool
+ * description says so. The bootstrap catalog pairs this with
+ * `str_replace_editor` (Minimal's two tools).
+ */
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'custom-bash'
+
+/** The subprocess and tools services must exist before this tool can register. */
+export const inject = ['subprocess', 'tools']
+
+const DEFAULT_TIMEOUT_MS = 120000
+const DEFAULT_MAX_OUTPUT_BYTES = 64000
+
+/** Tool parameter schema for the model-facing command. */
+const commandSchema = {
+  type: 'object',
+  properties: {
+    command: {
+      type: 'string',
+      description: 'The bash command to execute (`bash -c` string domain).',
+    },
+    workdir: {
+      type: 'string',
+      description: 'Optional working directory; defaults to the session cwd.',
+    },
+  },
+  required: ['command'],
+  additionalProperties: false,
+}
+
+/** 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 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
+
+  ctx.tools.register({
+    name: 'bash',
+    description: [
+      'Run commands in a bash shell (Git Bash on Windows)',
+      '* When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.',
+      "* You don't have access to the internet via this tool.",
+      '* You do have access to a mirror of common linux and python packages via apt and pip.',
+      '* State does NOT persist across command calls: each call runs in a fresh shell.',
+      "* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.",
+      '* Please avoid commands that may produce a very large amount of output.',
+      '* NOTE: runs without OS sandbox confinement on Windows (no landlock); treat output as untrusted.',
+    ].join('\n'),
+    parameters: commandSchema,
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          text: { type: 'string' },
+        },
+        required: ['text'],
+      },
+      render: (_args, value) => [{ type: 'text', text: value.text }],
+    },
+    async execute(args, exec) {
+      const shell = await ctx.subprocess.resolveExecutable(bashPath, undefined, exec?.signal)
+      const workdir = typeof args.workdir === 'string' && args.workdir.length > 0
+        ? args.workdir
+        : exec?.agent?.session?.header?.cwd
+      const signal = exec?.signal
+      const handle = ctx.subprocess.spawn({
+        argv: [shell, '-c', args.command],
+        ...workdir !== undefined ? { cwd: workdir } : {},
+        stdio: {
+          stdin: 'ignore',
+          stdout: { maxBytes: maxOutputBytes },
+          stderr: { maxBytes: maxOutputBytes },
+        },
+        ...signal !== undefined ? { signal } : {},
+        graceMs: 3000,
+      })
+      let outcome
+      try {
+        outcome = await handle.done
+      } catch (error) {
+        // A spawn-level failure (bad executable, EPERM) surfaces as a throw,
+        // which the runtime turns into an isError result.
+        throw new Error(`bash spawn failed: ${String(error)}`)
+      }
+      let stdout = ''
+      let stderr = ''
+      try {
+        stdout = handle.collected.stdout.readFrom(0).text
+        stderr = handle.collected.stderr.readFrom(0).text
+      } catch {
+        // Collected readers may be unavailable on some backends; tolerate.
+      }
+      const text = [stdout, stderr].filter((part) => part.length > 0).join('\n')
+      const tail = text.length > 0 ? text : `exit code: ${outcome.exitCode} (no output)`
+      if (outcome.exitCode !== 0) {
+        // Non-zero exit is a reported failure, not a throw: the model sees the
+        // command output plus the exit code.
+        throw new Error(tail)
+      }
+      return { text: tail }
+    },
+  })
+}

package/vendor/dsh-anchored-standard/preset/dev-tool-search.mjs

@@ -0,0 +1,129 @@
+/**
+ * dev-tool-search — on-demand tool discovery and unlock, the tool-search
+ * pattern for the anchored preset.
+ *
+ * The promoted phase keeps only a minimal resident set (shell +
+ * str_replace_editor + the discovery tools) instead of dumping the whole
+ * Standard catalog at once. This plugin registers ONE small tool:
+ *
+ *  - `dev_tool_search` — search the FULL assembled catalog by keyword and
+ *    return matching tool names with short descriptions; optionally unlock
+ *    tools by exact name (array `toolNames`). Unlocked names are recorded as
+ *    durable `tool/call` arguments, and tool-bootstrap.mjs's assemble filter
+ *    exposes them from the next request on (resume-safe).
+ *
+ * The tool description is deliberately an INDEX of what the minimal resident
+ * set cannot do: the model should reach for dev_tool_search the moment a task
+ * needs internet, delegation, workflows, goals, images, background jobs, or
+ * multi-agent coordination — not try to work around them with bash.
+ */
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'dev-tool-search'
+
+/** The tools registry must exist before this tool can register. */
+export const inject = ['tools']
+
+const MAX_RESULTS = 25
+
+/** 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 }
+}
+
+/**
+ * The capability index: resident minimal tools (bash / str_replace_editor /
+ * skill_search / skill_load) cannot cover these, so the model must search
+ * and unlock them on demand. Kept in the description so the model KNOWS what
+ * exists without a full catalog dump.
+ */
+const UNLOCKABLE_INDEX = [
+  'web_search — internet search and web retrieval',
+  'subagent / subagent_fork — delegate work to sub-agents',
+  'workflow — run multi-agent workflow scripts',
+  'ralph — fresh-agent iterative loop',
+  'create_goal / get_goal / update_goal — long-running goals',
+  'read_image — read image files',
+  'job_list / job_output / job_kill — background jobs',
+  'interrupt_agent / send_message / list_agents — multi-agent control',
+  'todo_write — task tracking',
+  'ask_user_question — ask the user',
+]
+
+/** Register the model-facing `dev_tool_search` tool. */
+export function apply(ctx) {
+  ctx.tools.register({
+    name: 'dev_tool_search',
+    description: [
+      'Discover and unlock tools that are NOT currently available.',
+      '',
+      'This session starts with a minimal resident set: bash, str_replace_editor, skill_search, skill_load. Everything else is unlocked on demand through this tool.',
+      '',
+      'If the current task needs any of the following, call dev_tool_search FIRST — do not try to work around them with bash:',
+      ...UNLOCKABLE_INDEX.map((line) => `- ${line}`),
+      '',
+      'Usage: pass `query` to search the catalog (returns matching tool names + descriptions), then pass `toolNames` with exact names to unlock them. Unlocked tools appear from the next request on and stay unlocked for the session.',
+    ].join('\n'),
+    parameters: toJsonSchema({
+      query: { type: 'string', required: false, description: 'search keywords (e.g. "web", "subagent")' },
+      toolNames: { type: 'array', required: false, description: 'exact tool names to unlock', items: { type: 'string' } },
+    }),
+    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 query = typeof args.query === 'string' ? args.query.trim() : ''
+      const unlock = Array.isArray(args.toolNames) ? args.toolNames.filter((name) => typeof name === 'string' && name.length > 0) : []
+
+      const lines = []
+      if (unlock.length > 0) {
+        lines.push(`Unlocked for the next request: ${unlock.join(', ')}`)
+      }
+      if (query.length === 0 && unlock.length === 0) {
+        lines.push('Provide `query` to search the catalog, or `toolNames` to unlock tools.')
+        return { text: lines.join('\n') }
+      }
+      if (query.length === 0) {
+        return { text: lines.join('\n') || 'Nothing to do.' }
+      }
+
+      try {
+        // The executing agent IS the viewing scope: preset tools register into
+        // the agent-scope layer of the tools registry, and schemas() with no
+        // scope only sees the global layer — every preset-provided tool would
+        // be invisible to keyword search (issue #24). Same pattern as the
+        // harness's own code mode (`registry.schemas(exec.agent)`).
+        const schemas = ctx.tools.schemas(exec?.agent)
+        const wanted = query.toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean)
+        const matches = schemas
+          .filter((schema) => {
+            const haystack = `${schema.name} ${schema.description ?? ''}`.toLowerCase()
+            return wanted.every((token) => haystack.includes(token))
+          })
+          .slice(0, MAX_RESULTS)
+        if (matches.length === 0) {
+          lines.push(`No tools match "${query}".`)
+        } else {
+          lines.push(`Matching tools (${matches.length}):`)
+          for (const schema of matches) {
+            const desc = (schema.description || '').split('\n')[0].slice(0, 90)
+            lines.push(`- ${schema.name}: ${desc}`)
+          }
+          lines.push('Unlock with dev_tool_search({"toolNames": ["<exact name>"]}).')
+        }
+      } catch (error) {
+        lines.push(`catalog search unavailable: ${String((error && error.message) || error)}`)
+      }
+      return { text: lines.join('\n') }
+    },
+  })
+}

package/vendor/dsh-anchored-standard/preset/instruction-hint.mjs

@@ -0,0 +1,178 @@
+/**
+ * instruction-hint — replace `dsh-agent-instructions`' full AGENTS.md/CLAUDE.md
+ * injection with a minimal "these files exist" hint.
+ *
+ * WHY: the full workspace-instruction digest is a large injected block. After
+ * the anchored bootstrap promotes, we want the model to KNOW the instruction
+ * files exist (so it reads them before acting) without dumping their content
+ * into every request. The model reads the files itself via the filesystem
+ * tools when it needs them.
+ *
+ * Behavior:
+ *  - After the session records its first durable promotion signal
+ *    (`promoteOn`, default `either`), ONE hint message is injected (once per
+ *    session — durable event scan, resume-safe), listing which instruction
+ *    files were found:
+ *      - user-global: `$DSH_HOME/AGENTS.md`
+ *      - project chain: AGENTS.md / CLAUDE.md / AGENTS.local.md / CLAUDE.local.md
+ *        walking up from the session cwd to the project root (a directory
+ *        containing `.git`, or the cwd itself).
+ *  - The hint instructs the model to READ the files before acting when
+ *    relevant, without embedding their content.
+ *  - Files are probed via `ctx.fs` (the host filesystem seam); a missing fs
+ *    service or an unreadable probe degrades to no hint (never throws).
+ *  - Pre-promotion requests get NO hint (matches the anchored bootstrap).
+ *
+ * ROW ORDER: this plugin registers its `agent/pre-step` handler with
+ * `prepend: true` and after `tool-bootstrap`, so it runs inside the
+ * bootstrap's outermost strip — but it emits AFTER promotion, when the strip
+ * is inactive. The hint source kind is `instruction-hint`, which is NOT in
+ * `suppressedContextSources`, so it is never stripped.
+ */
+
+import { createEpochPromotion } from './compaction-epoch.mjs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'instruction-hint'
+
+/** Durable session event types that count as a promotion signal per mode. */
+const PROMOTE_EVENTS = {
+  'tool-call': ['tool/call'],
+  'assistant-message': ['assistant/message'],
+  either: ['tool/call', 'assistant/message'],
+}
+
+/** Candidate file names, in probe order, for the project chain and user-global. */
+const PROJECT_CANDIDATES = ['AGENTS.md', 'CLAUDE.md', 'AGENTS.local.md', 'CLAUDE.local.md']
+const USER_GLOBAL_CANDIDATE = 'AGENTS.md'
+
+function parsePromoteOn(value) {
+  if (value === undefined || value === 'either') return PROMOTE_EVENTS.either
+  if (value === 'tool-call' || value === 'assistant-message') return PROMOTE_EVENTS[value]
+  throw new TypeError(`${name}: promoteOn must be one of "tool-call", "assistant-message", "either"; got ${JSON.stringify(value)}`)
+}
+
+/** Find the project root: first ancestor containing any root marker (e.g. .git). */
+async function findProjectRoot(fs, cwd, signal) {
+  let current = cwd
+  for (;;) {
+    for (const marker of ['.git', '.hg', '.svn']) {
+      try {
+        const target = await fs.resolve(joinPath(current, marker), { cwd, signal })
+        const info = await fs.stat(target, signal)
+        if (info !== undefined) return current
+      } catch {
+        // Probe failure = marker absent; continue.
+      }
+    }
+    const parent = parentPath(current)
+    if (parent === current || parent.length === 0) return cwd
+    current = parent
+  }
+}
+
+/** List instruction files present in one directory (project candidates). */
+async function presentInDir(fs, dir, candidates, signal) {
+  const found = []
+  for (const candidate of candidates) {
+    try {
+      const target = await fs.resolve(joinPath(dir, candidate), { cwd: dir, signal })
+      const info = await fs.stat(target, signal)
+      if (info !== undefined && info.type === 'file') found.push(candidate)
+    } catch {
+      // Absent or unreadable — skip.
+    }
+  }
+  return found
+}
+
+/** Join one path segment onto a directory (platform-agnostic string join). */
+function joinPath(dir, segment) {
+  if (dir.endsWith('/') || dir.endsWith('\\')) return dir + segment
+  const sep = dir.includes('\\') ? '\\' : '/'
+  return dir + sep + segment
+}
+
+/** Parent of an absolute Windows or POSIX path. */
+function parentPath(path) {
+  const idx = Math.max(path.lastIndexOf('/'), path.lastIndexOf('\\'))
+  if (idx <= 0) return path
+  const parent = path.slice(0, idx)
+  return parent.length === 0 ? path : parent
+}
+
+/** Register the post-promotion instruction-hint injector. */
+export function apply(ctx, config) {
+  const promoteEvents = parsePromoteOn(config.promoteOn)
+  const promotion = createEpochPromotion(promoteEvents)
+  ctx.on('session/event', (session, event) => promotion.observe(session, event))
+
+  /** Sessions that already received the hint. */
+  const hinted = new Set()
+  let warned = false
+  const warnOnce = (message) => {
+    if (warned) return
+    warned = true
+    try {
+      ctx.logger.warn(message)
+    } catch {
+      // Logger unavailable — the guard exists only to avoid spamming.
+    }
+  }
+
+  ctx.on('agent/pre-step', async ({ agent, signal }, next) => {
+    const decision = await next()
+    try {
+      if (promotion.status(agent).promoted !== true) return decision
+      const session = agent.session
+      if (session === undefined || hinted.has(session.id)) return decision
+      hinted.add(session.id)
+
+      const fs = ctx.get('fs')
+      if (fs === undefined) return decision
+      const cwd = session.header.cwd ?? process.cwd()
+
+      const projectFiles = []
+      const root = await findProjectRoot(fs, cwd, signal)
+      projectFiles.push(...await presentInDir(fs, root, PROJECT_CANDIDATES, signal))
+
+      const userGlobalFiles = []
+      try {
+        const dshHome = process.env.DSH_HOME ?? (process.env.USERPROFILE ? `${process.env.USERPROFILE}\\.dsh` : undefined)
+        if (dshHome !== undefined) {
+          userGlobalFiles.push(...await presentInDir(fs, dshHome, [USER_GLOBAL_CANDIDATE], signal))
+        }
+      } catch {
+        // Unreadable home probe — ignore.
+      }
+
+      const sections = []
+      if (projectFiles.length > 0) {
+        sections.push(`Workspace instruction files exist: ${projectFiles.join(', ')} (project root: ${root}).`)
+      }
+      if (userGlobalFiles.length > 0) {
+        sections.push(`A user-global instruction file exists: ${USER_GLOBAL_CANDIDATE}.`)
+      }
+      if (sections.length === 0) return decision
+
+      const text = [
+        ...sections,
+        'Do NOT assume their content. When a task touches this workspace, read the relevant instruction files first and follow them.',
+      ].join(' ')
+
+      return {
+        ...decision,
+        messages: [...decision.messages, {
+          id: `instruction-hint-${session.id}`,
+          role: 'user',
+          content: [{ type: 'text', text }],
+          source: { kind: 'instruction-hint', form: 'hint' },
+        }],
+      }
+    } catch (error) {
+      // A hint bug must never hurt the session: skip the hint.
+      warnOnce(`${name}: hint injection failed, skipping: ${String((error && error.message) || error)}`)
+      return decision
+    }
+  }, { prepend: true })
+}

package/vendor/dsh-anchored-standard/preset/preset.yml

@@ -0,0 +1,3 @@
+name: Anchored Standard (experimental)
+description: Bootstrap with the Minimal preset's real tool pair (persistent bash + str_replace_editor) and no auto-injected workspace or skill context, then expose the full Standard catalog after the first durable tool call or reply.
+order: 5

package/vendor/dsh-anchored-standard/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 ''
+}