feat(the-framework): bind a topic run to a project via a gate (#1121) - #1131
Merged
Conversation
Await-gates variant of #1121: a project-less topic run (#1120) ends a turn on an await-bind-project / await-create-project block; the framework resolves it by registering + binding the project and recording the bind. Reuses the same bind recording shapes as the MCP-tools spike (bind control entry, RunMeta.boundProjectId, bind event, terminal line) so only the trigger differs. The gate is taught via the runtime append layer (system-prompt.ts, topic-only), so no base-prompt edit and the prompt-drift check stays green. Spike for #1121, part of the #1129 decision.
This was referenced Jul 24, 2026
Harden the topic-run bind gate to the real feature and add the list-as-context "read" half (#1129). - Inject the registered projects (name + path) into a topic run's system channel as context, not a tool: the node side reads listProjects through the same injected seam the gate resolves against, so no node:fs reaches the browser path. An empty registry steers the agent to await-create-project. - Validate an await-create-project path via resolveProjectPath (absolute, exists, is a directory); a bad path declines cleanly back to the agent instead of crashing. Registration stays idempotent by resolved path and surfaces the existing record, with a distinct "already registered" reply. - await-create-project recommends Approve, so autopilot and a headless run auto-accept the grant, exactly like the plan confirmation gate. - The bind still only registers + records boundProjectId; the worktree re-home it implies is left as a #1122 TODO.
suleimansh
added
enhancement
suleimansh
changed the title
suleimansh
marked this pull request as ready for review
July 24, 2026 22:06
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
1 participant
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.
What
A project-less "topic" run (#1120) can now bind itself to a project mid-run, via an await gate, and the projects it can bind to are injected into its context.
Two halves, per the #1129 decision (an await-gate, not MCP tools; list = read, not a tool):
Bind (the "write" half). The agent ends a turn on one of two fenced blocks:
```await-bind-projectpicks from the already-registered projects. The framework fills the option list from the registry at resolution time, so the agent never names an id and can never pick one that is gone.```await-create-projectregisters a new project by its absolute path and binds to it.The framework resolves the gate, records
boundProjectIdon the run's meta, and re-prompts the agent with the result.List (the "read" half). For a topic run, the registered projects (name + path) are injected into the system channel as context, read through the same seam the gate resolves against so no
node:fsreaches the browser-rendered prompt path. An empty registry says so, steering the agent toawait-create-project.Permission semantics
await-create-projectrecommends Approve and renders as a confirmation, so autopilot and a headless run auto-accept it, exactly like the plan confirmation gate (#358). Registering a path is what grants the app filesystem access to it, so the confirmation is the grant.Hardening
await-create-projectpath that is relative, empty, missing, or not a directory declines cleanly back to the agent (resolveProjectPath), never crashing the run.resolvecollapses any./..and the absolute requirement is the traversal guard.Out of scope
The bind only registers + records here. The actual worktree allocation and continue-run (re-homing the topic run into the bound project) is a
// #1122:follow-up, not implemented in this PR.Notes
prompts/system_prompt.mdedit: the bind protocol and the project list live in the runtime append layer (system-prompt.ts), appended only for topic runs, so a normal run's channel stays byte-identical ([The Framework] Remove the persona / skill / memory framing #547).Closes #1121