---
id: TAMQ-WP-0006
type: workplan
title: "Shell-native message routing and explicit inbox filters"
domain: communication
repo: tmux-amq
status: active
owner: codex
topic_slug: coulomb-social
planning_priority: P0
planning_order: 11
created: "2026-08-24"
updated: "2026-08-24"
state_hub_workstream_id: "ea96613b-c9db-507e-bfa4-33bd046ef1bc"
---

# Shell-native message routing and explicit inbox filters

Make manual messaging usable from the ordinary shells that tamq opens. The
shell must recognize a repository address before trying to execute it, while
tamq remains neutral about shells, agents, and interactive programs.

## Required operator contract

Root help exposes the session shorthand and its explicit initial-command
option:

```bash
tamq --help
tamq --command codex flex-auth audit-core
```

Starting a session makes commands for its repository names available on each
new managed shell's `PATH`:

```bash
tamq flex-auth audit-core
@audit-core: Some message!
@flex-auth Another message
```

These are per-session executable command shims, not shell aliases. They enqueue
messages and do nothing else by default. Reading a manual inbox produces
comment-safe text:

```text
#flex-auth: Some message! [m-...]
```

An operator may explicitly consume pending messages through a command:

```bash
tamq inbox --filter 'cat >> msg.log'
```

The filter receives one comment-safe message on standard input with message
metadata in environment variables. A zero exit acknowledges that message; a
failure leaves it pending and stops processing. No filter runs in the
background, modifies a pane, or becomes a startup default.

## Expose the session shorthand in root help

```task
id: TAMQ-WP-0006-T01
status: progress
priority: high
state_hub_task_id: "f6228d55-37f0-5be6-a868-f681f09d091b"
```

Document repository-first invocation and `--command COMMAND` in `tamq --help`,
including the terminal-neutral default and exact opt-in nature of the command.

## Install shell-native repository address commands

```task
id: TAMQ-WP-0006-T02
status: todo
priority: high
state_hub_task_id: "432e737c-b34e-56aa-8003-3f61e8ef4faf"
```

Create a private command directory for the managed session, populate it with
safe `@repo` and `@repo:` entry points for every requested repository, and add
that directory to each newly created window's environment. Invocation must
route through tamq's existing validation and durable send path. Reject unsafe
repository names rather than creating ambiguous executable paths.

## Make manual inbox output comment-safe

```task
id: TAMQ-WP-0006-T03
status: todo
priority: high
state_hub_task_id: "b4ff430d-3b09-56de-9c1a-20afb018964c"
```

Render human-readable messages as shell comments prefixed with `#sender:` and
retain the message id for acknowledgement. Keep structured JSON stable for
automation.

## Add explicit pull-time inbox filters

```task
id: TAMQ-WP-0006-T04
status: todo
priority: high
state_hub_task_id: "d413ad83-06ff-5de1-97aa-256b4f684007"
```

Add `tamq inbox --filter COMMAND`. Invoke the command once per pending message,
pass only the comment-safe representation on standard input, expose bounded
metadata through environment variables, acknowledge only after a zero exit,
and leave failed and subsequent messages pending. Filters are explicit inbox
consumers and never background terminal interceptors.

## Prove and document the ordinary-shell workflow

```task
id: TAMQ-WP-0006-T05
status: todo
priority: high
state_hub_task_id: "da957158-fb75-5232-9610-7684ebca45b5"
```

Cover root help, both address spellings, spaces and shell metacharacters in
message bodies, unknown targets, comment-safe inbox output, successful and
failed filters, acknowledgement behavior, path isolation, and installed tmux
acceptance. Update the operator quickstart and practical command reference.