Repository navigation
Inbox MCP: a command run inside an agent session sends as that session - #1831
Merged
Merged
Conversation
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.
1 task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
plannotator inbox mcpfilledagent_sessionwith a newses_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 itsplannotator_inboxtool) 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 beclaude-code,pioropencode, and the id must match[A-Za-z0-9][A-Za-z0-9._-]{0,127}. Anything else is ignored.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()).agent_sessionout, the shim fills it with that session's id. Onsend_message,submit_guideandrecord_decisionit also fillsagent_hostandagent_namewhen the agent left the host out. The author is then byte for byte what the host'splannotator_inboxtool writes, so the store treats both as one session: the same default thread,asked_by: "me", and the reply wake throughpendingReplies. (read_threadandwait_for_replyhave strict schemas withoutagent_host, so they get only the session.)agent_host, or the same host. An agent that names another host ("codex") gets the shim's own per-processses_id, so a reply to it never wakes the tagged session.agent_sessionto override (documented in AGENTS.md).agent_sessionstill 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 passesagent_sessionitself keeps its threads across restarts.inbox-help.ts) and in theplannotatorskill: "Replies come back to the session that sent the message: send with yourplannotator_inboxtool; inside Claude Code or Pi, a command your session runs also carries the session's identity.". Also updated: AGENTS.md (the shim, thePLANNOTATOR_SESSION_TAGrow, "Session tag"), and the marketing Inbox reference.Pi and OpenCode
PI_SESSION_IDto its bash tool's commands (checked in 0.84.4:resolveSpawnContextdeletes 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).shell.create.beforehook carries no session id. The plugin runs in a server with many sessions, so settingprocess.envthere is not safe. OpenCode 1'sshell.envhook hassessionID, but OpenCode 1 has no wake. Follow-up: a per-session tag when OpenCode 2 passes a session id to the shell hook.PI_SESSION_ID. In the realistic nesting (pi -prun 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.tsrun the shim as a real process against a real Inbox, with a temp HOME and data dir:PLANNOTATOR_SESSION_TAG=claude-code:<id>, the author is{ host: "claude-code", session: <id>, name: "Claude Code" }.read_thread(asked_by: "me") lists it.<id>returns the reply and another session's poll returns nothing.agent_sessionwins.ses_id.PI_SESSION_IDsends as hostpi.__proto__, overlong ids), the per-tool filling, and the names against the mod and OpenCode constants.Checks run:
bun run typecheckbun 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.