aw-spec-cli 0.1.10 → 0.1.12

package/assets/.appweaver/ORCH-DIALECT.md

@@ -35,10 +35,22 @@ transport profile (`agent.json`) and their thin `/appweaver` launcher.
 
 1. **Context management is the orchestrator's** — as in `workflows/aw-spec-demo.orch.yaml`.
    `build_context` REPLACES the per-request envelope; `load_standards`
-   maintains the sticky system prefix. No agent ever assembles its own context.
+   maintains the sticky system prefix. Per-step `context:` is THIS request only
+   and is never appended onto the envelope. No agent ever assembles its own context.
+   `agent_author` / `agent_query` / `agent_review` get **no file tools by
+   default**: the inlined payload is the entire world. A step whose task names
+   files by PATH rather than inlining them declares `tools:` and gets exactly
+   that read-only set — the brownfield reversals do, because a legacy tree is
+   handed over as a file LIST and cannot fit a payload. `agent_generate` always
+   carries tools (it writes the code), and still receives only the
+   interpreter-assembled system + user blocks.
 2. **Execution follows any of the 4 strategies** (`--strategy`, per-step
    `strategy:` override): `sdk`, `sdk-apply`, `spawn`, `agent` — they only
-   govern WHO fulfills a generation, never what goes into it.
+   govern WHO fulfills a generation, never what goes into it. `agent` isolation
+   is best-effort (same conversation); `sdk` / `spawn` / `sdk-apply` generation
+   are isolated. Python scripts (`execute_script`) are deterministic only —
+   they never MODEL-author spec or code content (a few, like `aw-inventory.py`
+   and `aw-rev-constitution.py`, do generate documents — deterministically).
 3. **The checkpoint channel is strategy-independent** (D1): `ask`,
    `user_select` and `dispatch_hooks` suspend via `--checkpoint` under EVERY
    strategy, so the launching agent can relay to the human. Converted-skill
@@ -83,9 +95,9 @@ the raw object, not its JSON string.
 | `execute_script` | engine | F1 — run a `scripts:` ref (`subcommand:` + `args:`; sh/ps1 via `--os`); stdout's last line = JSON, bound via `outputs[]`; `on_error: continue` tolerated; cached across resumes; runs for real even in mock transport |
 | `verify_context` | engine | F2 — gates: `required_files` (+`allow_missing`), `require_non_empty` (+`on_empty[_message]`), `require_true` (+`on_false[_message]`), `require_value`+`equals` (+`on_mismatch[_message]`). `stop` raises a terminal stop |
 | `agent_generate` | fresh agent | demo contract (code work): agent DECIDES file paths per the loaded standards, writes with its tools, reports `files[]` in the trailing ```json fence. `sdk-apply` = read-only generation + invoking agent applies |
-| `agent_review` | fresh agent | read-only review of `review_of_var`/`review_of` files → `{pass, issues}` |
-| `agent_author` | fresh agent | F5 — **authored artifact** (decl `llm_generate`): the INTERPRETER owns `output_target: {type: file, path}`. Generation is READ-ONLY under every strategy; the ENGINE writes the returned content (sdk-apply degrades to sdk). Optional `context:` (per-request extras), `include_standards: false` (narrow payload) |
-| `agent_query` | fresh agent | F6 — generic read-only structured JSON (decl `llm_query`): `schema:` shapes the required fence, `outputs[]` binds it, `mock:` supplies the mock-transport result; one malformed-JSON retry on fresh strategies |
+| `agent_review` | fresh agent | payload-only review of `review_of_var`/`review_of` files (inlined into THIS request, never sticky) → `{pass, issues}` |
+| `agent_author` | fresh agent | F5 — **authored artifact** (decl `llm_generate`): the INTERPRETER owns `output_target: {type: file, path}`. Generation is payload-only under every strategy (mapped `context:` + sticky envelope + standards are the entire world) and never writes — the ENGINE writes the returned content (sdk-apply degrades to sdk). Optional `context:` (per-request extras), `include_standards: false` (narrow payload), `tools:` (read-only opt-in for a task that names files by path) |
+| `agent_query` | fresh agent | F6 — generic payload-only structured JSON (decl `llm_query`): `schema:` shapes the required fence, `outputs[]` binds it, `mock:` supplies the mock-transport result; one malformed-JSON retry on fresh strategies. Same tools contract as `agent_author` — none unless the step declares `tools:` |
 | `ask` | human (via launcher) | F7 — question: `prompt`, `options`/`options_from`/`options_from_variable`, `multi`, `answer_key`, `answer_var` (default `answer`). Sources in order: cache → `--answer k=v` → `--non-interactive` (first option; all when multi) → checkpoint suspend `ask` → stdin |
 | `user_select` | human (via launcher) | F7 — pick ONE from `options_from_variable`; `preselect_from` (direct-argument fast path), `single_option_confirm`; `--select stepid=v`; binds `selection` + `outputs[]` |
 | `dispatch_hooks` | invoking agent | F8 — suspend kind `hook` with the `hooks_from_variable` list (slash commands of the LAUNCHING agent); logged-only without a checkpoint; never re-fires across resumes |

package/assets/.appweaver/orchestrator/README.md

@@ -116,7 +116,7 @@ per step in the workflow YAML (`strategy:` on `agent_generate`/`agent_review`).
 | `sdk` | isolated SDK instance | SDK instance (tools) | 1 | guaranteed |
 | `sdk-apply` | isolated SDK instance (read-only) | **invoking agent** (suspend/resume) | 1 + you | generation clean; apply local |
 | `spawn` | fresh CLI process (profile) | same process | N cold | guaranteed |
-| `agent` | invoking agent (suspend/resume) | invoking agent | **0** | best-effort |
+| `agent` | invoking agent (suspend/resume) | invoking agent | **0** | best-effort (payload is interpreter-assembled; the invoking conversation can still add around it) |
 
 ```bash
 # Strategy 1 — SDK generates + implements (needs: pip install claude-agent-sdk)

