* feat: add runtime storage override

Co-authored-by: Codex <noreply@openai.com>

* test: update storage path source assertions

Co-authored-by: Codex <noreply@openai.com>

* test: normalize storage path expectations

Co-authored-by: Codex <noreply@openai.com>

* fix runtime storage override resolution

Consolidate storage overrides on CONTEXT_MODE_DIR, share resolver behavior across server, hooks, and statusline, and update docs/tests around the Codex Desktop failure contract.

Co-authored-by: Codex <noreply@openai.com>

* fix windows storage override tests

Make storage-path resolver expectations platform-aware and keep statusline multi-adapter tests on adapter-default discovery instead of the root override path.

Co-authored-by: Codex <noreply@openai.com>

* address runtime storage review

Compose tool registration wrappers, memoize storage writability checks, report storage roots in ctx_doctor, keep legacy statusline session-dir compatibility, and fold resolver tests into existing server coverage.

Co-authored-by: Codex <noreply@openai.com>

* fix windows storage path test

Use an absolute temp-directory fixture instead of a POSIX-rooted default path so resolver tests assert storage behavior consistently across platforms.

Co-authored-by: Codex <noreply@openai.com>

* fold storage resolver into session db

Move CONTEXT_MODE_DIR resolver exports into the existing session DB module so hooks and statusline can use the existing session-db bundle. Drop the new storage-paths source and hook bundle entries while preserving shared storage behavior.

Co-authored-by: Codex <noreply@openai.com>

* consolidate default storage session roots

Add the shared default session-dir helper to the existing session DB bundle boundary, route server/hooks/statusline through it, and document why storage resolution lives there. Expand storage resolver tests for the shared helper.

Co-authored-by: Codex <noreply@openai.com>

* fix codex default session guard

Update the source assertion for the shared default-session-dir helper so the CI guard checks CODEX_HOME via configDirEnvForSessionSegments instead of the removed direct Codex config import.

Co-authored-by: Codex <noreply@openai.com>

