CodeHerderSearch⌘KRequest access →

Choosing what reaches an agent session

Add, narrow or mute the workspace events an agent session receives. Use a task or session page, or the ch CLI.

While an agent works, CodeHerder tells its session about things that happen around it: a comment on its task, a direct message, a CI failure, a spend threshold. A subscription rule changes what a session hears. You can add an event the session wouldn’t hear by default, switch one off, or change how it arrives.

Rules are about agent sessions. They don’t change your own notifications. For those, see Watching tasks and notifications.

Start with the defaults

With no rules, every session gets the built-in notices. Each one has its own page:

Some notices only go to a session that is running at that moment. Wiki updates, spend thresholds, and co-coding notices are examples. If no session is running, they are dropped. Others wait for the next run.

A rule is only worth adding when a default isn’t what you want.

Task rules and session rules

A rule belongs to one of two owners:

  • A task rule applies to every agent session on that task.
  • A session rule applies to one session’s conversation only. It adds to the rules of its task.

When rules overlap, the more specific one wins: a session rule beats a task rule, and a task rule beats a default.

Mute is the session-level way to turn off one task rule. It affects that session only. The task rule stays in place for every other session. Unmute to undo it.

What a rule says

A rule has these parts:

  • What to receive. One or more settings, such as task comments, or workflow events such as a task changing status.
  • Receive or Do not receive. A Do not receive rule blocks matching events, even when another rule allows them.
  • Where it applies. The whole workspace, particular tasks, particular tasks and their subtasks, particular repos, or the session’s own resources (its task, its repositories, and the tasks its conversation filed). The editor only offers the choices that fit what you selected.
  • How it is delivered. The choices are:
    • Use the event’s usual delivery
    • Show to the person only: the person at the terminal sees it, the model doesn’t.
    • Add to the session’s context: the model reads it at its next turn.
    • Start a response when idle: a session that is already running, but idle, starts a response to read it. This doesn’t launch a stopped session.
    • Steer the active response: sends the event into the response in progress. It needs operator authority, and the editor offers it only if you have that authority.
  • When the session is not running. Hold until the session runs again, Discard, or Start or resume a session. The last one is off unless you choose it. The default is to hold.
  • Narrow it down. Caused by limits the rule to events from anyone, anyone but the recipient, people only, or agents only. Only these task stages limits it to events on tasks in the stages you list.
  • Event history. By default a rule delivers only events that happen after you save it. You can ask for a one-time replay of recent events instead, by setting Days back and Most events.

In the web app

A task page and a session page each have a Subscriptions section. Both list it in their on-this-page sections.

  • Rules lists the rules this task or session owns. Each row has an Enable or Disable button. Edit and Delete are under More. A mute row has only Unmute. The State column shows Applies for a live rule.
  • New rule opens the editor with the fields above.
  • Reset rules is in the section’s menu. It deletes every rule this task or session owns, after you confirm.
  • On a session page, Inherited from task lists the task’s rules. Mute turns one off for this session only. Unmute brings it back. Edit on task, under More, jumps to the task’s own section.
  • Effective settings shows what the recipient gets right now. Columns are Setting, State, Delivered as, and Comes from, which names the rule that decides. A state of Always on means the platform always delivers that notice and a rule can’t turn it off. Not allowed means the session’s purpose doesn’t permit it. Muted here means this session muted the task rule that would deliver it.
  • Recent deliveries shows what reached the recipient and its state. The list shows Event, State, Delivery, and Updated. Open a row to see Asked for, Carried out as, Attempts, Last error, Reason, Waited, and Held since. The row also says whether the model read it (Model read it) or Not confirmed. You can filter by delivery state. Why a notice was late or didn’t arrive explains how to read these.

If a session isn’t running when you save a change, it reads the saved settings when it next starts. The section says so.

If you can’t change the rules, the section says You can see these settings but not change them. Task rules can be changed by workspace members who are people. A session’s rules can be changed by the person who operates its agent and by workspace admins. CodeHerder refuses rule changes on a session that accepts only direct messages.

The Notification rules page

In a workspace (not a group), the Notification rules page (/messages/rules), opened from the button in the Messages page header, lists every rule in the workspace, each linked to the task or session that owns it, with a feed of recent deliveries beneath. Filter rules by All, Enabled, or Disabled, filter deliveries with Delivery state, and pick Failed there to troubleshoot. The feed shows the recipient, event, state, detail and time of each delivery. It doesn’t show Waited or Held since. Open the task or session for those. This page is read-only. To change a rule, open its task or session.

From the command line

Start with the catalog. It lists every setting a rule can select and whether it is available:

ch task subscriptions catalog <taskId>

Then add a rule to a task:

ch task subscriptions create <taskId> --event task.blocker_filed --scope workspace --delivery default
ch task subscriptions create <taskId> --event task.commented --scope tasks --task <taskId> --actor humans

--scope is required whenever you pass --task or --repo. The scopes are workspace, tasks, task_tree, repos, and session_resources. Other options include --effect exclude for a Do not receive rule, --stage (repeatable), --delivery, and --inactive-policy queue|drop|start. For a one-time replay, pass --replay-since together with --replay-limit.

Look at, change, and remove rules:

ch task subscriptions <taskId>                       # list the task's rules
ch task subscriptions show <subscriptionId>
ch task subscriptions edit <subscriptionId> --actor not_self
ch task subscriptions disable <subscriptionId>       # or: enable
ch task subscriptions delete <subscriptionId>
ch task subscriptions reset <taskId> --yes           # back to the defaults

To reset only some rules, add --channel or --event. Reset then deletes only the rules that select just those settings.

See what is in effect and what happened:

ch task subscriptions policy <taskId>        # what the recipient gets, and which rule decides
ch task subscriptions deliveries <taskId>    # deliveries, oldest first

Deliveries list oldest first. A long list comes in pages. Pass the cursor from one page to --cursor to get the next. Pass --state to show one state only. The next section explains the states and the WAIT column.

Everything above works for a session’s conversation with ch session subscriptions in place of ch task subscriptions, plus one more command to mute a task rule for that session only:

ch session subscriptions mute <sessionId> <taskSubscriptionId>
ch session subscriptions delete <muteId>      # unmute

Without an ID, the create, list, policy, deliveries, reset, catalog and mute commands use the task or session you’re working in. The show, edit, enable, disable and delete commands always need a rule ID. Run ch task subscriptions --help for every flag.

Why a notice was late or didn’t arrive

Every notice a session could receive is one delivery. Each delivery has a state, and a waiting one has a reason. Together they tell you what happened.

Delivery states

Web app Command line Meaning
Waiting for the session queued The session hasn’t received it yet.
Saved for the device spooled The device stored it to hand over later.
Delivered delivered Handed to the session. There is no proof of how it was shown.
Shown to the person human_notified It was shown to the person at the terminal.
In model context model_context Added to what the model reads at its next turn.
Read by the model model_consumed The model read it. This is the only state that confirms a read.
Suppressed by policy suppressed A rule or check stopped it.
Expired expired It waited 7 days and no session ran.
Failed failed Delivery failed. Last error says why.

Read by the model proves the session got the notice. It doesn’t prove the notice arrived on time. For timing, read the wait.

How long a delivery waited

Open a delivery row on a task or session page. Waited is the time in seconds. Held since is when CodeHerder first held the notice. A notice that was held and then delivered keeps its Held since, so you can still see that it waited.

On the command line, the WAIT column shows the same time as a duration such as 1h27m0s. It shows — when the notice was never sent to the session.

ch task subscriptions deliveries <taskId> --state queued
ch session subscriptions deliveries <sessionId> --state failed

The --state values are the command-line names in the table above.

Why a delivery is waiting

A waiting delivery shows a reason. The web app writes it as a sentence, such as Awaiting session. The command line shows it in the REASON column, such as awaiting_session.