package/assets/.appweaver/orchestrator/adapters/claude_agent_sdk.py

@@ -52,10 +52,10 @@ _PERMISSION_MAP = {"acceptEdits": "acceptEdits",
 
 
 async def generate(request):
+    allowed = [t.strip() for t in (request.get("tools") or "").split(",") if t.strip()]
     kwargs = dict(
         system_prompt=request["system"],
-        allowed_tools=[t.strip() for t in (request.get("tools") or "").split(",")
-                       if t.strip()],
+        allowed_tools=allowed,   # empty = payload-only; do not fall back to the SDK default set
         permission_mode=_PERMISSION_MAP.get(request["permission_mode"], "default"),
         setting_sources=[],   # isolation: no CLAUDE.md / settings / hooks
     )

package/assets/.appweaver/orchestrator/adapters/google_antigravity.py

@@ -10,8 +10,12 @@ Contract (see orchestrator.py `_run_sdk`):
 request keys:
     system            interpreter-assembled system block (standards + rules)
     user              interpreter-assembled user block (context + task)
-    tools             the workflow's neutral tools list (informational here;
-                      Antigravity governs capability via policies instead)
+    tools             the workflow's neutral tools list. Empty selects the
+                      payload-only posture (deny every file tool, no workspace);
+                      non-empty selects the permission_mode policy chain plus
+                      the project workspace. The individual NAMES are neutral
+                      (Read/Glob/…) and are not mapped one-to-one — Antigravity
+                      governs capability by policy, so the mode picks the set.
     permission_mode   neutral mode: readonly | acceptEdits |
                       bypassPermissions | default
     model             model name or None
@@ -49,6 +53,11 @@ from google.antigravity.hooks import policy
 _READONLY_TOOLS = ("view_file", "list_directory", "search_directory",
                    "find_file", "finish", "ask_question")
 
+# the two that touch no file: how the session ENDS its turn and how it asks.
+# A payload-only request still needs these — denying every tool including
+# `finish` leaves the agent no way to say it is done.
+_CONTROL_TOOLS = ("finish", "ask_question")
+
 
 def _policies(permission_mode):
     """Neutral permission modes → Antigravity policy chains."""
@@ -61,12 +70,25 @@ def _policies(permission_mode):
 
 
 async def generate(request):
