@krtclcdy/tersio 2.25.6 → 2.25.8

package/extensions/pstack/skills/why/references/sources/datadog.md

@@ -0,0 +1,97 @@
+# Datadog Telemetry
+
+## What this source contains
+
+Datadog holds the runtime record, what actually happened in production, as opposed to what was planned or discussed.
+
+- **Metrics.** Counters, gauges, histograms instrumented by the team. A metric's *presence* is itself evidence that someone thought the number worth watching.
+- **Monitors & alerts.** Conditions the team decided warranted waking someone up. A monitor firing on `rate_limit_hit > 10/min` is direct evidence the team worried about that threshold.
+- **Dashboards.** Curated views of what the team considers important for a subsystem.
+- **APM traces & spans.** Request-level runtime data, for "why is this slow" / "why is there a timeout here" questions.
+- **Logs.** High-volume event records, often holding the error conditions that motivated defensive code.
+- **Incidents.** Formal incident records with timelines and linked postmortems.
+- **Notebooks.** The team's exploratory investigations, often with hypotheses and analyses.
+
+## How to search it
+
+Use the Datadog MCP. Start broad, then narrow.
+
+1. **Identify the owning service(s).**
+
+   ```
+   search_datadog_services (filter by name or team)
+   search_datadog_service_dependencies (see upstream/downstream)
+   ```
+
+2. **Dashboards and monitors first.**
+
+   ```
+   search_datadog_dashboards (query: feature name, service name, symbol)
+   search_datadog_monitors   (same queries)
+   ```
+
+   When a dashboard or monitor covers the target, note its queries and watched thresholds. The threshold is frequently the answer to "why is this clamped at N?"
+
+3. **Metrics around the target.**
+
+   ```
+   search_datadog_metrics (by name pattern, e.g., the feature or symbol)
+   get_datadog_metric_context (metadata: description, units, tags)
+   get_datadog_metric (timeseries; "was there a spike around the PR date?")
+   ```
+
+   Correlating a metric's trajectory with the target's add/change date is strong supporting evidence: "the `payment_timeout` metric spiked 2023-11-03, and the retry logic merged 2023-11-06."
+
+4. **Logs. Narrow, don't dump.**
+
+   ```
+   search_datadog_logs (raw log patterns near the target, set use_log_patterns=true)
+   analyze_datadog_logs (SQL-style aggregations, only when you need counts)
+   ```
+
+   Search with symbols, error strings, or feature names. **Strongly prefer time-bounded queries** (e.g., 30 days before/after the change).
+
+5. **APM spans and traces.**
+
+   ```
+   aggregate_spans    (stats: "how often does this endpoint fail?")
+   search_datadog_spans (inspect individual spans)
+   get_datadog_trace  (a specific trace ID)
+   ```
+
+   Useful for timeouts, retries, slow paths, and cross-service behavior.
+
+6. **Incidents.**
+
+   ```
+   search_datadog_incidents (by title, team, date range)
+   get_datadog_incident     (full detail for a specific incident)
+   ```
+
+   If the target looks defensive, search for incidents around the time it was added. An incident whose timeline includes "added defensive check for X" is near-direct evidence.
+
+## What good evidence looks like here
+
+- A monitor whose query and threshold match the constraint the code enforces (code clamps to 100, monitor alerts when requests exceed 100/min)
+- A dashboard created by the target's author, with widgets that correspond to what the code measures or guards against
+- A metric showing a production spike immediately before the code was merged, and stable values after
+- An incident record referencing the target code, the same symbols, or the same error strings
+- Logs showing a specific error pattern the defensive code would prevent, timestamped in the window before the change
+
+## Common pitfalls
+
+- **Correlation is not causation.** A spike before a PR and stabilization after is suggestive, not definitive, since other changes may have landed in the same window. Check neighboring PRs.
+- **Overfitting to the chart you found.** A chart reflects its maker's framing. A chart named "retry success rate" is evidence the team cared about retry success, not that it's why a specific line of code exists.
+- **Vanished telemetry.** Metrics can be renamed, deleted, or have short retention. If you can't find data from the relevant window, that's a gap, not a null result.
+- **Noise at scale.** Narrow log searches by service, tag, and time window aggressively. Use `analyze_datadog_logs` to aggregate rather than dumping raw logs.
+- **Instrumented != caused.** A metric shows someone cared enough to measure something, not that the code was added *because* of it. Cross-reference with commit/PR dates.
+
+## What to return
+
+For each relevant item:
+- Type (dashboard / monitor / metric / log pattern / trace / incident / notebook)
+- Title or name
+- Link or identifier (dashboard ID, monitor ID, metric name, incident ID)
+- Owner/author and created/modified date
+- The specific condition, query, or quote that bears on the question (verbatim where possible)
+- Relevance: what this suggests about the target code, and how strong the connection is

package/extensions/pstack/skills/why/references/sources/incident-postmortem.md

@@ -0,0 +1,5 @@
+# Incident & Postmortem Context
+
+- **Linear**: look for tickets labeled `incident`, `sev-*`, `postmortem-action-item`, `reliability`
+- **Slack**: search `#sev-*` and `#incident-*` channels around the dates the target code was added
+- **Git**: commits with messages like "fix for incident", "add defensive check", "revert" followed by "re-apply with..." are strong signals

package/extensions/pstack/skills/why/references/sources/linear.md

@@ -0,0 +1,48 @@
+# Linear Tickets
+
+## What this source contains
+
+- Issues describing features, bugs, and their motivation
+- Project docs attached to issues (often PRDs or specs)
+- Parent/sub-issue relationships (broader initiative → specific tickets)
+- Comments on issues (clarifications, scope changes, "why we're doing this" rationale)
+- Labels (e.g., `compliance`, `customer-request`, `perf`) that signal the type of motivation
+- Status updates that explain scope changes
+- Attachments and linked GitHub PRs
+
+Linear is where the product/business context often lives: the "we're doing this because customer X asked" or "this is for the Q3 compliance initiative" layer.
+
+## How to search it
+
+Use the Linear MCP.
+
+1. **Start with linked tickets.** If the seed commits or PRs reference ticket IDs (e.g., `ENG-1234`, `[BUG-567]`), fetch those first with `get_issue`. Read the full issue including comments.
+2. **List related issues by keyword.** Use `list_issues` with text search for the feature name, key symbol, or business term. Try multiple phrasings.
+3. **Walk the issue tree.** If you land on a sub-issue, fetch its parent. Sub-issues are tactical. Parents often carry the "why."
+4. **Read project docs.** If the issue belongs to a project, use `get_project` and check attached docs. Project-level documents are where specs and rationale are most often captured.
+5. **Check labels and milestones.** Labels hint at the category of motivation (customer-request, incident-followup, compliance). Milestones tie work to deadlines, which often reveal motivation.
+
+## What good evidence looks like here
+
+- An issue description stating the business problem: "Customer Acme needs X because of their SOC2 audit"
+- A comment recording a decision: "We decided to go with approach B because approach A would require touching the billing service"
+- A parent issue titled like an initiative: "Q3 Enterprise Readiness" or "Reduce Payment Failures"
+- An attached PRD or spec
+- Labels like `customer:acme`, `incident-followup`, `compliance`, `perf-regression`
+
+## Common pitfalls
+
+- **Scope drift.** The ticket the PR references may have been closed and reopened with a different scope. Read the whole history.
+- **Mechanical templates.** Some teams require "Why" sections but fill them with boilerplate. Generic text ("improve user experience") is probably not a real answer.
+- **Stale tickets.** Old tickets often reflect a version of the plan that changed. Check dates and cross-reference with the code's ship date.
+- **Closed-as-duplicate chains.** Follow the duplicate-of relationships back to the canonical ticket.
+- **Private workspace content.** If you can't access an issue, note that as a gap rather than guessing.
+
+## What to return
+
+For each relevant ticket:
+- Ticket ID and title
+- The problem/motivation quoted from the description or comments (not paraphrased. The synthesizer needs the exact text to cite)
+- Labels, parent issue, project
+- Author, created date, closed date
+- Link to the ticket if available

