feat: add pass-through args (--) forwarded verbatim to the tool

Anything after a bare '--' separator on the command line is forwarded
to the tool inside the container. Works for both 'construct' and
'construct qs'. Pass-through args are not persisted to last-used
settings and are ignored in debug mode.

Generated by construct

Author: mtsfoni

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+### Added
+- **Pass-through args (`--`)** — both `construct [flags] [path] -- <tool-args>` and `construct qs [path] -- <tool-args>` now forward everything after the bare `--` separator verbatim to the tool inside the container (e.g. `construct qs -- continue-session <session-id>`). Pass-through args are not persisted to last-used settings. Debug mode (`--debug`) ignores them.
+
 ### Fixed
 - **Container startup "Permission denied" errors** — the entrypoint script's heredoc that writes `~/.config/opencode/AGENTS.md` used an unquoted delimiter, causing the shell to treat backtick-wrapped paths (`` `/workspace` ``, `` `/home/agent` ``) as command substitutions. The delimiter is now quoted (`<< 'AGENTSEOF'`), preventing the errors `/workspace: Permission denied` and `/home/agent: Permission denied` on startup.
 

README.md

@@ -51,9 +51,9 @@ go build -o construct ./cmd/construct
 ## Usage
 
 ```
-construct [--stack <stack>] [--docker <mode>] [--rebuild] [--reset] [--debug] [--mcp] [--port <port>] [path]
+construct [--stack <stack>] [--docker <mode>] [--rebuild] [--reset] [--debug] [--mcp] [--port <port>] [path] [-- <tool-args>]
 construct config <set|unset|list> [--local] [KEY [VALUE]]
-construct qs [path]
+construct qs [path] [-- <tool-args>]
 ```
 
 `path` defaults to the current working directory.
@@ -88,6 +88,22 @@ construct qs [path]
 
 `qs` restores the last `--stack`, `--docker`, `--mcp`, and all `--port` values used for that repo. Settings are stored in `~/.construct/last-used.json`.
 
+You can pass extra arguments to the tool after `--`. They are forwarded verbatim and are not saved to last-used:
+
+```bash
+# Resume a previous opencode session
+construct qs -- -s ses_deadbeefcafe1234abcd5678
+
+# Same with an explicit repo path
+construct qs ~/projects/myapp -- -s ses_deadbeefcafe1234abcd5678
+```
+
+The `--` separator works with plain `construct` too:
+
+```bash
+construct --stack go -- -s ses_deadbeefcafe1234abcd5678
+```
+
 ## Supported tools
 
 | Tool | Package | Yolo mode |

cmd/construct/main.go

@@ -28,6 +28,19 @@ func (p *portFlag) Set(v string) error {
 	return nil
 }
 