+    tools = [t.strip() for t in (request.get("tools") or "").split(",") if t.strip()]
+    # An empty allowlist is a payload-only author/query/review: the interpreter
+    # already inlined every file the model may see. Granting the project
+    # workspace (or view_file) would let the isolated session wander off the
+    # mapped payload. Only the control tools survive the deny — the file tools
+    # are the point of the deny, but a session that cannot call `finish` cannot
+    # end its turn. A step that DECLARES tools (the brownfield reversals, which
+    # are handed the slice's source as a path list) takes the branch below and
+    # gets the workspace its readonly policy chain needs.
+    if not tools:
+        policies = [policy.deny_all()] + [policy.allow(t) for t in _CONTROL_TOOLS]
+        workspaces = []
+    else:
+        policies = _policies(request["permission_mode"])
+        workspaces = [os.getcwd()]
     config = LocalAgentConfig(
         system_instructions=request["system"],
-        policies=_policies(request["permission_mode"]),
-        # a fresh SDK session has no workspace by default; grant the project
-        # root so the isolated generation can read/write the files it decides
-        workspaces=[os.getcwd()],
+        policies=policies,
+        workspaces=workspaces,
         model=request.get("model") or None,
     )
     async with Agent(config=config) as agent:

package/assets/.appweaver/orchestrator/modules/delta-spec.orch.yaml

@@ -1,7 +1,19 @@
 # =============================================================================
 # delta-spec (orchestrator module) — author the SPEC-side DELTA of a change
 #
-# Included by /appweaver specify on its DELTA branch (spec.md already exists).
+# ORPHANED — INCLUDED BY NO WORKFLOW. specify v3.0.0 removed the delta branch this module
+# was written for: a later requirement is now an edit to the living spec.md plus a computed
+# Change History row, not a delta document merged back later. Nothing else includes it, so
+# NOTHING AUTHORS A DELTA-SPEC TODAY — the delta-spec.md that cr-setup still scaffolds for
+# every change is an untouched template copy, which is why specify's delta_open guard tests
+# whether one was authored rather than whether a change is open.
+#
+# Kept, not deleted, because the sibling half is still live: /appweaver design includes
+# delta-design on its own delta branch, and finalize-delta / analyze-slice / close-delta
+# still run. Retiring this file is a decision about the delta FAMILY, not about this module.
+#
+# What follows describes it as it was written to be included by specify.
+#
 # This is the SPEC half of the former standalone `cr` capture, relocated here: a
 # later requirement is a new user story on the SAME aggregate. It opens the change
 # (cr-setup — single-active-change guarded; also scaffolds delta-spec AND delta-design)

package/assets/.appweaver/orchestrator/orchestrator.py

@@ -318,7 +318,11 @@ class Orchestrator:
                 "Perform this task YOURSELF, in this conversation. Read "
                 "system_path + user_path and treat them as your ONLY standards "
                 "and context (ignore anything else you know about this "
-                "session). Use the listed tools within the permission mode. "
+                "session). " + (
+                    "Use the listed tools within the permission mode. "
+                    if tools else
+                    "You have NO tools: the payload is the entire world for "
+                    "this request, so do not open other project files. ") +
                 "Write your full final reply — ending with the required "
                 "```json fence — to response_path, then re-run the resume "
                 "command. Do not edit the checkpoint state file."),
@@ -515,8 +519,13 @@ class Orchestrator:
             argv += [sysmode["flag"], system]
         elif sysmode == "prepend":
             prompt_user = system + "\n\n---\n\n" + user
-        if tools and prof.get("tools_flag"):
-            argv += [prof["tools_flag"], tools]
+        # Always pass the allowlist when the CLI has a tools flag — omitting it
+        # lets the CLI fall back to its default set (Write/Bash/…), which is
+        # how a read-only author/query leaked the rest of the repo. An empty
+        # string is a real allowlist of nothing: the inlined payload is the
+        # entire world.
+        if prof.get("tools_flag") is not None:
+            argv += [prof["tools_flag"], tools or ""]
         approval = prof.get("approval", {})
         argv += approval.get(permission_mode, approval.get("default", []))
         argv += prof.get("isolation", {}).get(self.opts.isolation, [])
@@ -686,10 +695,39 @@ class Orchestrator:
         sysn = len(_norm_files(self.envelope["system"]))
         self.emit(f"[build_context] system={sysn} file(s)  context={len(ctx)} file(s)")
 
