From 68d6066c5792f778d91b868b94798477f14c1c6b Mon Sep 17 00:00:00 2001
From: t <t@t>
Date: Sun, 7 Jun 2026 17:56:46 +0800
Subject: [PATCH] =?UTF-8?q?feat(cli):=20add=20/btw=20=E2=80=94=20queue=20a?=
 =?UTF-8?q?=20context=20note=20without=20firing=20a=20turn?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

/btw <note> appends a "by the way" note to the conversation history (via
ctx.newHistory) so the agent sees it with your next message, without running an
agent turn now. Useful for steering mid-task ("/btw use tabs not spaces").

Tests (+2): queues the note into newHistory; usage with no arg. cli 145.
Doc: /btw 🔄 → 🟡 (exact Claude Code behavior may differ; this is the useful
DeepCode interpretation). Deliberately did NOT guess at /terminal-setup escape
codes or /migrate-installer — those stay 🔄 pending verified specifics.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/cli/src/commands.ts             | 18 ++++++++++++++++++
 apps/cli/src/parity-commands.test.ts | 15 +++++++++++++++
 docs/BEHAVIOR_PARITY.md              |  2 +-
 3 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/apps/cli/src/commands.ts b/apps/cli/src/commands.ts
index 3e1c8a7..1515b37 100644
--- a/apps/cli/src/commands.ts
+++ b/apps/cli/src/commands.ts
@@ -1117,6 +1117,23 @@ export const PrivacySettingsCommand: SlashCommand = {
   },
 };
 
+export const BtwCommand: SlashCommand = {
+  name: '/btw',
+  description: 'Add a "by the way" note to the context (no agent turn fired).',
+  run(args, ctx) {
+    const note = args.join(' ').trim();
+    if (!note) {
+      return ['Usage: /btw <note> — queues a side-note the agent sees with your next message.'];
+    }
+    const base = ctx.history ?? [];
+    ctx.newHistory = [
+      ...base,
+      { role: 'user', content: [{ type: 'text', text: `(By the way: ${note})` }] },
+    ];
+    return [`Noted — the agent will see this with your next message.`];
+  },
+};
+
 export const BUILTIN_COMMANDS: SlashCommand[] = [
   HelpCommand,
   ClearCommand,
@@ -1152,6 +1169,7 @@ export const BUILTIN_COMMANDS: SlashCommand[] = [
   PrCommentsCommand,
   UpgradeCommand,
   PrivacySettingsCommand,
+  BtwCommand,
 ];
 
 // ──────────────────────────────────────────────────────────────────────────
diff --git a/apps/cli/src/parity-commands.test.ts b/apps/cli/src/parity-commands.test.ts
index 5448f86..1950df2 100644
--- a/apps/cli/src/parity-commands.test.ts
+++ b/apps/cli/src/parity-commands.test.ts
@@ -208,3 +208,18 @@ describe('/resume <id> (live switch)', () => {
     expect(out.join('\n')).toMatch(/Recent sessions/);
   });
 });
+
+describe('/btw', () => {
+  it('queues a context note into newHistory', async () => {
+    const c = ctx({ history: [{ role: 'user', content: [{ type: 'text', text: 'hello' }] }] });
+    const out = await reg.match('/btw')!.cmd.run(['use', 'tabs'], c);
+    expect(out.join('\n')).toMatch(/Noted/);
+    expect(c.newHistory).toHaveLength(2);
+    expect(JSON.stringify(c.newHistory)).toContain('use tabs');
+  });
+
+  it('shows usage with no note', async () => {
+    const out = await reg.match('/btw')!.cmd.run([], ctx());
+    expect(out.join('\n')).toMatch(/Usage: \/btw/);
+  });
+});
diff --git a/docs/BEHAVIOR_PARITY.md b/docs/BEHAVIOR_PARITY.md
index 9c985e5..1d11f10 100644
--- a/docs/BEHAVIOR_PARITY.md
+++ b/docs/BEHAVIOR_PARITY.md
@@ -41,7 +41,7 @@ Legend: `✅` matches · `🟡` matches with caveats · `🔄` deferred · `⚠
 | `/plugins`                 | ✓           | ✓                  | ✅ — lists wired plugins + contributed hook events + warnings (M5.2)                                                                 |
 | `/compact`                 | ✓           | ✓                  | ✅ — manual `/compact` + automatic threshold trigger in the agent loop                                                               |
 | `/diff`                    | ✓           | ✓                  | ✅ — git diff + untracked files in the working tree (PR #150)                                                                        |
-| `/btw`                     | ✓           | ✗                  | 🔄                                                                                                                                   |
+| `/btw`                     | ✓           | ✓                  | 🟡 — queues a "by the way" context note the agent sees with your next message (no turn fired); exact Claude Code behavior may differ |
 | `/recap`                   | ✓           | ✓                  | ✅ — provider-summarized recap of the session so far                                                                                 |
 | `/rewind`                  | ✓           | ✓                  | ✅ — 5 ops (code/conversation/both/summarize-from/up-to); `Esc Esc` bound                                                            |
 | `/voice`                   | ✓           | ✗                  | 🔄 M8                                                                                                                                |