package/extensions/pstack/skills/why/references/sources/notion.md

@@ -0,0 +1,55 @@
+# Notion Docs
+
+## What this source contains
+
+- PRDs (product requirement documents)
+- Technical specs and RFCs
+- Architectural decision records (ADRs)
+- Meeting notes from design reviews
+- Team pages with domain context
+- Postmortems from incidents
+- Runbooks that may explain defensive code
+- Strategy documents that set priorities
+
+Notion is where "why" often lives in long-form before it becomes code. A significant feature usually has a doc.
+
+## How to search it
+
+Use the Notion MCP.
+
+1. **Keyword searches with `notion-search`.** Try:
+   - The feature name
+   - Key symbols / class names from the target code
+   - Author handles (design docs are often authored before the code lands)
+   - Error strings or user-visible terms
+   - Time-bounded queries if you know when the code shipped
+2. **Fetch candidate pages with `notion-fetch`.** Read the full content, not the preview. Rationale is often buried mid-document.
+3. **Follow backlinks and child pages.** Design docs often have sub-pages for alternatives considered, appendices, or implementation notes.
+4. **Check related databases.** `notion-query-data-sources` and `notion-query-meeting-notes` can surface meeting notes that discussed the decision.
+5. **Search author-specific spaces.** If the PR author has a personal notebook (common at some companies), it may hold exploratory thinking that preceded the code.
+
+## What good evidence looks like here
+
+- A PRD with a "Problem statement" or "Motivation" section that matches the target code's purpose
+- An "Alternatives considered" or "Rejected approaches" section
+- A postmortem that names the target code as the fix for a specific incident
+- Meeting notes that record "we decided X because Y" and tie to the same author/date range as the PR
+- An ADR template filled out non-trivially (status, context, decision, consequences)
+
+## Common pitfalls
+
+- **Outdated docs.** Specs are often written before implementation and not updated. The doc may describe a plan that changed. Cross-check against the actual PR.
+- **Doc vs. reality drift.** A spec may say "we'll do X" but the code actually does Y. Flag the divergence. The synthesizer will surface the contradiction.
+- **Boilerplate templates.** Some orgs require a "Why" section that gets filled with fluff. Look for specificity.
+- **Unlinked docs.** The most relevant doc may not be linked from anywhere. Broad keyword searches help.
+- **Multiple drafts.** If a topic has multiple docs, find the one that was finalized or most recently updated. Check dates.
+- **Access-restricted pages.** If you can't access a page, note it as a gap.
+
+## What to return
+
+For each relevant doc:
+- Title and URL
+- Authors and last-updated date
+- The motivation text (verbatim quote), with page/section location
+- Relevant linked pages (so the synthesizer can cite them)
+- Whether the doc was finalized or draft

package/extensions/pstack/skills/why/references/sources/sentry.md

@@ -0,0 +1,66 @@
+# Sentry Error History
+
+## How to search it
+
+Use the Sentry MCP.
+
+1. **Orient.** If you don't know the project slug and organization:
+
+   ```
+   find_organizations
+   find_projects
+   ```
+
+2. **Search for issues related to the target.**
+
+   ```
+   search_issues (natural language, e.g., "errors in PaymentService timeout", "unhandled exceptions in uploadFile")
+   ```
+
+   Build queries from the exception class names the target handles, its function or class name, the error message strings it checks for, and its file path.
+
+3. **Narrow by release and time window.**
+
+   ```
+   search_issue_events (filter by release, time, environment, trace ID, tags)
+   get_issue_tag_values (for an issue, see distribution across versions, users, environments)
+   ```
+
+   For a suspected issue, check **first seen** and **last seen** (does the stop line up with the target's ship date?), the **affected releases** (which saw it, and which was the fix?), and the **frequency trajectory** (did it spike, then get resolved?).
+
+4. **Pull the full event for context.**
+
+   ```
+   get_sentry_resource (pass a Sentry URL or type+ID)
+   ```
+
+   Does the stack trace pass through the target code? Do the tags and breadcrumbs match the conditions the target defends against?
+
+5. **Check releases that landed near the target.**
+
+   ```
+   find_releases (around the commit date of the target)
+   ```
+
+   Cross-reference release version with the PR's merge date.
+
+6. **Use Seer sparingly.**
+
+   ```
+   analyze_issue_with_seer
+   ```
+
+   Seer's AI root-cause analyses are a hypothesis generator. Treat them as inference, not authoritative. The actual events and stack traces are the primary evidence.
+
+## What to return
+
+For each relevant issue:
+- Issue ID and title
+- Project and organization
+- First seen / last seen timestamps
+- Event count (and sampling rate if known)
+- Affected releases
+- A representative stack trace snippet showing relevance to the target (verbatim excerpt, not summary)
+- First/last-seen correlation with the target's ship date
+- Link to the issue
+- Any author comments or resolution notes

package/extensions/pstack/skills/why/references/sources/slack.md

@@ -0,0 +1,17 @@
+# Slack Conversations
+
+## How to search it
+
+Slack MCP tools vary. Check which Slack MCP is available and inspect its tool schema first. It may require `mcp_auth`. If authentication fails, stop and report the gap.
+
+1. **Author-bounded search.** Messages from the PR author around the PR merge date. Limits scope dramatically and often hits gold.
+3. **PR URL search.** Slack often links PRs when they're reviewed or discussed. Search for the PR URL (or just `/pull/<number>`).
+4. **Error string search.** If the code handles a specific error, search for the error string. Incident threads often surface.
+
+## Common pitfalls
+
+- **Channel archaeology limits.** Very old messages may be gone due to retention policies. If you can't find anything before a certain date, note the retention cliff.
+- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them. That's a known limitation.
+- **Speculative jokes as "decisions."** Slack is casual. "Lol just do the thing" isn't a decision, even if it preceded the commit. Look for considered discussion.
+- **Context collapse in single messages.** Without the thread, a single message often reads differently than in context. Always fetch threads.
+- **Auth failures.** If the MCP isn't authenticated, stop. Don't make up findings. Report that Slack wasn't searchable.

package/extensions/pstack/skills/why/references/synthesizer-prompt.md

@@ -0,0 +1,129 @@
+# Synthesizer Prompt Template
+
+Fill in the placeholders.
+
+---
+
+You are answering a "why" question about a piece of code by synthesizing findings from investigators who searched different historical sources (source control, issue / ticket tracker, long-form documents, real-time team chat, infrastructure observability, error / exception tracking, product analytics warehouse, and code comments). Produce a confidence-weighted, evidence-cited narrative that says honestly what the evidence supports, and just as honestly what it doesn't.
+
+## The Question
+
+> {QUESTION}
+
+## The Code Anchor
+
+**Target files:** {FILES_WITH_LINE_RANGES}
+
+**Key symbols:** {SYMBOLS}
+
+## Investigator Findings
+
+{ALL_INVESTIGATOR_FINDINGS}
+
+## Sources That Weren't Searched
+
+{SKIPPED_SOURCES_WITH_REASONS}
+
+## Epistemics Framework
+
+You MUST follow `references/epistemics.md`. Read it in full before writing. The key rules:
+
+1. Every claim must sit in one tier: **Direct**, **Supported**, **Inferred**, **Speculative**, **Unknown**. The tier sets its section and its phrasing.
+2. Every Direct/Supported claim must have a citation (PR #, ticket ID, doc URL, chat permalink, commit hash, or file:line).
+3. Inferred and Speculative claims must use hedged language ("appears to", "likely", "suggests", "one possibility is").
+4. Never cite code as evidence for its own intent.
+5. Document gaps. Don't fill them with plausible-sounding guesses.
+6. Treat a hypothesis embedded in the user's question as a candidate, not a conclusion. Check it independently.
+
+## Instructions
+
+1. **Read all investigator findings** and weigh the evidence yourself. Investigators gathered raw evidence, not conclusions.
+2. **Merge overlaps.** When several investigators cite the same PR, ticket, or doc, give it one authoritative reference.
+3. **Surface contradictions.** When two items disagree, show both. Don't pick one.
+4. **Calibrate each claim.** Find its evidence and tier. Direct: cite it and state it plainly. Inferred: hedge it and show the inference. Speculative: mark it. No evidence: put it in the gaps.
+5. **Verify citations by spot-checking.** If you're uncertain a cited item exists or says what the investigator claims, check it by reading the codebase or calling MCP tools. Don't propagate errors. Do not write files, commit, or modify external state.
+6. **Don't overreach.** The user will act on this. Leave an open question open rather than fill it with a confident guess.
+
+## Output Format
+
+Write for the user, in this exact structure:
+
+---
+
+### The Question
+
+Restate the user's question in one or two sentences.
+
+### The Code in Question
+
+File paths, line ranges, key symbols. Two or three lines to orient a cold reader.
+
+### What We Found
+
+Claims with textual evidence, each quoted or paraphrased and cited precisely:
+
+- **[Direct]** {Claim}. Source: [PR #123](url) / ticket ID / file:line. {Brief quote or paraphrase.}
+- **[Supported]** {Claim}. Evidence: {list of items and what each contributes}.
+
+`[Direct]` is single-source, explicit evidence. `[Supported]` is multiple indirect items converging on a conclusion.
+
+### What We Can Reasonably Infer
+
+Claims stated nowhere but well-supported by indirect evidence. Each bullet must make the inference chain visible ("Given A and B, it's likely that C") and must use hedged language ("appears to", "likely", "suggests", "is consistent with"):
+
+- **[Inferred]** {Hedged claim}. Reasoning: {the specific evidence and the inference step}.
+
+Skip this section if there's nothing to infer.
+
+### Competing Hypotheses
+
+If the evidence fits multiple stories, present each. Don't force a winner the record doesn't support. For each hypothesis:
+
+- **Hypothesis:** {one-sentence statement}
+- **Evidence for:** {specific items}
+- **Evidence against or missing:** {what would need to be true but isn't, or what counter-signals exist}
+
+Skip this section if there's a single clear answer.
+
+### What We Don't Know
+
+Specific gaps: "We searched the issue tracker for [query1], [query2], [query3] and found no issue discussing the rate-limit threshold", not "We don't know why." Include:
+
+- Questions that went unanswered
+- Searches that returned nothing
+- Sources that were unavailable, and why (such as a missing real-time team chat MCP)
+- People who would likely know but whom you can't ask
+
+### Sources Consulted
+
+What was actually searched, so the user can judge coverage and redirect:
+
+- **Source control history**: {file paths}, {number of commits reviewed}, PRs #{numbers}, and code comments searched. Or "Not searched. This should not happen because git and `gh` are always expected."
+- **Issue / ticket tracker**: {ticket IDs and keyword searches}. Or "Not searched. No matching MCP available in this environment."
+- **Long-form documents**: {page titles and search queries}. Or "Not searched. No matching MCP available in this environment."
+- **Real-time team chat**: {channels searched, date ranges, queries}. Or "Not searched. No matching MCP available in this environment."
+- **Infrastructure observability**: {dashboards, monitors, metrics, logs, traces, or incidents searched}. Or "Not searched. No matching MCP available in this environment."
+- **Error / exception tracking**: {issues, events, or releases searched}. Or "Not searched. No matching MCP available in this environment."
+- **Product analytics warehouse**: {fully-qualified tables queried, the time windows, and the numeric summaries (counts, percentiles, first/last-seen timestamps) that bore on the question}. Or "Not searched. No matching MCP available in this environment."
+
+### Confidence Summary
+
+One or two sentences on overall confidence, e.g.:
+
+> "The core rationale (A) is well-supported by direct PR and ticket evidence. The specific threshold value (100) is inferred from the surrounding context but not explicitly documented. The question of whether this was driven by a customer request could not be answered. No relevant issue tracker or long-form doc content surfaced, and real-time team chat search was unavailable."
+
+---
+
+## Quality Check Before Returning
+
+Revise if any item fails:
+
+1. Does every claim in "What We Found" have a citation? If not, add one or move it to "Inferred" or "Hypotheses."
+2. Is the phrasing tier-appropriate? (Direct claims can use "because". Inferred claims cannot.)
+3. Did you surface every contradiction you noticed, or quietly pick one?
+4. Does "What We Don't Know" name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps.
+5. Did you check any hypothesis embedded in the question against the evidence rather than rubber-stamp it?
+6. Did you cite code as evidence for its own intent? Remove it. Code is mechanics, not motivation.
+7. Is the tone calibrated? A confident-sounding answer on weak evidence is the exact failure this skill exists to prevent.
+
+The value of this output is its honesty, not its authority. A reader who takes it to the original author, an engineering lead, or a product manager should know what's known, what's inferred, and what's missing, so they can ask the right follow-up questions. Optimize for being useful, not for looking decisive.

package/extensions/rtk/filter.ts

@@ -5,6 +5,8 @@ import { join } from 'node:path';
 import { resolveRtkBinary } from '../shared/utils.ts';
 import { readRtkDefault } from '../shared/plugin-settings.ts';
 import { getSharedComboState, lastCustomValue, sessionEntries } from '../shared/session-state.ts';
+import { appendUsage } from '../shared/usage-ledger.ts';
+import { isPiHost } from '../shared/host.ts';
 import type { ExtensionApi, ExtensionCtx, SessionEntry, ToolResultEvent } from '../shared/types.ts';
 
 /** Tool name to `rtk pipe --filter` name. Exported so the OpenCode host reuses one map. */
@@ -18,8 +20,13 @@ export const FILTER_BY_TOOL = new Map([
 export const MIN_FILTER_BYTES = 1200;
 const FILTER_TIMEOUT_MS = 5000;
 
-/** Absolute, so a minimal PATH in the host cannot break the spawn. */
-const SHELL = '/bin/sh';
+// A shell that understands `<`, resolved per platform; separate flags, because Node quotes each argv element and cmd.exe rejects `"/d /s /c"`.
+/** The pipe's shell, and whether the whole command needs an extra quote pair: `cmd.exe /s` strips the outer one, so a quoted binary and redirect path must be wrapped. */
+export function filterShell(): { shell: string; flags: string[]; wrap: boolean } {
+  return process.platform === 'win32'
+    ? { shell: process.env.ComSpec || 'cmd.exe', flags: ['/d', '/s', '/c'], wrap: true }
+    : { shell: '/bin/sh', flags: ['-c'], wrap: false };
+}
 
 export type FilterExec = (
   cmd: string,
@@ -58,8 +65,10 @@ export async function filterThroughRtk(
     dir = mkdtempSync(join(tmpdir(), 'tersio-rtk-'));
     const file = join(dir, 'in.txt');
     writeFileSync(file, text, 'utf8');
-    // `rtk pipe` reads stdin only and execFile has no stdin, so one redirect.
-    const result = await exec(SHELL, ['-c', `"${bin}" pipe -f ${filter} < "${file}"`], { signal, timeout: FILTER_TIMEOUT_MS });
+    // `rtk pipe` reads stdin only and execFile has no stdin, so one redirect through the platform shell.
+    const { shell, flags, wrap } = filterShell();
+    const line = `"${bin}" pipe -f ${filter} < "${file}"`;
+    const result = await exec(shell, [...flags, wrap ? `"${line}"` : line], { signal, timeout: FILTER_TIMEOUT_MS });
     if (result.code !== 0) return null;
     const out = result.stdout;
     if (!out.trim() || out.length >= text.length) return null;
@@ -71,10 +80,48 @@ export async function filterThroughRtk(
   }
 }
 
+/** A bash tool call, before it runs. pi and omp hand the extension the mutable input. */
+interface BashCallEvent {
+  toolName?: unknown;
+  input?: { command?: unknown };
+}
+
+/** Ask rtk for the rewritten command; null on any failure, so the original runs. */
+async function rewriteCommand(
+  exec: FilterExec,
+  bin: string,
+  command: string,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  try {
+    const result = await exec(bin, ['rewrite', command], { timeout: FILTER_TIMEOUT_MS, signal });
+    const out = result.stdout.trim();
+    return out || null;
+  } catch {
+    return null;
+  }
+}
+
 export default function rtkFilterExtension(pi: ExtensionApi): void {
   const bin = resolveRtkBinary();
   const exec = pi.exec;
   if (!bin || !exec) return;
+  // omp records the post-hook command in its transcript, so only pi leaves an audit row here:
+  // opencode rewrites in its own plugin hook, and an omp row would double-count the transcript.
+  const auditHost = isPiHost(pi) ? 'pi' : null;
+  // Registered synchronously, unlike the rtk-init hook, whose async version probe can miss the first call of a fast session.
+  pi.on('tool_call', async (event, ctx: ExtensionCtx) => {
+    const call = (event ?? {}) as BashCallEvent;
+    const input = call.input;
+    if (call.toolName !== 'bash' || !input) return;
+    const command = input.command;
+    if (typeof command !== 'string' || !command.trim() || command.startsWith('rtk ')) return;
+    if (!rtkActive(sessionEntries(ctx))) return;
+    const rewritten = await rewriteCommand(exec, bin, command, ctx?.signal);
+    if (!rewritten || rewritten === command) return;
+    input.command = rewritten;
+    if (auditHost) appendUsage('rtk-audit', `${auditHost} ${command}`);
+  });
   pi.on<ToolResultEvent>('tool_result', async (event, ctx: ExtensionCtx) => {
     const filter = FILTER_BY_TOOL.get(String(event?.toolName ?? '').toLowerCase());
     if (!filter || event?.isError) return;

package/extensions/rtk/session.ts

@@ -1,7 +1,7 @@
 import { getSharedComboState, hasModeState, isOmpSubagentPrompt, lastCustomValue, reconcileSharedComboEntries, sessionEntries, setSharedComboListener, setSharedComboMode, systemPromptIncludes } from '../shared/session-state.ts';
 import { injectPromptText, onHostEvent, setExtensionLabel, stringArrayToolParams } from '../shared/host.ts';
 import { readRtkDefault } from '../shared/plugin-settings.ts';
-import { resolveRtkBinary } from '../shared/utils.ts';
+import { resolveRtkBinary, shimCommand } from '../shared/utils.ts';
 import { announceStatus } from '../shared/status.ts';
 import type { ExtensionApi, ExtensionCtx, SessionEntry, SystemPromptEvent } from '../shared/types.ts';
 
@@ -23,8 +23,11 @@ function setRtkProcessEnabled(enabled: boolean): void {
   else process.env.RTK_DISABLED = '1';
 }
 
-// rtk's contract: name the rewritten surface, never the binary — a hand-typed `rtk` fights the rewrite.
-const RTK_PROMPT = `RTK guidance active. What you run is condensed automatically: searches (grep, rg), listings (ls, find, cat as read), package and test runs (bun, npm run, pnpm run), version control (git), and type and lint checks (tsc, eslint). Every signal kept, costly noise dropped. Treat a condensed result as complete. Re-run something unfiltered only when its result is empty, garbled, or contradicts its exit code. A command with no condensed form passes through unchanged.`;
+// rtk's contract: name the rewritten surface first and the binary second — a hand-typed `rtk` in front of a
+// rewritten command fights the rewrite, and the direct calls cover only what the rewrite cannot express.
+const RTK_PROMPT = `RTK guidance active. What you run is condensed automatically, in the host's own rewritten form: searches (grep, rg, ast-grep), listings (ls, find, tree), reads (cat), package and test runs (bun, npm, pnpm, npx, cargo, go, pytest, vitest, jest, ctest, tsc), version control and forges (git, gh, glab), containers and clusters (docker, kubectl), cloud and platform CLIs (aws, oc, dotnet), PHP tooling (phpunit, pest, phpstan, pint, ecs), lint and format (eslint, ruff, mypy, prettier, sqlfluff, playwright, prisma, next), and data tools (jq, curl, wget, psql, wc, make, tail, docker logs). The runner's own subcommand, such as \`rtk bun run test\`, keeps the failing test name, the assertion, and the file and line. Every signal kept, costly noise dropped. Treat a condensed result as complete. Re-run something unfiltered only when its result is empty, garbled, or contradicts its exit code.
+
+Call rtk directly for what the rewrite cannot express: \`rtk read <file> --level aggressive\` for an overview, \`--max-lines N\` for a preview, \`rtk smart <file>\` for a two-line summary, \`rtk summary <cmd>\` for a heuristic one, \`rtk err <cmd>\` for errors only, \`rtk log <file>\` to dedupe logs, \`rtk json <file>\` with \`--keys-only\` for shape, plus \`rtk deps\`, \`rtk diff\`, \`rtk env\`, \`rtk ast-grep\`, and \`rtk test <cmd>\` for a runner without its own form. A command with no condensed form passes through unchanged, so wrap it: \`rtk err node build.js\`, and \`rtk find -name '*.ts'\` in place of fd. Never type \`rtk\` in front of a command listed above.`;
 
 export default function rtkSessionExtension(pi: ExtensionApi): void {
   let enabled = DEFAULT_ENABLED;
@@ -73,27 +76,34 @@ export default function rtkSessionExtension(pi: ExtensionApi): void {
   pi.registerTool?.({
     name: 'rtk_run',
     label: 'RTK Run',
-    description: 'Run the installed `rtk` binary for compact command output when RTK mode is enabled.',
+    description: 'Run a shell command through the installed `rtk` binary when RTK mode is on, and run it plainly when RTK mode is off.',
     parameters: stringArrayToolParams(pi, 'args', {
       minItems: 1,
       description: "Arguments passed to rtk, e.g. ['git','status'] or ['read','src/index.ts']",
     }),
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       // A subagent's own flag sits at its start-up default, so honour shared state too.
-      if (!(enabled || getSharedComboState().rtk === 'on')) return fail('RTK mode is off. Run /rtk on for this session, or use bash explicitly.');
+      const rtkOn = enabled || getSharedComboState().rtk === 'on';
       if (typeof pi.exec !== 'function') return fail('This host cannot run rtk.');
-      onUpdate?.({ content: [{ type: 'text', text: `rtk ${params.args.join(' ')}` }], details: { phase: 'start' } });
+      // RTK off: run the command as given rather than answering "mode is off". The tool is the only one left under --no-tools, and a refusal there made the model spend turns re-calling it. rtk is the condenser, never the command.
+      const cwd = ctx?.cwd || pi.cwd;
+      const bin = rtkOn ? resolveRtkBinary() : null;
+      if (rtkOn && bin === null) return fail('RTK mode is on but the rtk binary is not installed. Run: tersio update');
+      const argv = params.args;
+      onUpdate?.({ content: [{ type: 'text', text: `${bin === null ? '' : 'rtk '}${argv.join(' ')}` }], details: { phase: 'start' } });
       try {
         // A GUI-launched host may lack ~/.bun/bin on PATH, so prefer the resolved path.
-        const result = await pi.exec(resolveRtkBinary() ?? 'rtk', params.args, { signal, cwd: ctx?.cwd || pi.cwd });
+        // A `.cmd` shim cannot be spawned directly on Windows, so it runs through the shell.
+        const shim = shimCommand(bin ?? argv[0], argv);
+        const result = await pi.exec(shim.cmd, shim.args, { signal, cwd });
         const text = [result.stdout, result.stderr].filter(Boolean).join('\n');
         return {
           isError: result.code !== 0,
-          content: [{ type: 'text', text: text || `rtk exited ${result.code}` }],
-          details: { code: result.code, killed: result.killed, enabled },
+          content: [{ type: 'text', text: text || `exited ${result.code}` }],
+          details: { code: result.code, killed: result.killed, enabled, condensed: bin !== null },
         };
       } catch (e) {
-        return fail(`rtk could not run: ${e instanceof Error ? e.message : String(e)}`);
+        return fail(`${bin === null ? argv[0] : 'rtk'} could not run: ${e instanceof Error ? e.message : String(e)}`);
       }
     },
   });