Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

Sync from Copyberry

Copyberry36eef05a8a9c
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/mcp-app.html.br b/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/mcp-app.html.br
index e476ba4dd..82e23dbd8 100644
Binary files a/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/mcp-app.html.br and b/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/mcp-app.html.br differ
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/server.mjs.br.part-000 b/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/server.mjs.br.part-000
index 1748672d9..d2de05069 100644
Binary files a/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/server.mjs.br.part-000 and b/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/server.mjs.br.part-000 differ
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/server.mjs.br.part-001 b/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/server.mjs.br.part-001
index 9ebcb5673..014f19045 100644
Binary files a/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/server.mjs.br.part-001 and b/sdk/python/src/openai_codex_security/_bundled_plugin/mcp/server.mjs.br.part-001 differ
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/references/final-report.md b/sdk/python/src/openai_codex_security/_bundled_plugin/references/final-report.md
index b9911a161..c095d8766 100644
--- a/sdk/python/src/openai_codex_security/_bundled_plugin/references/final-report.md
+++ b/sdk/python/src/openai_codex_security/_bundled_plugin/references/final-report.md
@@ -16,7 +16,7 @@ Use `report.md` as the primary readable entry point. Explain report-relevant art
In the final response, link the generated markdown report path as the primary readable artifact.
-Every scan mode uses the same final report pipeline. The model authors canonical JSON only; it must not author, repair, or treat an existing `report.md` as input. `complete-scan` invokes finalization, which validates and enriches the canonical JSON, seals the canonical JSON and evidence artifacts, then deterministically generates and validates `report.md` as an unsealed downstream projection. Missing report prose must be added to the structured canonical fields rather than recovered from a separately authored report.
+Every scan mode uses the same final report pipeline. The model authors canonical JSON only; it must not author, repair, or treat an existing `report.md` as input. For an app-backed running scan, author `scan-manifest.json` as an unsealed draft and omit `scan.sealedAt` and `scan.artifacts`; finalization owns the exact workbench timestamps, seal, artifact digests, and derived finding identities. `complete-scan` invokes finalization, which validates and enriches the canonical JSON, seals the canonical JSON and evidence artifacts, then deterministically generates and validates `report.md` as an unsealed downstream projection. Missing report prose must be added to the structured canonical fields rather than recovered from a separately authored report.
When `complete_codex_security_scan` is available, use it to complete the scan. In Codex CLI or another terminal/chat host without that tool, run `python <plugin_dir>/scripts/finalize_scan_contract.py --scan-dir <scan_dir> --source-root <repo_root>` after writing the completed canonical JSON. Do not mark the scan goal complete until this command succeeds and the generated markdown report exists.
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/deep_scan_workbench.py b/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/deep_scan_workbench.py
index def3de4f7..caaeedbb2 100644
--- a/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/deep_scan_workbench.py
+++ b/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/deep_scan_workbench.py
@@ -517,6 +517,13 @@ def pending_deep_workspace_for_target(
).fetchone()
+def setup_ui_opt_out_enabled(connection: sqlite3.Connection) -> bool:
+ row = connection.execute(
+ "SELECT skip_setup_ui FROM setup_preferences WHERE singleton = 1"
+ ).fetchone()
+ return row is not None and bool(row["skip_setup_ui"])
+
+
def begin_deep_scan_for_scan(
connection: sqlite3.Connection,
scan_id: str,
@@ -567,12 +574,6 @@ def begin_deep_scan_for_target(
existing = existing_deep_scan_for_target(connection, thread_id, target_path, scope)
if existing is not None:
return begin_deep_scan_for_scan(connection, existing["id"], thread_id, args)
- if pending_deep_workspace_for_target(connection, thread_id, target_path, scope) is not None:
- raise SystemExit(
- "A matching Codex Security setup workspace is waiting for Start scan. "
- "Finish that setup and retry with its scanId."
- )
-
target_metadata = target.stat()
revision = git_revision(target)
target_snapshot_digest = (
@@ -604,7 +605,10 @@ def begin_deep_scan_for_target(
existing["id"],
start_disposition="joined" if existing_run is not None else "created",
)
- if pending_deep_workspace_for_target(connection, thread_id, target_path, scope) is not None:
+ pending_workspace = pending_deep_workspace_for_target(
+ connection, thread_id, target_path, scope
+ )
+ if pending_workspace is not None and not setup_ui_opt_out_enabled(connection):
raise SystemExit(
"A matching Codex Security setup workspace is waiting for Start scan. "
"Finish that setup and retry with its scanId."
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_cli.py b/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_cli.py
index f0b70fa57..e81db3094 100644
--- a/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_cli.py
+++ b/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_cli.py
@@ -26,6 +26,8 @@ def parse_args(description: str) -> argparse.Namespace:
parser = argparse.ArgumentParser(description=description)
subparsers = parser.add_subparsers(dest="command", required=True)
+ subparsers.add_parser("get-setup-preference")
+
create_workspace = subparsers.add_parser("create-workspace")
create_workspace.add_argument("--workspace-id", required=True)
create_workspace.add_argument("--thread-id")
@@ -110,6 +112,22 @@ def parse_args(description: str) -> argparse.Namespace:
start_scan.add_argument("--workspace-id", required=True)
start_scan.add_argument("--scan-root")
+ disable_setup_ui = subparsers.add_parser("disable-setup-ui")
+ disable_setup_ui.add_argument("--workspace-id", required=True)
+
+ start_prompt_only_scan = subparsers.add_parser("start-prompt-only-scan")
+ start_prompt_only_scan.add_argument("--thread-id", required=True)
+ start_prompt_only_scan.add_argument("--target-path", required=True)
+ start_prompt_only_scan.add_argument("--scope", required=True)
+ start_prompt_only_scan.add_argument("--mode", choices=("diff", "standard"), required=True)
+ start_prompt_only_scan.add_argument("--target-summary")
+ start_prompt_only_scan.add_argument("--user-context")
+ start_prompt_only_scan.add_argument("--diff-target-kind", choices=DIFF_TARGET_KINDS)
+ start_prompt_only_scan.add_argument("--diff-base-revision")
+ start_prompt_only_scan.add_argument("--diff-head-revision")
+ start_prompt_only_scan.add_argument("--diff-content-digest")
+ start_prompt_only_scan.add_argument("--scan-root")
+
deep_scan.register_subcommands(subparsers, positive_int)
get_scan = subparsers.add_parser("get-scan")
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_db.py b/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_db.py
index 79702c04d..d9a5674cf 100644
--- a/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_db.py
+++ b/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_db.py
@@ -38,10 +38,8 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
import deep_scan_workbench as deep_scan
import workbench_progress as progress
import workbench_remediation as remediation
-from filesystem_identity import (
- serialize_filesystem_identity,
- stored_filesystem_identity_matches,
-)
+from filesystem_identity import serialize_filesystem_identity as serialize_filesystem_identity
+from filesystem_identity import stored_filesystem_identity_matches
from finalize_scan_contract import (
ContractError,
_prepare_scan_finalization,
@@ -76,6 +74,13 @@ from workbench_constants import (
PATCH_PREVIEW_BYTES,
SQLITE_RETRY_ATTEMPTS,
)
+from workbench_scan_start import (
+ compact_timestamp,
+ insert_running_scan,
+ safe_segment,
+ scan_diff_identity,
+ scan_target_identity,
+)
from workbench_schema import MIGRATIONS
from workbench_source_excerpt import finding_source_excerpt
from workbench_target import (
@@ -235,6 +240,39 @@ def sqlite_busy(error: sqlite3.OperationalError) -> bool:
return "locked" in str(error).lower() or "busy" in str(error).lower()
+def setup_preference(connection: sqlite3.Connection) -> dict[str, bool]:
+ row = connection.execute(
+ "SELECT skip_setup_ui FROM setup_preferences WHERE singleton = 1"
+ ).fetchone()
+ return {"skipSetupUi": bool(row["skip_setup_ui"]) if row is not None else False}
+
+
+def record_setup_ui_disabled(connection: sqlite3.Connection, timestamp: str) -> None:
+ connection.execute(
+ """
+ INSERT INTO setup_preferences (singleton, skip_setup_ui, updated_at)
+ VALUES (1, ?, ?)
+ ON CONFLICT(singleton) DO UPDATE SET
+ skip_setup_ui = excluded.skip_setup_ui,
+ updated_at = excluded.updated_at
+ """,
+ (1, timestamp),
+ )
+
+
+def disable_setup_ui(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
+ workspace_id = require_uuid(args.workspace_id, "workspace-id")
+ try:
+ connection.execute("BEGIN IMMEDIATE")
+ require_workspace(connection, workspace_id)
+ record_setup_ui_disabled(connection, now())
+ connection.commit()
+ except BaseException:
+ connection.rollback()
+ raise
+ return workspace_state(connection, workspace_id)
+
+
def apply_migrations(connection: sqlite3.Connection) -> None:
connection.commit()
connection.execute("BEGIN IMMEDIATE")
@@ -1352,6 +1390,14 @@ def set_diff_target(connection: sqlite3.Connection, args: argparse.Namespace) ->
return workspace_state(connection, workspace["id"])
+def scan_target_root(scan_root: str | None, target: Path) -> Path:
+ root = Path(scan_root).expanduser().resolve() if scan_root else state_dir() / "scans"
+ target_root = (root / safe_segment(target.name)).resolve()
+ if target_root == target or target in target_root.parents:
+ raise SystemExit("The scan artifact directory must be outside the selected target.")
+ return target_root
+
+
def start_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
workspace_id = require_uuid(args.workspace_id, "workspace-id")
manages_transaction = not connection.in_transaction
@@ -1390,23 +1436,15 @@ def start_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict
)
if diff_target is not None and not target_summary:
target_summary = diff_target_summary(diff_target)
- root = (
- Path(args.scan_root).expanduser().resolve() if args.scan_root else state_dir() / "scans"
- )
- target_root = (root / safe_segment(target.name)).resolve()
- if target_root == target or target in target_root.parents:
- raise SystemExit("The scan artifact directory must be outside the selected target.")
- revision = diff_target["headRevision"] if diff_target else git_revision(target)
- target_snapshot_digest = None
- if diff_target is None:
- target_snapshot_digest = (
- directory_content_digest(target)
- if revision == "unversioned"
- else worktree_content_digest(target)
- )
scope_file_count = directory_snapshot_regular_file_count(
target if scope == "." else target / scope
)
+ target_identity = scan_target_identity(
+ target,
+ diff_target,
+ metadata=target_metadata,
+ )
+ target_root = scan_target_root(args.scan_root, target)
target_root.mkdir(parents=True, exist_ok=True)
if manages_transaction:
connection.execute("BEGIN IMMEDIATE")
@@ -1446,70 +1484,161 @@ def start_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict
"This Codex thread already has an active Deep Scan for the selected "
"target and scope. Rejoin that scan instead of starting another one."
)
- scan_dir = Path(
- tempfile.mkdtemp(
- prefix=f"{safe_segment(revision)}_{compact_timestamp()}_",
- dir=target_root,
+ insert_running_scan(
+ connection,
+ scan_id=scan_id,
+ workspace=workspace,
+ target=target,
+ scope=scope,
+ diff_target=diff_target,
+ target_identity=target_identity,
+ target_root=target_root,
+ target_summary=target_summary,
+ scope_file_count=scope_file_count,
+ timestamp=timestamp,
+ )
+ if manages_transaction:
+ connection.commit()
+ except BaseException:
+ if manages_transaction:
+ connection.rollback()
+ raise
+ return workspace_state(connection, workspace["id"])
+
+
+def start_prompt_only_scan(
+ connection: sqlite3.Connection, args: argparse.Namespace
+) -> dict[str, Any]:
+ thread_id = optional_text(args.thread_id, maximum=512)
+ if thread_id is None:
+ raise SystemExit("thread-id is required.")
+ inspected = inspect_setup_values(
+ args.target_path,
+ args.scope,
+ args.mode,
+ args.diff_target_kind,
+ args.diff_base_revision,
+ args.diff_head_revision,
+ args.diff_content_digest,
+ )
+ target = Path(inspected["target"]["targetPath"])
+ target_path = str(target)
+ scope = inspected["scope"]
+ diff_target = inspected["diffTarget"]
+ user_context = optional_text(args.user_context)
+ target_summary = optional_text(args.target_summary, maximum=2400)
+ if diff_target is not None and not target_summary:
+ target_summary = diff_target_summary(diff_target)
+ scope_file_count = directory_snapshot_regular_file_count(
+ target if scope == "." else target / scope
+ )
+ diff_identity = scan_diff_identity(diff_target)
+ target_identity = scan_target_identity(target, diff_target)
+ target_root = scan_target_root(args.scan_root, target)
+
+ connection.execute("BEGIN IMMEDIATE")
+ try:
+ if not setup_preference(connection)["skipSetupUi"]:
+ raise SystemExit(
+ "Prompt-only scanning requires the persisted setup UI opt-out preference."
)
- ).resolve()
- connection.execute(
+ current_target = require_remediation_target(target_path)
+ current_diff_target = (
+ require_diff_target(
+ current_target,
+ args.diff_target_kind,
+ args.diff_base_revision,
+ args.diff_head_revision,
+ args.diff_content_digest,
+ )
+ if args.mode == "diff"
+ else None
+ )
+ if (
+ scan_target_identity(current_target, current_diff_target) != target_identity
+ or scan_diff_identity(current_diff_target) != diff_identity
+ ):
+ raise SystemExit(
+ "The selected scan target changed while the scan was starting. Try again."
+ )
+ existing = connection.execute(
"""
- INSERT INTO scans (
- id, workspace_id, target_id, target_path, target_revision, target_snapshot_digest,
- target_device, target_inode,
- scope, mode, user_context, deep_scan_owner_thread_id,
- diff_target_kind, diff_base_revision, diff_head_revision, diff_content_digest,
- target_summary, scan_dir, status, phase, started_at, created_at, updated_at
- ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'running', 'preflight', ?, ?, ?)
+ SELECT scans.* FROM scans
+ JOIN workspaces ON workspaces.active_scan_id = scans.id
+ WHERE workspaces.thread_id = ? AND workspaces.target_path = ?
+ AND workspaces.default_scope = ? AND workspaces.default_mode = ?
+ AND workspaces.user_context IS ? AND workspaces.target_summary IS ?
+ AND workspaces.diff_target_kind IS ? AND workspaces.diff_base_revision IS ?
+ AND workspaces.diff_head_revision IS ? AND workspaces.diff_content_digest IS ?
+ AND workspaces.submitted = 1 AND scans.target_revision = ?
+ AND scans.target_snapshot_digest IS ? AND scans.target_device = ?
+ AND scans.target_inode = ? AND scans.status = 'running'
+ AND scans.handoff_status = 'delivered'
+ AND scans.handoff_claim_token IS NULL
+ ORDER BY scans.updated_at DESC, scans.started_at DESC, scans.id LIMIT 1
""",
(
- scan_id,
- workspace["id"],
- workspace["target_id"],
- str(target),
- revision,
- target_snapshot_digest,
- serialize_filesystem_identity(target_metadata.st_dev),
- serialize_filesystem_identity(target_metadata.st_ino),
+ thread_id,
+ target_path,
scope,
- workspace["default_mode"],
- workspace["user_context"],
- workspace["thread_id"] if workspace["default_mode"] == "deep" else None,
- diff_target["kind"] if diff_target else None,
- diff_target["baseRevision"] if diff_target else None,
- diff_target["headRevision"] if diff_target else None,
- diff_target.get("contentDigest") if diff_target else None,
+ args.mode,
+ user_context,
target_summary,
- str(scan_dir),
- timestamp,
- timestamp,
- timestamp,
+ *diff_identity,
+ *target_identity,
),
- )
+ ).fetchone()
+ if existing is not None:
+ connection.commit()
+ return {**scan_context(connection, existing["id"]), "startDisposition": "joined"}
+ target_root.mkdir(parents=True, exist_ok=True)
+ workspace_id = str(uuid.uuid4())
+ scan_id = str(uuid.uuid4())
+ timestamp = now()
+ target_id = ensure_security_target(connection, target_path)
connection.execute(
"""
- INSERT INTO scan_progress (
- scan_id, scope_file_count, review_items_total, review_items_completed,
- reportable_findings_count, updated_at
- ) VALUES (?, ?, 0, 0, 0, ?)
+ INSERT INTO workspaces (
+ id, thread_id, target_id, target_path, target_title, target_summary, default_scope,
+ default_mode, user_context, diff_target_kind, diff_base_revision,
+ diff_head_revision, diff_content_digest, submitted, created_at, updated_at
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, ?)
""",
(
- scan_id,
- scope_file_count,
+ workspace_id,
+ thread_id,
+ target_id,
+ target_path,
+ target.name,
+ target_summary,
+ scope,
+ args.mode,
+ user_context,
+ *diff_identity,
+ timestamp,
timestamp,
),
)
- connection.execute(
- "UPDATE workspaces SET active_scan_id = ?, updated_at = ? WHERE id = ?",
- (scan_id, timestamp, workspace["id"]),
+ workspace = require_workspace(connection, workspace_id)
+ insert_running_scan(
+ connection,
+ scan_id=scan_id,
+ workspace=workspace,
+ target=target,
+ scope=scope,
+ diff_target=diff_target,
+ target_identity=target_identity,
+ target_root=target_root,
+ target_summary=target_summary,
+ scope_file_count=scope_file_count,
+ timestamp=timestamp,
+ handoff_status="delivered",
)
- if manages_transaction:
- connection.commit()
+ connection.commit()
except BaseException:
- if manages_transaction:
- connection.rollback()
+ connection.rollback()
raise
- return workspace_state(connection, workspace["id"])
+ return {**scan_context(connection, scan_id), "startDisposition": "created"}
def require_unchanged_target(scan: sqlite3.Row) -> None:
@@ -3466,17 +3595,6 @@ def reject_non_finite_json(value: str) -> None:
raise ValueError(f"non-finite JSON number {value!r} is not supported")
-def safe_segment(value: str) -> str:
- segment = "".join(
- character if character.isalnum() or character in "._-" else "-" for character in value
- )
- return segment.strip("-") or "scan"
-
-
-def compact_timestamp() -> str:
- return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
-
-
def main() -> None:
args = parse_args(__doc__)
deep_scan.configure(
@@ -3504,7 +3622,11 @@ def main() -> None:
print(json.dumps(result, allow_nan=False, sort_keys=True))
return
with closing(connect()) as connection:
- if args.command == "create-workspace":
+ if args.command == "get-setup-preference":
+ result = setup_preference(connection)
+ elif args.command == "disable-setup-ui":
+ result = disable_setup_ui(connection, args)
+ elif args.command == "create-workspace":
result = create_workspace(connection, args)
elif args.command == "get-workspace":
result = workspace_state(connection, args.workspace_id, thread_id=args.thread_id)
@@ -3524,6 +3646,8 @@ def main() -> None:
result = set_capability_preflight(connection, args)
elif args.command == "start-scan":
result = start_scan(connection, args)
+ elif args.command == "start-prompt-only-scan":
+ result = start_prompt_only_scan(connection, args)
elif args.command == "begin-deep-scan":
result = deep_scan.begin_deep_scan(connection, args)
elif args.command == "get-deep-scan":
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_schema.py b/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_schema.py
index 6dda57daf..ec295ffae 100644
--- a/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_schema.py
+++ b/sdk/python/src/openai_codex_security/_bundled_plugin/scripts/workbench_schema.py
@@ -494,6 +494,17 @@ MIGRATIONS = (
WHERE handoff_status = 'delivered';
""",
),
+ (
+ 19,
+ "persist setup workspace preference",
+ """
+ CREATE TABLE setup_preferences (
+ singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+ skip_setup_ui INTEGER NOT NULL CHECK (skip_setup_ui IN (0, 1)),
+ updated_at TEXT NOT NULL
+ );
+ """,
+ ),
)
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/skills/deep-security-scan/SKILL.md b/sdk/python/src/openai_codex_security/_bundled_plugin/skills/deep-security-scan/SKILL.md
index 240a45d0b..3ab4df6c8 100644
--- a/sdk/python/src/openai_codex_security/_bundled_plugin/skills/deep-security-scan/SKILL.md
+++ b/sdk/python/src/openai_codex_security/_bundled_plugin/skills/deep-security-scan/SKILL.md
@@ -28,6 +28,8 @@ Do not jump from the discovery manifest directly to completion. A returned `mani
Use the setup workspace only when host context explicitly says this is the Codex desktop app and both `open_codex_security_workspace` and `await_codex_security_scan_start` are available. Tool availability alone does not prove the host is the desktop app.
+The workspace tool enforces the persisted setup preference. When setup is disabled it returns `status: "setup_disabled"` without creating or rendering a workspace. Treat that result as authoritative even when a matching stale or unsubmitted setup workspace exists: do not await setup or ask the user to finish the old workspace, and continue through the prompt-only target route after its required preflight.
+
Scanbench and Promptfoo evaluations are headless runs even when MCP app tools are listed. On those paths, never call `open_codex_security_workspace` or `await_codex_security_scan_start`; use the target-form `start_codex_security_deep_scan` path.
For a new desktop scan:
@@ -35,10 +37,11 @@ For a new desktop scan:
1. Resolve only the setup arguments from the user request: local `targetPath`, `mode: "deep"`, `scope: "."`, and only user-supplied security focus as `userContext`. For a scoped-path request, use the scoped directory itself as `targetPath`.
2. Do not inspect repository code, run capability preflight, create a goal, or start discovery before setup opens.
3. Call `open_codex_security_workspace`.
-4. Immediately call `await_codex_security_scan_start` with its `sessionId` and wait for the user to press **Start scan**.
+4. If opening returns `status: "setup_disabled"`, continue at step 6 without calling the wait tool. Otherwise, require its `sessionId`, immediately call `await_codex_security_scan_start`, and wait for the user to press **Start scan** or choose **Don't show setup again**.
5. On `status: "started"`, require `scanId`, load `get_codex_security_scan_context`, and pass `handoffClaimToken` when present.
-6. On `status: "already_delivered"`, end the turn because another continuation owns the scan.
-7. On `status: "timed_out"`, end the turn and tell the user to finish setup and use **Continue in Codex**. Do not open another workspace or switch to a terminal workflow.
+6. On `status: "setup_disabled"`, no scan was created. Resolve the same target, scope, and optional user context from the original prompt and immediately use the prompt-only target form of `start_codex_security_deep_scan`. Do not reopen or await setup.
+7. On `status: "already_delivered"`, end the turn because another continuation owns the scan.
+8. On `status: "timed_out"`, end the turn and tell the user to finish setup and use **Continue in Codex**. Do not open another workspace or switch to a terminal workflow.
For a desktop continuation that already includes `scanId`, load `get_codex_security_scan_context` directly and pass `handoffClaimToken` when present. If its validated mode is not `deep`, route to the matching top-level Codex Security skill.
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/skills/security-diff-scan/SKILL.md b/sdk/python/src/openai_codex_security/_bundled_plugin/skills/security-diff-scan/SKILL.md
index ba09cf55a..8377e702e 100644
--- a/sdk/python/src/openai_codex_security/_bundled_plugin/skills/security-diff-scan/SKILL.md
+++ b/sdk/python/src/openai_codex_security/_bundled_plugin/skills/security-diff-scan/SKILL.md
@@ -11,7 +11,9 @@ Used when a user wants to review a Git-backed change set for security regression
When this skill is the active top-level workflow, use the setup workspace only when the host context explicitly says it is running inside the Codex desktop app and both required setup continuation tools are available. Tool availability alone does not identify the app host. Otherwise, including Codex CLI interactive and headless runs, use the prompt-only terminal/chat workflow: do not call Codex Security app setup tools, ask the user to press Start scan, or wait for an app-generated `scanId`.
-Treat goal creation as scan execution, not setup. In the app setup path, do not create or adopt scan goals before the user presses Start scan, the authoritative scan context has been loaded from a `status: "started"` wait result or a direct continuation with a `scanId`, and the capability preflight has returned `ready`.
+The workspace tool enforces the persisted setup preference. When setup is disabled and complete diff context is available, it returns `status: "prompt_only_started"` with `startDisposition`, an authoritative UUID `scan.scanId` and `scan.scanDir`, and the exact `scan.diffTarget` without rendering setup. Use that returned context for the normal prompt-driven preflight and scan phases. Because this remains an app-backed scan, author the canonical artifacts under that `scanDir` and call `complete_codex_security_scan` with that exact `scanId` after all phases so the findings side panel renders. Author `scan-manifest.json` as an unsealed draft: omit `scan.sealedAt` and `scan.artifacts`; completion supplies the exact workbench timestamps, seal, artifact digests, and derived finding identities. If the workspace tool errors or returns malformed context, stop and surface that error instead of inventing an artifact path.
+
+Treat goal creation as scan execution, not setup. In the app setup path, do not create or adopt scan goals until the capability preflight has returned `ready` and authoritative scan context came from one of these routes: the user pressed **Start scan** and the `status: "started"` context was loaded; the user chose **Don't show setup again** and the same wait returned `status: "prompt_only_started"`; or a direct continuation supplied a `scanId`.
For an app continuation that already includes a `scanId` and optional `handoffClaimToken`, do not open another workspace: call `get_codex_security_scan_context` with the `scanId`, pass its `handoffClaimToken` when present, route elsewhere only if its validated mode differs, and use its target, `diffTarget`, optional `userContext`, and `scanDir`.
@@ -20,17 +22,18 @@ Otherwise, in a host that renders MCP Apps and exposes the Codex Security setup
1. Resolve setup arguments directly from the user's initial prompt and known thread context: checked-out Git repository `targetPath`, `mode: "diff"`, `scope: "."`, user-supplied security focus as `userContext`, and `diffTarget` only when the prompt unambiguously identifies uncommitted changes against current `HEAD`, one commit, or a locally resolved PR, branch comparison, or revision range.
2. Perform only the minimal path or revision resolution needed to construct those arguments. Do not run capability preflight, inspect the repository beyond that minimal resolution, threat model, discover findings, or create workers before setup opens.
3. Immediately call `open_codex_security_workspace` with the resolved arguments. Do not search for or substitute a separate scan command.
-4. Immediately call `await_codex_security_scan_start` with the `sessionId` from the workspace returned by `open_codex_security_workspace`. A returned workspace with `setup.submitted=false` is the expected wait state. Keep the tool call pending while waiting for the user to review setup and press Start scan; do not create or adopt a scan goal, run preflight, or pivot to terminal/chat fallback while waiting.
+4. If opening returns `status: "prompt_only_started"`, continue at step 6 without calling the wait tool. Otherwise, require the returned workspace `sessionId`, immediately call `await_codex_security_scan_start`, and keep that call pending while waiting for the user to review setup, press Start scan, or choose **Don't show setup again**. A returned workspace with `setup.submitted=false` is the expected wait state. Do not create or adopt a scan goal, run preflight, or pivot to another route while waiting.
5. If the wait returns `status: "started"`, require its `scanId`, call `get_codex_security_scan_context` with that `scanId`, and pass its `handoffClaimToken` when present. Then run the preflight in `../../references/config-preflight.md` for the selected target and `security_diff_scan` profile before goal setup, threat modeling, or other substantive scan work.
-6. If the wait returns `status: "already_delivered"`, end the current turn without loading scan context or starting scan work. Another continuation already owns the scan.
-7. If the wait returns `status: "timed_out"`, end the current turn and tell the user to finish setup and use **Continue in Codex** after pressing Start scan. Do not run preflight, create or adopt a scan goal, open another workspace, or pivot to terminal/chat fallback.
-8. Continue after a `ready` result, explaining material warn or suggest limitations. If preflight is `blocked` or `incomplete` with actionable remediation, present the exact reasons and config delta, ask whether to apply the remediation, and stop for the user's answer before creating or adopting a scan goal or calling `fail_codex_security_scan`. Do not fail automatically for declined or unavailable remediation, helper errors, or a non-ready rerun. Preserve the running scan and retry or hand off while recovery may still be possible. If the user declines required remediation, ask whether to cancel or leave the scan running for a later retry. Call `fail_codex_security_scan` with the exact reason only after documented recovery is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels.
+6. On `status: "prompt_only_started"` from either opening or waiting, require `startDisposition` plus an authoritative UUID `scan.scanId`, `scan.scanDir`, and the exact `scan.diffTarget`, then follow the prompt-only desktop route described above with that exact scan context. Do not reopen or await setup, and do not call `start_codex_security_prompt_only_scan` again. A `status: "setup_disabled"` result means the workspace call lacked complete diff context; stop and surface it instead of starting a replacement scan.
+7. If the wait returns `status: "already_delivered"`, end the current turn without loading scan context or starting scan work. Another continuation already owns the scan.
+8. If the wait returns `status: "timed_out"`, end the current turn and tell the user to finish setup and use **Continue in Codex** after pressing Start scan. Do not run preflight, create or adopt a scan goal, open another workspace, or pivot to terminal/chat fallback.
+9. Continue after a `ready` result, explaining material warn or suggest limitations. If preflight is `blocked` or `incomplete` with actionable remediation, present the exact reasons and config delta, ask whether to apply the remediation, and stop for the user's answer before creating or adopting a scan goal or calling `fail_codex_security_scan`. Do not fail automatically for declined or unavailable remediation, helper errors, or a non-ready rerun. Preserve the running scan and retry or hand off while recovery may still be possible. If the user declines required remediation, ask whether to cancel or leave the scan running for a later retry. Call `fail_codex_security_scan` with the exact reason only after documented recovery is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels.
-Before opening setup, use the existing terminal/chat preflight and scan workflow for local changes against another requested base because the setup app cannot represent that working-tree diff target. Codex CLI, including interactive and headless runs, and hosts without the required app capabilities use the same prompt-only fallback. Do not call `open_codex_security_workspace` or `await_codex_security_scan_start` on this path. Once `open_codex_security_workspace` succeeds in an MCP Apps-capable host, remain on the app path: immediately call `await_codex_security_scan_start`; a `status: "timed_out"` result means end the turn and point the user to **Continue in Codex**, while `status: "already_delivered"` means stop because another continuation owns the scan. Do not start a terminal/chat fallback for either result.
+Before opening setup, use the existing terminal/chat preflight and scan workflow for local changes against another requested base because the setup app cannot represent that working-tree diff target. Codex CLI, including interactive and headless runs, and hosts without the required app capabilities use the same prompt-only fallback. Do not call `open_codex_security_workspace`, `await_codex_security_scan_start`, or `start_codex_security_prompt_only_scan` on this non-app path. The desktop prompt-only path above is app-backed even though its phases are prompt-driven; keep its returned `scanId` and use MCP completion. Once `open_codex_security_workspace` succeeds in an MCP Apps-capable host, immediately call `await_codex_security_scan_start`; only `status: "prompt_only_started"` switches this same request to the desktop prompt-only route. A `status: "timed_out"` result means end the turn and point the user to **Continue in Codex**, while `status: "already_delivered"` means stop because another continuation owns the scan.
## Capability Preflight
-Read `../../references/config-preflight.md` and dispatch and await the preflight execution described there with the `security_diff_scan` capability profile before substantive scan work, including after an app wait or direct continuation has produced a `scanId` and loaded its authoritative scan context. Follow the returned block/warn/suggest results. For an app-generated scan, ask before applying actionable remediation and wait without creating a scan goal or calling `fail_codex_security_scan`. Do not fail automatically for declined or unavailable remediation, helper errors, or a non-ready rerun; preserve the running scan and retry or hand off while recovery may still be possible. Call `fail_codex_security_scan` only after documented recovery is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels. Do not treat a config value that differs from a suggested patch as a warning unless the capability requirement itself is unmet.
+Read `../../references/config-preflight.md` and dispatch and await the preflight execution described there with the `security_diff_scan` capability profile before substantive scan work, including after an app wait, desktop prompt-only start, or direct continuation has produced a `scanId` and loaded its authoritative scan context. Follow the returned block/warn/suggest results. For an app-backed scan, ask before applying actionable remediation and wait without creating a scan goal or calling `fail_codex_security_scan`. Do not fail automatically for declined or unavailable remediation, helper errors, or a non-ready rerun; preserve the running scan and retry or hand off while recovery may still be possible. Call `fail_codex_security_scan` only after documented recovery is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels. Do not treat a config value that differs from a suggested patch as a warning unless the capability requirement itself is unmet.
## Phase Sequence
@@ -56,7 +59,7 @@ Treat explicit invocation of this exhaustive diff-scan workflow as the user's au
## Goal Setup
-After the app wait or direct continuation has provided a `scanId`, the authoritative scan context has been loaded, and the `security_diff_scan` capability preflight has returned `ready`, or after the same preflight is `ready` in Codex CLI or terminal/chat hosts without the setup app, create a Codex goal for the scan if the runtime exposes goal tools and no active goal already covers this scan. The objective should state that the scan must not stop until the resolved diff-scoped files have been covered and the required coverage artifacts prove that closure.
+After the app wait, desktop prompt-only start, or direct continuation has provided an authoritative `scanId` and scan context, and the `security_diff_scan` capability preflight has returned `ready`, or after the same preflight is `ready` in Codex CLI or terminal/chat hosts without the setup app, create a Codex goal for the scan if the runtime exposes goal tools and no active goal already covers this scan. The objective should state that the scan must not stop until the resolved diff-scoped files have been covered and the required coverage artifacts prove that closure.
Use objective wording shaped like:
@@ -79,7 +82,7 @@ Use the shared scan artifact path conventions in `../../references/scan-artifact
## Execution Plan
-Start this plan only after `Setup Workspace Routing` has either loaded the app-generated scan context with a `scanId`, or determined that the host is using the non-app terminal/chat workflow, and the `security_diff_scan` capability preflight has returned `ready`.
+Start this plan only after `Setup Workspace Routing` has loaded an app-generated or desktop prompt-only scan context with a `scanId`, or determined that the host is using the non-app terminal/chat workflow, and the `security_diff_scan` capability preflight has returned `ready`.
Follow this plan in order. Do not skip ahead to a later phase until the current phase has produced its intended output.
@@ -159,5 +162,5 @@ Populate all final report semantics in the canonical manifest, findings, and cov
Read `../../references/shared-hard-rules.md` before applying scan-mode-specific hard rules.
-- After any app setup handoff has provided a `scanId`, or in the non-app terminal/chat workflow, create or adopt the scan goal only after the capability preflight has returned `ready`, and before substantive scan work. Do not complete it until the resolved diff-scoped files/worklist rows, candidate ledgers, and final report meet the `Goal Setup` closure criteria.
+- After any app setup handoff or desktop prompt-only start has provided a `scanId`, or in the non-app terminal/chat workflow, create or adopt the scan goal only after the capability preflight has returned `ready`, and before substantive scan work. Do not complete it until the resolved diff-scoped files/worklist rows, candidate ledgers, and final report meet the `Goal Setup` closure criteria.
- Do not claim diff coverage until every `deep_review_input.jsonl` row has a completion receipt in `work_ledger.jsonl`.
diff --git a/sdk/python/src/openai_codex_security/_bundled_plugin/skills/security-scan/SKILL.md b/sdk/python/src/openai_codex_security/_bundled_plugin/skills/security-scan/SKILL.md
index a5774dbed..ff8c56f43 100644
--- a/sdk/python/src/openai_codex_security/_bundled_plugin/skills/security-scan/SKILL.md
+++ b/sdk/python/src/openai_codex_security/_bundled_plugin/skills/security-scan/SKILL.md
@@ -11,9 +11,11 @@ Used when a user wants to audit an entire repository or a user-specified path, p
When this skill is the active top-level workflow, use the setup workspace only when the host context explicitly says it is running inside the Codex desktop app and both required setup continuation tools are available. Tool availability alone does not identify the app host. Otherwise, including Codex CLI interactive and headless runs, use the prompt-only terminal/chat workflow: do not call Codex Security app setup tools, ask the user to press Start scan, or wait for an app-generated `scanId`.
+The workspace tool enforces the persisted setup preference. When setup is disabled and complete standard-scan context is available, it returns `status: "prompt_only_started"` with `startDisposition` plus an authoritative UUID `scan.scanId` and `scan.scanDir` without rendering setup. Use that returned context for the normal prompt-driven preflight and scan phases. Because this remains an app-backed scan, author the canonical artifacts under that `scanDir` and call `complete_codex_security_scan` with that exact `scanId` after all phases so the findings side panel renders. Author `scan-manifest.json` as an unsealed draft: omit `scan.sealedAt` and `scan.artifacts`; completion supplies the exact workbench timestamps, seal, artifact digests, and derived finding identities. If the workspace tool errors or returns malformed context, stop and surface that error instead of inventing an artifact path.
+
Scanbench and Promptfoo evaluations are headless runs even when MCP app tools are listed. On those paths, never call `open_codex_security_workspace` or `await_codex_security_scan_start`; use the prompt-only terminal/chat workflow.
-Treat goal creation as scan execution, not setup. In the app setup path, do not create or adopt scan goals before the user presses Start scan, the authoritative scan context has been loaded from a `status: "started"` wait result or a direct continuation with a `scanId`, and the capability preflight has returned `ready`.
+Treat goal creation as scan execution, not setup. In the app setup path, do not create or adopt scan goals until the capability preflight has returned `ready` and authoritative scan context came from one of these routes: the user pressed **Start scan** and the `status: "started"` context was loaded; the user chose **Don't show setup again** and the same wait returned `status: "prompt_only_started"`; or a direct continuation supplied a `scanId`.
For an app continuation that already includes a `scanId` and optional `handoffClaimToken`, do not open another workspace: call `get_codex_security_scan_context` with the `scanId`, pass its `handoffClaimToken` when present, route elsewhere only if its validated mode differs, and use its target, scope, optional `userContext`, and `scanDir`.
@@ -22,17 +24,18 @@ Otherwise, in a host that renders MCP Apps and exposes the Codex Security setup
1. Resolve setup arguments directly from the user's initial prompt and known thread context: local `targetPath`, `mode: "standard"`, target-relative `scope` (`"."` for the whole target), and only user-supplied security focus as `userContext`.
2. Perform only the minimal path resolution needed to construct those arguments. Do not run capability preflight, inspect the repository, threat model, discover findings, or create workers before setup opens.
3. Immediately call `open_codex_security_workspace` with the resolved arguments. Do not search for or substitute a separate scan command.
-4. Immediately call `await_codex_security_scan_start` with the `sessionId` from the workspace returned by `open_codex_security_workspace`. A returned workspace with `setup.submitted=false` is the expected wait state. Keep the tool call pending while waiting for the user to review setup and press Start scan; do not create or adopt a scan goal, run preflight, or pivot to terminal/chat fallback while waiting.
+4. If opening returns `status: "prompt_only_started"`, continue at step 6 without calling the wait tool. Otherwise, require the returned workspace `sessionId`, immediately call `await_codex_security_scan_start`, and keep that call pending while waiting for the user to review setup, press Start scan, or choose **Don't show setup again**. A returned workspace with `setup.submitted=false` is the expected wait state. Do not create or adopt a scan goal, run preflight, or pivot to another route while waiting.
5. If the wait returns `status: "started"`, require its `scanId`, call `get_codex_security_scan_context` with that `scanId`, and pass its `handoffClaimToken` when present. Then run the preflight in `../../references/config-preflight.md` for the selected target and `security_scan` profile before goal setup, threat modeling, or other substantive scan work.
-6. If the wait returns `status: "already_delivered"`, end the current turn without loading scan context or starting scan work. Another continuation already owns the scan.
-7. If the wait returns `status: "timed_out"`, end the current turn and tell the user to finish setup and use **Continue in Codex** after pressing Start scan. Do not run preflight, create or adopt a scan goal, open another workspace, or pivot to terminal/chat fallback.
-8. Continue after a `ready` result, explaining material warn or suggest limitations. If preflight is `blocked` or `incomplete` with actionable remediation, present the exact reasons and config delta, ask whether to apply the remediation, and stop for the user's answer before creating or adopting a scan goal or calling `fail_codex_security_scan`. Do not fail automatically for declined or unavailable remediation, helper errors, or a non-ready rerun. Preserve the running scan and retry or hand off while recovery may still be possible. If the user declines required remediation, ask whether to cancel or leave the scan running for a later retry. Call `fail_codex_security_scan` with the exact reason only after documented recovery is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels.
+6. On `status: "prompt_only_started"` from either opening or waiting, require `startDisposition` plus an authoritative UUID `scan.scanId` and `scan.scanDir`, then follow the prompt-only desktop route described above with that exact scan context. Do not reopen or await setup, and do not call `start_codex_security_prompt_only_scan` again. A `status: "setup_disabled"` result means the workspace call lacked complete standard-scan context; stop and surface it instead of starting a replacement scan.
+7. If the wait returns `status: "already_delivered"`, end the current turn without loading scan context or starting scan work. Another continuation already owns the scan.
+8. If the wait returns `status: "timed_out"`, end the current turn and tell the user to finish setup and use **Continue in Codex** after pressing Start scan. Do not run preflight, create or adopt a scan goal, open another workspace, or pivot to terminal/chat fallback.
+9. Continue after a `ready` result, explaining material warn or suggest limitations. If preflight is `blocked` or `incomplete` with actionable remediation, present the exact reasons and config delta, ask whether to apply the remediation, and stop for the user's answer before creating or adopting a scan goal or calling `fail_codex_security_scan`. Do not fail automatically for declined or unavailable remediation, helper errors, or a non-ready rerun. Preserve the running scan and retry or hand off while recovery may still be possible. If the user declines required remediation, ask whether to cancel or leave the scan running for a later retry. Call `fail_codex_security_scan` with the exact reason only after documented recovery is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels.
-In Codex CLI, including interactive and headless runs, or hosts without those capabilities, use the existing prompt-only terminal/chat preflight and scan workflow and shared artifact paths. Do not call `open_codex_security_workspace` or `await_codex_security_scan_start` on this path. Once `open_codex_security_workspace` succeeds in an MCP Apps-capable host, remain on the app path: immediately call `await_codex_security_scan_start`; a `status: "timed_out"` result means end the turn and point the user to **Continue in Codex**, while `status: "already_delivered"` means stop because another continuation owns the scan. Do not start a terminal/chat fallback for either result.
+In Codex CLI, including interactive and headless runs, or hosts without those capabilities, use the existing prompt-only terminal/chat preflight and scan workflow and shared artifact paths. Do not call `open_codex_security_workspace`, `await_codex_security_scan_start`, or `start_codex_security_prompt_only_scan` on this path. The desktop prompt-only path above is app-backed even though its phases are prompt-driven; keep its returned `scanId` and use MCP completion. Once `open_codex_security_workspace` succeeds in an MCP Apps-capable host, immediately call `await_codex_security_scan_start`; only `status: "prompt_only_started"` switches this same request to the desktop prompt-only route. A `status: "timed_out"` result means end the turn and point the user to **Continue in Codex**, while `status: "already_delivered"` means stop because another continuation owns the scan.
## Capability Preflight
-Read `../../references/config-preflight.md` and dispatch and await the preflight execution described there with the `security_scan` capability profile before substantive scan work, including after an app wait or direct continuation has produced a `scanId` and loaded its authoritative scan context. Follow the returned block/warn/suggest results. For an app-generated scan, ask before applying actionable remediation and wait without creating a scan goal or calling `fail_codex_security_scan`. Do not fail automatically for declined or unavailable remediation, helper errors, or a non-ready rerun; preserve the running scan and retry or hand off while recovery may still be possible. Call `fail_codex_security_scan` only after documented recovery is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels. Do not treat a config value that differs from a suggested patch as a warning unless the capability requirement itself is unmet.
+Read `../../references/config-preflight.md` and dispatch and await the preflight execution described there with the `security_scan` capability profile before substantive scan work, including after an app wait, desktop prompt-only start, or direct continuation has produced a `scanId` and loaded its authoritative scan context. Follow the returned block/warn/suggest results. For an app-backed scan, ask before applying actionable remediation and wait without creating a scan goal or calling `fail_codex_security_scan`. Do not fail automatically for declined or unavailable remediation, helper errors, or a non-ready rerun; preserve the running scan and retry or hand off while recovery may still be possible. Call `fail_codex_security_scan` only after documented recovery is exhausted and the blocker is confirmed unrecoverable, or when the user explicitly cancels. Do not treat a config value that differs from a suggested patch as a warning unless the capability requirement itself is unmet.
## Phase Sequence
@@ -58,7 +61,7 @@ For repository-wide and scoped-path scans, treat explicit invocation of this exh
## Goal Setup
-After the app wait or direct continuation has provided a `scanId`, the authoritative scan context has been loaded, and the `security_scan` capability preflight has returned `ready`, or after the same preflight is `ready` in Codex CLI or terminal/chat hosts without the setup app, create a Codex goal for the scan if the runtime exposes goal tools and no active goal already covers this scan. The objective should state that the scan must not stop until the resolved files in scope have been covered and the required coverage artifacts prove that closure.
+After the app wait, desktop prompt-only start, or direct continuation has provided an authoritative `scanId` and scan context, and the `security_scan` capability preflight has returned `ready`, or after the same preflight is `ready` in Codex CLI or terminal/chat hosts without the setup app, create a Codex goal for the scan if the runtime exposes goal tools and no active goal already covers this scan. The objective should state that the scan must not stop until the resolved files in scope have been covered and the required coverage artifacts prove that closure.
Use objective wording shaped like:
@@ -81,7 +84,7 @@ Use the shared scan artifact path conventions in `../../references/scan-artifact
## Execution Plan
-Start this plan only after `Setup Workspace Routing` has either loaded the app-generated scan context with a `scanId`, or determined that the host is using the non-app terminal/chat workflow, and the `security_scan` capability preflight has returned `ready`.
+Start this plan only after `Setup Workspace Routing` has loaded an app-generated or desktop prompt-only scan context with a `scanId`, or determined that the host is using the non-app terminal/chat workflow, and the `security_scan` capability preflight has returned `ready`.
Follow this plan in order. Do not skip ahead to a later phase until the current phase has produced its intended output.
@@ -149,7 +152,7 @@ Populate all final report semantics in the canonical manifest, findings, and cov
Read `../../references/shared-hard-rules.md` before applying scan-mode-specific hard rules.
-- After any app setup handoff has provided a `scanId`, or in the non-app terminal/chat workflow, create or adopt the scan goal only after the capability preflight has returned `ready`, and before substantive scan work. Do not complete it until the resolved in-scope files/worklist rows, candidate ledgers, and final reports meet the `Goal Setup` closure criteria.
+- After any app setup handoff or desktop prompt-only start has provided a `scanId`, or in the non-app terminal/chat workflow, create or adopt the scan goal only after the capability preflight has returned `ready`, and before substantive scan work. Do not complete it until the resolved in-scope files/worklist rows, candidate ledgers, and final reports meet the `Goal Setup` closure criteria.
- For repository-wide and scoped-path scans, do not equate broad sink counts with completed coverage. The coverage ledger must close each applicable high-impact shard row as `reportable`, `suppressed`, `not_applicable`, or `deferred`.
- For every scan scope, candidate-finding coverage is required. Do not finalize a candidate finding until its candidate-ledger path from `../../references/scan-artifacts.md` shows discovery, validation, and attack-path receipts for that exact candidate, or an explicit deferred reason for the missing proof.
- For repository-wide and scoped-path scans, subagent dispatch must have explicit ownership: each of no more than six ranking subagents owns one static `rank_worker_assignments.json` pool slot containing one or more generated `rank_shards/*.input.jsonl` shards of at most 150 rows, processes its ordered list sequentially, and writes only the matching worker-local `.output.jsonl` files; file-review subagents own one assessed file or tiny shard and return full-file receipts plus pre-dedupe finding objects with candidate-local validation evidence and attack-path facts; validation subagents own one candidate or ledger row that needs validation closure; attack-path subagents own one validated candidate or validation closure row; the parent agent owns bounded worker orchestration, ledger reconciliation, aggregation, cross-file dedupe, and final closure.