+    def _step_extra_context(self, step):
+        """Per-step `context:` files, THIS request only — never sticky. The
+        workflow maps what the model may see; the envelope is the sticky set
+        `build_context` replaced, and this list is the extra the step named."""
+        p = step.get("parameters") or step
+        extra = self.resolve_value(p.get("context")) or []
+        return [c for c in extra if isinstance(c, (str, dict))]
+
+    def _step_read_tools(self, step):
+        """The read tools an `agent_author` / `agent_query` step declares.
+
+        The default is NONE — those two actions are payload-only, and the
+        interpreter inlines every file the workflow mapped. A step whose task
+        names files by PATH rather than inlining them declares `tools:` and gets
+        exactly that set. The brownfield reversals are the reason it exists:
+        adopt hands the model the slice's `source_files` as a LIST and tells it
+        to read the code, which cannot be inlined (a legacy tree is far larger
+        than any payload) — with no tools those steps authored a spec, a design
+        and a source-map from a list of filenames, and the fidelity check that
+        exists to catch exactly that fabrication could not read the code either.
+        Declaring it in the workflow keeps the dependency where a reader can see
+        it; the permission mode stays readonly either way."""
+        p = step.get("parameters") or step
+        v = p.get("tools", "")
+        if isinstance(v, (list, tuple)):
+            v = ",".join(str(x) for x in v)
+        return (self.resolve(str(v)) or "").strip()
+
     def act_agent_generate(self, step):
         tools = step.get("tools", "Read,Write,Edit,Bash")
         permission_mode = step.get("permission_mode", "acceptEdits")
         task = self.resolve(step.get("task", ""))
+        extra = self._step_extra_context(step)
         strat = self._effective_strategy(step)
         # checkpoint replay: this step was already fulfilled (any strategy) —
         # bind its cached structured result instead of executing again.
@@ -724,8 +762,8 @@ class Orchestrator:
                 '\n\nWhen done, end your reply with a fenced block listing the paths YOU '
                 'chose to write:\n```json\n{"status":"ok","files":["<path you wrote>"],'
                 '"summary":"<one line>"}\n```')
-        system, sys_files = self._assemble_system()
-        user, ctx_files = self._assemble_user(instr)
+        system, sys_files = self._assemble_system(step.get("include_standards", True))
+        user, ctx_files = self._assemble_user(instr, extra=extra)
         self._print_envelope("agent_generate", system, sys_files, user, ctx_files, tools, strat)
 
         if self.opts.transport == "mock":
@@ -760,10 +798,14 @@ class Orchestrator:
         instr = task + "\n\nFiles under review:\n" + "\n".join(f"- {r}" for r in review_of)
         instr += ('\n\nEnd your reply with a fenced block:\n'
                   '```json\n{"pass":true,"issues":[]}\n```')
-        # review is read-only: put the files to review INTO context, tools=Read only
-        # (mutate BEFORE the checkpoint-cache branch so a replayed run rebuilds
-        # the exact same envelope state for the steps that follow)
-        self.envelope["context"] = list(self.envelope["context"]) + review_of
+        # Review files are inlined into THIS request only. They used to be
+        # appended onto the sticky envelope, so every later generation in the
+        # same run inherited them — context the workflow never mapped.
+        extra = list(review_of) + self._step_extra_context(step)
+        # Payload-only like author/query, and the same opt-in: a review whose
+        # files are inlined needs nothing, but the escape hatch has to exist on
+        # all three or a `tools:` added here later would be silently ignored.
+        tools = self._step_read_tools(step)
         strat = self._effective_strategy(step)
         ck = self._key(step)
         if self.checkpoint and ck in self.cache:
@@ -772,22 +814,23 @@ class Orchestrator:
             self._bind(step, structured)
             self.emit(f"[agent_review] (cached) result={json.dumps(structured)[:200]}")
             return
-        system, sys_files = self._assemble_system()
-        user, ctx_files = self._assemble_user(instr)
-        self._print_envelope("agent_review", system, sys_files, user, ctx_files, "Read", strat)
+        system, sys_files = self._assemble_system(step.get("include_standards", True))
+        user, ctx_files = self._assemble_user(instr, extra=extra)
+        # No file tools by default: the files under review are already in the payload.
+        self._print_envelope("agent_review", system, sys_files, user, ctx_files, tools, strat)
 
         if self.opts.transport == "mock":
             # mock: pass if every reviewed file exists
             ok = all(os.path.exists(r) for r in review_of)
             structured = {"pass": ok, "issues": ([] if ok else ["missing output file(s)"])}
         elif strat == "agent":