+// splitPassthrough splits args on the first bare "--" token.
+// The left slice contains everything before "--" (construct flags and path).
+// The right slice contains everything after "--" (tool pass-through args).
+// If "--" is absent, right is nil.
+func splitPassthrough(args []string) (left, right []string) {
+	for i, arg := range args {
+		if arg == "--" {
+			return args[:i], args[i+1:]
+		}
+	}
+	return args, nil
+}
+
 func main() {
 	if len(os.Args) > 1 && (os.Args[1] == "--version" || os.Args[1] == "-version") {
 		v := buildinfo.Version
@@ -50,6 +63,8 @@ func main() {
 
 // runAgent is the original construct behaviour: build images and launch the agent.
 func runAgent(args []string) {
+	constructArgs, passthroughArgs := splitPassthrough(args)
+
 	allStacks := stacks.All()
 
 	fs := flag.NewFlagSet("construct", flag.ExitOnError)
@@ -63,12 +78,15 @@ func runAgent(args []string) {
 	fs.Var(&ports, "port", "Publish a container port to the host (repeatable): --port 3000 --port 8080:8080")
 
 	fs.Usage = func() {
-		fmt.Fprintf(os.Stderr, "Usage: construct [--stack <stack>] [--docker <mode>] [--rebuild] [--reset] [--debug] [--mcp] [--port <port>] [path]\n\n")
+		fmt.Fprintf(os.Stderr, "Usage: construct [--stack <stack>] [--docker <mode>] [--rebuild] [--reset] [--debug] [--mcp] [--port <port>] [path] [-- <tool-args>]\n\n")
 		fmt.Fprintf(os.Stderr, "Subcommands:\n")
 		fmt.Fprintf(os.Stderr, "  config    Manage credential environment variables\n")
 		fmt.Fprintf(os.Stderr, "  qs        Re-run the last stack used in the current repo\n\n")
 		fmt.Fprintf(os.Stderr, "Other flags:\n")
 		fmt.Fprintf(os.Stderr, "  --version  Print the construct version and exit\n\n")
+		fmt.Fprintf(os.Stderr, "Pass-through args:\n")
+		fmt.Fprintf(os.Stderr, "  Anything after -- is forwarded verbatim to the tool inside the container.\n")
+		fmt.Fprintf(os.Stderr, "  Example: construct qs -- continue-session <session-id>\n\n")
 		fmt.Fprintf(os.Stderr, "Available stacks:\n")
 		for _, s := range allStacks {
 			fmt.Fprintf(os.Stderr, "  %s\n", s)
@@ -87,7 +105,7 @@ func runAgent(args []string) {
 		fs.PrintDefaults()
 	}
 
-	if err := fs.Parse(args); err != nil {
+	if err := fs.Parse(constructArgs); err != nil {
 		os.Exit(1)
 	}
 
@@ -117,6 +135,7 @@ func runAgent(args []string) {
 	}
 
 	// Persist so `construct qs` can replay this invocation.
+	// Pass-through args (after --) are not persisted.
 	if err := config.SaveLastUsed(absRepoPath, *stackName, *mcp, []string(ports), *dockerMode); err != nil {
 		log.Printf("warning: could not save last-used settings: %v", err)
 	}
@@ -131,6 +150,7 @@ func runAgent(args []string) {
 		MCP:        *mcp,
 		Ports:      []string(ports),
 		DockerMode: *dockerMode,
+		ExtraArgs:  passthroughArgs,
 	}); err != nil {
 		log.Fatal(err)
 	}
@@ -231,12 +251,15 @@ func targetEnvFile(local bool) (string, error) {
 
 // runQuickstart re-runs the last stack recorded for the target repo.
 func runQuickstart(args []string) {
+	qsArgs, passthroughArgs := splitPassthrough(args)
+
 	fs := flag.NewFlagSet("construct qs", flag.ExitOnError)
 	fs.Usage = func() {
-		fmt.Fprintf(os.Stderr, "Usage: construct qs [path]\n\n")
+		fmt.Fprintf(os.Stderr, "Usage: construct qs [path] [-- <tool-args>]\n\n")
 		fmt.Fprintf(os.Stderr, "Re-runs the last stack used for the given repo (defaults to cwd).\n")
+		fmt.Fprintf(os.Stderr, "Anything after -- is forwarded verbatim to the tool inside the container.\n")
 	}
-	if err := fs.Parse(args); err != nil {
+	if err := fs.Parse(qsArgs); err != nil {
 		os.Exit(1)
 	}
 
@@ -284,5 +307,12 @@ func runQuickstart(args []string) {
 		agentArgs = append(agentArgs, "--port", p)
 	}
 	agentArgs = append(agentArgs, absRepoPath)
+	// Pass-through args are appended after -- so runAgent's splitPassthrough
+	// correctly routes them to runner.Config.ExtraArgs (and they are not saved
+	// to last-used, preserving the original session-resuming semantics).
+	if len(passthroughArgs) > 0 {
+		agentArgs = append(agentArgs, "--")
+		agentArgs = append(agentArgs, passthroughArgs...)
+	}
 	runAgent(agentArgs)
 }

cmd/construct/passthrough_test.go

@@ -0,0 +1,82 @@
+// Integration tests for the construct CLI -- pass-through args feature.
+//
+// These tests reuse the binary compiled by TestMain in config_test.go.
+package main_test
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestPassthrough_DoubleDashSeparatesToolArgs verifies that args after -- do
+// not cause a flag-parse error and are accepted by the binary.
+func TestPassthrough_DoubleDashSeparatesToolArgs(t *testing.T) {
+	home := t.TempDir()
+	// The binary will fail (no Docker), but must not exit with a flag-parse error.
+	out, _ := run(t, home, "", "--", "continue-session", "dead-beef-1234")
+	if strings.Contains(out, "flag provided but not defined") {
+		t.Errorf("-- caused a flag-parse error: %s", out)
+	}
+}
+
+// TestPassthrough_FlagsBeforeDoubleDash verifies that construct flags before --
+// are still parsed correctly when pass-through args follow.
+func TestPassthrough_FlagsBeforeDoubleDash(t *testing.T) {
+	home := t.TempDir()
+	out, _ := run(t, home, "", "--stack", "base", "--", "continue-session", "abc")
+	if strings.Contains(out, "flag provided but not defined") {
+		t.Errorf("flags before -- caused a parse error: %s", out)
+	}
+	if strings.Contains(out, "unknown stack") {
+		t.Errorf("valid stack was rejected: %s", out)
+	}
+}
+
+// TestPassthrough_UsageDocumentsDoubleDash verifies the usage text mentions --.
+func TestPassthrough_UsageDocumentsDoubleDash(t *testing.T) {
+	home := t.TempDir()
+	out, _ := run(t, home, "", "--help")
+	if !strings.Contains(out, "--") {
+		t.Errorf("usage output does not mention --:\n%s", out)
+	}
+}
+
+// TestPassthrough_QsDoubleDash verifies that qs accepts -- without a flag error.
+func TestPassthrough_QsDoubleDash(t *testing.T) {
+	home := t.TempDir()
+	repo := t.TempDir()
+
+	// Write a last-used entry so qs doesn't fail on "no previous run".
+	lastUsedDir := filepath.Join(home, ".construct")
+	if err := os.MkdirAll(lastUsedDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	entry := map[string]interface{}{
+		repo: map[string]interface{}{"stack": "base", "docker": "none"},
+	}
+	data, err := json.Marshal(entry)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(lastUsedDir, "last-used.json"), data, 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	out, _ := run(t, home, repo, "qs", repo, "--", "continue-session", "dead-beef-1234")
+	if strings.Contains(out, "flag provided but not defined") {
+		t.Errorf("qs -- caused a flag-parse error: %s", out)
+	}
+}
+
+// TestPassthrough_QsUsageDocumentsDoubleDash verifies the qs usage text mentions --.
+func TestPassthrough_QsUsageDocumentsDoubleDash(t *testing.T) {
+	home := t.TempDir()
+	// qs with no last-used entry exits non-zero with usage; that's fine.
+	out, _ := run(t, home, "", "qs", "--help")
+	if !strings.Contains(out, "--") {
+		t.Errorf("qs usage output does not mention --:\n%s", out)
+	}
+}

docs/spec/passthrough-args.md

@@ -0,0 +1,51 @@
+# Spec: Pass-through args (`--`)
+
+## Problem
+
+Some tools accept flags of their own (e.g. `opencode -s <session-id>`). Currently there is no way to hand those arguments to the tool when launching via `construct` or `construct qs`.
+
+## Solution
+
+Support a `--` separator in both `construct` and `construct qs`. Anything after `--` is appended verbatim to the tool's `RunCmd` inside the container.
+
+## Behaviour
+
+```
+construct [flags] [path] -- [tool-args...]
+construct qs [path] -- [tool-args...]
+```
+
+- Everything after the first bare `--` token is collected as `tool-args` and appended to the container's command after `Tool.RunCmd`.
+- The `[path]` positional and all `construct` flags are parsed from the portion **before** `--`.
+- If `--` is absent the behaviour is identical to today (no change in the default case).
+- `--debug` mode (`/bin/bash`) still ignores pass-through args — there is nothing useful to forward to a shell.
+
+### Examples
+
+```
+# Resume an existing opencode session
+construct qs -- -s ses_deadbeefcafe1234abcd5678
+
+# Same, specifying the repo explicitly
+construct qs ~/projects/myapp -- -s ses_deadbeefcafe1234abcd5678
+
+# Plain construct invocation with pass-through args
+construct --stack go -- -s ses_deadbeefcafe1234abcd5678
+```
+
+## Persistence
+
+Pass-through args are **not** persisted to `~/.construct/last-used.json`. They are one-off overrides. A subsequent bare `construct qs` will replay the saved flags without the pass-through args.
+
+## Implementation
+
+| File | Change |
+|------|--------|
+| `internal/runner/runner.go` | Add `ExtraArgs []string` to `Config`; append to `RunCmd` in `buildRunArgs` (only when not in debug mode) |
+| `cmd/construct/main.go` | `splitPassthrough` helper splits `args` on `--`; `runAgent` and `runQuickstart` use it to populate `runner.Config.ExtraArgs`; usage strings updated |
+
+## Non-goals
+
+- No persistence of pass-through args in last-used.
+- No validation of the tool args — they are forwarded verbatim.
+- No pass-through support in `--debug` mode (shell is the CMD; there is nothing to forward to).

docs/spec/quickstart-qs.md

@@ -11,7 +11,7 @@ Introduce a `qs` subcommand that replays the last `--stack`, `--docker`, `--mcp`
 ## Behaviour
 
 ```
-construct qs [path]
+construct qs [path] [-- <tool-args>]
 ```
 
 - `path` defaults to the current working directory.
@@ -20,6 +20,7 @@ construct qs [path]
 - Errors with a clear message if no previous run has been recorded for the given path.
 - Replays `--docker`, `--mcp`, and all `--port` values that were used in the last recorded invocation.
 - For entries recorded before `--docker` was introduced (no `"docker"` key), defaults to `--docker none`.
+- Anything after a bare `--` separator is forwarded verbatim to the tool inside the container and is **not** saved to last-used (see `docs/spec/passthrough-args.md`).
 
 ## Persistence
 
@@ -44,11 +45,12 @@ Settings are saved automatically at the end of argument validation in every norm
 | File | Change |
 |------|--------|
 | `internal/config/lastused.go` | New — `SaveLastUsed`, `LoadLastUsed`, JSON read/write helpers; `DockerMode` field added |
-| `cmd/construct/main.go` | `main()` routes `qs` → `runQuickstart`; `runAgent` calls `SaveLastUsed`; `runQuickstart` prints and replays all flags; help lists `qs` under Subcommands |
+| `cmd/construct/main.go` | `main()` routes `qs` → `runQuickstart`; `runAgent` calls `SaveLastUsed`; `runQuickstart` prints and replays all flags; `runQuickstart` uses `splitPassthrough` to forward `--` args without saving them; help lists `qs` under Subcommands |
 | `README.md` | New **Quickstart (qs)** section |
 
 ## Non-goals
 
 - No flag to disable auto-saving.
 - No `qs --stack` overrides (just use the full command instead).
 - No TTY prompt to confirm before launching; the reused settings are printed to stderr.
+- Pass-through args after `--` are not persisted; a subsequent bare `construct qs` replays only the saved flags.

internal/runner/runner.go

@@ -45,6 +45,10 @@ type Config struct {
 	// Valid values: "none" (no Docker; default), "dood" (Docker-outside-of-Docker
 	// via host socket bind-mount), "dind" (Docker-in-Docker sidecar).
 	DockerMode string
+	// ExtraArgs are additional arguments passed verbatim to the tool after
+	// Tool.RunCmd. They are collected from everything the user supplies after
+	// a bare "--" separator on the command line. Ignored in Debug mode.
+	ExtraArgs []string
 }
 
 // Run builds images, starts any requested Docker sidecar, and runs the agent
@@ -286,6 +290,7 @@ func buildRunArgs(cfg *Config, dindInst *dind.Instance, image, sessionID, homeVo
 		args = append(args, "/bin/bash")
 	} else {
 		args = append(args, cfg.Tool.RunCmd...)
+		args = append(args, cfg.ExtraArgs...)
 	}
 	return args
 }