refactor: replace overloaded surface terminology

packages/fs/tool-fs-search/src/direct-call.ts

@@ -1,11 +1,11 @@
-/** Shared surface-only post-policy selection for search result spill. @module dsh-tool-fs-search/surface */
+/** Shared top-level-call post-policy selection for search result spill. @module dsh-tool-fs-search/direct-call */
 
 import type { Context } from '@deepseek-ai/cordis'
 import type { JsonValue, PostToolDecision, ToolDefinition, ToolExecution, ToolExecutionResult } from '@deepseek-ai/dsh-tools'
 
 /**
  * Return the accepted canonical value only when this tool still owns a direct
- * successful surface call and no downstream policy replaced either projection.
+ * successful top-level call and no downstream policy replaced either projection.
  * @param ctx - the tool plugin context used to resolve the live scoped owner.
  * @param tool - the exact registered definition whose value may be projected.
  * @param exec - the completed execution identity.
@@ -13,7 +13,7 @@ import type { JsonValue, PostToolDecision, ToolDefinition, ToolExecution, ToolEx
  * @param decision - the composed downstream post-policy decision.
  * @returns the canonical value to project, or `undefined` when spill must defer.
  */
-export function acceptedSurfaceValue(
+export function acceptedDirectCallValue(
   ctx: Context,
   tool: ToolDefinition,
   exec: ToolExecution,

packages/fs/tool-fs-search/src/glob.ts

@@ -17,7 +17,7 @@ import type { SpillRef } from '@deepseek-ai/dsh-spill'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import { runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
 import { globSearchMeta, searchViewFromMeta } from './presentation.ts'
-import { acceptedSurfaceValue } from './surface.ts'
+import { acceptedDirectCallValue } from './direct-call.ts'
 
 /**
  * Default cap on paths retained inline by one `glob` call (the `globMaxResults`
@@ -360,7 +360,7 @@ export function applyGlobTool(ctx: Context, caps: GlobToolCaps): void {
 
   ctx.on('tools/post-execute', async (exec, result, next) => {
     const decision = await next()
-    const value = acceptedSurfaceValue(ctx, tool, exec, result, decision) as { root: string; paths: string[] } | undefined
+    const value = acceptedDirectCallValue(ctx, tool, exec, result, decision) as { root: string; paths: string[] } | undefined
     if (value === undefined) return decision
     const paths = value.paths
     if (paths.length <= caps.maxResults) return decision

packages/fs/tool-fs-search/src/grep.ts

@@ -20,7 +20,7 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 import type { GrepMatch } from './search-core.ts'
 import { SearchError, previewLine, retainGrepMatches, runRipgrep, toWorkdirRelative, trySaveFormattedResult } from './search-core.ts'
 import { grepSearchMeta, searchViewFromMeta } from './presentation.ts'
-import { acceptedSurfaceValue } from './surface.ts'
+import { acceptedDirectCallValue } from './direct-call.ts'
 
 /**
  * Default cap on flat matches retained inline by one `grep` call (the
@@ -340,7 +340,7 @@ export function applyGrepTool(ctx: Context, caps: GrepToolCaps): void {
 
   ctx.on('tools/post-execute', async (exec, result, next) => {
     const decision = await next()
-    const value = acceptedSurfaceValue(ctx, tool, exec, result, decision) as { matches: GrepMatch[] } | undefined
+    const value = acceptedDirectCallValue(ctx, tool, exec, result, decision) as { matches: GrepMatch[] } | undefined
     if (value === undefined) return decision
     const matches = value.matches
     if (matches.length <= caps.maxMatches) return decision

packages/fs/tool-fs-search/src/search-core.ts

@@ -82,7 +82,7 @@ export type SearchErrorCode =
 
 /**
  * Typed search failure. Extends {@link HarnessError} so it carries a stable
- * {@link SearchErrorCode} and chains `cause`; the tool registry surfaces
+ * {@link SearchErrorCode} and chains `cause`; the tool registry exposes
  * `{ name, code }` on `isError` results so retry/permission/UI layers can
  * branch without parsing messages.
  */

packages/fs/tool-fs-search/tests/tools.spec.ts

@@ -881,7 +881,7 @@ describe('glob results', () => {
     expect(spill?.saves).toHaveLength(0)
   })
 
-  it('keeps the full nested Code value without creating a surface spill', async () => {
+  it('keeps the full nested Code value without creating a top-level spill', async () => {
     const { ctx, subprocess, spill } = await setup({ config: { globMaxResults: 2 }, spill: true })
     subprocess.handler = () => runResult('a.ts\nb.ts\nc.ts\nd.ts\n')
     const result = await call(ctx, 'glob', { pattern: '*.ts' }, {
@@ -1028,7 +1028,7 @@ describe('grep results', () => {
     expect(spill?.saves).toHaveLength(0)
   })
 
-  it('keeps every nested Code match in the value without creating a surface spill', async () => {
+  it('keeps every nested Code match in the value without creating a top-level spill', async () => {
     const { ctx, subprocess, spill } = await setup({ config: { grepMaxMatches: 1 }, spill: true })
     subprocess.handler = () => runResult(`${matchLine('a.ts', 1, 'one')}\n${matchLine('b.ts', 2, 'two')}\n`)
     const result = await call(ctx, 'grep', { pattern: 'o' }, {