docs: rebalance prose cleanup and add trimming skill

examples/acp-agent/tests/acp.e2e.ts

@@ -26,12 +26,13 @@ import {
  * WITHOUT a key, since it only needs the server to boot and answer initialize.
  */
 
-// The dsh-acp-agent bin (the demo:acp entry) and this example's cordis.yml.
+// The child runs from a temp cwd, so its bin and config path are absolute.
 const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 // Resolve tsx absolutely because the subprocess runs outside the repo.
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
-// Absolute path to the repo-root tsconfig.
+// The root tsconfig supplies unbuilt workspace `paths`; making it explicit
+// avoids accidental resolution through stale built output.
 const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 
 interface Spawned {

examples/acp-agent/tests/acp.snapshot.ts

@@ -75,12 +75,15 @@ const SCENARIOS: Scenario[] = [
   // child runs as a spawn subagent under the worker-thread engine (its session is the
   // child fixture), and the tool result carries the script's return value.
   { name: 'workflow-run', hasModelTurn: true, recorded: true, childSessions: 1 },
-  // Hook matrix — one scenario per hook point × its headline Decision outcome, across BOTH
-  // bridges (Claude `hooks.json`, Codex `codex-hooks.json`, seeded in workspace/).
+  // Prompt-submit blocks are authored keylessly: they persist a rejected turn
+  // and hook events without starting a model step, so their logs still compare.
   { name: 'hook-cc-promptsubmit-block', hasModelTurn: false, comparesLog: true, recorded: false },
   { name: 'hook-codex-promptsubmit-block', hasModelTurn: false, comparesLog: true, recorded: false },
   // The mid-turn seams fire during a real model turn, so each is recorded with its hook active
   // (the model's reaction to a deny/block/force-continue is part of the captured transcript).
+  // SessionStart/SubagentStart are excluded because detached injection races log
+  // order; SubagentStop writes no transcript, so a golden could not prove it ran.
+  // Unit tests cover those points; the hook-snapshot-matrix RFC owns the rationale.
   { name: 'hook-cc-promptsubmit-context', hasModelTurn: true, recorded: true },
   { name: 'hook-cc-pretool-deny', hasModelTurn: true, recorded: true },
   { name: 'hook-cc-pretool-ask', hasModelTurn: true, recorded: true },
@@ -97,7 +100,7 @@ const SCENARIOS: Scenario[] = [
   { name: 'hook-codex-stop-continue', hasModelTurn: true, recorded: true },
   // Code Mode: the registry in `mode: code` — the wire tool list collapses to [run_code], the
   // tools:sdk section rides in the prompt, and the program's tool calls land as
-  // tool/code-dispatch events.
+  // tool/code-dispatch events. Each overlay composes and pins its own header class.
   { name: 'code-mode-turn', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'code', configPath: CODE_MODE_CONFIG },
   { name: 'both-mode-turn', hasModelTurn: true, recorded: true, pinsHeader: true, headerClass: 'both', configPath: BOTH_MODE_CONFIG },
 ]

examples/acp-agent/tests/hooks.e2e.ts

@@ -17,8 +17,10 @@ import {
 } from '@agentclientprotocol/sdk'
 
 /**
- * With-key e2e: the Claude Code hook bridge running against the real acp-agent subprocess and
- * the real model.
+ * With-key e2e for the Claude hook bridge. The process-level `./hooks.json` is
+ * resolved from a temporary launch cwd and blocks all PreToolUse calls; a real
+ * model is asked to write there, and absence of the file proves interception.
+ * The test owns and disposes the ACP subprocess.
  */
 
 const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url))
@@ -76,7 +78,8 @@ afterEach(async () => {
 describe.skipIf(!process.env.DEEPSEEK_API_KEY)('acp-agent e2e: a PreToolUse hook blocks bash (real model)', () => {
   it('denies every bash command, so the requested file is never written (verified on disk)', async () => {
     workdir = await mkdtemp(join(tmpdir(), 'acp-hooks-e2e-'))
-    // A PreToolUse hook that blocks every tool (exit 2, no matcher = match-all).
+    // `configPath` is process-relative, so placing the match-all hook in the
+    // launch cwd selects it; hook commands themselves run in the session cwd.
     await writeFile(join(workdir, 'hooks.json'), JSON.stringify({
       hooks: { PreToolUse: [{ hooks: [{ type: 'command', command: 'echo "bash blocked by policy" >&2; exit 2' }] }] },
     }))