Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

fix(signals): keep repo hooks out of report research (#124248)

Dylan Martin973e1ef69763
diff --git a/packages/agent/packages/agent-contracts/src/domain-types.ts b/packages/agent/packages/agent-contracts/src/domain-types.ts
index 2acc07d14306..03475f3483fa 100644
--- a/packages/agent/packages/agent-contracts/src/domain-types.ts
+++ b/packages/agent/packages/agent-contracts/src/domain-types.ts
@@ -370,6 +370,7 @@ const taskRunStateFields = {
benjamin_version: optionalField(z.string()),
codex_max_subagents: optionalField(z.number().int().positive()),
codex_shared_prompt_cache: optionalField(z.boolean()),
+ disable_repo_hooks: optionalField(z.boolean()),
initial_permission_mode: optionalField(executionModeSchema),
initial_prompt_override: optionalField(z.string()),
pending_followup_messages: optionalField(
diff --git a/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts b/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts
index 0d1d31c1065e..83fe1765557a 100644
--- a/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts
+++ b/packages/agent/packages/agent/src/adapters/claude/claude-agent.ts
@@ -3313,6 +3313,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
getCurrentModelId: () => this.session?.modelId,
gatewayEnv: this.options?.gatewayEnv,
traceparentHookNonce,
+ disableRepoHooks: meta?.disableRepoHooks === true,
machineAuth: this.options?.machineAuth,
bedrockGatewayVariant,
contextWiki: this.options?.contextWiki,
diff --git a/packages/agent/packages/agent/src/adapters/claude/session/options.test.ts b/packages/agent/packages/agent/src/adapters/claude/session/options.test.ts
index c71b26b28d6a..a62dd19f21cc 100644
--- a/packages/agent/packages/agent/src/adapters/claude/session/options.test.ts
+++ b/packages/agent/packages/agent/src/adapters/claude/session/options.test.ts
@@ -1085,6 +1085,42 @@ describe("buildSessionOptions", () => {
expect(options.settingSources).toEqual(["user", "project", "local"]);
});
+ it("pins disableAllHooks for a run that opts out of repo hooks", () => {
+ const options = buildSessionOptions({
+ ...makeParams(),
+ gatewayEnv,
+ disableRepoHooks: true,
+ });
+
+ const settings = flagSettings(options);
+ expect(settings.disableAllHooks).toBe(true);
+ expect(settings.hooks).toBeUndefined();
+ expect(settings.env.ANTHROPIC_BASE_URL).toBe("https://gateway.example");
+ expect(options.settingSources).toEqual(["user", "project", "local"]);
+ });
+
+ it("passes disableAllHooks inline when no gateway pin is written", () => {
+ const options = buildSessionOptions({
+ ...makeParams(),
+ disableRepoHooks: true,
+ });
+
+ expect(JSON.parse(String(options.extraArgs?.settings))).toEqual({
+ disableAllHooks: true,
+ });
+ });
+
+ it("drops repo settings to keep repo hooks off when the caller owns the settings flag", () => {
+ const options = buildSessionOptions({
+ ...makeParams(),
+ gatewayEnv,
+ disableRepoHooks: true,
+ userProvidedOptions: { settings: '{"model":"x"}' },
+ });
+
+ expect(options.settingSources).toEqual(["user"]);
+ });
+
it.each([
["a settings file path", { settings: "/tmp/caller-settings.json" }],
["an unparseable settings flag", { extraArgs: { settings: "not json" } }],
diff --git a/packages/agent/packages/agent/src/adapters/claude/session/options.ts b/packages/agent/packages/agent/src/adapters/claude/session/options.ts
index b23e863baa1d..5909be0c9e1a 100644
--- a/packages/agent/packages/agent/src/adapters/claude/session/options.ts
+++ b/packages/agent/packages/agent/src/adapters/claude/session/options.ts
@@ -136,6 +136,8 @@ export interface BuildOptionsParams {
/** Session's discriminator for the traceparent hook's stderr; the hook is
* skipped when absent (see session/traceparent-hook.ts). */
traceparentHookNonce?: string;
+ /** Keeps hooks from the repo's `.claude/settings*.json` from running. */
+ disableRepoHooks?: boolean;
machineAuth?: MachineClaudeAuth;
/** Matched `bedrock-llm-gateway` variant; `test` serves this session from Bedrock. */
bedrockGatewayVariant?: BedrockGatewayVariant;
@@ -711,7 +713,18 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
// option or a raw `extraArgs` flag — both reach the same CLI flag, and the
// SDK silently drops the extraArgs one on collision) rather than clobbering
// it. The hook command is POSIX shell, so Windows Desktop hosts skip it.
+ // A repo's Stop hook can block the final turn of a run that must end with
+ // JSON. `disableAllHooks` at flag level outranks project and local settings,
+ // so the repo cannot turn its hooks back on. It also stops the traceparent
+ // hook, so that hook is skipped for these runs.
+ const repoHooksOffSettings =
+ params.disableRepoHooks &&
+ params.userProvidedOptions?.settings === undefined &&
+ params.userProvidedOptions?.extraArgs?.settings === undefined
+ ? JSON.stringify({ disableAllHooks: true })
+ : undefined;
const traceparentHookSettings =
+ !params.disableRepoHooks &&
params.gatewayEnv?.anthropicBaseUrl &&
params.traceparentHookNonce &&
process.platform !== "win32" &&
@@ -753,6 +766,7 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
extraArgs: {
...params.userProvidedOptions?.extraArgs,
"replay-user-messages": "",
+ ...(repoHooksOffSettings && { settings: repoHooksOffSettings }),
...(traceparentHookSettings && { settings: traceparentHookSettings }),
},
// Surfaces the traceparent hook's output as `hook_response` messages.
@@ -828,6 +842,13 @@ export function buildSessionOptions(params: BuildOptionsParams): Options {
);
}
+ if (params.disableRepoHooks && !repoHooksOffSettings) {
+ // The caller owns the settings flag, so drop the repo settings instead.
+ options.settingSources = options.settingSources?.filter(
+ (source) => source !== "project" && source !== "local",
+ );
+ }
+
if (params.machineAuth?.oauthToken) {
delete options.pathToClaudeCodeExecutable;
delete options.executable;
diff --git a/packages/agent/packages/agent/src/adapters/claude/types.ts b/packages/agent/packages/agent/src/adapters/claude/types.ts
index 6dba6788f6cf..54b53dd61dc8 100644
--- a/packages/agent/packages/agent/src/adapters/claude/types.ts
+++ b/packages/agent/packages/agent/src/adapters/claude/types.ts
@@ -267,6 +267,8 @@ export type NewSessionMeta = {
taskOriginProduct?: string;
/** Workflow-action opt-in: exposes the `finish` tool to a workflow-origin run. */
endRunWhenDone?: boolean;
+ /** Keeps hooks from the repo's `.claude/settings*.json` from running. */
+ disableRepoHooks?: boolean;
/**
* The user's spoken-narration setting at session start. Gates the speak
* tool and its prompt instructions. Unset falls back by environment: cloud
diff --git a/packages/agent/packages/agent/src/server/agent-server.ts b/packages/agent/packages/agent/src/server/agent-server.ts
index 10cec653112e..f29f93de3ae6 100644
--- a/packages/agent/packages/agent/src/server/agent-server.ts
+++ b/packages/agent/packages/agent/src/server/agent-server.ts
@@ -2435,6 +2435,7 @@ export class AgentServer {
taskOriginProduct: launch.originProduct,
}),
...(launch.endRunWhenDone && { endRunWhenDone: true }),
+ ...(launch.disableRepoHooks && { disableRepoHooks: true }),
...(this.config.baseBranch && { baseBranch: this.config.baseBranch }),
...(runtimeAdapter === "claude" &&
this.config.contextWindow && {
diff --git a/packages/agent/packages/agent/src/server/launch/run-launch.ts b/packages/agent/packages/agent/src/server/launch/run-launch.ts
index 609beddefecc..87a142fe8cd3 100644
--- a/packages/agent/packages/agent/src/server/launch/run-launch.ts
+++ b/packages/agent/packages/agent/src/server/launch/run-launch.ts
@@ -34,6 +34,7 @@ export interface RunLaunch {
readonly initialPermissionMode: PermissionMode | null;
readonly pendingUserArtifactIds: string[];
readonly endRunWhenDone: boolean;
+ readonly disableRepoHooks: boolean;
readonly systemPrompt: ClaudeCodeConfig["systemPrompt"];
readonly systemPromptValid: boolean;
readonly tokenUsage: unknown;
@@ -67,6 +68,7 @@ export function readRunLaunch(sources: RunLaunchSources): RunLaunch {
initialPermissionMode: runState?.initial_permission_mode ?? null,
pendingUserArtifactIds: runState?.pending_user_artifact_ids ?? [],
endRunWhenDone: runState?.end_run_when_done === true,
+ disableRepoHooks: runState?.disable_repo_hooks === true,
systemPrompt: systemPrompt.success ? systemPrompt.data : undefined,
systemPromptValid: systemPrompt.success,
tokenUsage: runState?.token_usage,
diff --git a/products/signals/backend/report_generation/research.py b/products/signals/backend/report_generation/research.py
index 5fba265cdddf..ab063570f40f 100644
--- a/products/signals/backend/report_generation/research.py
+++ b/products/signals/backend/report_generation/research.py
@@ -101,6 +101,12 @@ MAX_REPORT_LAYERS = 6
MAX_REPORT_LAYER_TITLE_LENGTH = 96
MAX_REPORT_LAYER_SCOPE_LENGTH = 2_000
+# Sent once when the research agent ends its first turn with prose instead of the finding JSON.
+RESEARCH_JSON_RETRY_PROMPT = (
+ "Your last reply did not contain the JSON object the task asks for. "
+ "Reply now with only that JSON object, matching the schema above. Do not add prose or code fences."
+)
+
class ReportLayer(BaseModel):
"""One pull request in a stack of dependent pull requests. Each layer becomes a child report."""
@@ -1657,6 +1663,7 @@ async def run_multi_turn_research(
model=SignalFindingUpdate,
branch=branch,
step_name="report_research",
+ json_retry_prompt=RESEARCH_JSON_RETRY_PROMPT,
verbose=verbose,
output_fn=output_fn,
origin_product=tasks_facade.TaskOriginProduct.SIGNAL_REPORT,
diff --git a/products/signals/backend/temporal/agentic/report.py b/products/signals/backend/temporal/agentic/report.py
index 03f191dabfe0..569663f8feb0 100644
--- a/products/signals/backend/temporal/agentic/report.py
+++ b/products/signals/backend/temporal/agentic/report.py
@@ -11,6 +11,7 @@ import structlog
import temporalio
import posthoganalytics
from pydantic import BaseModel, ValidationError
+from temporalio.exceptions import ApplicationError
from posthog.dataclasses import frozen
from posthog.event_usage import groups
@@ -84,7 +85,7 @@ from products.signals.backend.typed_report_links import (
outgoing_links,
)
from products.tasks.backend.facade import api as tasks_facade
-from products.tasks.backend.facade.agents import CustomPromptSandboxContext, SandboxRunFailed
+from products.tasks.backend.facade.agents import CustomPromptSandboxContext, SandboxRunFailed, turn_failure_error_type
logger = structlog.get_logger(__name__)
@@ -1145,6 +1146,7 @@ async def run_agentic_report_activity(input: RunAgenticReportInput) -> RunAgenti
runtime_adapter=agent_runtime.runtime_adapter,
reasoning_effort=agent_runtime.reasoning_effort,
service_tier=agent_runtime.service_tier,
+ disable_repo_hooks=True,
)
has_bk = await database_sync_to_async(_team_has_business_knowledge, thread_sensitive=False)(input.team_id)
metrics_enabled = await database_sync_to_async(team_report_metrics_enabled, thread_sensitive=False)(
@@ -1294,4 +1296,7 @@ async def run_agentic_report_activity(input: RunAgenticReportInput) -> RunAgenti
team_id=input.team_id,
error=str(error),
)
+ error_type = turn_failure_error_type(error)
+ if error_type is not None:
+ raise ApplicationError(str(error), type=error_type) from error
raise
diff --git a/products/signals/backend/temporal/metrics.py b/products/signals/backend/temporal/metrics.py
index 03a354cfc75b..f1cb29d8c925 100644
--- a/products/signals/backend/temporal/metrics.py
+++ b/products/signals/backend/temporal/metrics.py
@@ -106,11 +106,13 @@ def increment_dropped(stage: str, reason: str, count: int = 1) -> None:
).add(count)
-def increment_report_completed(result: str) -> None:
+def increment_report_completed(result: str, failure_reason: str | None = None, error_type: str | None = None) -> None:
"""Count report completions by result (ready/failed/not_actionable/pending_input)."""
if not _in_temporal_context():
return
- get_metric_meter({"result": result}).create_counter(
+ get_metric_meter(
+ {"result": result, "failure_reason": failure_reason or "", "error_type": error_type or ""}
+ ).create_counter(
"signals_reports_total",
"Signal reports completed by result",
).add(1)
diff --git a/products/signals/backend/temporal/summary.py b/products/signals/backend/temporal/summary.py
index 479a0c51dc20..d6e6916be873 100644
--- a/products/signals/backend/temporal/summary.py
+++ b/products/signals/backend/temporal/summary.py
@@ -17,6 +17,11 @@ import posthoganalytics
from structlog.types import FilteringBoundLogger
from temporalio import workflow
from temporalio.common import RetryPolicy, WorkflowIDReusePolicy
+from temporalio.exceptions import (
+ ActivityError,
+ ApplicationError,
+ TimeoutError as TemporalTimeoutError,
+)
from temporalio.workflow import ParentClosePolicy
from posthog.clickhouse.client.connection import ClickHouseUser
@@ -102,6 +107,7 @@ def _capture_report_event(
source_products: list[str],
result: str | None = None,
failure_reason: str | None = None,
+ error_type: str | None = None,
pending_reason: str | None = None,
chart_count: int | None = None,
charts_enabled: bool | None = None,
@@ -126,11 +132,13 @@ def _capture_report_event(
properties["charts_enabled"] = charts_enabled
if failure_reason is not None:
properties["failure_reason"] = failure_reason
+ if error_type is not None:
+ properties["error_type"] = error_type
if pending_reason is not None:
properties["pending_reason"] = pending_reason
if event == "signal_report_completed" and result is not None:
- metrics.increment_report_completed(result)
+ metrics.increment_report_completed(result, failure_reason=failure_reason, error_type=error_type)
try:
posthoganalytics.capture(
@@ -149,6 +157,17 @@ def _capture_report_event(
)
+def _activity_error_type(error: BaseException) -> str | None:
+ if not isinstance(error, ActivityError):
+ return None
+ if isinstance(error.cause, TemporalTimeoutError):
+ return "activity_timeout"
+ # Temporal puts the class name of an unhandled activity exception in the ApplicationError type.
+ if isinstance(error.cause, ApplicationError):
+ return error.cause.type
+ return None
+
+
@frozen
class ReportDecision:
title: str
@@ -743,6 +762,7 @@ class SignalReportSummaryWorkflow:
if _is_research_sandbox_unavailable(e)
else "agentic_activity_error"
),
+ error_type=_activity_error_type(e),
signal_count=signal_count,
source_products=source_products,
),
@@ -1227,12 +1247,13 @@ async def maybe_autostart_implementation_activity(input: MaybeAutostartImplement
)
-@dataclass
+@dataclass(frozen=True)
class MarkReportFailedInput:
team_id: int
report_id: str
error: str
failure_reason: str | None = None
+ error_type: str | None = None
signal_count: int = 0
source_products: list[str] = field(default_factory=list)
@@ -1279,6 +1300,7 @@ async def mark_report_failed_activity(input: MarkReportFailedInput) -> None:
source_products=input.source_products,
result="failed",
failure_reason=input.failure_reason,
+ error_type=input.error_type,
)
logger.debug(
f"Marked report {input.report_id} as failed",
diff --git a/products/signals/backend/test/test_agentic_report_activity.py b/products/signals/backend/test/test_agentic_report_activity.py
index 5cabb74653b1..3d001e461cf3 100644
--- a/products/signals/backend/test/test_agentic_report_activity.py
+++ b/products/signals/backend/test/test_agentic_report_activity.py
@@ -86,7 +86,7 @@ from products.signals.backend.temporal.summary import (
mark_report_ready_activity,
)
from products.signals.backend.temporal.types import SignalData
-from products.tasks.backend.facade.agents import SandboxRunFailed
+from products.tasks.backend.facade.agents import CustomPromptSandboxContext, SandboxRunFailed
from products.tasks.backend.models import Task # tach-ignore
@@ -1521,7 +1521,16 @@ async def test_report_transition_discards_legacy_goal_fields(ateam: Team, pendin
@pytest.mark.asyncio
@pytest.mark.django_db
-async def test_run_agentic_report_activity_does_not_persist_partial_artefacts(monkeypatch, ateam):
+ "error,raised_type,error_type",
+ [
+ (RuntimeError("sandbox failed"), RuntimeError, None),
+ (ValueError("No JSON in initial turn: end-turn text was prose"), ApplicationError, "output_parse_failed"),
+ ],
+)
+async def test_run_agentic_report_activity_does_not_persist_partial_artefacts(
+ monkeypatch, ateam, error: Exception, raised_type: type[Exception], error_type: str | None
+):
report = await database_sync_to_async(SignalReport.objects.create)(
team=ateam,
status=SignalReport.Status.IN_PROGRESS,
@@ -1534,8 +1543,11 @@ async def test_run_agentic_report_activity_does_not_persist_partial_artefacts(mo
lambda team_id: 1,
)
- async def fake_run_multi_turn_research(*args, **kwargs):
- raise RuntimeError("sandbox failed")
+ contexts: list[CustomPromptSandboxContext] = []
+
+ async def fake_run_multi_turn_research(signals, context, **kwargs):
+ contexts.append(context)
+ raise error
monkeypatch.setattr(
"products.signals.backend.temporal.agentic.report.run_multi_turn_research",
@@ -1543,7 +1555,7 @@ async def test_run_agentic_report_activity_does_not_persist_partial_artefacts(mo
)
with patch("products.signals.backend.temporal.agentic.report.Heartbeater"):
- with pytest.raises(RuntimeError, match="sandbox failed"):
+ with pytest.raises(raised_type, match=str(error)) as raised:
await run_agentic_report_activity(
RunAgenticReportInput(
team_id=ateam.id,
@@ -1557,6 +1569,8 @@ async def test_run_agentic_report_activity_does_not_persist_partial_artefacts(mo
lambda: SignalReportArtefact.objects.filter(report=report).count()
)()
assert artefact_count == 0
+ assert getattr(raised.value, "type", None) == error_type
+ assert contexts[0].disable_repo_hooks
@pytest.mark.parametrize("enabled", [False, True])
diff --git a/products/signals/backend/test/test_summary_workflow.py b/products/signals/backend/test/test_summary_workflow.py
index 99fc737bed3c..26713ce490c4 100644
--- a/products/signals/backend/test/test_summary_workflow.py
+++ b/products/signals/backend/test/test_summary_workflow.py
@@ -201,6 +201,7 @@ class _Recorder:
self.checks_monitoring_enabled = False
self.selected_repository = selected_repository
self.research_errors = list(research_errors or [])
+ self.failure_error_types: list[str | None] = []
self.gate_checks: list[str] = []
self.fetches = 0
self.assigned_signal_checks = 0
@@ -328,6 +329,7 @@ async def _run_summary_workflow(recorder: _Recorder) -> None:
async def fake_failed(input: MarkReportFailedInput) -> None:
recorder.failures += 1
recorder.failure_reasons.append(input.failure_reason)
+ recorder.failure_error_types.append(input.error_type)
# The production self-driving worker runs with the pydantic data converter; the default converter
# mangles the enum/pydantic payloads these activities exchange (RepoSelectionResult,
@@ -427,13 +429,21 @@ async def test_research_fails_the_report_once_the_sandbox_retry_budget_is_spent(
@pytest.mark.asyncio
-async def test_research_does_not_retry_other_activity_errors():
- recorder = _Recorder(research_errors=[ApplicationError("bad output", type="ValueError") for _ in range(2)])
+ "research_error,error_type",
+ [
+ (ApplicationError("No JSON in initial turn", type="output_parse_failed"), "output_parse_failed"),
+ (RuntimeError("sandbox failed"), "RuntimeError"),
+ ],
+)
+async def test_research_does_not_retry_other_activity_errors(research_error: Exception, error_type: str):
+ recorder = _Recorder(research_errors=[research_error, research_error])
with pytest.raises(WorkflowFailureError):
await _run_summary_workflow(recorder)
assert recorder.researches == 2
assert recorder.failures == 1
assert recorder.failure_reasons == ["agentic_activity_error"]
+ assert recorder.failure_error_types == [error_type]
@pytest.mark.asyncio
diff --git a/products/signals/backend/test/test_temporal_metrics.py b/products/signals/backend/test/test_temporal_metrics.py
index 4b46ac489c01..5911cb166b61 100644
--- a/products/signals/backend/test/test_temporal_metrics.py
+++ b/products/signals/backend/test/test_temporal_metrics.py
@@ -82,8 +82,14 @@ class TestCounterHelpers:
patch.object(metrics, "get_metric_meter", return_value=meter) as get_meter,
):
metrics.increment_report_completed("not_actionable")
+ metrics.increment_report_completed(
+ "failed", failure_reason="agentic_activity_error", error_type="output_parse_failed"
+ )
- assert get_meter.call_args[0][0] == {"result": "not_actionable"}
+ assert [call[0][0] for call in get_meter.call_args_list] == [
+ {"result": "not_actionable", "failure_reason": "", "error_type": ""},
+ {"result": "failed", "failure_reason": "agentic_activity_error", "error_type": "output_parse_failed"},
+ ]
def test_dropped_labels(self):
meter = _mock_meter()
diff --git a/products/tasks/backend/facade/api.py b/products/tasks/backend/facade/api.py
index 885af287db54..ec7fbe017587 100644
--- a/products/tasks/backend/facade/api.py
+++ b/products/tasks/backend/facade/api.py
@@ -563,6 +563,7 @@ _TASK_RUN_PUBLIC_STATE_KEYS = frozenset(
"codex_subscription_user_id",
"context_window",
"custom_image_id",
+ "disable_repo_hooks",
"fast_mode",
# An imported transcript's provenance and mirror cursor: the viewer marks the run as
# imported, and the legacy mirror reads its own cursor back through this DTO.
diff --git a/products/tasks/backend/logic/services/custom_prompt_internals.py b/products/tasks/backend/logic/services/custom_prompt_internals.py
index 9cfc7c6947fb..092e2efad760 100644
--- a/products/tasks/backend/logic/services/custom_prompt_internals.py
+++ b/products/tasks/backend/logic/services/custom_prompt_internals.py
@@ -141,6 +141,10 @@ class CustomPromptSandboxContext:
"""Let runs that start from the same prompt prefix read each other's prompt cache. Codex-only. The
agent server asks the AI gateway to drop Codex's per-session cache key on every request of the run,
sub-agents included."""
+ disable_repo_hooks: bool = False
+ """Stop hooks from the cloned repo's ``.claude/settings*.json`` from running. A repo's Stop hook
+ can block the turn that must return the caller's JSON. The agent still reads the repo's CLAUDE.md.
+ Claude-only."""
initial_permission_mode: str | None = None
"""Agent approval mode. ``None`` lets ``_build_task`` pick the default (``"auto"`` for Codex). A
headless run that calls MCP tools must set ``"full-access"`` (Codex) / ``"bypassPermissions"``
@@ -359,6 +363,8 @@ async def _create_task_and_trigger(
extra_run_state["codex_max_subagents"] = context.codex_max_subagents
if context.codex_shared_prompt_cache:
extra_run_state["codex_shared_prompt_cache"] = True
+ if context.disable_repo_hooks:
+ extra_run_state["disable_repo_hooks"] = True
if analytics_query_context is not None:
queries = [query for query in analytics_query_context if query is not None]
if queries: