# rtk

Rewrites Pi `bash` tool calls through RTK.

## Install / load

Loaded through the root `pi-ext` package.
See [../../README.md](../../README.md).

Requires `rtk >= 0.23.0` on `PATH`.
If missing or old, the extension prints one warning and stays idle.

## Commands / tools / settings

Pi commands:
none.

Pi tools:
none.

Pi hooks:

- `tool_call`:
  watches builtin `bash` calls and may replace `input.command` with `rtk rewrite` output.

Pi settings:

- `rtk.rewriteTimeoutMs`:
  timeout in milliseconds for `rtk rewrite` and the `rtk --version` probe.
  Env var `PI_RTK_REWRITE_TIMEOUT_MS`.
  Default `2000`.
  Valid values are integers from `1` to `2147483647`.

Precedence: env var, trusted project `.pi/settings.json`, user `~/.pi/agent/settings.json`, default.
Project settings are ignored until the project is trusted.
The value is resolved once per session at session start.
An invalid value never falls through to a lower source.
It produces one warning naming the source and the default `2000` is used.

Env vars:

```text
PI_RTK_REWRITE_TIMEOUT_MS=5000
RTK_DISABLED=1
```

Prefix one command with `RTK_DISABLED=1` to bypass rewriting.

## UI

The bash tool widget is the command indicator.
When RTK applies, Pi shows the rewritten `rtk ...` command.
After session start, Pi checks RTK in the background and warns if it is unavailable or too old.
The first `bash` call waits for that shared check when it is still running.

## Behavior

`rtk` does one thing:

1. registers the `bash` hook without blocking extension load
2. probes `rtk --version` after session start, or on the first `bash` call
3. warns once and leaves commands unchanged if `rtk` is missing or too old
4. ignores non-bash tools
5. ignores empty, already-`rtk`, and disabled commands
6. calls `rtk rewrite <command>` with `rtk.rewriteTimeoutMs` timeout (default 2s)
7. applies exit `0` and `3` rewrites
8. caches exact successful rewrites for the current session
9. locally maps missing `journalctl`, `systemctl status`, `hyprctl clients`, and `ps` filters to `rtk summary`
10. leaves other exit `1`, exit `2`, timeouts, errors, and empty output untouched

## Performance

`rtk rewrite` starts an external process, so repeated exact commands reuse deterministic successful results within one session.
Session transitions clear the cache, and no-match or transient failures remain retryable.
`mise run //extensions/rtk:bench` compares repeated commands against unique-command controls through Pi's test harness and installed RTK executable.
`mise run //extensions/rtk:profile` records a Node CPU profile under `.research/rtk`.
`mise run //extensions/rtk:benchstat <baseline> <candidate>` performs statistical comparison.

No prompt injection.
No status widget.
No command gating.
No output compaction.
No shell-specific helpers.

## Debug

Opt in through [debug configuration](../DEBUG.md).
Safe events: `session.start`, `session.shutdown`, `rtk.status.start`, `rtk.status.finish`.