* Fix Claude plugin skills path and pack integrity guard (#661)

* ci: update server.bundle.mjs, cli.bundle.mjs, session hook & security bundles

* ci: update install stats

* ci: update install stats

* ci: update install stats

* Fix Claude plugin skills manifest path

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

* fix(pi): prevent mixed-width TUI over-width crashes (CJK/Korean/emoji) (#676)

* fix(pi): CJK wide-character width-aware truncation in PiTextComponent (#665)

PiTextComponent/truncateAnsiLine counted every JS character as width 1,
but CJK ideographs occupy 2 terminal columns. This produced lines whose
actual visibleWidth exceeded the requested width, triggering a pi-tui
crash: 'visible width: 162 > terminal width: 147'.

Root cause: truncateAnsiLine() iterated chars with visible++ (always 1)
instead of accounting for east-asian-width W/F codepoints.

Fix:
- Add charWidth() helper that returns 2 for CJK/Hangul/fullwidth ranges.
- Change truncateAnsiLine to use charWidth and check visible + w > maxWidth
  (not >=), so a 2-wide char still fits when exactly 2 columns remain.
- Export PiTextComponent and truncateAnsiLine for testability.

Tests (Slice 10 in pi-mcp-bridge.test.ts):
- Pure CJK text respects requested width.
- Mixed ASCII + CJK is correctly truncated.
- ANSI escape sequences are preserved and not counted toward width.
- The real crash line from pi-crash.log fits within terminal width 147.
- Edge case: maxWidth 0 or negative returns empty string.

Fixes #665

* test(asymmetric-drift): make npm pack dry-run windows-safe

---------

Co-authored-by: baifan <ubuntu@BaiFanPC.localdomain>

* fix(server): add z.preprocess coercions to ctx_fetch_and_index force and requests params (#679)

fix(server): add z.preprocess coercions to ctx_fetch_and_index params

The OpenCode/Kilo in-process native plugin bridge stringifies primitive types. Other tools already use z.preprocess(coerceBoolean/coerceJsonArray) to handle this, but ctx_fetch_and_index was missing these wrappers on its force and requests parameters.

Added schema-level test verifying preprocess wrappers are present. Updated existing schema tests to match new structure.

* feat(fetch): add per-call cache ttl (#666)

* feat(fetch): add per-call cache ttl

* test: run npm pack dry-run on Windows

* fix(batch_execute): preserve heredoc commands (#657)

Stops appending `2>&1` to user command strings in `runBatchCommands()` — that mutation broke heredoc terminators (`NODE` → `NODE 2>&1`). Now executes commands as-written and merges executor-captured stdout+stderr via new `combineExecOutput()` helper. Symmetric across serial + parallel paths.

Adds serial + parallel regression tests for heredoc commands with stderr. Updates the nodeOptsPrefix edge-case test to reflect the new behavior.

Bundles taken from `next` (CI-authoritative); regenerate on next main push.

Fixes #656.

Co-Authored-By: Noctivoro <nick@movermarketing.ai>

* fix(server): surrogate-safe preview truncation in ctx_fetch_and_index (#659) (#660)

The fetch-preview path at src/server.ts truncated `f.markdown` with
`String.prototype.slice(0, FETCH_PREVIEW_LIMIT)` where the limit
(3072) is a UTF-16 code-unit count. When the cut fell between the two
halves of an astral-plane character (e.g. 🟡 = U+1F7E1 = 🟡),
the high surrogate remained and the low surrogate was dropped.
JSON.stringify then emitted the orphan as a literal `\uD83D` escape
in the tool_result body, causing RFC 8259-strict consumers (the host
LLM API) to reject the next request with `400 ... no low surrogate
in string`. Sessions could not recover without removing the bad
message from the transcript.

Adds a new `charSafePrefix(str, maxChars)` export to `src/truncate.ts`
mirroring the existing internal `byteSafePrefix` semantics: cap by
UTF-16 code units, back off one unit if the cut would split a
surrogate pair. Wires it into the fetch-preview construction.

Tests cover the helper directly plus a regression that walks the
exact preview-construction pattern with an emoji at the LIMIT
boundary and asserts the resulting JSON contains no orphan high
surrogate and round-trips through a strict parser.

Other `.slice(0, N)` sites in src/ (small label/error/timestamp
truncations) are out of scope for this PR — they have low bounds and
their inputs are unlikely to contain emoji at the boundary. Happy to
extend coverage in a follow-up if the maintainer wants to remove the
class of bug entirely.

Fixes #659

* fix(auto-memory): scope memory dir by projectDir to stop cross-project leak (#663) (#664)

* fix(auto-memory): scope memory dir by projectDir to stop cross-project leak (#663)

getMemoryDir() ignored projectDir, so every adapter (except OpenClaw, whose
configDir IS the project root) returned a path shared by every project on
the machine. Two terminals open in different repos read each other's .md
memory files via searchAutoMemory(), then those notes contaminated
ctx_search timeline results.

Fix: HookAdapter.getMemoryDir now accepts an optional projectDir. When
supplied, the path is scoped via hashProjectDirCanonical(projectDir) under
the existing base. searchAutoMemory passes projectDir through; the
adapterless legacy fallback applies the same hash directly so the contract
holds at both call sites. Reuses the same canonicalization as ContentStore
and searchEvents, so all three project-scoped surfaces share one identity.

Backwards compat: getMemoryDir() without projectDir keeps returning the
unscoped path so external adapter consumers don't break.

Tests: leak canary (write under projectA scope, search from projectB,
assert 0 hits) + positive control + #663 negative test pinning that the
old unscoped path is no longer surfaced.

* test(windows): fix two flaky Windows-only CI failures

- asymmetric-drift-assert: spawnSync("npm", ...) needs shell:true on
  Windows because npm resolves to npm.cmd. Without it Node returned
  status=null/stderr=null/stdout=null and the assertion failed with no
  diagnostic. Also surface r.error in the assertion message.
- server.test.ts "python: cap works with python scripts": replace the
  10k-iteration Python loop with a single 100KB write. The cap still
  triggers (and stderr still gets "output capped"), but the test no
  longer races the 10s timeout on slow Windows CI VMs.

---------

Co-authored-by: Codex <noreply@openai.com>
Co-authored-by: Baijack-star <71923891+Baijack-star@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: ByF <222546298+ByronFinn@users.noreply.github.com>
Co-authored-by: baifan <ubuntu@BaiFanPC.localdomain>
Co-authored-by: LeoNardo <58056860+LeoNardo-LB@users.noreply.github.com>
Co-authored-by: NgoQuocViet2001 <123613986+NgoQuocViet2001@users.noreply.github.com>
Co-authored-by: /noctivoro-x <nick@movermarketing.ai>
Co-authored-by: ccheng555 <ccheng5@gmail.com>
Co-authored-by: Seba Breguel <62109266+sebastianbreguel@users.noreply.github.com>
Co-authored-by: Mert Koseoglu <bm.ksglu@gmail.com>

…pabilities, technical depth (#683)

Maintainer's third-pass review covered ten distinct critiques. Addressed
together because they all stem from the same direction: surface the
load-bearing mechanism the LLM needs to act correctly, in terms the LLM
understands at tool-selection time.

ctx_search — full rewrite. The previous headline ("BM25 over FTS5") sold
the tool short. The actual ranking pipeline is BM25 + Reciprocal Rank
Fusion over two parallel tokenizers (Porter stemming + trigram
substring), plus a proximity rerank pass for multi-term queries, plus
Levenshtein typo correction, plus window-extracted smart snippets.
The knowledge base is unified: ctx_search reaches both content the user
indexed AND auto-captured session memory (26 event categories). WHEN
NOT bullets reframed to intent ("you have an ad-hoc question") so the
tool-name references don't get lost across long conversations.
contentType code|prose filter surfaced. Four EXAMPLE lines cover the
four most common shapes (source-scoped batch, timeline-sorted memory,
contentType-filtered, multi-source recall).

ctx_fetch_and_index — custom TTL (PR #666) now first-class. Default
24h, override per-call with ttl: <ms>, ttl: 0 bypasses like force:true.
Removed the "~3KB" hard preview claim — replaced with mechanism prose.
RETURNS explains the FTS5 single-writer reality and net-latency math
(parallel-fetch + serial-index). Concurrency guardrails kept generic
(I/O-bound 4-8, lower for rate-limited hosts) — no third-party API
specifics (Mert flag: not our policy to editorialize on someone else's
API contract).

ctx_batch_execute — Think-in-Code restored as the load-bearing concept
("concurrency parallelizes FETCH; derivation belongs in code"). Same
generic concurrency guardrails as ctx_fetch_and_index. EXAMPLE shows
the pattern with a summarize-step command at the end.

ctx_execute — background and intent capabilities now surfaced in
description (previously only in the schema field describe). background
covers server/daemon detach. intent triggers auto-index of large output
into the knowledge base, with title+preview return instead of raw stdout.

ctx_execute_file — same intent surfacing for file-derivation output.

ctx_insight — port (default 4747) and sessionDir/contentDir overrides
surfaced. Useful for diagnosing multi-install setups or pointing at a
sibling project's data.

README.md — TTL Cache section rewritten for custom TTL. The "Fresh (<24h)"
hard claim is now "Cache hit (within TTL)" with the default-and-override
mechanism explained. Tools table row for ctx_fetch_and_index updated to
match.

Two contract tests (tests/core/server.test.ts) that pinned the old exact
phrasing for batch_execute / fetch_and_index concurrency guidance now
pin the LOAD-BEARING CONCEPTS via regex (4-8 window, CPU/stateful keep
at 1, FTS5 serial-write) — same coverage, immune to future copy-edits.

Three pre-existing PR #617 failures (ctx_doctor + ctx_index storage path
e2e under CONTEXT_MODE_DIR) remain — out of scope, separate work.

…fusal (substitutes #654) (#683)

* fix(server): replace "blocked" wording in WebFetch refusal with imperative retry hint (substitutes #654)

Three redirect messages in hooks/core/routing.mjs (curl/wget, Inline HTTP,
WebFetch) reframed from the negation-heavy "blocked" voice to imperative-
positive "redirected (NOT a network restriction)" — and crucially append
"— retry if it fails with a transient DNS error" so the next action is
explicit across all model tiers.

PR #654 (contributor) correctly identified Opus 4.6's "blocked → capitulate
to training" failure mode under the EAI_AGAIN cascade. Our internal A/B
audit (Probe 3, 6 trials Haiku) confirmed the fix on Opus but uncovered
a 2/6 Haiku regression — the parenthetical "(NOT a network restriction)"
landed as information without a paired action, and 2 trials concluded
"since the redirect isn't a restriction either, I can just use training
data." Audit recommended appending the imperative retry clause — this
substitute ships exactly that.

Sibling-tool consistency on ctx_fetch_and_index:
  - ssrfGuard pre-flight DNS path: classify EAI_AGAIN / ETIMEDOUT /
    ETIMEOUT / ENETUNREACH / EPERM as transient and append the same
    retry hint. Non-transient codes (ENOTFOUND) stay silent — retry
    won't help on a genuinely bad domain.
  - Subprocess fetch stderr path: closes the contributor's flagged
    "Known follow-up" (batch wrapper bypassed the single-URL hint).
    Same code regex on result.stderr — same retry hint surfaces in the
    common multi-URL batch case the original PR couldn't reach.

Tests updated, no new test files (CONTRIBUTING L275):
  - tests/hooks/core-routing.test.ts: assert "redirected" + retry hint,
    explicit negative-assert .not.toContain("blocked") regression guard.
  - tests/hooks/cursor-hooks.test.ts, tool-naming.test.ts: wording sync.
  - tests/hooks/integration.test.ts: curl-warning regex relaxed to
    survive both old "Do NOT use curl" and new "Do NOT retry with curl".

Bundles untouched — CI rebuilds on main push (project_ci_bundles).

Targeted: npx vitest run tests/hooks/ → 438/438 pass.
TypeScript: npx tsc --noEmit clean.

Closes work on #654 (PR closed in favor of this direct-to-next commit).
Audit doc: .cw/ctx-analytics/TOOL-DESCRIPTIONS-AUDIT.md §6.1
Substitute log: .cw/ctx-analytics/PR-654-SUBSTITUTE-LOG.md

* docs(adr): tool description style (ADR-0002) + routing deny reasons (ADR-0003)

ADR-0002 formalizes the structure every ctx_* tool description must
follow (1-line role / WHEN: / WHEN NOT: / RETURNS: / EXAMPLE:), the
forbidden-token list (MANDATORY:, BLOCKED, PREFER X OVER Y, Do NOT,
Never use, SESSION STATE, emoji bullets), and the MUST/SHOULD/MAY
hierarchy reserved for post-call obligations only. Grounded in 38
trials x 6 probes A/B evidence: heavy framing helps ctx_purge on Haiku
(5/5 vs 3/5 parameter fidelity) but hurts ctx_execute selection — one
size does not fit all, so rewrites are probe-gated.

ADR-0003 splits routing deny reasons into CASE A (redirect — supported
via alternative tool) and CASE B (true policy restriction). PR #654's
finding: the bare word "blocked" in WebFetch's CASE A denial was
misread by Opus 4.6 as a network restriction, triggering training-data
capitulation. CASE A MUST use "redirected", state "this is NOT a
network/security restriction", and end with a transient-error retry
hint. CASE B keeps "denied"/"blocked by security policy".

PR #683 (substitutes #654).

* fix(server): apply ADR-0002 voice to 6 ctx_* tool descriptions + contract test

Comprehensive audit of all 11 ctx_* MCP tool descriptions (see
TOOL-DESCRIPTIONS-AUDIT.md). Six tools rewritten per ADR-0002 verbatim
templates; the remaining 5 are unchanged (3 minimal-description
exemptions, 1 MUST-allowed post-call obligation, 1 deferred to a
probe-gated follow-up PR).

HIGH severity (audit §3): voice consistency on the ctx_execute family.
  - ctx_execute (src/server.ts:1419): drop "MANDATORY:" opener,
    "PREFER THIS OVER BASH", "THINK IN CODE" voice-of-trainer paragraph,
    "Do NOT read raw data". Replace with role definition + WHEN: /
    WHEN NOT: / RETURNS: / EXAMPLE: sections. ~1200 -> ~700 chars.
  - ctx_execute_file (src/server.ts:1755): same shape; drop "PREFER
    THIS OVER Read/cat" and "Don't read files into context to analyze
    mentally". Probe 2 evidence: disambiguation was already strong;
    this is a voice-consistency pass.
  - ctx_batch_execute (src/server.ts:3109): drop "THIS IS THE PRIMARY
    TOOL", "THINK IN CODE — NON-NEGOTIABLE", and the emoji-bulleted
    PARALLELIZE I/O block. Replace with WHEN: / CONCURRENCY: prose.
    ~1700 -> ~900 chars.

MEDIUM severity (audit §3):
  - ctx_search (src/server.ts:2072): drop the SESSION STATE clause
    (it is a routing-block.mjs concern; semantic-equivalence proof
    in GRILL-Q1-VERDICT.md Round 5). Add explicit WHEN: structure
    and a one-line EXAMPLE with batched queries.
  - ctx_index (src/server.ts:1900): rewrite "Do NOT use for: log
    files..." as a positive WHEN NOT: clause pointing at
    ctx_execute_file. Keep the existing WHEN TO USE: header
    (transitional alias permitted by ADR-0002).
  - ctx_fetch_and_index (src/server.ts:2865): replace
    "PARALLELIZE I/O" banner + ✅/❌ emoji bullets with a positive
    CONCURRENCY: prose block. ✅/❌ tokenize inconsistently across
    Llama/Gemini and act as negative-example leakage (rubric #4 +
    Probe 3 evidence).

Regression guard (audit §10.1, folded into existing test file per
CONTRIBUTING.md L282 "Do NOT create new test files"):
  - tests/core/server.test.ts: new describe block "tool description
    style contract (#683 ADR-0002)" parses every
    server.registerTool() block and asserts:
      * MUST NOT contain forbidden tokens (MANDATORY:, BLOCKED,
        PREFER X OVER Y, Do NOT read/use/pull, Never use,
        SESSION STATE, ✅, ❌)
      * MUST contain a WHEN: section (WHEN TO USE: accepted)
    Exemptions: ctx_stats/ctx_doctor/ctx_insight (minimal by
    design), ctx_upgrade (MUST is appropriate for post-call
    obligation), ctx_purge (deferred entirely — see below).
  - Updated two existing tests that asserted the old wording:
    concurrency-field guidance now checks prose form;
    PARALLELIZE I/O test now checks CONCURRENCY: section.

Explicitly deferred — ctx_purge:
  Probe 4 (5 trials x 2 variants, Haiku) showed the proposed soft
  rewrite REGRESSES parameter fidelity 5/5 -> 3/5. Counter-intuitive:
  the heavy negative framing (DESTRUCTIVE, REFUSAL RULES, NEVER call
  with bare {confirm:true}) actually anchors small models to the
  required scope discipline. A follow-up PR must run a tri-LLM probe
  (Haiku/Sonnet/Opus) and gate merge on that probe before changing
  this tool. Documented inline in tests/core/server.test.ts via
  EXEMPT_FROM_FORBIDDEN_TOKENS with rationale.

Verification:
  - npx tsc --noEmit: clean
  - tests/core/server.test.ts: 361/364 pass (3 pre-existing failures
    unrelated to this PR — confirmed via git stash diff)
  - tests/hooks/: 438/439 pass (1 skipped, unchanged)
  - tests/adapters/: 787/787 pass

PR #683 (substitutes #654). See docs/adr/0002 and docs/adr/0003.

* fix(hooks): apply ADR-0002 + ADR-0003 contract to routing-block.mjs + lock with regression test

Extends PR #683 to the highest-blast-radius prompt surface in the project:
hooks/routing-block.mjs ships into the system prompt of every session, while
src/server.ts tool descriptions only fire at tool-selection time. The original
PR #683 scope cleaned up the per-tool surface and the routing.mjs deny reasons
but missed the system-prompt surface itself.

Three forbidden-token violations rewritten per ADR-0002 rubric #2 (affirmative >
negative) + #9 (cross-LLM Constitutional AI safety bias):

- <forbidden_actions> XML container -> <when_not_to_use>; the container name
  itself is a Constitutional AI trigger on Anthropic-tier models.
- "NEVER use ctx_execute ... for file writes" -> descriptive form
  "File writes use the native Write or Edit tool -- ctx_execute,
  ctx_execute_file, and Bash subprocesses do not persist edits to the host
  filesystem." Same operational intent, no forbidding voice.
- "Write artifacts ... NEVER inline" -> "Write artifacts ... to files. Return
  only: file path + 1-line description."

Semantic-equivalence verified by enumerating all 16 directives in the current
block and mapping each to its rewrite (0 orphans, 0 additions). Net character
delta: -76 chars. RFC 2119 MUST kept in <priority_instructions> per the
ADR-0002 post-call-obligation carve-out.

Adds a sibling contract describe block to tests/core/server.test.ts:
"hook routing prompt-surface contract (#683 ADR-0002 + ADR-0003)". Folded
into the same file per CONTRIBUTING.md L282 (no new test files). Scans:

- hooks/routing-block.mjs and hooks/core/routing.mjs for forbidden tokens
  (<forbidden_actions>, NEVER, FORBIDDEN, "NO X for Y" bullets).
- Every "redirected"-bearing template literal in routing.mjs for ADR-0003
  CASE A compliance: MUST open with "redirected", MUST NOT contain bare
  uppercase BLOCKED, MUST name at least one ctx_* alternative tool.

15 assertions total. CASE B strings (Blocked by security policy: ...)
correctly excluded by the extractor. This is the contract test ADR-0003
Consequences L79-82 invited as follow-up.

Three tests/hooks/core-routing.test.ts assertions and one tests/core/
server.test.ts hook-injection assertion updated to match the new positive
wording (same semantic coverage, new container name).

Full regression sweep: 841 passing / 1 skipped / 3 pre-existing storage-
roots failures (verified by git stash on the branch HEAD; out of scope per
PR #683 body).

* fix(server): apply ADR-0002 canonical structure to ctx_purge + 4 ctx_* tools (PR #683 WS2/WS3)

WS2 — ctx_purge rewrite (audit §6.5, Probe 4 evidence preserved):
  - Replace negative flat framing (DESTRUCTIVE/REFUSAL RULES/NEVER) with the
    canonical WHEN/WHEN NOT/SCOPES/CONTRACT/RETURNS/EXAMPLE structure.
  - Preserve all four refusal rules verbatim under CONTRACT (confirm:false,
    sessionId+scope ambiguity, scope:'session' without sessionId, deprecated
    bare {confirm:true}) so Probe 4 parameter-fidelity discipline holds on
    Haiku (5/5 baseline must not regress).
  - Keep DESTRUCTIVE headline as accurate user-facing signaling (distinct
    from the cross-LLM-bias negative framing the ADR-0002 rubric forbids).
  - Add two EXAMPLE lines for the two valid input shapes (per-session +
    per-project) so the LLM has explicit parameter templates.
  - Add WHEN NOT clause covering the ambiguous-scope handler ("User says
    'reset'/'clear'/'wipe' without naming a scope -> ask first").

WS3 — corpus-wide canonical structure pass:
  - ctx_index: add EXAMPLE: line (was missing); fold the path-hash sentence
    into the RETURNS block so the canonical four-section shape holds.
  - ctx_search: drop the non-canonical TIPS: header (fold into RETURNS
    prose); add explicit WHEN NOT clauses (empty-index redirect, single
    one-off question -> ctx_execute).
  - ctx_fetch_and_index: drop the non-canonical CONCURRENCY: header (fold
    the I/O-bound split into the WHEN clause; fold the SQLite single-writer
    note into RETURNS); add WHEN NOT clauses (local content -> ctx_index,
    SPA-rendered content -> headless browser).
  - ctx_batch_execute: drop the non-canonical CONCURRENCY: header (fold the
    I/O-bound guidance into WHEN; fold the CPU-bound + stateful guidance
    into WHEN NOT).

Section order on all six routing-target tools is now strictly
WHEN -> WHEN NOT -> RETURNS -> EXAMPLE per ADR-0002 §Canonical structure.
Bullets are markdown '- ' only. ctx_stats/ctx_doctor/ctx_upgrade/ctx_insight
remain minimal one-line diagnostic descriptions (exempt).

Empirical reference: TOOL-DESCRIPTIONS-AUDIT.md §6.1 (ctx_purge Probe 4),
audit §3 row-by-row standardization verdicts.

* test(server): lock canonical-structure contract + amend ADR-0002 (PR #683 WS3)

ADR-0002 amendment (docs/adr/0002-tool-description-style.md):
  - Add ### Canonical structure (locked rubric — PR #683 WS3) subsection
    with seven numbered rules (section order, bullet uniformity, header
    casing, indent, blank-line spacing, single canonical EXAMPLE per tool,
    per-tool carve-out allow-list).
  - Add ### Cross-LLM rationale subsection citing the tokenizer-uniformity
    argument across Claude / GPT / Gemini / Llama as the empirical basis
    for the UPPERCASE+colon header shape.
  - Update ### Exemptions and ## Consequences to reflect that ctx_purge is
    no longer deferred — the WS2 rewrite ships with audit-approved
    DESTRUCTIVE/SCOPES/CONTRACT carve-outs allow-listed in the contract
    test, while still meeting the canonical four-section shape.

Contract test extensions (tests/core/server.test.ts):
  - Remove ctx_purge from EXEMPT_FROM_FORBIDDEN_TOKENS and EXEMPT_FROM_WHEN
    (the WS2 rewrite passes the canonical structure with the carve-outs).
  - Add ALLOWED_EXTRA_SECTIONS map carving out DESTRUCTIVE/SCOPES/CONTRACT
    on ctx_purge only, with inline rationale citing Probe 4.
  - Add four new per-tool assertions (run on every non-exempt ctx_* tool):
    1. MUST contain RETURNS: and EXAMPLE: (mandatory presence).
    2. Section order WHEN -> WHEN NOT -> RETURNS -> EXAMPLE (strictly
       increasing flat.indexOf() positions for canonical sections).
    3. UPPERCASE+colon headers must be in the canonical set OR the
       per-tool carve-out list (rejects off-spec sections like CONCURRENCY:
       and TIPS:).
    4. Bullets must be markdown '- ' only (rejects 1./1-/* /•).
  - Add flattenDescription() helper that collapses the literal '\n' escapes
    and joins the "+ \n " concat continuation so the assertions run against
    the shape the host LLM actually sees at tool-selection time.

Two stale-test updates (folded CONCURRENCY: into WHEN: prose):
  - "tool description documents the concurrency field with positive
     guidance" — expect 'parallelize I/O-bound calls' + 'concurrency 4-8'
     + 'CPU-bound or stateful' + 'keep concurrency at 1' (inline now).
  - "PARALLELIZE I/O guidance + locked requests:[] schema in description"
     — expect 'requests: [{url' + 'concurrency 4-8' + 'FTS5 indexing then
     serializes writes' (inline now).

CONTRIBUTING.md L282 compliance: all assertions folded into the existing
tests/core/server.test.ts file; no new test files.

Result: tests/core/server.test.ts goes from 88 to 124 contract assertions
across 7 non-exempt ctx_* tools; all 124 pass. Three pre-existing baseline
failures (ctx_index storage-error + 2 ctx_doctor settings.json) are
environment-specific and not introduced by this PR.

Empirical reference: PR-683-FINALIZE-LOG.md (WS1 verdict table, WS2 probe
design, WS3 before/after section structure).

* fix: skip context-mode redirect echoes in isToolError + rename forbidden_actions test anchor

PR #683 CI failed across all 3 OS on two tests, both downstream of this
PR's own intentional changes:

1. tests/session/continuity.test.ts:79 'outputs additionalContext with
   XML routing block' — Expected <forbidden_actions> tag.

   The PR renamed <forbidden_actions> → <when_not_to_use> in hooks/
   routing-block.mjs (ADR-0002, affirmative framing — describe when NOT
   to reach for a tool instead of declaring it forbidden). The
   continuity test still asserted on the old name. Update the assertion
   to match the new tag + cross-reference ADR-0002 in the failure
   message so a future maintainer who runs `npm test` sees the rename
   instead of a bare diff.

2. tests/opencode-plugin.test.ts:1241 'blocked tool command is replaced
   before execution' — expected snapshot=="", got <session_resume
   events="1"> containing a fake <errors count="1"> with our own echo
   text.

   The PR rewrote the curl/wget/inline-HTTP/WebFetch redirect echo
   from "context-mode: curl/wget blocked. …" to user-friendlier
   "context-mode: curl/wget redirected … retry if it fails with a
   transient DNS error. …". The new copy legitimately mentions failure
   modes ("fails", "transient DNS error"), but `isToolError` at
   src/session/extract.ts:63 keyword-matches /FAIL/i and `failed/i`
   (case-insensitive, no word boundary), so "fails" inside "if it
   fails" triggered a substring match → our OWN guidance echo was
   captured as a session error → next chat would show a fake error in
   <session_resume>.

   Fix: gate isToolError on the unique `context-mode:` prefix. The
   check is defensive at the source — any future copy change to the
   guidance text cannot reintroduce the bug. Match BOTH sides because
   real shell runs report `response = "context-mode: …"` (the echo
   stdout), while the OpenCode plugin test path captures `response =
   'echo "context-mode: …"'` (the raw command itself, never executed).

Verified locally on Node 20:
  npx vitest run tests/session/continuity.test.ts -t "outputs additionalContext"
   → 1 passed
  npx vitest run tests/opencode-plugin.test.ts -t "blocked tool command"
   → 1 passed
  npx vitest run tests/session/  (all 28 files)
   → 594 passed | 4 skipped, no regressions

* fix(routing): drop negation framing from CASE A deny reasons (#683)

All four redirect-style deny reasons in hooks/core/routing.mjs (curl/wget,
inline HTTP, build tools, WebFetch) rewritten to fully positive imperative
voice per ADR-0002 + ADR-0003.

- Removed "(context-window optimization, NOT a network restriction)"
- Removed "Do NOT retry with curl/wget|Bash|WebFetch"
- Replaced "retry if it fails" hedge with imperative "Retry the same call
  on a transient DNS error (EAI_AGAIN, ETIMEDOUT, ENETUNREACH)"

Cross-LLM rationale: negation framing primes LLM attention on the
forbidden item (ironic process theory). Positive routing intent +
explicit capability affirmation + imperative next-action work uniformly
across Claude/GPT/Gemini/Llama.

ADR-0003 amended with §Amendment noting the empirical rationale.
Contract tests in tests/core/server.test.ts gain two guards (PR #683
follow-up) that fail loud if "NOT a network" or "Do NOT retry" reappear.

* test(hooks): update WebFetch + curl deny assertions for affirmative voice (#683)

77f4ec6 rewrote the CASE A deny reasons in hooks/core/routing.mjs to
positive imperative voice. The two existing assertions that pinned the
old "Do NOT retry" / "Think in Code" wording now need to pin the
surviving affirmative anchors instead.

- tests/hooks/integration.test.ts: WebFetch path asserts on the
  "Retry the same call on a transient DNS error" hint and the explicit
  "Call ctx_fetch_and_index" instruction.
- tests/hooks/tool-naming.test.ts: curl redirect path asserts on
  "Call ctx_execute" — the imperative call instruction that absorbed
  the "Think in Code" trainer voice.

Both keep the integration coverage of the redirect path intact while
matching the new wording.

* refactor(server): standardize MCP tool description source format (#683)

Tool descriptions in src/server.ts used two competing source styles —
template literals with embedded "\n\n" escape sequences, and multi-line
string concatenation with "+". Both render identically at runtime but
the inconsistency made the source hard to scan and made the canonical
WHEN/WHEN NOT/RETURNS/EXAMPLE rubric (ADR-0002) harder to enforce by
sight during review.

All multi-section tool descriptions now use a single style: template
literals with real newlines inside the literal. The runtime payload is
unchanged. The forbidden-word + canonical-structure contract tests in
tests/core/server.test.ts (PR #683 WS3) continue to pass against the
normalized source.

* fix(routing+desc): drop org-rationale + normalize RETURNS form (#683)

Second-pass review of PR #683. Two visual / prompt-economy regressions
the first pass missed.

(1) "for context-window efficiency" — org-rationale, not action input.

The first amendment replaced the bare-NOT parenthetical with the
affirmative opener "redirected to <ctx_tool> for context-window
efficiency". The "for X reason" preface is still post-hoc justification
the agent does not need to act on. Compare HTTP 301: the response
carries Location: <new-url> and the client uses it — the server never
appends "for SEO efficiency". The capability affirmation
"<ctx_tool> has full network access" already carries the substantive
signal the rationale was double-encoding.

All four CASE A sites in hooks/core/routing.mjs (curl/wget, inline HTTP,
build tools, WebFetch) now open with "redirected to <ctx_tool>." flat
— affirmative routing intent, no rationale preface.

ADR-0003 gains §Second amendment documenting the rule and rationale.
A new contract test in tests/core/server.test.ts asserts the phrase
"for context-window efficiency" never reappears in any CASE A site.

(2) RETURNS form inconsistency — three tools used inline form.

ADR-0002 L56-57 specifies RETURNS as a header on its own line with the
body indented below (matching WHEN: / WHEN NOT: shape). Three tools
(ctx_execute, ctx_execute_file, ctx_purge) used inline form
("RETURNS: only your printed output.") while four tools used canonical
header+body form. Mert flagged the visual inconsistency on review.

All three inline tools rewritten to header+body form. EXAMPLE: stays
inline per ADR-0002 L59 — the asymmetry is intentional (RETURNS prose
is multi-line capable; EXAMPLE values are one-call-per-line).

A new contract test asserts RETURNS: never appears in inline form on
any multi-section ctx_* tool. Both new guards run alongside the existing
ADR-0002 forbidden-token + canonical-structure suites.

* feat(desc): surface auto-captured session memory in ctx_search + ctx_purge (#683)

context-mode captures 23 categories of structured events at hook time
(decisions, errors, blockers, plans, user prompts, rejected approaches,
file ops, git ops, tasks, latency, MCP tool counts, etc.) and persists
them across compaction. The mechanism is documented in README and the
project CLAUDE.md routing block. The MCP tool descriptions themselves
do not surface this — so at tool-selection time the LLM only sees
"search indexed content" and misses the much larger
search-session-memory capability.

ctx_search description gains:
  - A 4th WHEN: bullet calling out session-memory queries as a valid
    use case alongside indexed content.
  - A RETURNS: note listing the common session-memory source labels
    (decision, error, error-resolution, blocker, plan, user-prompt,
    rejected-approach, compaction) and a pointer to ctx_stats for
    live category counts.
  - A second EXAMPLE: showing a timeline-sorted decision lookup —
    permitted under ADR-0002 L103-106 (tools with two valid input
    shapes MAY include two EXAMPLE lines).

ctx_purge SCOPES block gains:
  - Per-session: clarifies "events" means auto-captured session
    memory so the agent knows what is being deleted.
  - Per-project: adds a "use ctx_stats first to preview category
    counts" hint to prevent destructive surprises.

No structural changes: WHEN/WHEN NOT/RETURNS/EXAMPLE canonical order
preserved, header-on-own-line RETURNS form preserved, no forbidden
tokens introduced, no org-rationale prefaces. 131 ADR-0002 forbidden-
token tests + 7 canonical-structure tests + 12 PR #683 contract tests
all pass.

* feat(desc): principle-first rewrite of ctx_execute/_file + truth-fix ctx_index/fetch (#683)

Five maintainer critiques on tool descriptions, addressed together. Two
overarching principles emerged from the review:

1. PRINCIPLE OVER HEURISTIC. The LLM picks a tool BEFORE seeing the
   output. "Use when output >= 20 lines" is unactionable — the LLM
   can't predict that. Replace with the INTENT principle: "use when you
   intend to derive an answer FROM the data". The LLM knows its own
   intent at tool-selection time.

2. TRUTHFUL RETURN DESCRIPTIONS. ctx_index handler at L2022 returns
   chunk count + source label + ctx_search call hint — NOT a summary.
   The headline "Only a brief summary is returned" was false. Same
   false-claim pattern existed in ctx_fetch_and_index RETURNS
   ("plus an indexing summary"). Reframe as "indexing metadata" and
   make explicit that raw content is NOT echoed back.

ctx_execute (largest rewrite):

- Headline + philosophy paragraph: Think-in-Code is now taught
  explicitly with the concrete 47-files / 700 KB → 3.6 KB example
  (700 KB into conversation vs 3.6 KB summary printed). The principle
  is the load-bearing concept, not the implementation detail.
- WHEN bullets reframed around INTENT (derive / parse / aggregate)
  rather than predicted output size.
- WHEN NOT bullets reframed around INTENT (observe vs process) rather
  than enumerated command shapes.
- Examples replaced: 'npm test | tail -40' (naive truncate) → smart
  grep for failure-relevant lines; awkward 'aws' example → gh JSON
  query with filter+count in code.

ctx_execute_file:

- Same Think-in-Code framing scoped to single-file analysis.
- "raw contents would flood context" reframed in LLM-native terms
  ("every byte you Read enters your conversation memory and costs
  reasoning capacity for the rest of the session"). The LLM does not
  necessarily know which host it is running in or what "context" means
  in technical terms — describe the actual cost in cognitive terms it
  reasons about.
- Better examples: error filtering with count + tail; CSV row count
  with header read.

ctx_index:

- Headline corrected: stores raw content, returns indexing metadata
  + retrieval hint. Nothing is summarized.
- RETURNS body lists what is actually returned: chunk counts (total,
  code-bearing), source label, ctx_search call shape. Makes explicit
  that the raw content is NOT echoed back — it lives in storage and
  is retrievable via ctx_search.
- Added second EXAMPLE showing file-backed path (auto-refresh hash).

ctx_fetch_and_index:

- "raw HTML entering context" → "raw page bytes should NOT enter your
  conversation memory" (same LLM-native phrasing principle).
- RETURNS "plus an indexing summary" → "plus indexing metadata"
  + explicit "Raw content is NOT echoed back" — eradicates the same
  false-claim pattern.

131 ADR-0002 forbidden-token tests + 7 canonical-structure tests + 12
PR #683 contract tests all pass. No structural changes — WHEN / WHEN
NOT / RETURNS / EXAMPLE canonical order preserved, header-on-own-line
RETURNS preserved, no forbidden tokens introduced.

* feat(desc): comprehensive description batch — ranking, TTL custom, capabilities, technical depth (#683)

Maintainer's third-pass review covered ten distinct critiques. Addressed
together because they all stem from the same direction: surface the
load-bearing mechanism the LLM needs to act correctly, in terms the LLM
understands at tool-selection time.

ctx_search — full rewrite. The previous headline ("BM25 over FTS5") sold
the tool short. The actual ranking pipeline is BM25 + Reciprocal Rank
Fusion over two parallel tokenizers (Porter stemming + trigram
substring), plus a proximity rerank pass for multi-term queries, plus
Levenshtein typo correction, plus window-extracted smart snippets.
The knowledge base is unified: ctx_search reaches both content the user
indexed AND auto-captured session memory (26 event categories). WHEN
NOT bullets reframed to intent ("you have an ad-hoc question") so the
tool-name references don't get lost across long conversations.
contentType code|prose filter surfaced. Four EXAMPLE lines cover the
four most common shapes (source-scoped batch, timeline-sorted memory,
contentType-filtered, multi-source recall).

ctx_fetch_and_index — custom TTL (PR #666) now first-class. Default
24h, override per-call with ttl: <ms>, ttl: 0 bypasses like force:true.
Removed the "~3KB" hard preview claim — replaced with mechanism prose.
RETURNS explains the FTS5 single-writer reality and net-latency math
(parallel-fetch + serial-index). Concurrency guardrails kept generic
(I/O-bound 4-8, lower for rate-limited hosts) — no third-party API
specifics (Mert flag: not our policy to editorialize on someone else's
API contract).

ctx_batch_execute — Think-in-Code restored as the load-bearing concept
("concurrency parallelizes FETCH; derivation belongs in code"). Same
generic concurrency guardrails as ctx_fetch_and_index. EXAMPLE shows
the pattern with a summarize-step command at the end.

ctx_execute — background and intent capabilities now surfaced in
description (previously only in the schema field describe). background
covers server/daemon detach. intent triggers auto-index of large output
into the knowledge base, with title+preview return instead of raw stdout.

ctx_execute_file — same intent surfacing for file-derivation output.

ctx_insight — port (default 4747) and sessionDir/contentDir overrides
surfaced. Useful for diagnosing multi-install setups or pointing at a
sibling project's data.

README.md — TTL Cache section rewritten for custom TTL. The "Fresh (<24h)"
hard claim is now "Cache hit (within TTL)" with the default-and-override
mechanism explained. Tools table row for ctx_fetch_and_index updated to
match.

Two contract tests (tests/core/server.test.ts) that pinned the old exact
phrasing for batch_execute / fetch_and_index concurrency guidance now
pin the LOAD-BEARING CONCEPTS via regex (4-8 window, CPU/stateful keep
at 1, FTS5 serial-write) — same coverage, immune to future copy-edits.

Three pre-existing PR #617 failures (ctx_doctor + ctx_index storage path
e2e under CONTEXT_MODE_DIR) remain — out of scope, separate work.

* feat(hooks): apply principle-first pattern to routing-block + 4 CASE A deny reasons (#683)

The MCP tool descriptions in src/server.ts were rewritten over the
previous PR #683 commits to follow a consistent pattern: principle
over heuristic, intent over threshold, LLM-native phrasing over jargon,
Think-in-Code as the load-bearing concept. The hook layer
(routing-block.mjs system-prompt injection + routing.mjs CASE A deny
reasons) had not yet been brought to the same standard.

Two maintainer flags drove the work:
- "bash with output >20 lines → use ..." — the LLM cannot predict
  output size BEFORE running. Threshold-based heuristic, same anti-
  pattern as the original ctx_execute description.
- The curl/wget deny reason doesn't follow the same pattern as the
  description rewrites — overloaded with implementation prescription
  ("Write pure JS with try/catch, no npm deps"), missing principle.

routing-block.mjs (system-prompt injection on every session):

- <priority_instructions> reframed in cognitive-cost terms: "every
  byte enters your conversation memory and costs reasoning capacity
  for the rest of the session". Think-in-Code surfaced explicitly
  ("program the analysis, do not compute it by reading raw data").
- <tool_selection_hierarchy> entries enriched: ctx_search now
  describes the auto-captured session memory it reaches; ctx_batch_-
  execute explains why batching matters (round-trip cost paid once);
  PROCESSING entry frames around derivation intent rather than the
  old "API calls, log analysis, data processing" enumeration.
- <when_not_to_use> intent-based, no thresholds: "intend to PROCESS
  the output" vs "intend to OBSERVE a short fixed output". Same shape
  for Read (analyze vs Edit), WebFetch, ctx_execute/_file file writes.

createReadGuidance / createGrepGuidance / createBashGuidance /
createExternalMcpGuidance:

- All four rewritten with the same intent-based / principle-first
  framing. "May flood context" / "May produce large output" /
  "with output >20 lines" all replaced with intent triggers ("when
  you intend to PROCESS / count / filter / aggregate").
- LLM-native phrasing throughout: "your conversation" not "context",
  "your derived answer" not "your printed summary" (the latter
  implies a pre-shaped narrative; the former matches what code
  actually produces).
- Bash carve-out preserved (mutating state / observational commands)
  but expressed as intent shapes, not enumerated commands.

hooks/core/routing.mjs CASE A deny reasons (curl/wget, inline HTTP,
build tool, WebFetch):

- All four open with the bare "redirected" verb (no preamble), then
  go straight into the imperative call with the principle embedded
  ("derive your answer in code, and print only the result — the raw
  HTTP body stays in the sandbox instead of entering your
  conversation").
- Selection criteria added where multiple paths exist (curl: inline
  derivation via ctx_execute vs persist-for-later-query via
  ctx_fetch_and_index; WebFetch: same).
- "Write pure JS with try/catch, no npm deps" preachiness removed —
  the LLM gets that info from the ctx_execute schema when it actually
  calls the tool. The deny reason stays focused on routing.
- Build tool deny reason now also nudges toward smarter filtering
  (grep over ERROR|warning|FAIL patterns) instead of leaving the
  agent with naive `tail -30` as the only suggested shape.

All four CASE A sites still satisfy the ADR-0003 contract: open with
"redirected", name at least one ctx_* alternative, contain no bare
"BLOCKED" / "NOT a network" / "Do NOT retry" / "for context-window
efficiency". 635 tests pass (was 579 before this batch), zero new
failures. The 3 remaining failures are pre-existing PR #617 ctx_doctor
/ ctx_index storage-path e2e tests — out of scope.