-            self._suspend("agent_review", ck, system, user, "Read", "readonly")
+            self._suspend("agent_review", ck, system, user, tools, "readonly")
         elif strat in ("sdk", "sdk-apply"):
             # review has no apply phase — sdk-apply degrades to a plain sdk read
-            structured, _ = self._run_sdk(system, user, "Read", "readonly",
+            structured, _ = self._run_sdk(system, user, tools, "readonly",
                                           model=step.get("model"))
         else:  # spawn
-            structured, _ = self._run_fresh(system, user, "Read", "acceptEdits",
+            structured, _ = self._run_fresh(system, user, tools, "readonly",
                                             model=step.get("model"))
         self.last_result = structured
         if self.checkpoint:
@@ -963,7 +1006,8 @@ class Orchestrator:
         if not target:
             raise Stop(f"step {step.get('id')}: agent_author needs output_target.path")
         task = self.resolve(p.get("task") or p.get("prompt") or "")
-        extra = [c for c in (self.resolve_value(p.get("context")) or []) if isinstance(c, (str, dict))]
+        extra = self._step_extra_context(step)
+        tools = self._step_read_tools(step)
         strat = self._effective_strategy(step)
         ck = self._key(step)
         if self.checkpoint and ck in self.cache:
@@ -974,28 +1018,38 @@ class Orchestrator:
             self.emit(f"[agent_author] (cached) rewrote {target}")
             return
         instr = task + (
-            f"\n\nAuthor the COMPLETE content of the file `{target}`. You have "
-            "no write tools — return the content itself. Reply with ONLY the "
+            f"\n\nAuthor the COMPLETE content of the file `{target}`. " + (
+                f"Your tools are read-only ({tools}), and they are for the files "
+                "this task names by PATH — everything else you need is already in "
+                "the payload. "
+                if tools else
+                "You have no tools — the payload is the entire world for this "
+                "request. ") +
+            "Return the content itself. Reply with ONLY the "
             "full file content: no commentary, no surrounding code fence.")
         system, sys_files = self._assemble_system(p.get("include_standards", True))
         user, ctx_files = self._assemble_user(instr, extra=extra)
-        self._print_envelope("agent_author", system, sys_files, user, ctx_files, "Read", strat)
+        self._print_envelope("agent_author", system, sys_files, user, ctx_files, tools, strat)
         if self.opts.transport == "mock":
             content = self._mock_author(target, task)
         elif strat == "agent":
-            self._suspend("author", ck, system, user, "Read", "readonly",
+            self._suspend("author", ck, system, user, tools, "readonly",
                           instructions=(
                               "Author this artifact YOURSELF, in this conversation. "
                               "Read system_path + user_path as your ONLY standards "
-                              "and context. Write the COMPLETE file content — the "
-                              "content ONLY, no commentary, no code fence — to "
-                              "response_path, then re-run the resume command. Do "
-                              "NOT write the target file yourself; the interpreter "
-                              "does that."),
+                              "and context" + (
+                                  ", and open ONLY the files the task names by path. "
+                                  if tools else
+                                  " — do not open other project files. ") +
+                              "Write "
+                              "the COMPLETE file content — the content ONLY, no "
+                              "commentary, no code fence — to response_path, then "
+                              "re-run the resume command. Do NOT write the target "
+                              "file yourself; the interpreter does that."),
                           extra={"target": target})
         else:
             run = self._run_sdk if strat in ("sdk", "sdk-apply") else self._run_fresh
-            _, raw = run(system, user, "Read", "readonly", model=step.get("model"))
+            _, raw = run(system, user, tools, "readonly", model=step.get("model"))
             content = _strip_fence(raw)
             if not content.strip():
                 raise Stop(f"step {step.get('id')}: agent_author returned empty content")
@@ -1012,16 +1066,16 @@ class Orchestrator:
                   f"({len(content)} chars)")
 
     # -- F6: structured queries --------------------------------------------------
-    def _structured_fresh(self, step, strat, system, user):
+    def _structured_fresh(self, step, strat, system, user, tools=""):
         """spawn/sdk executor for JSON-returning steps, with ONE malformed-JSON
         retry (agent strategy instead re-suspends with a note on resume)."""
         run = self._run_sdk if strat in ("sdk", "sdk-apply") else self._run_fresh
-        structured, _ = run(system, user, "Read", "readonly", model=step.get("model"))
+        structured, _ = run(system, user, tools, "readonly", model=step.get("model"))
         if not structured:
             self.emit(f"[retry] {step.get('id')}: no parseable ```json fence — asking once more")
             user2 = user + ("\n\nYour previous reply could not be parsed. Return "
                             "ONLY the required ```json fenced block, nothing else.")
-            structured, _ = run(system, user2, "Read", "readonly", model=step.get("model"))
+            structured, _ = run(system, user2, tools, "readonly", model=step.get("model"))
         if not structured:
             raise Stop(f"step {step.get('id')}: fresh agent returned no parseable JSON")
         return structured
@@ -1033,7 +1087,8 @@ class Orchestrator:
         specialization of this. `mock:` supplies the mock-transport result."""
         p = step.get("parameters") or step
         task = self.resolve(p.get("task") or p.get("prompt") or "")
-        extra = [c for c in (self.resolve_value(p.get("context")) or []) if isinstance(c, (str, dict))]
+        extra = self._step_extra_context(step)
+        tools = self._step_read_tools(step)
         strat = self._effective_strategy(step)
         ck = self._key(step)
         if self.checkpoint and ck in self.cache:
@@ -1044,18 +1099,24 @@ class Orchestrator:
             return
         schema = p.get("schema")
         hint = json.dumps(schema) if isinstance(schema, (dict, list)) else (schema or "{ … }")
-        instr = task + ("\n\nDo not modify any files. End your reply with a "
+        instr = task + ("\n\nDo not modify any files. " + (
+                        f"Your tools are read-only ({tools}), and they are for the "
+                        "files this task names by PATH — everything else you need is "
+                        "already in the payload. "
+                        if tools else
+                        "The payload is the entire world for this request. ") +
+                        "End your reply with a "
                         "fenced block containing ONLY the JSON result, shaped "
                         "like:\n```json\n" + hint + "\n```")
         system, sys_files = self._assemble_system(p.get("include_standards", True))
         user, ctx_files = self._assemble_user(instr, extra=extra)
-        self._print_envelope("agent_query", system, sys_files, user, ctx_files, "Read", strat)
+        self._print_envelope("agent_query", system, sys_files, user, ctx_files, tools, strat)
         if self.opts.transport == "mock":
             structured = self.resolve_value(p.get("mock")) or {}
         elif strat == "agent":
-            self._suspend("agent_query", ck, system, user, "Read", "readonly")
+            self._suspend("agent_query", ck, system, user, tools, "readonly")
         else:
-            structured = self._structured_fresh(step, strat, system, user)
+            structured = self._structured_fresh(step, strat, system, user, tools)
         self.last_result = structured
         if self.checkpoint:
             self.cache[ck] = structured
@@ -1065,17 +1126,43 @@ class Orchestrator:
 
     # -- F7: HITL (D1 — the checkpoint is the interaction channel under EVERY
     #    strategy; --answer/--select/--non-interactive prefill for headless runs)
-    def _prompt_choice(self, prompt, options):
+    def _prompt_choice(self, prompt, options, multi=False):
         print(prompt)
         for i, o in enumerate(options, 1):
             print(f"  {i}) {o}")
+        if multi:
+            print("  (pick any: numbers or names, comma-separated \u2014 "
+                  "'all', or blank for none)")
         try:
             raw = input("> ").strip()
         except EOFError:
             return None
-        if raw.isdigit() and 1 <= int(raw) <= len(options):
-            return options[int(raw) - 1]
-        return raw if raw in options else None
+        if not multi:
+            if raw.isdigit() and 1 <= int(raw) <= len(options):
+                return options[int(raw) - 1]
+            return raw if raw in options else None
+        # A multi-select answer is a SET, and a set has no single-token spelling. Read by
+        # the single-select parser, "1,3" was neither a number in range nor an option, so it
+        # returned None and the run stopped as "question cancelled" \u2014 leaving exactly two
+        # reachable answers, "the first one" and "abort". act_ask splits the string it gets
+        # back on commas, so returning one is all that is needed here.
+        if raw.lower() in ("all", "*"):
+            return ",".join(str(o) for o in options)
+        if raw.lower() in ("", "none"):
+            return ""
+        picked = []
+        for tok in re.split(r"\s*,\s*|\s+", raw):
+            if not tok:
+                continue
+            if tok.isdigit() and 1 <= int(tok) <= len(options):
+                v = options[int(tok) - 1]
+            elif tok in options:
+                v = tok
+            else:
+                return None      # an unrecognised token is a typo, not a silent omission
+            if v not in picked:
+                picked.append(v)
+        return ",".join(str(o) for o in picked)
 
     def act_ask(self, step):
         """F7 — single/multi-select question. Answer sources, in order: replay
@@ -1113,7 +1200,7 @@ class Orchestrator:
                     (" (comma-separated)" if multi else "") +
                     " to response_path, then re-run the resume command.")})
         if raw is None:
-            raw = self._prompt_choice(prompt, options) if options else \
+            raw = self._prompt_choice(prompt, options, multi) if options else \
                 input(prompt + " ").strip()
         if raw is None:
             raise Stop("question cancelled")

package/assets/.appweaver/orchestrator/workflows/aw-spec-adopt.orch.yaml

@@ -360,6 +360,7 @@ workflow:
       - { path: .appweaver/memory/constitution.ui.md, optional: true }         # the frontend lane's UX-* base — absent on a backend-only repo, which onboard leaves unwritten by design
   - id: reverse_spec
     action: agent_author
+    tools: Read   # the code arrives as a PATH LIST, not inlined — a legacy tree does not fit a payload
     include_standards: false                       # the technical/arch sticky set is for design, never the spec
     output_target: { type: file, path: "{{spec_file}}" }
     task: |
@@ -435,6 +436,7 @@ workflow:
       - { path: .appweaver/memory/constitution.technical.md, optional: true } # technology base ONLY — no domain
   - id: reverse_design
     action: agent_author
+    tools: Read   # grounded in the CODE, which arrives as {{source_files}} paths
     include_standards: true                        # the technical/architecture sticky set (reference only — the CODE wins)
     output_target: { type: file, path: "{{design_doc}}" }
     task: |
