Skip to content

Inbox MCP: a command run inside an agent session sends as that session - #1831

Merged
backnotprop merged 2 commits into
mainfrom
fix/inbox-mcp-session-tag
Oct 10, 2026
Merged

backnotprop merged 2 commits into
mainfrom
fix/inbox-mcp-session-tag

Conversation

@backnotprop

@backnotprop backnotprop commented Oct 10, 2026 •

Copy link
Copy Markdown
Owner

Problem

plannotator inbox mcp filled agent_session with a new ses_ id per shim process when the agent left it out. An agent inside Claude Code that scripts the Inbox or runs the CLI (instead of its plannotator_inbox tool) therefore sent as a session that was gone a second later: every send started a new thread, and the person's reply woke nobody.

Fix

  • inboxHostSessionFromEnv (apps/hook/server/inbox-mcp-shim.ts) reads the agent host session the shim runs inside:
    • PLANNOTATOR_SESSION_TAG (<host>:<id>, which the Claude Code mod sets in every process its session starts), validated strictly: the host must be claude-code, pi or opencode, and the id must match [A-Za-z0-9][A-Za-z0-9._-]{0,127}. Anything else is ignored.
    • Otherwise Pi's own PI_SESSION_ID, which Pi sets on each bash tool call. It is the id the Pi connection's tool and wake use (ctx.sessionManager.getSessionId()).
  • When the agent leaves agent_session out, the shim fills it with that session's id. On send_message, submit_guide and record_decision it also fills agent_host and agent_name when the agent left the host out. The author is then byte for byte what the host's plannotator_inbox tool writes, so the store treats both as one session: the same default thread, asked_by: "me", and the reply wake through pendingReplies. (read_thread and wait_for_reply have strict schemas without agent_host, so they get only the session.)
  • The host session is used only when the agent named no agent_host, or the same host. An agent that names another host ("codex") gets the shim's own per-process ses_ id, so a reply to it never wakes the tagged session.
  • A tag inherited by a long-lived process started from an agent's shell (tmux, nohup) keeps naming that session. Pass agent_session to override (documented in AGENTS.md).
  • An explicit agent_session still wins. Without a session variable the shim keeps one id per process. The guide, skill, marketing page and AGENTS.md now say that an MCP client that passes agent_session itself keeps its threads across restarts.
  • No fallback hands an ended session's replies to another session.
  • Docs: one line in the agent guide (inbox-help.ts) and in the plannotator skill: "Replies come back to the session that sent the message: send with your plannotator_inbox tool; inside Claude Code or Pi, a command your session runs also carries the session's identity.". Also updated: AGENTS.md (the shim, the PLANNOTATOR_SESSION_TAG row, "Session tag"), and the marketing Inbox reference.

Pi and OpenCode

  • Pi: Pi exports PI_SESSION_ID to its bash tool's commands (checked in 0.84.4: resolveSpawnContext deletes any inherited value and sets the current one per call). The shim honours it. Nothing was added to the extension. A Pi older than that feature just gets a fresh id. The reply wakes the session only where the Pi inbox tool is on (it is off by default).
  • OpenCode: no follow-up was added. OpenCode 2's shell.create.before hook carries no session id. The plugin runs in a server with many sessions, so setting process.env there is not safe. OpenCode 1's shell.env hook has sessionID, but OpenCode 1 has no wake. Follow-up: a per-session tag when OpenCode 2 passes a session id to the shell hook.
  • Precedence: the Plannotator tag wins over PI_SESSION_ID. In the realistic nesting (pi -p run from a Claude Code session's Bash), the reply then reaches the live Claude Code session, not a print-mode Pi session that cannot be woken.

Tests

The new tests in apps/hook/server/inbox-cli.test.ts run the shim as a real process against a real Inbox, with a temp HOME and data dir:

  • With PLANNOTATOR_SESSION_TAG=claude-code:<id>, the author is { host: "claude-code", session: <id>, name: "Claude Code" }.
  • A call with the mod tool's exact arguments joins the same thread.
  • A second shim process with the same tag also joins that thread, with an identical author, and read_thread (asked_by: "me") lists it.
  • After the person replies, the bridge poll for <id> returns the reply and another session's poll returns nothing.
  • An explicit agent_session wins.
  • A malformed tag gives a fresh ses_ id.
  • PI_SESSION_ID sends as host pi.
  • Unit tests cover the strict parser (malformed tags, __proto__, overlong ids), the per-tool filling, and the names against the mod and OpenCode constants.

Checks run:

  • bun run typecheck
  • bun test apps/hook/server/inbox-cli.test.ts apps/hook/server/inbox-help.test.ts apps/hook/server/plannotator-skill-reference.test.ts packages/server/inbox-bridge.test.ts apps/hook/hooks/mod/inbox.test.ts apps/hook/hooks/mod/inbox-contract.test.ts: 58 pass. A tailscale trap script was first on PATH.

plannotator inbox mcp filled agent_session with a fresh ses_ id per shim
process, so a script or CLI run inside a Claude Code session sent as a
throwaway session: every send started a new thread and the person's reply
woke nobody. The shim now reads the session it runs inside
(PLANNOTATOR_SESSION_TAG from the Claude Code mod, else Pi's PI_SESSION_ID),
validated strictly, and fills agent_session, plus agent_host / agent_name on
the tools that record an author, exactly as the host's plannotator_inbox tool
does. An explicit agent_session still wins; without a session it keeps one id
per process.
…Claude Code and Pi

An agent that passes another agent_host now gets the shim's own ses_ id, so
a reply to it never wakes the tagged session. The guide and skill no longer
promise OpenCode a command identity it does not have; AGENTS.md notes that a
tag inherited by a long-lived process keeps naming its session. Pi's agent
name is pinned to the shim's map.
@backnotprop
backnotprop merged commit e06f137 into main Oct 10, 2026
32 checks passed
@backnotprop
backnotprop deleted the fix/inbox-mcp-session-tag branch October 10, 2026 23:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant