ccqa 1.58.3 → 1.59.0

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.58.3",
+  "version": "1.59.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/dist/runtime/judge.cjs

@@ -415,7 +415,7 @@ function formatDuration(ms) {
 	return `${minutes} minute${minutes === 1 ? "" : "s"}`;
 }
 async function invokeClaudeStreaming(options, onEvent) {
-	const { prompt, systemPrompt, allowedTools, disableThinking = false, mcpServers, maxTurns, timeoutMs, env, model, cwd, onAbAction, onAbActionFailed, silenceBashLog = false, envScrubMap = [], relaxAbConstraints = false, additionalDirectories } = options;
+	const { prompt, systemPrompt, allowedTools, disableThinking = false, effort, bashGuard, mcpServers, maxTurns, timeoutMs, env, model, cwd, onAbAction, onAbActionFailed, beforeAbCommand, silenceBashLog = false, envScrubMap = [], relaxAbConstraints = false, additionalDirectories } = options;
 	const resolvedModel = resolveModel(model);
 	const mergedEnv = buildInvocationEnv(env);
 	const abortController = new AbortController();
@@ -443,52 +443,35 @@ async function invokeClaudeStreaming(options, onEvent) {
 		env: mergedEnv,
 		...mcpServers ? { mcpServers } : {},
 		...disableThinking ? { thinking: { type: "disabled" } } : {},
-		hooks: onAbAction || onAbActionFailed ? {
+		...effort ? { effort } : {},
+		hooks: onAbAction || onAbActionFailed || bashGuard || beforeAbCommand ? {
 			PreToolUse: [{ hooks: [async (input) => {
 				if (input.hook_event_name !== "PreToolUse") return {};
 				if (input.tool_name !== "Bash") return {};
 				const cmd = input.tool_input?.["command"];
 				if (typeof cmd !== "string") return {};
+				const guarded = bashGuard?.(cmd);
+				if (guarded) return {
+					decision: "block",
+					reason: guarded
+				};
 				if (!relaxAbConstraints) {
-					if (isBlockedAbSubcommand(cmd)) return {
+					const reason = abCommandBlockReason(cmd, envScrubMap);
+					if (reason !== null) return {
 						decision: "block",
-						reason: "This agent-browser subcommand is not allowed because it cannot be recorded as a structured test action. Use only the standard commands: click, check, fill, select, hover, press, wait, find (with role/text/label/placeholder/alt/title/testid/first/last/nth). Take a fresh snapshot to find the correct selector."
+						reason
 					};
-					if (hasRefSelector(cmd)) return {
+					const checkpoint = beforeAbCommand?.(extractCcqaStepFromBashCommand(cmd) ?? void 0);
+					if (checkpoint) return {
 						decision: "block",
-						reason: "@ref selectors (like @e14) are session-specific and change every run. They cannot be used in generated tests. Use one of the allowed selector formats instead: [aria-label='...'], text=..., [placeholder='...'], or [type='password']. Take a fresh snapshot and find the element's aria-label or visible text. If an allowed selector already clicks the element but nothing happens, the element is clipped by an inner scroll container: `scrollintoview` it (addressed by a CSS selector, not `text=`) and click again — a @ref would not have fixed that either."
-					};
-					const bareTag = findPositionalBareTag(cmd);
-					if (bareTag !== null) return {
-						decision: "block",
-						reason: `\`find ${bareTag.locator}\` with a bare tag selector (\`${bareTag.selector}\`) is rejected: it matches every <${bareTag.selector}> on the page and is non-deterministic on replay. Pass a specific attribute selector instead, e.g. \`find ${bareTag.locator} "[aria-label='...']" ${bareTag.action}\` or \`find ${bareTag.locator} "[data-qa='...']" ${bareTag.action}\`. Take a fresh snapshot to find the right attribute.`
-					};
-					if (hasMultipleAbInvocations(cmd)) return {
-						decision: "block",
-						reason: "Run each `agent-browser` call as its own Bash command. Chaining multiple invocations with &&, ;, |, or || prevents ccqa from recording them as discrete steps and lets failed attempts leak into the trace. Issue one Bash tool call per agent-browser command."
-					};
-					if (hasErrorSuppression(cmd)) return {
-						decision: "block",
-						reason: "Do not suppress errors on `agent-browser` commands. Remove `|| true`, `|| :`, `2>/dev/null`, `; true`, and similar redirects so ccqa can detect failures and roll back unsuccessful attempts. Run the command standalone and let it surface its exit code."
-					};
-					const runProducedUrl = findRunProducedOpenUrl(cmd, envScrubMap);
-					if (runProducedUrl !== null) return {
-						decision: "block",
-						reason: `Do not open ${runProducedUrl} — that address was produced by this run (the id in it belongs to a record this run created), so the generated test would open a record later runs do not have. Reach the page the way a person does: click through from where the run already is. If the spec's instruction really names this exact address, put the id in a profile variable so it survives replay.`
+						reason: checkpoint
 					};
 				}
-				const assertMarker = relaxAbConstraints ? null : extractCcqaAssertFromBashCommand(cmd);
-				const ab = relaxAbConstraints ? null : extractAbActionFromBashCommand(cmd) ?? (assertMarker !== null ? extractObservationAbAction(cmd) : null);
-				if ((ab !== null || assertMarker !== null) && onAbAction) {
+				const recorded = relaxAbConstraints ? null : abActionEventFromCommand(cmd);
+				if (recorded !== null && onAbAction) {
 					lastAbToolUseId = input.tool_use_id;
-					lastAbAnswerHolds = assertMarker === null ? null : markerHolds(assertMarker, ab);
-					const stepId = extractCcqaStepFromBashCommand(cmd);
-					onAbAction({
-						...ab !== null ? { abAction: ab } : {},
-						...stepId ? { stepId } : {},
-						...assertMarker !== null ? { assertMarker } : {},
-						...hasCcqaSecretPrefix(cmd) ? { secret: true } : {}
-					});
+					lastAbAnswerHolds = recorded.holds;
+					onAbAction(recorded.event);
 				} else lastAbToolUseId = null;
 				return {};
 			}] }],
@@ -1076,6 +1059,41 @@ async function fireMockPreToolUseHooks(msg, options) {
 		for (const matcher of matchers) for (const hook of matcher.hooks) await hook(input, block.id, { signal: new AbortController().signal });
 	}
 }
+/**
+* Why the trace refuses this agent-browser command, or null when it may run.
+* Shared by the Bash hook and the trace's own batch tool, so both enforce the
+* same replayability contract.
+*/
+function abCommandBlockReason(cmd, envScrubMap = []) {
+	if (isBlockedAbSubcommand(cmd)) return "This agent-browser subcommand is not allowed because it cannot be recorded as a structured test action. Use only the standard commands: click, check, fill, select, hover, press, wait, find (with role/text/label/placeholder/alt/title/testid/first/last/nth). Take a fresh snapshot to find the correct selector.";
+	if (hasRefSelector(cmd)) return "@ref selectors (like @e14) are session-specific and change every run. They cannot be used in generated tests. Use one of the allowed selector formats instead: [aria-label='...'], text=..., [placeholder='...'], or [type='password']. Take a fresh snapshot and find the element's aria-label or visible text. If an allowed selector already clicks the element but nothing happens, the element is clipped by an inner scroll container: `scrollintoview` it (addressed by a CSS selector, not `text=`) and click again — a @ref would not have fixed that either.";
+	const bareTag = findPositionalBareTag(cmd);
+	if (bareTag !== null) return `\`find ${bareTag.locator}\` with a bare tag selector (\`${bareTag.selector}\`) is rejected: it matches every <${bareTag.selector}> on the page and is non-deterministic on replay. Pass a specific attribute selector instead, e.g. \`find ${bareTag.locator} "[aria-label='...']" ${bareTag.action}\` or \`find ${bareTag.locator} "[data-qa='...']" ${bareTag.action}\`. Take a fresh snapshot to find the right attribute.`;
+	if (hasMultipleAbInvocations(cmd)) return "Run each `agent-browser` call as its own Bash command. Chaining multiple invocations with &&, ;, |, or || prevents ccqa from recording them as discrete steps and lets failed attempts leak into the trace. Issue one Bash tool call per agent-browser command.";
+	if (hasErrorSuppression(cmd)) return "Do not suppress errors on `agent-browser` commands. Remove `|| true`, `|| :`, `2>/dev/null`, `; true`, and similar redirects so ccqa can detect failures and roll back unsuccessful attempts. Run the command standalone and let it surface its exit code.";
+	const runProducedUrl = findRunProducedOpenUrl(cmd, envScrubMap);
+	if (runProducedUrl !== null) return `Do not open ${runProducedUrl} — that address was produced by this run (the id in it belongs to a record this run created), so the generated test would open a record later runs do not have. Reach the page the way a person does: click through from where the run already is. If the spec's instruction really names this exact address, put the id in a profile variable so it survives replay.`;
+	return null;
+}
+/**
+* What recording this command produces, and — for a marked probe — what its
+* output must say for the check to hold. Null when it records nothing.
+*/
+function abActionEventFromCommand(cmd) {
+	const assertMarker = extractCcqaAssertFromBashCommand(cmd);
+	const ab = extractAbActionFromBashCommand(cmd) ?? (assertMarker !== null ? extractObservationAbAction(cmd) : null);
+	if (ab === null && assertMarker === null) return null;
+	const stepId = extractCcqaStepFromBashCommand(cmd);
+	return {
+		event: {
+			...ab !== null ? { abAction: ab } : {},
+			...stepId ? { stepId } : {},
+			...assertMarker !== null ? { assertMarker } : {},
+			...hasCcqaSecretPrefix(cmd) ? { secret: true } : {}
+		},
+		holds: assertMarker === null ? null : markerHolds(assertMarker, ab)
+	};
+}
 //#endregion
 //#region src/drift/auth.ts
 /**

package/dist/runtime/judge.mjs

@@ -414,7 +414,7 @@ function formatDuration(ms) {
 	return `${minutes} minute${minutes === 1 ? "" : "s"}`;
 }
 async function invokeClaudeStreaming(options, onEvent) {
-	const { prompt, systemPrompt, allowedTools, disableThinking = false, mcpServers, maxTurns, timeoutMs, env, model, cwd, onAbAction, onAbActionFailed, silenceBashLog = false, envScrubMap = [], relaxAbConstraints = false, additionalDirectories } = options;
+	const { prompt, systemPrompt, allowedTools, disableThinking = false, effort, bashGuard, mcpServers, maxTurns, timeoutMs, env, model, cwd, onAbAction, onAbActionFailed, beforeAbCommand, silenceBashLog = false, envScrubMap = [], relaxAbConstraints = false, additionalDirectories } = options;
 	const resolvedModel = resolveModel(model);
 	const mergedEnv = buildInvocationEnv(env);
 	const abortController = new AbortController();
@@ -442,52 +442,35 @@ async function invokeClaudeStreaming(options, onEvent) {
 		env: mergedEnv,
 		...mcpServers ? { mcpServers } : {},
 		...disableThinking ? { thinking: { type: "disabled" } } : {},
-		hooks: onAbAction || onAbActionFailed ? {
+		...effort ? { effort } : {},
+		hooks: onAbAction || onAbActionFailed || bashGuard || beforeAbCommand ? {
 			PreToolUse: [{ hooks: [async (input) => {
 				if (input.hook_event_name !== "PreToolUse") return {};
 				if (input.tool_name !== "Bash") return {};
 				const cmd = input.tool_input?.["command"];
 				if (typeof cmd !== "string") return {};
+				const guarded = bashGuard?.(cmd);
+				if (guarded) return {
+					decision: "block",
+					reason: guarded
+				};
 				if (!relaxAbConstraints) {
-					if (isBlockedAbSubcommand(cmd)) return {
+					const reason = abCommandBlockReason(cmd, envScrubMap);
+					if (reason !== null) return {
 						decision: "block",
-						reason: "This agent-browser subcommand is not allowed because it cannot be recorded as a structured test action. Use only the standard commands: click, check, fill, select, hover, press, wait, find (with role/text/label/placeholder/alt/title/testid/first/last/nth). Take a fresh snapshot to find the correct selector."
+						reason
 					};
-					if (hasRefSelector(cmd)) return {
+					const checkpoint = beforeAbCommand?.(extractCcqaStepFromBashCommand(cmd) ?? void 0);
+					if (checkpoint) return {
 						decision: "block",
-						reason: "@ref selectors (like @e14) are session-specific and change every run. They cannot be used in generated tests. Use one of the allowed selector formats instead: [aria-label='...'], text=..., [placeholder='...'], or [type='password']. Take a fresh snapshot and find the element's aria-label or visible text. If an allowed selector already clicks the element but nothing happens, the element is clipped by an inner scroll container: `scrollintoview` it (addressed by a CSS selector, not `text=`) and click again — a @ref would not have fixed that either."
-					};
-					const bareTag = findPositionalBareTag(cmd);
-					if (bareTag !== null) return {
-						decision: "block",
-						reason: `\`find ${bareTag.locator}\` with a bare tag selector (\`${bareTag.selector}\`) is rejected: it matches every <${bareTag.selector}> on the page and is non-deterministic on replay. Pass a specific attribute selector instead, e.g. \`find ${bareTag.locator} "[aria-label='...']" ${bareTag.action}\` or \`find ${bareTag.locator} "[data-qa='...']" ${bareTag.action}\`. Take a fresh snapshot to find the right attribute.`
-					};
-					if (hasMultipleAbInvocations(cmd)) return {
-						decision: "block",
-						reason: "Run each `agent-browser` call as its own Bash command. Chaining multiple invocations with &&, ;, |, or || prevents ccqa from recording them as discrete steps and lets failed attempts leak into the trace. Issue one Bash tool call per agent-browser command."
-					};
-					if (hasErrorSuppression(cmd)) return {
-						decision: "block",
-						reason: "Do not suppress errors on `agent-browser` commands. Remove `|| true`, `|| :`, `2>/dev/null`, `; true`, and similar redirects so ccqa can detect failures and roll back unsuccessful attempts. Run the command standalone and let it surface its exit code."
-					};
-					const runProducedUrl = findRunProducedOpenUrl(cmd, envScrubMap);
-					if (runProducedUrl !== null) return {
-						decision: "block",
-						reason: `Do not open ${runProducedUrl} — that address was produced by this run (the id in it belongs to a record this run created), so the generated test would open a record later runs do not have. Reach the page the way a person does: click through from where the run already is. If the spec's instruction really names this exact address, put the id in a profile variable so it survives replay.`
+						reason: checkpoint
 					};
 				}
-				const assertMarker = relaxAbConstraints ? null : extractCcqaAssertFromBashCommand(cmd);
-				const ab = relaxAbConstraints ? null : extractAbActionFromBashCommand(cmd) ?? (assertMarker !== null ? extractObservationAbAction(cmd) : null);
-				if ((ab !== null || assertMarker !== null) && onAbAction) {
+				const recorded = relaxAbConstraints ? null : abActionEventFromCommand(cmd);
+				if (recorded !== null && onAbAction) {
 					lastAbToolUseId = input.tool_use_id;
-					lastAbAnswerHolds = assertMarker === null ? null : markerHolds(assertMarker, ab);
-					const stepId = extractCcqaStepFromBashCommand(cmd);
-					onAbAction({
-						...ab !== null ? { abAction: ab } : {},
-						...stepId ? { stepId } : {},
-						...assertMarker !== null ? { assertMarker } : {},
-						...hasCcqaSecretPrefix(cmd) ? { secret: true } : {}
-					});
+					lastAbAnswerHolds = recorded.holds;
+					onAbAction(recorded.event);
 				} else lastAbToolUseId = null;
 				return {};
 			}] }],
@@ -1075,6 +1058,41 @@ async function fireMockPreToolUseHooks(msg, options) {
 		for (const matcher of matchers) for (const hook of matcher.hooks) await hook(input, block.id, { signal: new AbortController().signal });
 	}
 }
+/**
+* Why the trace refuses this agent-browser command, or null when it may run.
+* Shared by the Bash hook and the trace's own batch tool, so both enforce the
+* same replayability contract.
+*/
+function abCommandBlockReason(cmd, envScrubMap = []) {
+	if (isBlockedAbSubcommand(cmd)) return "This agent-browser subcommand is not allowed because it cannot be recorded as a structured test action. Use only the standard commands: click, check, fill, select, hover, press, wait, find (with role/text/label/placeholder/alt/title/testid/first/last/nth). Take a fresh snapshot to find the correct selector.";
+	if (hasRefSelector(cmd)) return "@ref selectors (like @e14) are session-specific and change every run. They cannot be used in generated tests. Use one of the allowed selector formats instead: [aria-label='...'], text=..., [placeholder='...'], or [type='password']. Take a fresh snapshot and find the element's aria-label or visible text. If an allowed selector already clicks the element but nothing happens, the element is clipped by an inner scroll container: `scrollintoview` it (addressed by a CSS selector, not `text=`) and click again — a @ref would not have fixed that either.";
+	const bareTag = findPositionalBareTag(cmd);
+	if (bareTag !== null) return `\`find ${bareTag.locator}\` with a bare tag selector (\`${bareTag.selector}\`) is rejected: it matches every <${bareTag.selector}> on the page and is non-deterministic on replay. Pass a specific attribute selector instead, e.g. \`find ${bareTag.locator} "[aria-label='...']" ${bareTag.action}\` or \`find ${bareTag.locator} "[data-qa='...']" ${bareTag.action}\`. Take a fresh snapshot to find the right attribute.`;
+	if (hasMultipleAbInvocations(cmd)) return "Run each `agent-browser` call as its own Bash command. Chaining multiple invocations with &&, ;, |, or || prevents ccqa from recording them as discrete steps and lets failed attempts leak into the trace. Issue one Bash tool call per agent-browser command.";
+	if (hasErrorSuppression(cmd)) return "Do not suppress errors on `agent-browser` commands. Remove `|| true`, `|| :`, `2>/dev/null`, `; true`, and similar redirects so ccqa can detect failures and roll back unsuccessful attempts. Run the command standalone and let it surface its exit code.";
+	const runProducedUrl = findRunProducedOpenUrl(cmd, envScrubMap);
+	if (runProducedUrl !== null) return `Do not open ${runProducedUrl} — that address was produced by this run (the id in it belongs to a record this run created), so the generated test would open a record later runs do not have. Reach the page the way a person does: click through from where the run already is. If the spec's instruction really names this exact address, put the id in a profile variable so it survives replay.`;
+	return null;
+}
+/**
+* What recording this command produces, and — for a marked probe — what its
+* output must say for the check to hold. Null when it records nothing.
+*/
+function abActionEventFromCommand(cmd) {
+	const assertMarker = extractCcqaAssertFromBashCommand(cmd);
+	const ab = extractAbActionFromBashCommand(cmd) ?? (assertMarker !== null ? extractObservationAbAction(cmd) : null);
+	if (ab === null && assertMarker === null) return null;
+	const stepId = extractCcqaStepFromBashCommand(cmd);
+	return {
+		event: {
+			...ab !== null ? { abAction: ab } : {},
+			...stepId ? { stepId } : {},
+			...assertMarker !== null ? { assertMarker } : {},
+			...hasCcqaSecretPrefix(cmd) ? { secret: true } : {}
+		},
+		holds: assertMarker === null ? null : markerHolds(assertMarker, ab)
+	};
+}
 //#endregion
 //#region src/drift/auth.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.58.3",
+  "version": "1.59.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {