Let apps deliver work into their own sessions, visible on the board

[psantus]

Discussions → Ideas. Floating this as a design idea before writing any code — I'd rather
hear "not in this shape" now than after a PR. If it's "no in principle", that's a useful
answer too.

Where this comes from

I'm building a third-party app that receives webhooks (from Github or ANY other source), buffers them in SQS,
and hands each event to an agent. Building it, I realised the thing I'd written is a channel in all but
name: an inbound transport that turns outside events into agent work. Same shape as Slack,
Discord, Telegram, or cron — just speaking HTTPS-plus-a-queue instead.

And that's where I hit a wall that I don't think is about my app. Every part of Kiro Crew that
has this shape gets to own its sessions, so its work shows up on the board and can be opened and
replied to. A third-party app can't. The dividing line isn't what the code does — it's
where the code lives:

• Task Runner isn't an app at all; it's core (taskrunner.py, held as state.task_runner).
  It holds the SessionManager directly, mints its own keys (taskrunner:run:…), and picks any
  agent.
• Channels ships as a builtin app whose app.json is the only file in its directory — a UI
  page and a permission. The engine is core (channel.py, channels.py, channel_history.py).
• Cron injects cron:{job.id} sessions into visible slots from core
  (dashboard/cron_inject.py).

So the capability is real, mature, and used by three producers — but it's reachable only by
being core. My app does the same job as those, and the only difference is that it's installed
rather than shipped. That asymmetry is what I'd like to close.

To be concrete about the gap, here's what a user gets from my app today versus what I'd like
them to get:

	today	with this
See the job that ran at 14:02	no — nothing to open	it's on the board, like a Slack thread
Read what it did tomorrow	no — the run record is pruned	a normal transcript, kept
Reply to it ("skip the migration")	no — there's no conversation	yes
Who can handle it	only agents the app itself ships	(separate ask, below)

The first three are one capability, not three. The fourth is a different question with real
security weight, so I've split it out rather than bundling them.

It isn't just my app

Anything that turns outside events into agent work has this shape: a webhook ingress, a queue
consumer, an IMAP or SMS bridge, a CI listener, a bridge for any transport Kiro Crew doesn't
natively speak. For all of them an event is not a sub-task of a chat turn — it's its own
conversation someone may later want to read, resume, or steer. Today each of those authors gets
the subagent primitive, which is the wrong one: invisible, short-lived, unrepliable.

There's a "do nothing" cost worth naming too. Without a sanctioned path, an app author who wants
this either does without, or reaches for something worse — and the worse options are the
concerning ones, because they'd each re-derive session ownership logic that has already produced
real bugs (see the failure history below).

The first thing I want: apps own the sessions they deliver into

I'm volunteering to implement this, not asking someone else to. Concretely:

One SDK call, ctx.sessions.deliver(key, prompt, title), gated by a new deny-by-default
permissions.sessions. The framework owns key derivation (app:<app_name>:<suffix>, suffix
sanitised — an app can never name slack:…, dashboard:…, or another app's keys), the
ownership/idempotency check, and surface publication. Implementation mirrors cron_inject.py
rather than introducing a parallel path.

Defaults I'd pick unless you'd rather they were different:

• Idempotent per (app, key) — a redelivered event resolves to the same session instead of
  creating a second one. At-least-once transports make this mandatory, and it's the Slack inbound message handling can create a duplicate/competing session for a thread already linked to a dashboard session #2796
  failure mode.
• Persistent memory mode, honouring the existing slot cap and the existing restricted /
  ephemeral machinery rather than adding a parallel notion of either.
• Audited through log_api_access, like other app-initiated privileged calls.
• No new retention rule — an app-delivered transcript ages exactly like a Slack or cron one.

The one decision I need from you: is this something you'd accept in principle? If yes I'll
open a PR with the app above as the working consumer, so you can see the capability exercised
end-to-end rather than in the abstract. If you'd prefer a different shape — an event the
framework consumes, or extending channels to accept app-registered transports — say which and
I'll build that instead. If it's a no, I'll stop here and keep the fallback.

One thing I want to be explicit about rather than gloss: linked sessions have a real bug history
(#2796 split one logical conversation in two, #2462 cancelled the wrong session, #2795 is still
open). I read that as the argument for a single framework-owned entry point rather than
against the idea — the failures came from a second inbound path reasoning about ownership
differently from the first, and the worst outcome would be N app authors each hand-rolling their
own version. Details in the failure-history section below. If your conclusion is "we don't want
more producers on that mechanism at all", that's a legitimate reason to decline.

The second thing I want: routing an event to a crew

I'll state this plainly rather than bury it, because it's the other half of what my app needs.
When a webhook arrives I want to route it to a crew the user chose — their triage crew, their
deploy-watcher crew — not only to an agent my app happens to ship. Today apps/spawn_sdk.py
restricts an app to its own <app>--* agents, so a crew is unreachable.

I am not asking you to relax that check. I'm asking whether an operator could grant an app
access to specific crews: declared as intent in the manifest, granted per-crew by the operator,
enforced by the framework. Deny-by-default, revocable, visible.

The check is doing real work and I don't want it weakened for every app at once. A user crew's
agent carries none of the managedToolPolicy exclusions that app agents carry, it brings a
workspace (filesystem scope the app was never granted) and a memory store it can write to, and
for an ingress app the prompt is built from an inbound payload — so "route to any crew" would put
attacker-influenced text into a fully-capable agent with real files and real memory. Hence
consent rather than a wider default. Full reasoning in the security section below.

One constraint makes that consent real: the grant must live in framework-owned config, not in
app-writable state. My app's routing table lives in its own data_dir and my app writes it, so
it cannot be the consent record. The grant belongs alongside app enablement, and my crew picker
should only be able to offer crews already granted.

This ask is independent: a no here doesn't affect the session-namespace one.

The sections below are supporting detail — what exists today, the failure history, the API
sketch, and the security analysis behind the crew grant.

---

How the platform already does this (code references)

Non-dashboard sessions being visible and browsable is established behaviour:

• dashboard/state.py:1202 — self.linked_session_key: str = "" # when set, _run_chat uses this as session key
• dashboard/state.py:3296 — linked_session_key is a named kwarg of get_or_create_slot,
  documented as binding "a new slot to the session its conversation" runs on
• dashboard/chat_utils.py:519-535 — effective_session_key(): "A channel-born slot carries
  the real channel key (slack:<ts>) in linked_session_key, so its turns run on the
  channel's own session and its transcript IS the channel transcript"
• history.py:904-906 — _safe_key() is a generic re.sub(r"[^\w\-.]", "_", key), so any
  prefix:id folds to a filename with no per-transport logic
• dashboard/chat_persistence.py:573,922,1649 — linked_session_key is persisted in slot
  meta, so such a tab survives a restart

Already used by three producers, only one of which is a chat transport:

Producer	Session key	File
Channels	channel:… / slack:…	dashboard/channel_slots.py:267
Cron	cron:{job.id}	dashboard/cron_inject.py:90
Workflows	(injected key)	dashboard/workflow_inject.py:156

The only reason an app can't do this is that slot creation touches DashboardState, which the
app sandbox rightly cannot reach.

Why it must be ONE framework-owned entry point (and the bug history)

I'd rather name the risk than sell the mechanism as free. Linked sessions have a real bug
history, all in the same area:

• Slack inbound message handling can create a duplicate/competing session for a thread already linked to a dashboard session #2796 (closed) — inbound Slack handling could create a duplicate/competing session for a
  thread already linked to a dashboard session, "effectively splitting one logical conversation
  into two". Root cause: a newer inbound path "checks only an in-memory, explicit link to
  dashboard mechanism", and a false result there does not imply no persisted owner exists.
• Stop on a channel-linked session addresses the wrong session key and cancels nothing #2462 (closed) — stop on a channel-linked session addressed the wrong session key and
  cancelled nothing.
• A Slack turn routed to a linked dashboard session loses the model's own accurate self-description of that session #2795 (open) — a Slack turn routed to a linked dashboard session loses the model's own
  accurate self-description of that session.

Those failures came from a second inbound path reasoning about ownership slightly differently
from the first. So the ask is explicitly not "expose linked_session_key to apps" — it's
one framework-owned function that owns key derivation, ownership/idempotency checks, and
surface publication, so every app-delivered session inherits the fixes those issues produced
instead of becoming a fourth divergent implementation.

If the conclusion is "we don't want more producers on that mechanism at all", that's a
legitimate reason to decline, and worth saying plainly.

Two invariants I'd want that entry point to own, both learned from the above:

• Idempotency on redelivery. At-least-once transports (SQS, webhook retries) will deliver
  the same event twice; the same logical event must resolve to the same session rather than
  splitting it — the Slack inbound message handling can create a duplicate/competing session for a thread already linked to a dashboard session #2796 failure mode.
• Publication before routing. cron_inject.py documents it: publish the slot to the
  surface registry before anything routes against it, or "a created-but-unpublished slot
  silently fails those gates until some unrelated slot change happens to republish".

API sketch

One SDK method, opt-in per app, deny-by-default:

# manifest
"permissions": { "sessions": true }

# app backend
session_key = await ctx.sessions.deliver(
    key="job-8f21c3",          # app-chosen suffix; the namespace is NOT app-controlled
    prompt="A GitHub webhook arrived …",
    title="GitHub: PR #843 opened",
)
# → session runs under  app:<app_name>:job-8f21c3
# → slot created + published to the surface registry
# → returns the key so the app can link to it

Constraints I'd suggest baking in:

• The app never chooses its namespace. The framework forces app:<app_name>:<suffix> and
  sanitises the suffix. An app cannot mint slack:…, dashboard:…, or another app's keys.
• Deny-by-default. Without the permission the SDK attribute isn't attached — same shape as
  spawn / storage today.
• Reuse, don't duplicate. Implementation is about the size of cron_inject.py and follows it.
• Audited, like other app-initiated privileged calls.

Security analysis behind the crew grant (why consent, not a wider default)

Dispatching to a non-app agent would today:

1. Void the app-agent containment by construction. managedToolPolicy is framework-owned
   and force-refreshed on every install precisely so app agents "cannot reach
   spawn_run/cron_*/task_run or inherit the global mcp.json" (apps/bridges.py:668). A
   user crew's agent carries none of those exclusions, so an app naming one reaches those
   capabilities indirectly — including spawning further agents.
2. Grant filesystem scope never granted. A crew carries a workspace; dispatching to it
   means prompt-driven work in that project directory. No app permission covers filesystem
   scope beyond the app's own data_dir.
3. Grant memory read and write. The turn can read the crew's accumulated facts and write
   to them. Pollution is the subtle half: false facts written there silently influence the
   human's later sessions in that workspace.
4. Put attacker-influenced text in a privileged context. For an ingress app the prompt is
   built from an inbound payload, so the real shape is "internet-reachable input becomes the
   prompt of a fully-capable agent with a real workspace and memory". Bearer auth
   authenticates the sender, not the payload.

None of that argues the operator shouldn't be able to do this — they can already wire a webhook
to any crew with their own script. It argues the authority must be explicitly granted rather
than inherited from having installed the app, because an app is a distributable artifact
someone else installs.

Two further limits mean "just ship an app-owned agent" isn't a full substitute: app agents are
absent from config.agents, so resolve_agent_bindings (config/loader.py:6256-6274) binds
them to the default workspace and memory store — a crew mirror reproduces the model but not
the memory — and their tool policy is narrowed as in (1).

Alternatives considered, and today's permission surface

• Widen the SpawnSDK prefix check — rejected: removes a check that protects every app, to
  fix a problem that's really about the wrong primitive.
• Keep using subagents, link to the parent conversation — rejected: these jobs have no
  parent chat; the parent is the app.
• Ship a core patch / fork per app — rejected: makes apps non-portable, which is exactly
  what an app platform should avoid.
• Do nothing — viable. Apps in this class stay usable but can't offer browsable, resumable
  job history. Mine ships this way today, with the limitation stated in its UI.

For reference, the complete set of capabilities an app can be granted today is api
(exact-path allowlist), events, storage, network, cron, spawn, plus declared mcp
servers and system commands (apps/manifest.py:411-418). There's no session, agent, workspace,
or dashboard capability of any kind — which is why both asks introduce new consent-gated
permissions rather than relaxing existing ones.

[iamwhatever]

Very interesting. Just kindly share some related stuff, we have already got endpoint to deliver result back to a session. Recently some new tools are added to manage top level session (chat slot) in the mcp-core.

[kyleseaman]

FYI @CrysisDeu as we think about the app development lifecycle

[psantus]

Thanks @iamwhatever; you're right, and it changed what I'm asking for. Let me be specific about what I found, because the gap turned out to be narrower and sharper than what I originally wrote.

• POST /api/hooks/agent does almost all of this today. It takes a message, a caller-chosen sessionKey, and an agent — and that agent field is not prefix-checked, so it already resolves a crew name against config.agents with that crew's real workspace and memory. I built an AWS-backed webhook ingress as a third-party app (API Gateway → SQS → poller → routing → agent) and the delivery half is genuinely a solved problem. I withdraw the framing that apps have no way to deliver inbound work.
• What the endpoint does not do is keep the session. One turn runs, the session is destroyed, and the result goes to notifications — the same lifecycle subagents have. That is clearly deliberate for one-shot work, and I'm not arguing against it. My point is narrower: the platform has decided what happens to one-shot work, and has not said anything about inbound work that deserves a durable
  home.

So the revised ask is one flag, not a new subsystem: let a caller opt in to persisting the hook session (write it to history and surface it as a slot), instead of destroying it after the turn. Concretely, what I'd want from POST /api/hooks/agent with something like
"persist": true:

• the session is written to history like any other, so it survives the turn;
• it appears as a slot the operator can open, read, and reply into, which turns a fire-and-forget delivery into a conversation someone can pick up;
• the existing sessionKey becomes a real handle rather than a routing key, so a second delivery on the same key continues the same thread instead of starting an unrelated turn.

Defaults I'd propose, so this doesn't widen anyone's blast radius: off by default (unchanged behaviour for every current caller), gated by the same webhook token, and subject to the same concurrency cap. If a persisted session should count against a different limit than an ephemeral one, that seems right to me.

I'll note the direction already exists elsewhere: session_create on main does create a real sidebar session. What it can't do is be driven by an app, or receive its first message from one. If the intended answer is "apps should reach sessions through the slot tools rather than through the hooks endpoint", say so and I'll build against that instead — I mostly want to know which of the two is the supported path before I ship something that depends on the wrong one.

On the second ask (routing an event to a crew), which I don't think the endpoint supersedes.

Reaching a crew through the webhook token works, but only because the operator pasted a token into an app's config: it's a workaround that happens to function, not a sanctioned capability, and it launders the app's identity through a credential that carries no scope.

What I asked for was an operator-granted, consent-gated app→crew route with the grant stored in framework config rather than in app-writable state, so the operator can see and revoke it. That still seems worth having independently of anything above, and I'd rather it be a real permission than an accident of token possession.

Happy to implement either piece if the direction is acceptable; the persist flag looks like a small change to handlers/hooks.py plus the history write, and I've already got a third-party app that exercises the whole path end to end and can serve as the test case.