docs: rebalance prose cleanup and add trimming skill

packages/core/tools/src/code-mode.ts

@@ -1,5 +1,7 @@
 /**
- * Code Mode: the `run_code` tool and its dispatch bridge.
+ * Code Mode `run_code` transport. Programs call the registry's agent-visible
+ * tools through nested, sequential executions; each sub-dispatch is logged for
+ * reconstruction, while only the outer curated result enters model history.
  * @module @deepseek-ai/dsh-tools/src/code-mode
  */
 
@@ -119,7 +121,7 @@ function asRunCodeMeta(meta: unknown): RunCodeMeta | undefined {
 
 /**
  * Build the `run_code` {@link ToolDefinition}: one required `code` parameter,
- * executed through the dispatch bridge described in the module doc. The
+ * executed through the dispatch bridge described above. The
  * registry reserves it as presentation infrastructure under non-native modes,
  * outside the filterable global/scoped capability layers.
  * @param registry - the owning registry (sub-calls go through its `execute`,

packages/core/tools/src/index.ts

@@ -117,7 +117,7 @@ declare module 'cordis' {
   }
 }
 
-// TODO(review): revisit these shapes when concurrency metadata becomes useful
+// TODO(concurrency): revisit these shapes when concurrency metadata becomes useful
 // (for example, a read-only hint that would permit safe parallel execution).
 
 /** Tool output, optionally with lossless-JSON presentation metadata persisted for replay. */
@@ -251,13 +251,21 @@ export interface ToolExecutionResult {
   meta?: unknown
 }
 
-/** Pre-dispatch decision. Input rewriting is excluded because arguments are already logged and presented. */
+/**
+ * Pre-dispatch decision. `allow` runs the call; `deny` materializes an error;
+ * `ask` runs only after an approval service returns `allowed-once` and otherwise
+ * denies. Input rewriting is excluded because arguments are already logged and
+ * presented.
+ */
 export type PreToolDecision =
   | { kind: 'allow' }
   | { kind: 'deny'; reason: string }
   | { kind: 'ask'; reason?: string }
 
-/** Post-dispatch decision: accept or replace content, attach context, or block with corrective feedback. */
+/**
+ * Post-dispatch decision: accept or replace content, attach context for the next
+ * request, or block by turning corrective feedback into an error result.
+ */
 export type PostToolDecision =
   | { kind: 'accept'; content?: ContentBlock[]; additionalContext?: HookContext }
   | { kind: 'block'; feedback: ContentBlock[]; additionalContext?: HookContext }
@@ -298,7 +306,12 @@ export type ToolPresentationMode = 'native' | 'code' | 'both'
 
 /** Plugin config: how the registered tools are presented to the model. */
 export interface Config {
-  /** Model presentation: native schemas, `run_code` plus SDK, or both. Code modes require a TypeScript runtime. */
+  /**
+   * Model presentation. `native` (default) sends every visible schema; `code`
+   * sends only `run_code` plus a generated SDK prompt; `both` sends both forms.
+   * Code modes require a TypeScript runtime and fail prompt assembly when it is
+   * absent or mismatched. Under `code`, native names in `toolOrder` are invalid.
+   */
   mode?: ToolPresentationMode
 }
 
@@ -393,7 +406,10 @@ export class ToolRegistry extends Service {
     }
   }
 
-  /** Build one scope's wire schemas and pre-restriction names for prompt-order validation. */
+  /**
+   * Build one scope's wire schemas and names for prompt-order validation.
+   * Restrictions do not make known tools invalid, but a mode collapse does.
+   */
   private wireSchemas(scope?: ScopeKey): ToolProviderResult {
     const view = this.view(scope)
     const schemas = [...view.visible.values()].map(definition => this.schemaOf(definition, false))
@@ -655,7 +671,8 @@ export class ToolRegistry extends Service {
   /**
    * Execute through pre-policy, guards, around-dispatch, post-policy, and final
    * notification. Tool and listener failures resolve as materialized error
-   * results; an invisible tool reports `UNKNOWN_TOOL`.
+   * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is
+   * the same lossless, frozen snapshot final observers receive.
    * @param exec - the typed same-process call input. The registry assigns its
    *   correlation token before policy begins.
    * @returns the materialized final result.

packages/core/tools/src/json-schema.ts

@@ -1,7 +1,9 @@
 /**
- * Structured-output JSON Schema subset: the vocabulary a caller uses to demand a
- * machine-readable result from a subagent (`SubagentStartRequest.outputSchema`) or a workflow
- * `agent()` call.
+ * Structured-output JSON Schema subset for subagents and workflows. It supports
+ * one scalar `type`; object `properties`/`required`/boolean
+ * `additionalProperties`; array `items`; scalar `enum`/`const`; and JSON-valued
+ * annotations. Unsupported or misplaced keywords reject rather than being
+ * accepted without enforcement, and structured-output roots must be objects.
  * @module dsh-tools/json-schema
  */
 

packages/core/tools/src/presentation.ts

@@ -167,8 +167,10 @@ export interface TerminalResultView {
 }
 
 /**
- * A completed file mutation rendered as an inline diff card, the *result-time* analogue of
- * {@link DiffCallView}.
+ * A completed file mutation rendered as an inline diff card, the result-time
+ * analogue of {@link DiffCallView}. Because a completed UI update replaces the
+ * pending card content, mutation tools return this even when it repeats the
+ * call-time diff; otherwise raw result text would replace the diff.
  */
 export interface DiffResultView {
   card: 'diff'

packages/core/tools/src/schema.ts

@@ -310,7 +310,8 @@ export interface DefineToolOptions<S extends SchemaSpec> {
 
 /**
  * Define a first-party tool whose execution and presentation arguments are
- * inferred from its per-property schema.
+ * inferred from its per-property schema. Raw JSON-Schema definitions remain
+ * valid inputs to {@link ToolRegistry.register}; this helper is authoring sugar.
  * @param options - the tool's name, description, typed parameter schema,
  *   execute body, and optional presenters.
  * @returns a registry-ready definition with strict execution validation and

packages/core/tools/src/ts-types.ts

@@ -24,8 +24,8 @@ function pad(indent: number): string {
 /** A one-line JSDoc block for a schema `description`, or no lines when there is none. */
 function docLines(description: unknown, indent: number): string[] {
   if (typeof description !== 'string' || description.length === 0) return []
-  // Keep the doc a single-line comment per property: descriptions are prose (possibly with
-  // newlines); collapse whitespace so the rendered SDK stays stable and compact.
+  // Collapse prose to stable one-line docs and escape comment closers so a
+  // schema description cannot terminate generated JSDoc.
   const collapsed = description.replace(/\s+/g, ' ').trim()
   return [`${pad(indent)}/** ${collapsed.replaceAll('*/', String.raw`*\/`)} */`]
 }