dsh-plugin-prompt-tool 0.4.2 → 0.6.0

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

@@ -1,231 +0,0 @@
-/**
- * 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, 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 is ONCE PER SESSION, DERIVED FROM DURABLE EVENTS: the guard
- *    scans the session log for an existing `instruction-hint` message (then
- *    O(1)), so a process restart — whose in-memory state starts empty —
- *    cannot inject a second copy. A duplicate would collide with the first
- *    message's deterministic id (`instruction-hint-<sessionId>`) and break
- *    history replay.
- *  - 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).
- *  - Subagents skip the phase wait by default (their first request already
- *    counts as promoted); `includeSubagents: true` makes a subagent's own
- *    first reply or tool call open the hint — which also keeps the injection
- *    out of the context gate's stripped first request (the gate strips
- *    non-claimed messages while unpromoted).
- *
- * ROW ORDER: this plugin registers its `agent/pre-step` handler with
- * `prepend: true` and after `context-gate`/`tool-bootstrap`, so it runs
- * inside the gate's outermost strip — but it emits AFTER promotion, when the
- * strip is inactive. The hint source kind is `instruction-hint`, which is
- * not in the gate's claimed-baseline allowlist, so the gate can strip it
- * only while the session is unpromoted (never the intended path).
- */
-
-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)}`)
-}
-
-/** Every config key this plugin accepts — anything else is a typo. */
-const ALLOWED_KEYS = new Set(['promoteOn', 'includeSubagents'])
-
-/** Validate an optional boolean flag with a default. */
-function booleanOption(value, field, fallback) {
-  if (value === undefined) return fallback
-  if (typeof value !== 'boolean') {
-    throw new TypeError(`${name}: ${field} must be a boolean`)
-  }
-  return 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 source = config === undefined ? {} : config
-  if (typeof source !== 'object' || source === null || Array.isArray(source)) {
-    throw new TypeError(`${name}: config must be an object`)
-  }
-  const unknown = Object.keys(source).filter((key) => !ALLOWED_KEYS.has(key))
-  if (unknown.length > 0) {
-    throw new TypeError(
-      `${name}: unknown config key(s) ${unknown.join(', ')} — allowed keys: ${[...ALLOWED_KEYS].sort().join(', ')}`,
-    )
-  }
-  const promoteEvents = parsePromoteOn(source.promoteOn)
-  const includeSubagents = booleanOption(source.includeSubagents, 'includeSubagents', false)
-  const promotion = createEpochPromotion(promoteEvents, { includeSubagents })
-  ctx.on('session/event', (session, event) => promotion.observe(session, event))
-
-  /**
-   * Sessions whose hint is already durable in the event log — the
-   * restart-safe replacement for an in-memory "already hinted" set. Seeded by
-   * a one-time scan, then maintained incrementally through `session/event`.
-   */
-  const hinted = new Map()
-  const hintIsDurable = (session) => {
-    const known = hinted.get(session.id)
-    if (known !== undefined) return known
-    const found = (Array.isArray(session.events) ? session.events : []).some((event) =>
-      event.type === 'user/message' && event.data?.source?.kind === 'instruction-hint',
-    )
-    hinted.set(session.id, found)
-    return found
-  }
-  ctx.on('session/event', (session, event) => {
-    if (event.type === 'user/message' && event.data?.source?.kind === 'instruction-hint') {
-      hinted.set(session.id, true)
-    }
-  })
-
-  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 || hintIsDurable(session)) return decision
-      hinted.set(session.id, true)
-
-      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/upstream/dsh-anchored-standard/preset/preset.yml

@@ -1,3 +0,0 @@
-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/upstream/dsh-anchored-standard/preset/skill-search.mjs

@@ -1,142 +0,0 @@
-/**
- * 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/upstream/dsh-anchored-standard/preset/tool-bootstrap.mjs

@@ -1,301 +0,0 @@
-/**
- * Anchored tool bootstrap — keep the FIRST model request on the Minimal
- * preset's REAL tool schema (persistent `bash` + `str_replace_editor`), then
- * narrow the catalog to a minimal RESIDENT set once the session has produced
- * its first durable promotion signal. 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 request #2 always sees the
- * resident 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
- * (resident 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 RESIDENT SET (local addition, user-measured): the promoted
- * phase does NOT dump the whole Standard catalog at once — that dump pulls
- * the trajectory back to standard-like behavior (the root cause of the
- * post-promotion regression measured on the zero variant). Instead the
- * catalog narrows to the bootstrap tool pair PLUS the three discovery tools
- * (`dev_tool_search`, `skill_search`, `skill_load`) plus whatever the model
- * explicitly unlocked via `dev_tool_search`. Heavier Standard tools
- * (web_search, subagent, workflow, …) are one `dev_tool_search` call away;
- * unlocked names are derived from durable `tool/call` events, so resume and
- * reload keep them. read/write/edit/glob/grep/todo/ask are deliberately NOT
- * resident: bash + str_replace_editor cover file work.
- *
- * 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 (resident 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'
-
-/** 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 = []
-
-/** 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'],
-}
-
-/** Every config key this plugin accepts — anything else is a typo. */
-const ALLOWED_KEYS = new Set(['bootstrapTools', 'promoteOn', 'bootstrapMaxTokens', 'compactionTools', 'includeSubagents'])
-
-/** Validate an optional boolean flag with a default. */
-function booleanOption(value, field, fallback) {
-  if (value === undefined) return fallback
-  if (typeof value !== 'boolean') {
-    throw new TypeError(`${name}: ${field} must be a boolean`)
-  }
-  return value
-}
-
-/**
- * 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']
-
-/** Discovery tools always resident after promotion (the tool-search pattern). */
-const RESIDENT_DISCOVERY_TOOLS = ['dev_tool_search', 'skill_search', 'skill_load']
-
-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)
-}
-
-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)}`)
-}
-
-/**
- * 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 = config === undefined ? {} : config
-  if (typeof source !== 'object' || source === null || Array.isArray(source)) {
-    throw new TypeError(`${name}: config must be an object`)
-  }
-  const unknown = Object.keys(source).filter((key) => !ALLOWED_KEYS.has(key))
-  if (unknown.length > 0) {
-    throw new TypeError(
-      `${name}: unknown config key(s) ${unknown.join(', ')} — allowed keys: ${[...ALLOWED_KEYS].sort().join(', ')}`,
-    )
-  }
-  const bootstrapTools = stringList(source.bootstrapTools, 'bootstrapTools')
-  const promoteEvents = parsePromoteOn(source.promoteOn)
-  const bootstrapMaxTokens = optionalPositiveInt(source.bootstrapMaxTokens, 'bootstrapMaxTokens')
-  const includeSubagents = booleanOption(source.includeSubagents, 'includeSubagents', false)
-  // 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 })
-  ctx.on('session/event', (session, event) => promotion.observe(session, event))
-
-  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.
-    }
-  }
-
-  /**
-   * Tool names the model explicitly unlocked via `dev_tool_search` for one
-   * session. Derived from durable `tool/call` events so resume/reload keeps
-   * them. The event's `arguments` is the raw JSON string the model produced;
-   * we parse it defensively and read the `toolNames` array.
-   */
-  const unlockedFor = (session) => {
-    const unlocked = new Set()
-    if (session === undefined || !Array.isArray(session.events)) return unlocked
-    for (const event of session.events) {
-      if (event.type !== 'tool/call') continue
-      if (event.data?.name !== 'dev_tool_search') continue
-      let args
-      try {
-        args = JSON.parse(event.data.arguments)
-      } catch {
-        continue
-      }
-      if (args === null || typeof args !== 'object' || Array.isArray(args)) continue
-      const names = args.toolNames
-      if (Array.isArray(names)) for (const name of names) if (typeof name === 'string' && name.length > 0) unlocked.add(name)
-    }
-    return unlocked
-  }
-
-  /** 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 status = promotion.status(context.agent)
-      if (status.promoted) {
-        // PROMOTED: keep the minimal resident set — the bootstrap pair + the
-        // discovery tools + whatever the model explicitly unlocked via
-        // dev_tool_search — instead of dumping the whole Standard catalog at
-        // once (the post-promotion regression fix; see the header note).
-        const keep = new Set([...bootstrapTools, ...RESIDENT_DISCOVERY_TOOLS, ...unlockedFor(context.agent?.session)])
-        return keepTools(assembled, keep, false)
-      }
-      // 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 })
-  }
-}