From 5383a6f38494598db44d3d4f798c9dc3d19d6192 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 13 Oct 2026 21:28:13 +0000 Subject: [PATCH 01/13] fix(sdk): keep the source's cipher and secrets on a forked conversation LocalConversation.fork() built the fork without the source's cipher, so the fork's base_state.json stored the LLM key redacted. The agent-server resumes every fork from that file, so the fork's first turn failed with LLMAuthenticationError. Forward the cipher, and copy the source's conversation secrets into the fork's registry so they persist too. The verify-agent-server map bullets F10.fork-keeps-credentials and F10.fork-run-memory now pass; their known-bug markers are removed. Fixes #5465 Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_014MKndVj7XWvRQmvW9w2bDg --- .../F10-fork-navigate-condense-ask.md | 38 ++++++------ .../conversation/impl/local_conversation.py | 18 +++++- tests/sdk/conversation/local/test_fork.py | 59 ++++++++++++++++++- 3 files changed, 92 insertions(+), 23 deletions(-) diff --git a/.agents/skills/verify-agent-server/references/feature-map/F10-fork-navigate-condense-ask.md b/.agents/skills/verify-agent-server/references/feature-map/F10-fork-navigate-condense-ask.md index 1283172dbe2..02139bb54da 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F10-fork-navigate-condense-ask.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F10-fork-navigate-condense-ask.md @@ -254,30 +254,28 @@ SIDE_AGENT="{\"llm\": {\"model\": \"openai/qa-stub\", \"api_key\": \"qa-stub-key alone. Server code that reads `meta.json` tags (telemetry's automation flag, the observability span's conversation tags) sees a different set than every consumer. -- **The fork keeps the model keys (`F10.fork-keeps-credentials`), known bug.** +- **The fork keeps the model keys (`F10.fork-keeps-credentials`).** Fork `S`, whose placeholder agent has a model key, and compare the stored agents. ```sh KF=$(control-agent-server api POST "/api/conversations/$S/fork" --expect 201 --field id) control-agent-server state cat base_state.json --conversation "$S" --max-chars 200 --check agent.llm.api_key exists --check agent.condenser.llm.api_key exists - control-agent-server state cat base_state.json --conversation "$KF" --max-chars 200 --check agent.llm.api_key exists --check agent.condenser.llm.api_key exists # bug: content.agent.llm.model exists && checks.0.actual eq null && checks.1.actual eq null + control-agent-server state cat base_state.json --conversation "$KF" --max-chars 200 --check agent.llm.api_key exists --check agent.condenser.llm.api_key exists ``` Expected: both files hold the keys (encrypted with the server's cipher; - `state cat` shows ``). Today the source's do and the - fork's have no `api_key` at all (the check reports `null`): - `LocalConversation.fork` builds the fork's - `LocalConversation` without the source's `cipher`, so its state is - serialized with secrets dropped, and the server then loads the fork's - agent from that file (`ConversationService.fork_conversation` starts the - fork's `EventService` with no agent of its own). -- **A fork runs with the source's memory (`F10.fork-run-memory`), known bug.** + `state cat` shows ``). `LocalConversation.fork` builds + the fork with the source's `cipher`, and the server loads the fork's agent + from that file (`ConversationService.fork_conversation` starts the fork's + `EventService` with no agent of its own), so a fork written without the + cipher would lose the keys and fail its first model call. +- **A fork runs with the source's memory (`F10.fork-run-memory`).** Fork the finished DeepSeek conversation `A` and ask the fork what only the source was told. ```sh N_A_MSG=$(control-agent-server api GET "/api/conversations/$A/events/count" --query kind=$MSG --field .) AF=$(control-agent-server api POST "/api/conversations/$A/fork" --json '{"title": "QA F10 memory fork"}' --expect 201 --field id) control-agent-server conversation send "$AF" --text 'What is the project codename I told you? Answer with the codename only.' --wait --until finished,error --timeout 180 - control-agent-server conversation events "$AF" --kinds ConversationErrorEvent --contains LLMAuthenticationError --expect-count 0 --save F10.fork-run-memory/auth-errors # bug: matching ge 1 + control-agent-server conversation events "$AF" --kinds ConversationErrorEvent --contains LLMAuthenticationError --expect-count 0 --save F10.fork-run-memory/auth-errors control-agent-server api GET "/api/conversations/$AF" --quiet --check execution_status eq finished --save F10.fork-run-memory/status control-agent-server api GET "/api/conversations/$AF/agent_final_response" --check response matches '(?i)pelican' --save F10.fork-run-memory/final control-agent-server api GET "/api/conversations/$A/events/count" --query kind=$MSG --check . eq "$N_A_MSG" @@ -287,13 +285,10 @@ SIDE_AGENT="{\"llm\": {\"model\": \"openai/qa-stub\", \"api_key\": \"qa-stub-key to `finished`, its answer names the codename from the copied history (a fact only the source was told, not wording; `agent_final_response` reads a reply given as a message or through `finish`), and `A` gains no message - from the fork's run. Today the fork's run ends in `error` within seconds - with a `ConversationErrorEvent` `LLMAuthenticationError` ("Your LLM API key - appears to be invalid or has expired."), because the fork lost the model - key (`F10.fork-keeps-credentials`); the marked check fails on that event. - Any other failure (a provider outage, a wrong answer) fails a later, - unmarked check and reports `fail`, not `xfail`. Any fork of a conversation - whose model needs a key cannot run. + from the fork's run. A fork that lost the model key + (`F10.fork-keeps-credentials`) instead ends in `error` within seconds with + a `ConversationErrorEvent` `LLMAuthenticationError` ("Your LLM API key + appears to be invalid or has expired."). - **Navigate to an earlier event (`F10.navigate-event`).** Move `S`'s HEAD back to its first message. ```sh @@ -567,9 +562,10 @@ SIDE_AGENT="{\"llm\": {\"model\": \"openai/qa-stub\", \"api_key\": \"qa-stub-key `{"qa": "src"}` shows `{"title": ...}` on GET (also after a restart) while its `meta.json` says `{"qa": "src"}` (`F10.fork-tags-consistent`, a known bug). The fork's `last_user_message_id` starts `null`. -- The fork's `base_state.json` is written without the server's cipher, so - the model keys in the fork's agent are dropped from it - (`F10.fork-keeps-credentials`) and a fork cannot call its model +- The fork's `base_state.json` is written with the source's cipher (the + server's), so the fork's agent keeps its model keys + (`F10.fork-keeps-credentials`) and its conversation secrets; the fork is + resumed from that file, so without them it could not call its model (`F10.fork-run-memory`). - `navigate` with `{}` silently selects the empty tree (the agent loses all context on its next run), because `event_id` defaults to `null`; a request diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index 884e92d7ece..a276f6ec6c8 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -18,7 +18,7 @@ from openhands.sdk.conversation.cancellation import CancellationToken from openhands.sdk.conversation.event_store import EventLog from openhands.sdk.conversation.exceptions import ConversationRunError -from openhands.sdk.conversation.secret_registry import SecretValue +from openhands.sdk.conversation.secret_registry import SecretRegistry, SecretValue from openhands.sdk.conversation.state import ( ConversationExecutionStatus, ConversationState, @@ -873,6 +873,9 @@ def fork( visualizer=type(self._visualizer) if self._visualizer else None, delete_on_close=self.delete_on_close, tags=tags, + # Same cipher as the source, so the fork's base_state.json keeps + # secrets encrypted rather than redacted (#5465). + cipher=self._cipher, _parent_llm_call_context=self._llm_call_context, ) @@ -910,6 +913,19 @@ def fork( self._state.activated_path_rules ) fork_conv._state.agent_state = copy.deepcopy(self._state.agent_state) + # Conversation secrets (``secrets=`` / update_secrets) live in the + # registry, not the agent. Assigning the field (rather than + # mutating the registry) autosaves them, encrypted with the cipher. + source_secrets = self._state.secret_registry.secret_sources + fork_conv._state.secret_registry = SecretRegistry( + secret_sources={ + **fork_conv._state.secret_registry.secret_sources, + **{ + name: source.model_copy(deep=True) + for name, source in source_secrets.items() + }, + } + ) # Copy title via tags if provided if title is not None: diff --git a/tests/sdk/conversation/local/test_fork.py b/tests/sdk/conversation/local/test_fork.py index 51f891f8681..62d07d37b64 100644 --- a/tests/sdk/conversation/local/test_fork.py +++ b/tests/sdk/conversation/local/test_fork.py @@ -1,5 +1,6 @@ """Tests for Conversation.fork() primitive.""" +import json import tempfile import threading import uuid @@ -12,10 +13,14 @@ from openhands.sdk.agent import Agent from openhands.sdk.conversation import Conversation, LocalConversation -from openhands.sdk.conversation.state import ConversationExecutionStatus +from openhands.sdk.conversation.state import ( + ConversationExecutionStatus, + ConversationState, +) from openhands.sdk.event.llm_convertible import MessageEvent, SystemPromptEvent from openhands.sdk.llm import LLM, Message, TextContent from openhands.sdk.tool import Action, Observation, ToolDefinition, ToolExecutor +from openhands.sdk.utils.cipher import Cipher def _agent() -> Agent: @@ -347,3 +352,55 @@ def test_fork_with_aliased_agent_does_not_clobber_source_cache_key(): ) assert fork.get_llm_call_context().prompt_cache_key == str(fork.id) assert fork.agent.llm is not src.agent.llm + + +def _persisted_base_state(conv: LocalConversation) -> dict: + persistence_dir = conv.state.persistence_dir + assert persistence_dir is not None + return json.loads((Path(persistence_dir) / "base_state.json").read_text()) + + +def test_fork_keeps_source_cipher_for_persisted_secrets(tmp_path): + """A fork of a cipher-backed conversation stores its secrets encrypted (#5465). + + The agent-server resumes a fork from its ``base_state.json``, so a key + persisted redacted there makes the fork's first LLM call fail. + """ + cipher = Cipher("test-secret-key") + src = LocalConversation( + agent=_agent(), + workspace=str(tmp_path / "workspace"), + persistence_dir=str(tmp_path / "conversations"), + cipher=cipher, + secrets={"GITHUB_TOKEN": "ghp-test"}, + ) + fork = src.fork() + + state = _persisted_base_state(fork) + api_key = cipher.decrypt(state["agent"]["llm"]["api_key"]) + assert api_key is not None + assert api_key.get_secret_value() == "test-key" + + # Conversation secrets survive the fork too, under the same cipher. + sources = state["secret_registry"]["secret_sources"] + token = cipher.decrypt(sources["GITHUB_TOKEN"]["value"]) + assert token is not None + assert token.get_secret_value() == "ghp-test" + + # Resuming the fork from disk (the agent-server path) restores the key. + resumed = ConversationState.model_validate(state, context={"cipher": cipher}) + resumed_key = resumed.agent.llm.api_key + assert isinstance(resumed_key, SecretStr) + assert resumed_key.get_secret_value() == "test-key" + + +def test_fork_without_cipher_still_redacts_secrets(tmp_path): + """Forks of cipher-less conversations keep redacting persisted secrets.""" + src = LocalConversation( + agent=_agent(), + workspace=str(tmp_path / "workspace"), + persistence_dir=str(tmp_path / "conversations"), + ) + fork = src.fork() + + assert set(_persisted_base_state(fork)["agent"]["llm"]["api_key"]) == {"*"} From 0fb50d610cad1e3dbd9e103c101e9043d3f87eb9 Mon Sep 17 00:00:00 2001 From: Xiaoping Liao <106010272+kyletser@users.noreply.github.com> Date: Sat, 3 Oct 2026 16:09:07 +0800 Subject: [PATCH 02/13] test(agent-server): preserve fork credentials across restart Adapt the server restart regression test from #5473, source commit 583fb5e2089d2d486363212e4498ca697d2f4f86. Keep the existing registry merge and deep-copy implementation in #5765. Co-authored-by: openhands --- .../agent_server/test_conversation_service.py | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/tests/agent_server/test_conversation_service.py b/tests/agent_server/test_conversation_service.py index 45b82a694ae..4529c409286 100644 --- a/tests/agent_server/test_conversation_service.py +++ b/tests/agent_server/test_conversation_service.py @@ -3951,6 +3951,50 @@ async def test_fork_unknown_event_raises_without_leaking_dir(self, tmp_path): # Validation must fail-fast before any fork dir is written to disk. assert {p.name for p in conversations_dir.iterdir()} == before + @pytest.mark.asyncio + async def test_cipher_backed_fork_resumes_with_credentials(self, tmp_path): + """A cipher-backed fork survives a restart with its secrets (#5465).""" + conversations_dir = tmp_path / "conversations" + cipher = Cipher("fork-resume-test-key") + request = StartConversationRequest( + agent=Agent( + llm=LLM( + model="gpt-4o", + api_key=SecretStr("sk-fork-test"), + usage_id="test-llm", + ), + tools=[], + ), + workspace=LocalWorkspace(working_dir=tmp_path / "workspace"), + ) + + async with ConversationService( + conversations_dir=conversations_dir, cipher=cipher + ) as svc: + info, _ = await svc.start_conversation(request) + source_service = await svc.get_event_service(info.id) + assert source_service is not None + source_service.get_conversation().update_secrets({"MY_TOKEN": "tok-123"}) + + fork_info = await svc.fork_conversation(info.id) + assert fork_info is not None + + async with ConversationService( + conversations_dir=conversations_dir, cipher=cipher + ) as restarted: + # Resume path: the restarted server loads the fork from its + # persisted base_state.json with agent=None. + fork_service = await restarted.get_event_service(fork_info.id) + assert fork_service is not None + fork_conversation = fork_service.get_conversation() + api_key = fork_conversation.agent.llm.api_key + assert isinstance(api_key, SecretStr) + assert api_key.get_secret_value() == "sk-fork-test" + assert ( + fork_conversation.state.secret_registry.get_secret_value("MY_TOKEN") + == "tok-123" + ) + @pytest.mark.asyncio @pytest.mark.parametrize( "navigate_to_none", [False, True], ids=["to_event", "to_empty_tree"] From a50176d698799ae3832973a324d73b78a01c2768 Mon Sep 17 00:00:00 2001 From: BSmick6 Date: Fri, 4 Sep 2026 20:31:05 +0000 Subject: [PATCH 03/13] fix(sdk): copy confirmation_policy and security_analyzer in LocalConversation.fork() These fields are part of ConversationState but fork() did not copy them, so the fork's base_state.json was written with the NeverConfirm / None defaults and the source conversation's policy was silently lost: a fork of a conversation under AlwaysConfirm ran its actions unasked. Split out of #4813 (commit 61b865e). Co-Authored-By: Claude Sonnet 4.6 (1M context) Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- .../openhands/sdk/conversation/impl/local_conversation.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index 21712944870..d13fd3d2961 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -984,6 +984,8 @@ def fork( self._state.activated_path_rules ) fork_conv._state.agent_state = copy.deepcopy(self._state.agent_state) + fork_conv._state.confirmation_policy = self._state.confirmation_policy + fork_conv._state.security_analyzer = self._state.security_analyzer # Conversation secrets (``secrets=`` / update_secrets) live in the # registry, not the agent. Assigning the field (rather than # mutating the registry) autosaves them, encrypted with the cipher. From 17412085cfe3d35aebe9084a8fdc436ddcf64934 Mon Sep 17 00:00:00 2001 From: Engel Nyst Date: Fri, 9 Oct 2026 03:33:34 +0000 Subject: [PATCH 04/13] fix(conversation): a fork gets its own security analyzer, credentials kept The fork shared the source's analyzer object, so a stateful analyzer's history (e.g. ToolShieldLLMSecurityAnalyzer) mixed two conversations. Give the fork its own instance through a JSON round-trip with expose_secrets, so the fork's cipher re-encrypts nested credentials (the guardrail LLM api_key) instead of writing them redacted. Tests: the fork owns its analyzer, a ciphered analyzer key survives a resume of the fork, and secrets passed at start reach the fork (the registry copy itself comes from #5765). Split out of #4813 (commit f6ade80). Co-Authored-By: Claude Opus 5.5 Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- .../conversation/impl/local_conversation.py | 15 +++- tests/sdk/conversation/local/test_fork.py | 84 +++++++++++++++++++ 2 files changed, 98 insertions(+), 1 deletion(-) diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index d13fd3d2961..cf0f57800a6 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -985,7 +985,20 @@ def fork( ) fork_conv._state.agent_state = copy.deepcopy(self._state.agent_state) fork_conv._state.confirmation_policy = self._state.confirmation_policy - fork_conv._state.security_analyzer = self._state.security_analyzer + # The fork gets its own analyzer: analyzers keep mutable runtime + # state in PrivateAttrs (e.g. ToolShieldLLMSecurityAnalyzer's action + # history) that a shared reference would mix between the two + # conversations. Round-trip via JSON like the agent above rather + # than model_copy(deep=True): a guardrail LLM may hold a lock that + # cannot be deep-copied, and expose_secrets keeps its credentials + # for the fork's cipher to re-encrypt. + source_analyzer = self._state.security_analyzer + if source_analyzer is not None: + fork_conv._state.security_analyzer = type( + source_analyzer + ).model_validate( + source_analyzer.model_dump(context={"expose_secrets": True}), + ) # Conversation secrets (``secrets=`` / update_secrets) live in the # registry, not the agent. Assigning the field (rather than # mutating the registry) autosaves them, encrypted with the cipher. diff --git a/tests/sdk/conversation/local/test_fork.py b/tests/sdk/conversation/local/test_fork.py index ac233de692a..5115c153011 100644 --- a/tests/sdk/conversation/local/test_fork.py +++ b/tests/sdk/conversation/local/test_fork.py @@ -19,6 +19,10 @@ ) from openhands.sdk.event.llm_convertible import MessageEvent, SystemPromptEvent from openhands.sdk.llm import LLM, Message, TextContent +from openhands.sdk.security.llm_analyzer import LLMSecurityAnalyzer +from openhands.sdk.security.toolshield_llm_analyzer import ( + ToolShieldLLMSecurityAnalyzer, +) from openhands.sdk.tool import Action, Observation, ToolDefinition, ToolExecutor from openhands.sdk.utils.cipher import Cipher @@ -422,6 +426,86 @@ def test_fork_without_cipher_still_redacts_secrets(tmp_path): assert set(_persisted_base_state(fork)["agent"]["llm"]["api_key"]) == {"*"} +def test_fork_copies_secret_registry(): + """Registry-direct secrets must survive a fork. + + base_state.json is the fork's only source of truth for secrets, so fork() + must copy the source's secret_registry into the fork's state; otherwise a + token injected via ``Conversation(secrets=...)`` is empty on the fork. + """ + with tempfile.TemporaryDirectory() as tmpdir: + src = Conversation( + agent=_agent(), + persistence_dir=tmpdir, + workspace=tmpdir, + secrets={"MY_TOKEN": "s3kr3t-value"}, + ) + + fork = src.fork() + + assert fork.state.secret_registry.get_secret_value("MY_TOKEN") == ( + "s3kr3t-value" + ) + + +def test_fork_gives_independent_security_analyzer(): + """The fork must own its analyzer instance, not alias the source's. + + A shared analyzer would let a stateful analyzer's runtime state (e.g. + ToolShieldLLMSecurityAnalyzer._action_history) leak between conversations. + """ + with tempfile.TemporaryDirectory() as tmpdir: + src = Conversation(agent=_agent(), persistence_dir=tmpdir, workspace=tmpdir) + src.set_security_analyzer(LLMSecurityAnalyzer()) + + fork = src.fork() + + assert fork.state.security_analyzer is not None + assert fork.state.security_analyzer is not src.state.security_analyzer + + +def test_fork_preserves_ciphered_security_analyzer_credentials(): + """A fork persisted with the parent's cipher must keep the analyzer's + nested guardrail-LLM api_key instead of redacting it to base_state.json. + """ + with tempfile.TemporaryDirectory() as tmpdir: + cipher = Cipher("stable-conversation-key") + src = LocalConversation( + agent=_agent(), + persistence_dir=tmpdir, + workspace=tmpdir, + cipher=cipher, + ) + src.set_security_analyzer( + ToolShieldLLMSecurityAnalyzer( + llm=LLM( + model="gpt-4o-mini", + api_key=SecretStr("sk-GUARD-xyz"), + usage_id="guard", + ) + ) + ) + + fork = src.fork() + + # Resume the fork from its base_state.json with the cipher, the same way + # the agent-server fork path reloads it. + assert fork.state.persistence_dir is not None + base = str(Path(fork.state.persistence_dir).parent) + resumed = LocalConversation( + agent=_agent(), + workspace=tmpdir, + persistence_dir=base, + conversation_id=fork.id, + cipher=cipher, + ) + + resumed_analyzer = resumed.state.security_analyzer + assert isinstance(resumed_analyzer, ToolShieldLLMSecurityAnalyzer) + assert isinstance(resumed_analyzer.llm.api_key, SecretStr) + assert resumed_analyzer.llm.api_key.get_secret_value() == "sk-GUARD-xyz" + + def test_fork_preserves_max_budget_per_run(): with tempfile.TemporaryDirectory() as tmpdir: src = Conversation( From 8bc2352acc454b34aed6108cbd4f01a45c51f268 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 18:12:51 +0000 Subject: [PATCH 05/13] test(sdk): a fork keeps the source's confirmation policy The policy copy had no test. This one checks the fork's live state and its base_state.json, which is what the agent-server resumes a fork from. It fails on main, where the fork starts with NeverConfirm. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- tests/sdk/conversation/local/test_fork.py | 26 +++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/tests/sdk/conversation/local/test_fork.py b/tests/sdk/conversation/local/test_fork.py index 5115c153011..d653753ccc1 100644 --- a/tests/sdk/conversation/local/test_fork.py +++ b/tests/sdk/conversation/local/test_fork.py @@ -19,7 +19,9 @@ ) from openhands.sdk.event.llm_convertible import MessageEvent, SystemPromptEvent from openhands.sdk.llm import LLM, Message, TextContent +from openhands.sdk.security.confirmation_policy import ConfirmRisky from openhands.sdk.security.llm_analyzer import LLMSecurityAnalyzer +from openhands.sdk.security.risk import SecurityRisk from openhands.sdk.security.toolshield_llm_analyzer import ( ToolShieldLLMSecurityAnalyzer, ) @@ -426,6 +428,30 @@ def test_fork_without_cipher_still_redacts_secrets(tmp_path): assert set(_persisted_base_state(fork)["agent"]["llm"]["api_key"]) == {"*"} +def test_fork_keeps_confirmation_policy(tmp_path): + """A fork asks for confirmation under the same policy as its source. + + The fork's base_state.json must carry it too: the agent-server resumes a + fork from that file. + """ + policy = ConfirmRisky(threshold=SecurityRisk.MEDIUM, confirm_unknown=False) + src = LocalConversation( + agent=_agent(), + workspace=str(tmp_path / "workspace"), + persistence_dir=str(tmp_path / "conversations"), + ) + src.set_confirmation_policy(policy) + + fork = src.fork() + + assert fork.state.confirmation_policy == policy + assert _persisted_base_state(fork)["confirmation_policy"] == { + "kind": "ConfirmRisky", + "threshold": "MEDIUM", + "confirm_unknown": False, + } + + def test_fork_copies_secret_registry(): """Registry-direct secrets must survive a fork. From 214ccba92d34eab708b56de6de05377a6e1c7065 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 18:36:11 +0000 Subject: [PATCH 06/13] verify-sdk: S04 shows what a fork keeps of the source's state New sub-feature S04.fork-keeps-state with a program that forks a ciphered conversation carrying ConfirmRisky(MEDIUM), a ToolShield analyzer with its own key and a runtime secret, then changes the fork and loads it again from disk. The recipe checks the fork's memory, its base_state.json and the reload. On main fifteen of its checks fail: the fork starts with NeverConfirm, no analyzer and no secrets, and its saved key is the placeholder. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- .../verify-sdk/programs/S04/fork_state.py | 113 ++++++++++++++++++ .../references/feature-map/README.md | 4 +- .../feature-map/S04-local-conversation.md | 16 +++ 3 files changed, 131 insertions(+), 2 deletions(-) create mode 100644 .agents/skills/verify-sdk/programs/S04/fork_state.py diff --git a/.agents/skills/verify-sdk/programs/S04/fork_state.py b/.agents/skills/verify-sdk/programs/S04/fork_state.py new file mode 100644 index 00000000000..13acea9e5c8 --- /dev/null +++ b/.agents/skills/verify-sdk/programs/S04/fork_state.py @@ -0,0 +1,113 @@ +"""Fork a conversation that carries a confirmation policy, a security analyzer +with its own model key, and secrets, all set after construction, and report +what the fork has: in memory, in its `base_state.json`, and after it is loaded +again from disk. No model is called. + +Usage: fork_state.py +""" + +import json +from pathlib import Path + +from pydantic import SecretStr +from sdk_verify import emit, make_llm, run_paths + +from openhands.sdk import LLM, Agent, LocalConversation +from openhands.sdk.security.confirmation_policy import ConfirmRisky, NeverConfirm +from openhands.sdk.security.risk import SecurityRisk +from openhands.sdk.security.toolshield_llm_analyzer import ( + ToolShieldLLMSecurityAnalyzer, +) +from openhands.sdk.utils.cipher import Cipher + + +paths = run_paths() +BASE = paths["run"] / "fork-state" +WORKSPACE = str(paths["workspace"]) +VALUES = ("start-secret-value-1", "guard-key-value-2", "runtime-secret-value-3") +cipher = Cipher("sdk-verify-fork-state-key") + + +def agent() -> Agent: + return Agent(llm=make_llm([{"finish": "unused"}]), tools=[]) + + +def secret_values(conversation) -> dict[str, str | None]: + registry = conversation.state.secret_registry + return {name: registry.get_secret_value(name) for name in registry.secret_sources} + + +def guard_key(conversation) -> str | None: + analyzer = conversation.state.security_analyzer + if not isinstance(analyzer, ToolShieldLLMSecurityAnalyzer): + return None + key = analyzer.llm.api_key + return key.get_secret_value() if isinstance(key, SecretStr) else None + + +source = LocalConversation( + agent=agent(), + workspace=WORKSPACE, + persistence_dir=str(BASE), + cipher=cipher, + secrets={"START_TOKEN": VALUES[0]}, + visualizer=None, +) +source.set_confirmation_policy( + ConfirmRisky(threshold=SecurityRisk.MEDIUM, confirm_unknown=False) +) +source.set_security_analyzer( + ToolShieldLLMSecurityAnalyzer( + llm=LLM(model="openai/guard", api_key=SecretStr(VALUES[1]), usage_id="guard") + ) +) +source.update_secrets({"RUNTIME_TOKEN": VALUES[2]}) + +fork = source.fork() +fork_dir = Path(fork.state.persistence_dir or "") +saved = json.loads((fork_dir / "base_state.json").read_text()) +saved_text = "".join(p.read_text() for p in fork_dir.rglob("*.json")) +out: dict = { + "ok": True, + "fork_policy": fork.state.confirmation_policy.model_dump(mode="json"), + "fork_analyzer": type(fork.state.security_analyzer).__name__, + "fork_analyzer_is_own_object": fork.state.security_analyzer + is not source.state.security_analyzer, + "fork_guard_key_kept": guard_key(fork) == VALUES[1], + "fork_secrets": secret_values(fork), + "saved_policy": saved.get("confirmation_policy"), + "saved_analyzer": (saved.get("security_analyzer") or {}).get("kind"), + "saved_secret_names": sorted(saved["secret_registry"]["secret_sources"]), + "saved_guard_key_is_placeholder": set( + ((saved.get("security_analyzer") or {}).get("llm") or {}).get("api_key") or "*" + ) + == {"*"}, + "plaintext_on_disk": any(value in saved_text for value in VALUES), +} + +# Changing the fork does not reach back into the source. +fork.set_confirmation_policy(NeverConfirm()) +fork.update_secrets({"FORK_ONLY": "fork-only-value-4"}) +out["source_policy_after_fork_change"] = type(source.state.confirmation_policy).__name__ +out["source_has_fork_only_secret"] = ( + "FORK_ONLY" in source.state.secret_registry.secret_sources +) + +fork_id = fork.id +fork.close() +source.close() +reloaded = LocalConversation( + agent=agent(), + workspace=WORKSPACE, + persistence_dir=str(BASE), + conversation_id=fork_id, + cipher=cipher, + visualizer=None, +) +out |= { + "reloaded_policy": type(reloaded.state.confirmation_policy).__name__, + "reloaded_guard_key_kept": guard_key(reloaded) == VALUES[1], + "reloaded_secrets": secret_values(reloaded), +} +reloaded.close() +emit(out) diff --git a/.agents/skills/verify-sdk/references/feature-map/README.md b/.agents/skills/verify-sdk/references/feature-map/README.md index 3f2f315b2b9..c98be39505b 100644 --- a/.agents/skills/verify-sdk/references/feature-map/README.md +++ b/.agents/skills/verify-sdk/references/feature-map/README.md @@ -12,7 +12,7 @@ that map's `Fnn`. Maintenance baseline: main@4db1ad742ad143ddc3411631f04efb70323f40f9 (2026-11-09). The first mapping; the next maintenance pass starts from this commit, a pass proposes the next baseline in its PR, and merging that PR accepts it. -The map has **458 sub-features**, **29 of them untested** (no unit or cross +The map has **459 sub-features**, **29 of them untested** (no unit or cross test exercises the behavior; most of those have an example script). ## What each sub-feature links @@ -74,7 +74,7 @@ an interactive login are labeled **blocked**. | S01 | [Agent step loop](S01-agent-loop.md) | step handling (tool calls, text, empty replies), iteration and budget limits, stuck detector, parallel tools, messages sent mid-run, image input, `ask_agent`, structured output, recovery from bad tool calls and context overflow | `Conversation(max_iteration_per_run=, stuck_detection=, max_budget_per_run=)`, `Agent(tool_concurrency_limit=)`, `ask_agent()`, `response_schema` | llm, tmux, network | 24 | 1 | | S02 | [LLM core](S02-llm-core.md) | completion, responses and `generate`; streaming; reasoning and thinking blocks; native and prompted tool calling; metrics, stats and pricing; retries and error mapping; caching, token counts, image inlining, completion logs | `LLM(...)`, `llm.completion`/`responses`, `Conversation(token_callbacks=)`, `llm.metrics` | llm, network | 25 | 0 | | S03 | [LLM registry, routing, fallback, profiles and model switching](S03-llm-routing-profiles.md) | `LLMRegistry`, multimodal and random routers, `FallbackStrategy`, `LLMProfileStore`, `switch_profile`/`switch_llm`, the switch-LLM tool, `route_task_to_model`, subscription login | `LLMRegistry`, `MultimodalRouter`, `FallbackStrategy`, `LLMProfileStore`, `LLM.subscription_login()` | llm, network | 24 | 3 | -| S04 | [Local conversation lifecycle](S04-local-conversation.md) | factory and ids, persistence and resume, callbacks, close, pause, `arun` and interrupt, secrets, visualizers, fork and branches, goal loop, final response, stats, title and tags | `Conversation(persistence_dir=, callbacks=, visualizer=, secrets=)`, `run`/`pause`/`arun`/`interrupt`/`fork`/`run_goal` | llm, tmux, network, uvx | 25 | 0 | +| S04 | [Local conversation lifecycle](S04-local-conversation.md) | factory and ids, persistence and resume, callbacks, close, pause, `arun` and interrupt, secrets, visualizers, fork and branches, goal loop, final response, stats, title and tags | `Conversation(persistence_dir=, callbacks=, visualizer=, secrets=)`, `run`/`pause`/`arun`/`interrupt`/`fork`/`run_goal` | llm, tmux, network, uvx | 26 | 0 | | S05 | [Events and the event log](S05-events.md) | event model, JSON round trip, conversion to LLM messages and OpenAI formats, unmatched actions, the `EventLog`, error classification, completion and token events | `Event.model_validate_json`, `events_to_messages`, `conversation.state.events` | llm, tmux | 18 | 1 | | S06 | [Agent context, system prompt, condensers and memory](S06-context-condensers.md) | `AgentContext`, system prompt sections and vendor files, persona, persistent memory, the condenser `View`, `LLMSummarizingCondenser`, `condense()`, overflow condensation, no-op and pipeline condensers | `Agent(agent_context=, system_prompt=, condenser=)`, `AgentContext(load_memory=)`, `conversation.condense()` | llm, tmux | 23 | 1 | | S07 | [Skills](S07-skills.md) | skill sources (programmatic, Markdown, AGENTS.md, SKILL.md, user, project, public, installed), keyword, task and path triggers, ``, `invoke_skill`, inline commands, disabling, install and marketplace | `AgentContext(skills=, load_*_skills=, disabled_skills=)`, `.agents/skills/`, `install_skill` | llm, git, network | 24 | 0 | diff --git a/.agents/skills/verify-sdk/references/feature-map/S04-local-conversation.md b/.agents/skills/verify-sdk/references/feature-map/S04-local-conversation.md index caa0d421da9..0bc17c12810 100644 --- a/.agents/skills/verify-sdk/references/feature-map/S04-local-conversation.md +++ b/.agents/skills/verify-sdk/references/feature-map/S04-local-conversation.md @@ -30,6 +30,7 @@ Examples: `examples/01_standalone_sdk/06_interactive_terminal_w_reasoning.py`, ` - `S04.visualizer-custom`: a `ConversationVisualizerBase` subclass passed as `visualizer=` receives every event through `on_event`; each event type has its own `visualize` rendering. Unit: `tests/sdk/conversation/test_visualizer.py`. Example: `examples/01_standalone_sdk/26_custom_visualizer.py`. Real-LLM: none. - `S04.fork`: `fork()` deep-copies the conversation under a new id (or `conversation_id=`), starts IDLE, leaves the source untouched, resets metrics unless `reset_metrics=False`, accepts `agent=` and `tags=` (`title=` is deprecated and ignored locally since #4814; only `RemoteConversation` stores it), shares the workspace, and persists so the fork survives a reload. Unit: `tests/sdk/conversation/local/test_fork.py`. Example: `examples/01_standalone_sdk/48_conversation_fork.py`. Real-LLM: none. - `S04.fork-branch`: events carry parent ids forming a tree; `fork(from_event_id=...)` copies only that branch, and `navigate_to(event_id)` moves HEAD so the next event starts a sibling branch (`None` empties the active branch). Unit: `tests/sdk/conversation/local/test_conversation_tree.py`. Example: `examples/01_standalone_sdk/48_conversation_fork.py`. Real-LLM: none. +- `S04.fork-keeps-state`: a fork carries the source's confirmation policy, its own copy of the security analyzer (credentials kept) and the conversation secrets, and is written with the source's cipher, so its `base_state.json` alone restores them. Unit: `tests/sdk/conversation/local/test_fork.py`. Example: none. Real-LLM: none. - `S04.goal-loop`: `run_goal(conversation, objective, judge_llm, max_iterations=N)` sends the objective, runs, asks the judge LLM for a verdict, re-prompts with the missing items, and returns a `GoalOutcome` with status `"complete"` or `"capped"`, the iteration count and the verdict. Unit: `tests/sdk/conversation/goal/`. Example: `examples/01_standalone_sdk/54_goal_completion_loop.py`. Real-LLM: none. - `S04.interactive-terminal`: with `Tool(name=TerminalTool.name, params={"no_change_timeout_seconds": 3})` the agent can start `python3`, feed it input and exit; an `LLMConvertibleEvent` callback collects the raw LLM messages. Unit: `tests/tools/terminal/test_terminal_session.py::test_python_interactive_input`, `::test_interactive_command`. Example: `examples/01_standalone_sdk/06_interactive_terminal_w_reasoning.py`. Real-LLM: `tests/integration/tests/t07_interactive_commands.py`. - `S04.final-response`: `get_agent_final_response(conversation.state.events)` returns the text of whichever came last of the agent's `finish` call and its plain-text `MessageEvent`, else `""`. Unit: `tests/sdk/conversation/test_agent_final_response.py`. Example: none. Real-LLM: `tests/integration/tests/t08_image_file_viewing.py`. @@ -224,6 +225,21 @@ Scripted bullets use the SDK's `TestLLM` (`--script`, or `make_llm(script=...)` --check old_branch_in_active eq false --check active_ends_with eq "answer on a new branch" \ --check unknown_event_error contains "Unknown event_id" --check active_after_none eq 0 --check log_after_none eq 7 ``` +- **What a fork keeps (`S04.fork-keeps-state`).** A ciphered conversation gets `ConfirmRisky(MEDIUM)`, a `ToolShieldLLMSecurityAnalyzer` with its own model key and a runtime secret after construction, then is forked; the fork is changed and loaded again from disk. + ```sh + export SDK_VERIFY_RUN=$(control-sdk new --field run) + control-sdk program S04/fork_state \ + --check fork_policy.kind eq ConfirmRisky --check fork_policy.threshold eq MEDIUM --check fork_policy.confirm_unknown eq false \ + --check fork_analyzer eq ToolShieldLLMSecurityAnalyzer --check fork_analyzer_is_own_object eq true --check fork_guard_key_kept eq true \ + --check fork_secrets.START_TOKEN eq start-secret-value-1 --check fork_secrets.RUNTIME_TOKEN eq runtime-secret-value-3 \ + --check saved_policy.kind eq ConfirmRisky --check saved_analyzer eq ToolShieldLLMSecurityAnalyzer \ + --check saved_secret_names.0 eq RUNTIME_TOKEN --check saved_secret_names.1 eq START_TOKEN \ + --check saved_guard_key_is_placeholder eq false --check plaintext_on_disk eq false \ + --check source_policy_after_fork_change eq ConfirmRisky --check source_has_fork_only_secret eq false \ + --check reloaded_policy eq NeverConfirm --check reloaded_guard_key_kept eq true \ + --check reloaded_secrets.START_TOKEN eq start-secret-value-1 --check reloaded_secrets.FORK_ONLY eq fork-only-value-4 + ``` + The fork has the policy with its threshold, an analyzer object of its own whose key still works, and both secrets; its `base_state.json` holds them encrypted (neither the plaintext nor the `**********` placeholder). Setting `NeverConfirm` and a new secret on the fork leaves the source as it was, and the fork loaded again from disk has the fork's values. - **The goal loop (`S04.goal-loop`).** `run_goal` with a scripted judge: incomplete then complete (the follow-up names what was missing), and a capped run whose last verdict cannot be parsed. ```sh export SDK_VERIFY_RUN=$(control-sdk new --field run) From e64a60d488152bb19cc1c3145a75fe30a6d7fef2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 19:06:44 +0000 Subject: [PATCH 07/13] fix(sdk): fork copies its values the same way, before the fork exists Review of the fork changes found three small things: - Secret sources were deep-copied. A custom source that holds a lock or a client made fork() raise ("cannot pickle '_thread.lock' object"), after the fork's directory had already been written. They are now copied like the agent and the analyzer, through a dump/validate round trip (`_own_copy`), and the analyzer and the secrets are copied before the fork is constructed, so a copy that fails leaves nothing behind. - `invoked_skills` was not copied, next to two skill lists that are. - The analyzer test passed with a shallow copy. It now uses a ToolShield analyzer and checks that the guardrail LLM is the fork's own object too. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- .../conversation/impl/local_conversation.py | 58 ++++++++-------- tests/sdk/conversation/local/test_fork.py | 66 ++++++++++++++++--- 2 files changed, 88 insertions(+), 36 deletions(-) diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index cf0f57800a6..60d588dec37 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -9,6 +9,8 @@ from pathlib import Path, PurePath from typing import Any, Final, TypeGuard, cast +from pydantic import BaseModel + from openhands.sdk.agent.acp_agent import ACPAgent from openhands.sdk.agent.base import AgentBase from openhands.sdk.agent.stream_context import StreamProgressCallbackType @@ -199,6 +201,18 @@ def _same_llm_config(a: LLM, b: LLM) -> bool: ) +def _own_copy[ModelT: BaseModel](model: ModelT) -> ModelT: + """A copy that shares nothing with ``model`` and keeps its credentials. + + A dump/validate round trip rather than ``model_copy(deep=True)``: a deep + copy carries private runtime state along (an analyzer's history) and fails + on members that cannot be copied (a lock, an open client). + """ + return type(model).model_validate( + model.model_dump(context={"expose_secrets": True}) + ) + + class LocalConversation(BaseConversation): agent: AgentBase workspace: LocalWorkspace @@ -873,6 +887,8 @@ def fork( Events are copied so the source remains immutable. The fork starts in ``execution_status='idle'``; calling ``run()`` resumes from the copied state — meaning the agent has full event memory of the source. + It also keeps the source's confirmation policy, its own copy of the + security analyzer and of the secrets, and the source's cipher. Args: conversation_id: ID for the forked conversation (auto-generated @@ -899,17 +915,12 @@ def fork( """ del title # no local title storage; see docstring fork_id = conversation_id or uuid.uuid4() - # Always deep-copy the agent (supplied or source) so the fork owns + # Always copy the agent (supplied or source) so the fork owns # its own object graph. Required because __init__ binds # per-conversation call context on the LLM (#2917, #3443): a # shared/aliased agent would clobber the source conversation's - # context. Round-trip via JSON avoids thread-lock pickling issues - # with model_copy(deep=True). - source_agent = agent if agent is not None else self.agent - agent_cls = type(source_agent) - fork_agent = agent_cls.model_validate( - source_agent.model_dump(context={"expose_secrets": True}), - ) + # context. + fork_agent = _own_copy(agent if agent is not None else self.agent) # Hold the state lock while reading mutable state from the source # conversation to avoid torn reads if run() is executing concurrently. @@ -918,6 +929,15 @@ def fork( # does not leave an orphaned persistence directory behind. if from_event_id is not None and from_event_id not in self._state.events: raise ValueError(f"Unknown from_event_id: {from_event_id}") + # Copied before the fork exists too, for the same reason. + source_analyzer = self._state.security_analyzer + fork_analyzer = ( + _own_copy(source_analyzer) if source_analyzer is not None else None + ) + fork_secrets = { + name: _own_copy(source) + for name, source in self._state.secret_registry.secret_sources.items() + } # Determine persistence_dir for the fork. # Pass the *base* directory only — __init__ calls @@ -984,32 +1004,16 @@ def fork( self._state.activated_path_rules ) fork_conv._state.agent_state = copy.deepcopy(self._state.agent_state) + fork_conv._state.invoked_skills = list(self._state.invoked_skills) fork_conv._state.confirmation_policy = self._state.confirmation_policy - # The fork gets its own analyzer: analyzers keep mutable runtime - # state in PrivateAttrs (e.g. ToolShieldLLMSecurityAnalyzer's action - # history) that a shared reference would mix between the two - # conversations. Round-trip via JSON like the agent above rather - # than model_copy(deep=True): a guardrail LLM may hold a lock that - # cannot be deep-copied, and expose_secrets keeps its credentials - # for the fork's cipher to re-encrypt. - source_analyzer = self._state.security_analyzer - if source_analyzer is not None: - fork_conv._state.security_analyzer = type( - source_analyzer - ).model_validate( - source_analyzer.model_dump(context={"expose_secrets": True}), - ) + fork_conv._state.security_analyzer = fork_analyzer # Conversation secrets (``secrets=`` / update_secrets) live in the # registry, not the agent. Assigning the field (rather than # mutating the registry) autosaves them, encrypted with the cipher. - source_secrets = self._state.secret_registry.secret_sources fork_conv._state.secret_registry = SecretRegistry( secret_sources={ **fork_conv._state.secret_registry.secret_sources, - **{ - name: source.model_copy(deep=True) - for name, source in source_secrets.items() - }, + **fork_secrets, } ) diff --git a/tests/sdk/conversation/local/test_fork.py b/tests/sdk/conversation/local/test_fork.py index d653753ccc1..97d6948e5f4 100644 --- a/tests/sdk/conversation/local/test_fork.py +++ b/tests/sdk/conversation/local/test_fork.py @@ -9,7 +9,7 @@ from typing import Self import pytest -from pydantic import SecretStr +from pydantic import PrivateAttr, SecretStr from openhands.sdk.agent import Agent from openhands.sdk.conversation import Conversation, LocalConversation @@ -19,8 +19,8 @@ ) from openhands.sdk.event.llm_convertible import MessageEvent, SystemPromptEvent from openhands.sdk.llm import LLM, Message, TextContent +from openhands.sdk.secret import SecretSource from openhands.sdk.security.confirmation_policy import ConfirmRisky -from openhands.sdk.security.llm_analyzer import LLMSecurityAnalyzer from openhands.sdk.security.risk import SecurityRisk from openhands.sdk.security.toolshield_llm_analyzer import ( ToolShieldLLMSecurityAnalyzer, @@ -44,6 +44,16 @@ def _msg(event_id: str, text: str = "hi") -> MessageEvent: ) +class _LockedSecretSource(SecretSource): + """A secret source that holds something a deep copy cannot copy.""" + + _lock: threading.Lock = PrivateAttr(default_factory=threading.Lock) + + def get_value(self) -> str: + with self._lock: + return "locked-source-value" + + class ForkCopyMockAction(Action): command: str = "test" @@ -475,19 +485,57 @@ def test_fork_copies_secret_registry(): def test_fork_gives_independent_security_analyzer(): - """The fork must own its analyzer instance, not alias the source's. + """The fork's analyzer is a copy of its own, down to the guardrail LLM: a + shared analyzer, or a shallow copy of one, would mix the two conversations + in a stateful analyzer such as ToolShieldLLMSecurityAnalyzer.""" + with tempfile.TemporaryDirectory() as tmpdir: + src = Conversation(agent=_agent(), persistence_dir=tmpdir, workspace=tmpdir) + src.set_security_analyzer( + ToolShieldLLMSecurityAnalyzer( + llm=LLM(model="gpt-4o-mini", usage_id="guard"), history_window=7 + ) + ) - A shared analyzer would let a stateful analyzer's runtime state (e.g. - ToolShieldLLMSecurityAnalyzer._action_history) leak between conversations. - """ + fork = src.fork() + + source_analyzer = src.state.security_analyzer + fork_analyzer = fork.state.security_analyzer + assert isinstance(source_analyzer, ToolShieldLLMSecurityAnalyzer) + assert isinstance(fork_analyzer, ToolShieldLLMSecurityAnalyzer) + assert fork_analyzer is not source_analyzer + assert fork_analyzer.llm is not source_analyzer.llm + assert fork_analyzer.history_window == 7 + assert fork_analyzer.llm.model == "gpt-4o-mini" + + +def test_fork_copies_a_secret_source_that_cannot_be_deep_copied(): + """A custom secret source may hold a lock or a client; the fork still gets + a working copy of it.""" + with tempfile.TemporaryDirectory() as tmpdir: + src = Conversation( + agent=_agent(), + persistence_dir=tmpdir, + workspace=tmpdir, + secrets={"LOCKED": _LockedSecretSource()}, + ) + + fork = src.fork() + + assert fork.state.secret_registry.get_secret_value("LOCKED") == ( + "locked-source-value" + ) + fork_source = fork.state.secret_registry.secret_sources["LOCKED"] + assert fork_source is not src.state.secret_registry.secret_sources["LOCKED"] + + +def test_fork_copies_invoked_skills(): with tempfile.TemporaryDirectory() as tmpdir: src = Conversation(agent=_agent(), persistence_dir=tmpdir, workspace=tmpdir) - src.set_security_analyzer(LLMSecurityAnalyzer()) + src._state.invoked_skills = ["release-notes"] fork = src.fork() - assert fork.state.security_analyzer is not None - assert fork.state.security_analyzer is not src.state.security_analyzer + assert fork.state.invoked_skills == ["release-notes"] def test_fork_preserves_ciphered_security_analyzer_credentials(): From e27a26e59a3a0ff14c724bd9c2873b4a7f399bfd Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 19:10:13 +0000 Subject: [PATCH 08/13] fix(sdk): a fork keeps what the source's hooks decided fork() copied the events but not the hook verdicts recorded against them. A pending action that a PreToolUse hook had denied was executed when the fork ran, and a user message that a UserPromptSubmit hook had blocked was sent to the model, while the source did neither. This is on main too; it is the same gap as the confirmation policy, a safety decision that a fork silently dropped, so it is closed here. The fork takes over `blocked_actions` and `blocked_messages` for the events it copies, and `last_user_message_id` (the last user message it actually has, for a fork of an earlier branch point). Found in review of this stack. Each new test fails without the change: the denied command runs, the blocked prompt reaches the model. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- .../F10-fork-navigate-condense-ask.md | 4 +- .../conversation/impl/local_conversation.py | 24 +++ .../local/test_fork_hook_blocks.py | 183 ++++++++++++++++++ 3 files changed, 210 insertions(+), 1 deletion(-) create mode 100644 tests/sdk/conversation/local/test_fork_hook_blocks.py diff --git a/.agents/skills/verify-agent-server/references/feature-map/F10-fork-navigate-condense-ask.md b/.agents/skills/verify-agent-server/references/feature-map/F10-fork-navigate-condense-ask.md index 280a178572f..b9710d2299c 100644 --- a/.agents/skills/verify-agent-server/references/feature-map/F10-fork-navigate-condense-ask.md +++ b/.agents/skills/verify-agent-server/references/feature-map/F10-fork-navigate-condense-ask.md @@ -552,7 +552,9 @@ SIDE_AGENT="{\"llm\": {\"model\": \"openai/qa-stub\", \"api_key\": \"qa-stub-key both the response and persisted metadata. The title is stored separately and adds no tag (#4814). Other stored configuration (secrets, plugins, `parent_conversation_id`, client tools) is copied from the source. The - fork's `last_user_message_id` starts `null`. + fork's `last_user_message_id` is the last user message among the events + it copied, and what a hook decided about a copied action or message + (`blocked_actions`, `blocked_messages`) comes with them. - The fork's `base_state.json` is written with the source's cipher (the server's), so the fork's agent keeps its model keys (`F10.fork-keeps-credentials`) and its conversation secrets; the fork is diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index 60d588dec37..1f72669326f 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -1005,6 +1005,30 @@ def fork( ) fork_conv._state.agent_state = copy.deepcopy(self._state.agent_state) fork_conv._state.invoked_skills = list(self._state.invoked_skills) + # A hook's verdict on a copied action or message still holds in the + # fork: without it the fork would run an action a hook denied. + copied_ids = {event.id for event in source_events} + fork_conv._state.blocked_actions = { + event_id: reason + for event_id, reason in self._state.blocked_actions.items() + if event_id in copied_ids + } + fork_conv._state.blocked_messages = { + event_id: reason + for event_id, reason in self._state.blocked_messages.items() + if event_id in copied_ids + } + last_user_message_id = self._state.last_user_message_id + if last_user_message_id not in copied_ids: + last_user_message_id = next( + ( + event.id + for event in reversed(source_events) + if isinstance(event, MessageEvent) and event.source == "user" + ), + None, + ) + fork_conv._state.last_user_message_id = last_user_message_id fork_conv._state.confirmation_policy = self._state.confirmation_policy fork_conv._state.security_analyzer = fork_analyzer # Conversation secrets (``secrets=`` / update_secrets) live in the diff --git a/tests/sdk/conversation/local/test_fork_hook_blocks.py b/tests/sdk/conversation/local/test_fork_hook_blocks.py new file mode 100644 index 00000000000..51aa0f0b5d8 --- /dev/null +++ b/tests/sdk/conversation/local/test_fork_hook_blocks.py @@ -0,0 +1,183 @@ +"""A fork keeps what the source's hooks decided about the events it copies.""" + +from collections.abc import Sequence +from typing import ClassVar, Self +from unittest.mock import patch + +from litellm import ChatCompletionMessageToolCall +from litellm.types.utils import ( + Choices, + Function, + Message as LiteLLMMessage, + ModelResponse, +) +from pydantic import SecretStr + +from openhands.sdk.agent import Agent +from openhands.sdk.conversation import LocalConversation +from openhands.sdk.event.llm_convertible import UserRejectObservation +from openhands.sdk.hooks.config import HookConfig +from openhands.sdk.llm import LLM +from openhands.sdk.security.confirmation_policy import AlwaysConfirm +from openhands.sdk.tool import ( + Action, + Observation, + Tool, + ToolDefinition, + ToolExecutor, + register_tool, +) + + +class _ForkHookAction(Action): + command: str + + +class _ForkHookObservation(Observation): + pass + + +class _RecordingExecutor(ToolExecutor[_ForkHookAction, _ForkHookObservation]): + executed: ClassVar[list[str]] = [] + + def __call__( + self, + action: _ForkHookAction, + conversation: LocalConversation | None = None, + ) -> _ForkHookObservation: + self.executed.append(action.command) + return _ForkHookObservation.from_text(action.command) + + +class _ForkHookTool(ToolDefinition[_ForkHookAction, _ForkHookObservation]): + name: ClassVar[str] = "fork_hook_tool" + + @classmethod + def create(cls, *args, **kwargs) -> Sequence[Self]: + return [ + cls( + description="records the commands it is given", + action_type=_ForkHookAction, + observation_type=_ForkHookObservation, + executor=_RecordingExecutor(), + ) + ] + + +register_tool(_ForkHookTool.name, _ForkHookTool) + + +def _deny(hook_event: str, reason: str) -> HookConfig: + return HookConfig.from_dict( + { + "hooks": { + hook_event: [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": f"echo '{reason}' >&2; exit 2", + } + ], + } + ] + } + } + ) + + +def _response(*, tool_command: str | None = None) -> ModelResponse: + tool_calls = None + if tool_command is not None: + tool_calls = [ + ChatCompletionMessageToolCall( + id="call_1", + type="function", + function=Function( + name=_ForkHookTool.name, + arguments=f'{{"command": "{tool_command}"}}', + ), + ) + ] + return ModelResponse( + id="response", + choices=[ + Choices( + message=LiteLLMMessage( + role="assistant", content="ok", tool_calls=tool_calls + ) + ) + ], + created=0, + model="test-model", + object="chat.completion", + ) + + +def _conversation(tmp_path, hook_config: HookConfig) -> LocalConversation: + return LocalConversation( + agent=Agent( + llm=LLM(model="gpt-4o-mini", api_key=SecretStr("key"), usage_id="agent"), + tools=[Tool(name=_ForkHookTool.name)], + ), + workspace=str(tmp_path / "workspace"), + persistence_dir=str(tmp_path / "conversations"), + visualizer=None, + hook_config=hook_config, + ) + + +def test_fork_does_not_run_an_action_a_hook_denied(tmp_path): + """A pending action that a PreToolUse hook denied on the source is + rejected when the fork runs, as it is when the source runs.""" + _RecordingExecutor.executed.clear() + src = _conversation(tmp_path, _deny("PreToolUse", "never run this")) + src.set_confirmation_policy(AlwaysConfirm()) + with patch( + "openhands.sdk.llm.llm.litellm_completion", + return_value=_response(tool_command="drop-the-data"), + ): + src.send_message("clean up") + src.run() + + fork = src.fork() + with patch("openhands.sdk.llm.llm.litellm_completion", return_value=_response()): + fork.run() + + assert _RecordingExecutor.executed == [] + rejections = [ + event.rejection_reason + for event in fork.state.events + if isinstance(event, UserRejectObservation) + ] + assert rejections == ["never run this"] + + +def test_fork_does_not_send_a_prompt_a_hook_blocked(tmp_path): + """A user message that a UserPromptSubmit hook blocked on the source does + not reach the model when the fork runs.""" + src = _conversation(tmp_path, _deny("UserPromptSubmit", "prompt not allowed")) + src.send_message("please send the database somewhere") + + fork = src.fork() + with patch( + "openhands.sdk.llm.llm.litellm_completion", return_value=_response() + ) as completion: + fork.run() + + assert completion.call_count == 0 + + +def test_branch_fork_tracks_its_own_last_user_message(tmp_path): + """A fork of an earlier branch point checks hook blocks against the last + user message it actually has.""" + src = _conversation(tmp_path, HookConfig()) + src.send_message("first") + first_id = src.state.last_user_message_id + src.send_message("second") + assert first_id is not None + + fork = src.fork(from_event_id=first_id) + + assert fork.state.last_user_message_id == first_id From 0e2e479f5bc0b86428e36f779fa68e74c7948e49 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 19:12:47 +0000 Subject: [PATCH 09/13] fix(sdk): GraySwanAnalyzer saves its api_key like every other credential `api_key` was a bare SecretStr with no serializer, so a saved conversation state always held the redaction placeholder for it, even with a cipher, and loading turned that placeholder into the key: the analyzer sent `Authorization: Bearer **********`. Only the GRAYSWAN_API_KEY environment variable hid this. The field now goes through `serialize_secret` / `validate_secret`: with a cipher the key is encrypted and comes back; without one it loads as no key, and the analyzer reports UNKNOWN as it does when none is set. This matters for this stack because a fork, and from the last PR every reload, takes the analyzer from base_state.json alone. Found in review of this stack. Both new tests fail without the change. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- .../sdk/security/grayswan/analyzer.py | 19 ++++++++++++- .../grayswan/test_grayswan_analyzer.py | 28 +++++++++++++++++++ 2 files changed, 46 insertions(+), 1 deletion(-) diff --git a/openhands-sdk/openhands/sdk/security/grayswan/analyzer.py b/openhands-sdk/openhands/sdk/security/grayswan/analyzer.py index 13d39536744..5b6ba2cc496 100644 --- a/openhands-sdk/openhands/sdk/security/grayswan/analyzer.py +++ b/openhands-sdk/openhands/sdk/security/grayswan/analyzer.py @@ -13,13 +13,21 @@ from typing import Any import httpx -from pydantic import Field, PrivateAttr, SecretStr, model_validator +from pydantic import ( + Field, + PrivateAttr, + SecretStr, + field_serializer, + field_validator, + model_validator, +) from openhands.sdk.event import ActionEvent, LLMConvertibleEvent, SystemPromptEvent from openhands.sdk.logger import get_logger from openhands.sdk.security.analyzer import SecurityAnalyzerBase from openhands.sdk.security.grayswan.utils import convert_events_to_openai_messages from openhands.sdk.security.risk import SecurityRisk +from openhands.sdk.utils.pydantic_secrets import serialize_secret, validate_secret logger = get_logger(__name__) @@ -79,6 +87,15 @@ class GraySwanAnalyzer(SecurityAnalyzerBase): _client: httpx.Client | None = PrivateAttr(default=None) _events: list[LLMConvertibleEvent] = PrivateAttr(default_factory=list) + @field_validator("api_key") + @classmethod + def _validate_api_key(cls, v: SecretStr | None, info): + return validate_secret(v, info) + + @field_serializer("api_key", when_used="always") + def _serialize_api_key(self, v: SecretStr | None, info): + return serialize_secret(v, info) + @model_validator(mode="after") def validate_thresholds(self) -> GraySwanAnalyzer: """Validate that thresholds are properly ordered.""" diff --git a/tests/sdk/security/grayswan/test_grayswan_analyzer.py b/tests/sdk/security/grayswan/test_grayswan_analyzer.py index 1450e9643e4..95fb02f7454 100644 --- a/tests/sdk/security/grayswan/test_grayswan_analyzer.py +++ b/tests/sdk/security/grayswan/test_grayswan_analyzer.py @@ -12,6 +12,7 @@ from openhands.sdk.security.grayswan import GraySwanAnalyzer from openhands.sdk.security.risk import SecurityRisk from openhands.sdk.tool import Action +from openhands.sdk.utils.cipher import Cipher class GraySwanTestAction(Action): @@ -533,3 +534,30 @@ def mock_handler(request: httpx.Request) -> httpx.Response: assert result == SecurityRisk.UNKNOWN finally: analyzer.close() + + +def test_api_key_survives_a_ciphered_save_and_load(monkeypatch): + """Saved with a cipher (as conversation state is), the key comes back.""" + monkeypatch.delenv("GRAYSWAN_API_KEY", raising=False) + cipher = Cipher("grayswan-test-key") + analyzer = GraySwanAnalyzer(api_key=SecretStr("gs-secret-key")) + + saved = analyzer.model_dump(mode="json", context={"cipher": cipher}) + loaded = GraySwanAnalyzer.model_validate(saved, context={"cipher": cipher}) + + assert "gs-secret-key" not in json.dumps(saved) + assert loaded.api_key is not None + assert loaded.api_key.get_secret_value() == "gs-secret-key" + + +def test_api_key_saved_without_a_cipher_loads_as_missing(monkeypatch): + """Without a cipher the key is redacted on save. It must load as no key, + not as the redaction placeholder sent to the API as a bearer token.""" + monkeypatch.delenv("GRAYSWAN_API_KEY", raising=False) + analyzer = GraySwanAnalyzer(api_key=SecretStr("gs-secret-key")) + + saved = analyzer.model_dump(mode="json") + loaded = GraySwanAnalyzer.model_validate(saved) + + assert "gs-secret-key" not in json.dumps(saved) + assert loaded.api_key is None From 9430e570a1672da22ad6d43793c87c123bec270b Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 19:23:11 +0000 Subject: [PATCH 10/13] test(sdk): the fork's registry is its own, and a replacement agent keeps its secrets Two properties of the registry copy that had no test: - Replacing a secret on the fork must not change what the source masks. With a registry copied by `model_copy`, as #4813 first did, the two share one masking cache and the source stops masking its own value once the fork has resolved the new one. The test fails on that copy. - `fork(agent=...)` with an agent that brings secrets in its context has them next to the ones copied from the source. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- tests/sdk/conversation/local/test_fork.py | 51 +++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/tests/sdk/conversation/local/test_fork.py b/tests/sdk/conversation/local/test_fork.py index 97d6948e5f4..97cd034b4e5 100644 --- a/tests/sdk/conversation/local/test_fork.py +++ b/tests/sdk/conversation/local/test_fork.py @@ -12,6 +12,7 @@ from pydantic import PrivateAttr, SecretStr from openhands.sdk.agent import Agent +from openhands.sdk.context import AgentContext from openhands.sdk.conversation import Conversation, LocalConversation from openhands.sdk.conversation.state import ( ConversationExecutionStatus, @@ -484,6 +485,56 @@ def test_fork_copies_secret_registry(): ) +def test_fork_secret_change_does_not_reach_the_source_masking(): + """The fork resolves and masks with a registry of its own: replacing a + secret on the fork leaves the source masking its own value.""" + with tempfile.TemporaryDirectory() as tmpdir: + src = Conversation( + agent=_agent(), + persistence_dir=tmpdir, + workspace=tmpdir, + secrets={"TOKEN": "source-token-value"}, + ) + src_registry = src.state.secret_registry + assert src_registry.get_secrets_as_env_vars("echo $TOKEN") == { + "TOKEN": "source-token-value" + } + + fork = src.fork() + fork.update_secrets({"TOKEN": "fork-token-value"}) + assert fork.state.secret_registry.get_secrets_as_env_vars("echo $TOKEN") == { + "TOKEN": "fork-token-value" + } + + assert ( + src.state.secret_registry.mask_secrets_in_output("out: source-token-value") + == "out: " + ) + + +def test_fork_keeps_a_replacement_agents_own_secrets(): + """`fork(agent=...)` with an agent that brings secrets in its context has + them next to the ones copied from the source.""" + with tempfile.TemporaryDirectory() as tmpdir: + src = Conversation( + agent=_agent(), + persistence_dir=tmpdir, + workspace=tmpdir, + secrets={"SOURCE_TOKEN": "source-value"}, + ) + replacement = Agent( + llm=LLM(model="gpt-4o-mini", api_key=SecretStr("k"), usage_id="other"), + tools=[], + agent_context=AgentContext(secrets={"AGENT_TOKEN": "agent-value"}), + ) + + fork = src.fork(agent=replacement) + + registry = fork.state.secret_registry + assert registry.get_secret_value("AGENT_TOKEN") == "agent-value" + assert registry.get_secret_value("SOURCE_TOKEN") == "source-value" + + def test_fork_gives_independent_security_analyzer(): """The fork's analyzer is a copy of its own, down to the guardrail LLM: a shared analyzer, or a shallow copy of one, would mix the two conversations From 2b1c0b24a40e3632153d82bf51858d87dff45ee5 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 11 Nov 2026 20:22:45 +0000 Subject: [PATCH 11/13] refactor(sdk): the fork's copy helper lives with the secret utilities The helper that copies a model through its own dump and validate, with credentials kept, moves from local_conversation.py to utils/pydantic_secrets.py as copy_keeping_secrets. The agent-server makes the same kind of copy for a child conversation and can import it instead of spelling the round trip out again. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- .../conversation/impl/local_conversation.py | 23 +++++-------------- .../openhands/sdk/utils/pydantic_secrets.py | 14 ++++++++++- 2 files changed, 19 insertions(+), 18 deletions(-) diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index 230e2d940ed..fe5a24ac919 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -9,8 +9,6 @@ from pathlib import Path, PurePath from typing import Any, Final, TypeGuard, cast -from pydantic import BaseModel - from openhands.sdk.agent.acp_agent import ACPAgent from openhands.sdk.agent.base import AgentBase from openhands.sdk.agent.stream_context import StreamProgressCallbackType @@ -116,6 +114,7 @@ from openhands.sdk.tool.client_tool import ClientToolSpec from openhands.sdk.tool.schema import Action, Observation from openhands.sdk.utils.cipher import Cipher +from openhands.sdk.utils.pydantic_secrets import copy_keeping_secrets from openhands.sdk.utils.redact import ( redact_url_credentials, redact_url_credentials_in_text, @@ -201,18 +200,6 @@ def _same_llm_config(a: LLM, b: LLM) -> bool: ) -def _own_copy[ModelT: BaseModel](model: ModelT) -> ModelT: - """A copy that shares nothing with ``model`` and keeps its credentials. - - A dump/validate round trip rather than ``model_copy(deep=True)``: a deep - copy carries private runtime state along (an analyzer's history) and fails - on members that cannot be copied (a lock, an open client). - """ - return type(model).model_validate( - model.model_dump(context={"expose_secrets": True}) - ) - - class LocalConversation(BaseConversation): agent: AgentBase workspace: LocalWorkspace @@ -920,7 +907,7 @@ def fork( # per-conversation call context on the LLM (#2917, #3443): a # shared/aliased agent would clobber the source conversation's # context. - fork_agent = _own_copy(agent if agent is not None else self.agent) + fork_agent = copy_keeping_secrets(agent if agent is not None else self.agent) # Hold the state lock while reading mutable state from the source # conversation to avoid torn reads if run() is executing concurrently. @@ -932,10 +919,12 @@ def fork( # Copied before the fork exists too, for the same reason. source_analyzer = self._state.security_analyzer fork_analyzer = ( - _own_copy(source_analyzer) if source_analyzer is not None else None + copy_keeping_secrets(source_analyzer) + if source_analyzer is not None + else None ) fork_secrets = { - name: _own_copy(source) + name: copy_keeping_secrets(source) for name, source in self._state.secret_registry.secret_sources.items() } diff --git a/openhands-sdk/openhands/sdk/utils/pydantic_secrets.py b/openhands-sdk/openhands/sdk/utils/pydantic_secrets.py index 5379e0fb619..71c359dcb6e 100644 --- a/openhands-sdk/openhands/sdk/utils/pydantic_secrets.py +++ b/openhands-sdk/openhands/sdk/utils/pydantic_secrets.py @@ -2,7 +2,7 @@ from collections.abc import Mapping from typing import Any, Final, Literal, overload -from pydantic import SecretStr, ValidationInfo +from pydantic import BaseModel, SecretStr, ValidationInfo from openhands.sdk.utils.cipher import FERNET_TOKEN_PREFIX, Cipher @@ -250,3 +250,15 @@ def _decrypt_env(cls, value, info): k: decrypt_str_with_cipher_or_keep(cipher, v, description=description) for k, v in value.items() } + + +def copy_keeping_secrets[ModelT: BaseModel](model: ModelT) -> ModelT: + """A copy that shares nothing with ``model`` and keeps its credentials. + + A dump/validate round trip rather than ``model_copy(deep=True)``: a deep + copy carries private runtime state along (an analyzer's history) and fails + on members that cannot be copied (a lock, an open client). + """ + return type(model).model_validate( + model.model_dump(context={"expose_secrets": True}) + ) From 249f4cbedeb18758ed5f0b3ffe51e2098b965ba8 Mon Sep 17 00:00:00 2001 From: Claude Date: Sat, 14 Nov 2026 02:11:18 +0000 Subject: [PATCH 12/13] fork: give the fork the hooks the source was created with Part of the fork's state was the hooks' verdicts on the events it copies, but not the hooks. A pending action the source's PreToolUse hook had denied stayed denied in the fork, and the next action the fork asked for ran with no hook at all. The fork is now built with the caller's own hook_config. The plugin hooks are not passed along: the fork loads the plugins itself, and the merged config would register them twice. Hooks of a plugin the source loaded at runtime are still not carried. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- .../verify-sdk/programs/S04/fork_state.py | 21 +++- .../feature-map/S04-local-conversation.md | 7 +- .../conversation/impl/local_conversation.py | 10 +- .../local/test_fork_hook_blocks.py | 107 +++++++++++++++++- 4 files changed, 134 insertions(+), 11 deletions(-) diff --git a/.agents/skills/verify-sdk/programs/S04/fork_state.py b/.agents/skills/verify-sdk/programs/S04/fork_state.py index 13acea9e5c8..ffd496ce3d7 100644 --- a/.agents/skills/verify-sdk/programs/S04/fork_state.py +++ b/.agents/skills/verify-sdk/programs/S04/fork_state.py @@ -1,7 +1,7 @@ -"""Fork a conversation that carries a confirmation policy, a security analyzer -with its own model key, and secrets, all set after construction, and report -what the fork has: in memory, in its `base_state.json`, and after it is loaded -again from disk. No model is called. +"""Fork a conversation that was built with a hook and carries a confirmation +policy, a security analyzer with its own model key, and secrets, all set after +construction, and report what the fork has: in memory, in its +`base_state.json`, and after it is loaded again from disk. No model is called. Usage: fork_state.py """ @@ -13,6 +13,7 @@ from sdk_verify import emit, make_llm, run_paths from openhands.sdk import LLM, Agent, LocalConversation +from openhands.sdk.hooks import HookConfig, HookDefinition, HookMatcher from openhands.sdk.security.confirmation_policy import ConfirmRisky, NeverConfirm from openhands.sdk.security.risk import SecurityRisk from openhands.sdk.security.toolshield_llm_analyzer import ( @@ -25,6 +26,7 @@ BASE = paths["run"] / "fork-state" WORKSPACE = str(paths["workspace"]) VALUES = ("start-secret-value-1", "guard-key-value-2", "runtime-secret-value-3") +HOOK_REASON = "blocked by the source hook" cipher = Cipher("sdk-verify-fork-state-key") @@ -51,6 +53,13 @@ def guard_key(conversation) -> str | None: persistence_dir=str(BASE), cipher=cipher, secrets={"START_TOKEN": VALUES[0]}, + hook_config=HookConfig( + user_prompt_submit=[ + HookMatcher( + hooks=[HookDefinition(command=f"echo '{HOOK_REASON}' >&2; exit 2")] + ) + ] + ), visualizer=None, ) source.set_confirmation_policy( @@ -85,6 +94,10 @@ def guard_key(conversation) -> str | None: "plaintext_on_disk": any(value in saved_text for value in VALUES), } +# A prompt sent to the fork goes through the hook the source was built with. +fork.send_message("hello") +out["fork_prompt_block"] = next(iter(fork.state.blocked_messages.values()), None) + # Changing the fork does not reach back into the source. fork.set_confirmation_policy(NeverConfirm()) fork.update_secrets({"FORK_ONLY": "fork-only-value-4"}) diff --git a/.agents/skills/verify-sdk/references/feature-map/S04-local-conversation.md b/.agents/skills/verify-sdk/references/feature-map/S04-local-conversation.md index 0bc17c12810..e28c62bdf4d 100644 --- a/.agents/skills/verify-sdk/references/feature-map/S04-local-conversation.md +++ b/.agents/skills/verify-sdk/references/feature-map/S04-local-conversation.md @@ -30,7 +30,7 @@ Examples: `examples/01_standalone_sdk/06_interactive_terminal_w_reasoning.py`, ` - `S04.visualizer-custom`: a `ConversationVisualizerBase` subclass passed as `visualizer=` receives every event through `on_event`; each event type has its own `visualize` rendering. Unit: `tests/sdk/conversation/test_visualizer.py`. Example: `examples/01_standalone_sdk/26_custom_visualizer.py`. Real-LLM: none. - `S04.fork`: `fork()` deep-copies the conversation under a new id (or `conversation_id=`), starts IDLE, leaves the source untouched, resets metrics unless `reset_metrics=False`, accepts `agent=` and `tags=` (`title=` is deprecated and ignored locally since #4814; only `RemoteConversation` stores it), shares the workspace, and persists so the fork survives a reload. Unit: `tests/sdk/conversation/local/test_fork.py`. Example: `examples/01_standalone_sdk/48_conversation_fork.py`. Real-LLM: none. - `S04.fork-branch`: events carry parent ids forming a tree; `fork(from_event_id=...)` copies only that branch, and `navigate_to(event_id)` moves HEAD so the next event starts a sibling branch (`None` empties the active branch). Unit: `tests/sdk/conversation/local/test_conversation_tree.py`. Example: `examples/01_standalone_sdk/48_conversation_fork.py`. Real-LLM: none. -- `S04.fork-keeps-state`: a fork carries the source's confirmation policy, its own copy of the security analyzer (credentials kept) and the conversation secrets, and is written with the source's cipher, so its `base_state.json` alone restores them. Unit: `tests/sdk/conversation/local/test_fork.py`. Example: none. Real-LLM: none. +- `S04.fork-keeps-state`: a fork carries the source's confirmation policy, its own copy of the security analyzer (credentials kept) and the conversation secrets, and is written with the source's cipher, so its `base_state.json` alone restores them; it also runs the hooks in the `hook_config` the source was built with. Unit: `tests/sdk/conversation/local/test_fork.py`, `tests/sdk/conversation/local/test_fork_hook_blocks.py`. Example: none. Real-LLM: none. - `S04.goal-loop`: `run_goal(conversation, objective, judge_llm, max_iterations=N)` sends the objective, runs, asks the judge LLM for a verdict, re-prompts with the missing items, and returns a `GoalOutcome` with status `"complete"` or `"capped"`, the iteration count and the verdict. Unit: `tests/sdk/conversation/goal/`. Example: `examples/01_standalone_sdk/54_goal_completion_loop.py`. Real-LLM: none. - `S04.interactive-terminal`: with `Tool(name=TerminalTool.name, params={"no_change_timeout_seconds": 3})` the agent can start `python3`, feed it input and exit; an `LLMConvertibleEvent` callback collects the raw LLM messages. Unit: `tests/tools/terminal/test_terminal_session.py::test_python_interactive_input`, `::test_interactive_command`. Example: `examples/01_standalone_sdk/06_interactive_terminal_w_reasoning.py`. Real-LLM: `tests/integration/tests/t07_interactive_commands.py`. - `S04.final-response`: `get_agent_final_response(conversation.state.events)` returns the text of whichever came last of the agent's `finish` call and its plain-text `MessageEvent`, else `""`. Unit: `tests/sdk/conversation/test_agent_final_response.py`. Example: none. Real-LLM: `tests/integration/tests/t08_image_file_viewing.py`. @@ -225,7 +225,7 @@ Scripted bullets use the SDK's `TestLLM` (`--script`, or `make_llm(script=...)` --check old_branch_in_active eq false --check active_ends_with eq "answer on a new branch" \ --check unknown_event_error contains "Unknown event_id" --check active_after_none eq 0 --check log_after_none eq 7 ``` -- **What a fork keeps (`S04.fork-keeps-state`).** A ciphered conversation gets `ConfirmRisky(MEDIUM)`, a `ToolShieldLLMSecurityAnalyzer` with its own model key and a runtime secret after construction, then is forked; the fork is changed and loaded again from disk. +- **What a fork keeps (`S04.fork-keeps-state`).** A ciphered conversation built with a `UserPromptSubmit` hook that blocks every prompt gets `ConfirmRisky(MEDIUM)`, a `ToolShieldLLMSecurityAnalyzer` with its own model key and a runtime secret after construction, then is forked; the fork is sent a message, changed and loaded again from disk. ```sh export SDK_VERIFY_RUN=$(control-sdk new --field run) control-sdk program S04/fork_state \ @@ -235,11 +235,12 @@ Scripted bullets use the SDK's `TestLLM` (`--script`, or `make_llm(script=...)` --check saved_policy.kind eq ConfirmRisky --check saved_analyzer eq ToolShieldLLMSecurityAnalyzer \ --check saved_secret_names.0 eq RUNTIME_TOKEN --check saved_secret_names.1 eq START_TOKEN \ --check saved_guard_key_is_placeholder eq false --check plaintext_on_disk eq false \ + --check fork_prompt_block eq "blocked by the source hook" \ --check source_policy_after_fork_change eq ConfirmRisky --check source_has_fork_only_secret eq false \ --check reloaded_policy eq NeverConfirm --check reloaded_guard_key_kept eq true \ --check reloaded_secrets.START_TOKEN eq start-secret-value-1 --check reloaded_secrets.FORK_ONLY eq fork-only-value-4 ``` - The fork has the policy with its threshold, an analyzer object of its own whose key still works, and both secrets; its `base_state.json` holds them encrypted (neither the plaintext nor the `**********` placeholder). Setting `NeverConfirm` and a new secret on the fork leaves the source as it was, and the fork loaded again from disk has the fork's values. + The fork has the policy with its threshold, an analyzer object of its own whose key still works, and both secrets; its `base_state.json` holds them encrypted (neither the plaintext nor the `**********` placeholder). The message sent to the fork is blocked with the source hook's reason. Setting `NeverConfirm` and a new secret on the fork leaves the source as it was, and the fork loaded again from disk has the fork's values. - **The goal loop (`S04.goal-loop`).** `run_goal` with a scripted judge: incomplete then complete (the follow-up names what was missing), and a capped run whose last verdict cannot be parsed. ```sh export SDK_VERIFY_RUN=$(control-sdk new --field run) diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index 745eaf43ce7..6be27137b23 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -267,6 +267,9 @@ class LocalConversation(BaseConversation): _resolved_plugins: list[ResolvedPluginSource] | None _plugins_loaded: bool _pending_hook_config: HookConfig | None # Hook config to combine with plugin hooks + # The caller's hook_config, never merged with plugin hooks, so a fork can + # be given it without receiving the plugin hooks twice. + _explicit_hook_config: HookConfig | None _mcp_tool_provider: MCPToolProvider _mcp_config_from_parent: bool _llm_call_context: LLMCallContext @@ -395,6 +398,7 @@ def __init__( self._resolved_plugins = None self._plugins_loaded = False self._pending_hook_config = hook_config # Will be combined with plugin hooks + self._explicit_hook_config = hook_config self._agent_ready = False # Agent initialized lazily after plugins loaded self._mcp_tool_provider = mcp_tool_provider or DefaultMCPToolProvider() self._mcp_config_from_parent = _mcp_config_from_parent @@ -964,8 +968,9 @@ def fork( Events are copied so the source remains immutable. The fork starts in ``execution_status='idle'``; calling ``run()`` resumes from the copied state — meaning the agent has full event memory of the source. - It also keeps the source's confirmation policy, its own copy of the - security analyzer and of the secrets, and the source's cipher. + It also keeps the source's confirmation policy, the ``hook_config`` the + source was created with, its own copy of the security analyzer and of + the secrets, and the source's cipher. Args: conversation_id: ID for the forked conversation (auto-generated @@ -1033,6 +1038,7 @@ def fork( agent=fork_agent, workspace=self.workspace, plugins=self._plugin_specs, + hook_config=self._explicit_hook_config, persistence_dir=fork_persistence, conversation_id=fork_id, max_iteration_per_run=self.max_iteration_per_run, diff --git a/tests/sdk/conversation/local/test_fork_hook_blocks.py b/tests/sdk/conversation/local/test_fork_hook_blocks.py index 51aa0f0b5d8..760cc464e0f 100644 --- a/tests/sdk/conversation/local/test_fork_hook_blocks.py +++ b/tests/sdk/conversation/local/test_fork_hook_blocks.py @@ -1,6 +1,8 @@ -"""A fork keeps what the source's hooks decided about the events it copies.""" +"""A fork keeps the source's hooks and what they decided about the events it copies.""" +import json from collections.abc import Sequence +from pathlib import Path from typing import ClassVar, Self from unittest.mock import patch @@ -14,10 +16,13 @@ from pydantic import SecretStr from openhands.sdk.agent import Agent +from openhands.sdk.context import AgentContext from openhands.sdk.conversation import LocalConversation from openhands.sdk.event.llm_convertible import UserRejectObservation from openhands.sdk.hooks.config import HookConfig from openhands.sdk.llm import LLM +from openhands.sdk.marketplace import MarketplaceRegistration +from openhands.sdk.plugin import PluginSource from openhands.sdk.security.confirmation_policy import AlwaysConfirm from openhands.sdk.tool import ( Action, @@ -115,16 +120,51 @@ def _response(*, tool_command: str | None = None) -> ModelResponse: ) -def _conversation(tmp_path, hook_config: HookConfig) -> LocalConversation: +def _plugin_with_hook(plugin_dir: Path, matcher: str) -> PluginSource: + (plugin_dir / ".plugin").mkdir(parents=True) + (plugin_dir / ".plugin" / "plugin.json").write_text( + json.dumps({"name": plugin_dir.name}) + ) + (plugin_dir / "hooks").mkdir() + hooks = {"PreToolUse": [{"matcher": matcher, "hooks": [{"command": "exit 0"}]}]} + (plugin_dir / "hooks" / "hooks.json").write_text(json.dumps({"hooks": hooks})) + return PluginSource(source=str(plugin_dir)) + + +def _marketplace_with_hook_plugin(marketplace_dir: Path, matcher: str) -> AgentContext: + """An agent context whose marketplace offers one plugin, named "runtime".""" + _plugin_with_hook(marketplace_dir / "plugins" / "runtime", matcher) + (marketplace_dir / ".plugin").mkdir() + manifest = { + "name": "market", + "owner": {"name": "test"}, + "plugins": [{"name": "runtime", "source": "./plugins/runtime"}], + } + (marketplace_dir / ".plugin" / "marketplace.json").write_text(json.dumps(manifest)) + return AgentContext( + registered_marketplaces=[ + MarketplaceRegistration(name="market", source=str(marketplace_dir)) + ] + ) + + +def _conversation( + tmp_path, + hook_config: HookConfig, + plugins: list[PluginSource] | None = None, + agent_context: AgentContext | None = None, +) -> LocalConversation: return LocalConversation( agent=Agent( llm=LLM(model="gpt-4o-mini", api_key=SecretStr("key"), usage_id="agent"), tools=[Tool(name=_ForkHookTool.name)], + agent_context=agent_context, ), workspace=str(tmp_path / "workspace"), persistence_dir=str(tmp_path / "conversations"), visualizer=None, hook_config=hook_config, + plugins=plugins, ) @@ -154,6 +194,69 @@ def test_fork_does_not_run_an_action_a_hook_denied(tmp_path): assert rejections == ["never run this"] +def test_fork_runs_the_source_hooks_on_a_new_action(tmp_path): + """An action the model first asks for in the fork goes through the + PreToolUse hook the source was created with.""" + _RecordingExecutor.executed.clear() + src = _conversation(tmp_path, _deny("PreToolUse", "never run this")) + src.send_message("clean up") + + fork = src.fork() + with patch( + "openhands.sdk.llm.llm.litellm_completion", + side_effect=[_response(tool_command="drop-the-data"), _response()], + ): + fork.run() + + assert _RecordingExecutor.executed == [] + rejections = [ + event.rejection_reason + for event in fork.state.events + if isinstance(event, UserRejectObservation) + ] + assert rejections == ["never run this"] + + +def test_fork_has_each_hook_once_when_the_source_also_has_plugin_hooks(tmp_path): + """The fork loads the plugins itself, so it is given the source's own + hooks without the plugin hooks the source merged into them.""" + src = _conversation( + tmp_path, + _deny("PreToolUse", "never run this"), + plugins=[_plugin_with_hook(tmp_path / "plugin", "plugin-*")], + ) + src.send_message("first") + + fork = src.fork() + fork.send_message("second") + + assert fork.state.hook_config is not None + matchers = [matcher.matcher for matcher in fork.state.hook_config.pre_tool_use] + assert matchers == ["*", "plugin-*"] + + +def test_fork_does_not_repeat_hooks_after_a_runtime_plugin_load(tmp_path): + """A plugin the source loaded at runtime does not make the fork register + the hooks of the source's other plugins a second time.""" + src = _conversation( + tmp_path, + _deny("PreToolUse", "never run this"), + plugins=[_plugin_with_hook(tmp_path / "plugin", "plugin-*")], + agent_context=_marketplace_with_hook_plugin( + tmp_path / "marketplace", "runtime-*" + ), + ) + src.load_plugin("runtime") + + fork = src.fork() + fork.send_message("hello") + + assert fork.state.hook_config is not None + matchers = [matcher.matcher for matcher in fork.state.hook_config.pre_tool_use] + assert matchers.count("*") == 1 + assert matchers.count("plugin-*") == 1 + + def test_fork_does_not_send_a_prompt_a_hook_blocked(tmp_path): """A user message that a UserPromptSubmit hook blocked on the source does not reach the model when the fork runs.""" From bba1de0102fa5c3d10c6848cba929cdb5dba44f1 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 20 Nov 2026 00:35:55 +0000 Subject: [PATCH 13/13] fork: keep what a custom secret source holds outside its fields The fork copied every secret source through a dump and validate round trip. A custom `SecretSource` that keeps its value in a private attribute or in a field the dump leaves out came out of that with no value (and a required field of that kind made `fork()` raise), where main's deep copy (#5765) keeps it. The same held for such a source in the agent's context. Secret sources are deep-copied again, as on main. A source the deep copy cannot handle (one that holds a lock or an open client, which makes `fork()` raise on main) is rebuilt from its fields instead. Tests for each case; each fails with only the other half in place. Found by the review of the merge with main. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_013ArwwMuszm1Nt9r2whddpY --- .../conversation/impl/local_conversation.py | 17 ++++- tests/sdk/conversation/local/test_fork.py | 69 ++++++++++++++++++- 2 files changed, 83 insertions(+), 3 deletions(-) diff --git a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py index 088860f0cf2..ada4121c91b 100644 --- a/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py +++ b/openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py @@ -118,7 +118,7 @@ load_available_plugins, ) from openhands.sdk.plugin.strict_fetch import expand_plugin_source -from openhands.sdk.secret import StaticSecret +from openhands.sdk.secret import SecretSource, StaticSecret from openhands.sdk.security.analyzer import SecurityAnalyzerBase from openhands.sdk.security.confirmation_policy import ( ConfirmationPolicyBase, @@ -220,6 +220,19 @@ def _copy_event_for_fork(event: Event, source: EventLog) -> Event: return copied.model_copy(update={"parent_id": bridged}) +def _copy_secret_source_for_fork(source: SecretSource) -> SecretSource: + """A copy of a secret source that the fork owns. + + A deep copy keeps what a custom source holds outside its fields, such as a + value in a private attribute. A source with a member that cannot be copied + (a lock, an open client) is rebuilt from its fields instead. + """ + try: + return source.model_copy(deep=True) + except Exception: + return copy_keeping_secrets(source) + + def _hooks_not_in(hooks: HookConfig, existing: HookConfig) -> HookConfig: """Return the matchers of ``hooks`` that ``existing`` does not already hold.""" @@ -1047,7 +1060,7 @@ def fork( else None ) fork_secrets = { - name: copy_keeping_secrets(source) + name: _copy_secret_source_for_fork(source) for name, source in self._state.secret_registry.secret_sources.items() } diff --git a/tests/sdk/conversation/local/test_fork.py b/tests/sdk/conversation/local/test_fork.py index 97cd034b4e5..d74e346de2a 100644 --- a/tests/sdk/conversation/local/test_fork.py +++ b/tests/sdk/conversation/local/test_fork.py @@ -9,7 +9,7 @@ from typing import Self import pytest -from pydantic import PrivateAttr, SecretStr +from pydantic import Field, PrivateAttr, SecretStr from openhands.sdk.agent import Agent from openhands.sdk.context import AgentContext @@ -55,6 +55,24 @@ def get_value(self) -> str: return "locked-source-value" +class _PrivateValueSecretSource(SecretSource): + """A secret source that keeps its value outside its fields.""" + + _value: str | None = PrivateAttr(default=None) + + def get_value(self) -> str | None: + return self._value + + +class _ExcludedFieldSecretSource(SecretSource): + """A secret source that keeps its value in a field a dump leaves out.""" + + token: str = Field(default="", exclude=True) + + def get_value(self) -> str | None: + return self.token or None + + class ForkCopyMockAction(Action): command: str = "test" @@ -579,6 +597,55 @@ def test_fork_copies_a_secret_source_that_cannot_be_deep_copied(): assert fork_source is not src.state.secret_registry.secret_sources["LOCKED"] +def _private_value_source() -> SecretSource: + source = _PrivateValueSecretSource() + source._value = "held-outside-the-fields" + return source + + +@pytest.mark.parametrize( + "make_source", + [ + _private_value_source, + lambda: _ExcludedFieldSecretSource(token="held-outside-the-fields"), + ], + ids=["private-attribute", "excluded-field"], +) +def test_fork_keeps_what_a_secret_source_holds_outside_its_fields(make_source): + """A custom secret source may keep its value in a private attribute or in + a field a dump leaves out; the fork's copy still resolves.""" + with tempfile.TemporaryDirectory() as tmpdir: + src = Conversation( + agent=_agent(), workspace=tmpdir, secrets={"HELD": make_source()} + ) + + fork = src.fork() + + assert fork.state.secret_registry.get_secret_value("HELD") == ( + "held-outside-the-fields" + ) + fork_source = fork.state.secret_registry.secret_sources["HELD"] + assert fork_source is not src.state.secret_registry.secret_sources["HELD"] + + +def test_fork_keeps_such_a_secret_source_from_the_agents_context(): + """The agent goes through a dump, which drops what such a source holds; + the fork's registry still has the working copy.""" + with tempfile.TemporaryDirectory() as tmpdir: + agent = _agent().model_copy( + update={ + "agent_context": AgentContext(secrets={"CTX": _private_value_source()}) + } + ) + src = Conversation(agent=agent, workspace=tmpdir) + + fork = src.fork() + + assert fork.state.secret_registry.get_secret_value("CTX") == ( + "held-outside-the-fields" + ) + + def test_fork_copies_invoked_skills(): with tempfile.TemporaryDirectory() as tmpdir: src = Conversation(agent=_agent(), persistence_dir=tmpdir, workspace=tmpdir)