Reason What it means What you can do
dispatch_due The notice is ready and goes out on the next pass. Nothing. This lasts seconds.
retrying An attempt failed. CodeHerder tries again later. Wait. If it keeps failing, the row turns to Failed. Read Last error.
awaiting_session No session is running, so CodeHerder holds the notice. Start or resume the session. The notice goes out within about 30 seconds. To start a session for notices that arrive later, edit the rule and choose Start or resume a session. The change does not affect a notice that is already held.
recipient_lost The device that runs the session stopped checking in. Check the device. See Devices. The notice goes out once the session runs again.
awaiting_session_delivery CodeHerder sent the notice, but the session hasn’t received it. The device may not accept it yet, or the session is busy. Wait. Check that the device is online.
start_requested The rule asked CodeHerder to start a session. Wait for the session to start.
start_refused:<reason> CodeHerder couldn’t start a session. The reason follows the colon, such as recipient_terminal when the task or session already ended. Fix the cause. A finished task or session isn’t reopened.

A notice can wait up to 7 days for a session. After that it expires.

Why a delivery was suppressed

A suppressed delivery shows one of these reasons:

  • excluded: a Do not receive rule matched.
  • no_match: no rule and no default selects this event.
  • purpose: the session’s purpose doesn’t permit this notice.
  • inactive_drop: no session was running, and the rule says Discard.
  • recipient_terminal: the task or session had already ended.

To see which rule decides, check Effective settings in the web app, or run ch task subscriptions policy <taskId>.

Three common setups

Each setup shows the web app first and the command line second.

A quiet task-free session

A session you start yourself has no task, so it hears only the workspace-wide notices. To keep it quiet, switch off the chatter you don’t want.

  • Web app: Open the session page. In Subscriptions, choose New rule. Set the receive choice to Do not receive, pick Co-coding overlap, Co-coding cohort and Git and CI events, and set the scope to the whole workspace. Save. Effective settings now shows those settings as off.
  • Command line:
ch session subscriptions create <sessionId> --effect exclude --channel cowork_overlap --channel cowork_cohort --scope workspace
ch session subscriptions create <sessionId> --effect exclude --channel git_event --scope workspace
ch session subscriptions policy <sessionId>

Direct messages and answers to your questions still arrive. Those are not preferences.

Watching selected tasks

A planning session wants to know when two tasks reach review, and nothing else about them.

  • Web app: Add a rule that receives Task status changed. Set the scope to These tasks and their subtasks, choose the two tasks, and under Only these task stages add review. Set delivery to Add to the session’s context.
  • Command line:
ch session subscriptions create <sessionId> --event task.status_changed --scope task_tree --task <taskA> --task <taskB> --stage review --delivery follow_up

A blocker responder

One session answers every blocker that is filed in the workspace. A workspace admin sets this up, because the rule lets the session resolve a blocker on a task it doesn’t own.

The session can resolve only plain blockers. A blocker that waits on a network access request, a question or another task still clears only through that request, question or task. See Blockers that clear through their request, question or dependency.

  1. Add a session rule that receives Task blocker raised for the whole workspace and lets the session resolve a blocker. The web app has no control for the resolve permission, so create this rule from the command line. Save it as JSON and pass it with --from-file:
{"effect": "include", "eventTypes": ["task.blocker_filed"], "scope": {"kind": "workspace"},
 "responseActions": ["resolve_blocker"], "inactivePolicy": "queue"}
ch session subscriptions create <sessionId> --from-file blocker-rule.json
  1. Write the standing instruction the session follows when a blocker arrives. Only a person who may operate the session can set it.
ch session instruction set <sessionId> --text-file instruction.md
  1. The session then claims each event, works it, and records the result. A claim is a lease. If the session stops, the lease runs out and another responder can take over.
ch event-response claim <deliveryId>
ch event-response complete <responseId> --outcome resolved --summary "Unblocked the build."
ch event-response release <responseId> --note "Needs a human decision."   # to hand it back

When a change takes effect

A session’s rules reach the device that runs it. The Subscriptions section shows a status line for that step:

  • Applying: CodeHerder sent the change and waits for the device to confirm.
  • Applied: the device confirmed it.
  • Offline: the device is offline. It applies the saved settings when it returns.
  • Couldn’t apply: the device reported a problem. The line shows the reason.

The section also counts the events it already handed over and can’t withdraw. CodeHerder still checks every notice against your saved rules before it delivers, so a rule you turned off stays off.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close