docs: rebalance prose cleanup and add trimming skill

packages/workflow/tool-workflow/src/index.ts

@@ -3,7 +3,10 @@
  * subagents, and return the script's final value. Pure schema + lifecycle shaping — script
  * parsing, execution, caps, and cancellation live behind `ctx.workflows`
  * (`@deepseek-ai/dsh-workflow`), so a hardened engine swaps in without touching what the model
- * sees.
+ * sees. Execution awaits `run.result` and always disposes the run; non-completed reasons become tool
+ * errors, and background collection remains deferred. Presentation is an args-only generic card
+ * titled from `meta.name`. Explicit-ask usage guidance is registered as the tool's own prompt
+ * section rather than deployment persona prose.
  * @module @deepseek-ai/dsh-tool-workflow
  */
 
@@ -169,7 +172,8 @@ export function apply(ctx: Context, config: Config): void {
       })
 
       // Bridge the tool's abort signal to the run: if the parent step is aborted while the
-      // script is in flight, cancel the whole run.
+      // script is in flight, cancel the whole run. The signal also enters the engine directly, but
+      // this local bridge preserves the tool contract even if an implementation ignores it.
       const onAbort = (): void => { run.cancel('parent step aborted') }
       exec.signal?.addEventListener('abort', onAbort, { once: true })
       // `addEventListener` does NOT fire for a signal already aborted before

packages/workflow/tool-workflow/tests/tool-workflow.spec.ts

@@ -224,10 +224,8 @@ describe('dsh-tool-workflow', () => {
 
   describe('composition with the REAL worker-thread engine (the mock above must stay honest)', () => {
     it('an abort releases the tool even when the script parks on a promise no hook owns', async () => {
-      // Regression for the review-found turn wedge: the tool awaits run.result before its
-      // disposing finally, the registry and the loop await the tool — so if cancellation could
-      // not settle result (a script parked on `await new Promise(() => {})`), an aborted turn
-      // stayed wedged forever.
+      // The tool and loop await run.result before cleanup, so cancellation must settle a script
+      // parked on an unowned promise. Exercise that guarantee through the real registry and worker.
       const ctx = new Context()
       await ctx.plugin(SystemPrompt)
       await ctx.plugin(ToolRegistry)