@@ -499,6 +501,7 @@ workflow:
   - id: reverse_ui_design
     condition: "{{ui_lane}} == true"
     action: agent_author
+    tools: Read   # same, for the lane's surface ({{ui_source_files}})
     include_standards: true                        # the lane's sticky technical set (reference only — the CODE wins)
     output_target: { type: file, path: "{{ui_design_doc}}" }
     task: |
@@ -545,6 +548,7 @@ workflow:
       - { path: "{{concept_path}}" }              # both file lists to map
   - id: source_map
     action: agent_author
+    tools: Read   # one row per legacy artefact; the artefacts are paths in the concept
     include_standards: false
     output_target: { type: file, path: "{{feature_dir}}/source-map.md" }
     task: |
@@ -576,6 +580,7 @@ workflow:
   # → written to an Adopt Review report and closed OUT OF BAND (Brownfield B1·R).
   - id: fidelity
     action: agent_query
+    tools: Read   # the check is spec/design vs CODE; with no code it degrades to spec vs design and certifies fabrication as ok
     context:
       - "{{spec_file}}"
       - "{{design_doc}}"

package/assets/.appweaver/orchestrator/workflows/aw-spec-characterize.orch.yaml

@@ -188,6 +188,7 @@ workflow:
       - { path: "{{design_file}}" }
   - id: scan_existing_tests
     action: agent_query
+    tools: Read,Glob,Grep   # no test list is supplied — it globs the tree; empty results make characterize write duplicate golden-masters
     include_standards: false
     schema:
       duplicates: [ { behaviour: "<observable behaviour>", spec_id: "<US-/FR-/BR- id>", existing_test: "<file:test-name>", seam: "<endpoint|handler|domain|persistence>", source_file: "<production file it covers>" } ]

package/assets/.appweaver/orchestrator/workflows/aw-spec-onboard.orch.yaml

@@ -844,6 +844,7 @@ workflow:
       - { path: "{{bundle_dir}}/architecture/frontend.md", optional: true }            # SECONDARY (shallow): the OKF as-built frontend note — corroborate, don't rely on alone
   - id: author_ui
     action: agent_author
+    tools: Read   # EVIDENCE = THE UI CODE ITSELF; the inventory inlines the file LISTS, not the files
     condition: "{{ui_lane}} == true"
     include_standards: false
     output_target: { type: file, path: "{{constitution_ui_file}}" }