agents-gl 0.0.1__py3-none-any.whl

agents_gl-0.0.1.dist-info/METADATA

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: agents-gl
+Version: 0.0.1
+Summary: A framework for running AI agent workflows against code repositories.
+Project-URL: Homepage, https://github.com/jashioq/AGL
+Project-URL: Repository, https://github.com/jashioq/AGL
+Author-email: Jan <janwylegalaandrzej@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,git,llm,orchestration,workflows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.14
+Provides-Extra: all
+Requires-Dist: agl[claude,terminal]; extra == 'all'
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk>=0.2.140; extra == 'claude'
+Provides-Extra: terminal
+Requires-Dist: rich>=15.0.0; extra == 'terminal'
+Description-Content-Type: text/markdown
+
+# AGL
+
+AGL runs AI agent workflows against a code repository. A workflow is ordinary Python that asks for
+a worktree, hands roles to agents and lands what comes back: `fix` runs one worktree sequentially
+with Claude implementing and OpenAI reviewing, `split` runs N chunks concurrently.
+
+## Install
+
+```bash
+uv tool install "agl[all]"
+```
+
+The `[all]` extra pulls in the Claude adapter (`claude-agent-sdk`) and the rich terminal. Without
+it you get the core, which is stdlib-only.
+
+## Python 3.14 or newer
+
+This is the one thing most likely to trip you up. AGL declares `requires-python = ">=3.14"`, so a
+plain `pip install agl` on an older interpreter refuses before it downloads anything, and it
+reports that as not finding a version rather than as your interpreter being too old. `uv tool
+install` sidesteps it by fetching a matching interpreter itself.
+
+## Status
+
+Early. 0.0.1 is a name claim rather than a release, and the surface may still change.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).

agents_gl-0.0.1.dist-info/RECORD

@@ -0,0 +1,115 @@
+agl/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/api.py,sha256=SFxNudzyd_wjNxKoHizXvCbYArbUBbjrDPy_8OGC8bo,8106
+agl/testing.py,sha256=4NhJy2i4fZ4bP6LO3J6bYtrsRVDVV982AyLjolannXM,7816
+agl/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/adapters/routing.py,sha256=mWKR6RoMyoGR5hVXhSpb6xc0AASpmLvEV6-ahHIyPNk,2310
+agl/adapters/system_clock.py,sha256=yChkyzdKS-Cjir1TOhgC9asp0-YSnOoE_z1yD9kzBSQ,1489
+agl/adapters/claude_code/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/adapters/claude_code/_session.py,sha256=8jFXjge0B3bZD9vTtXZ7xcd4ezyKCzI6SRMqoBoIAHQ,4239
+agl/adapters/claude_code/_tools.py,sha256=VN6ylJPs7kPIejlDaZc4Mt1J3DVGo-lfiXWvvai4JK0,2740
+agl/adapters/claude_code/fake.py,sha256=qqteEYq37EDa_8RwnjgdX2iL4GtcVKSQi1BpKpXpwhk,6753
+agl/adapters/claude_code/runner.py,sha256=WNjduqsa_xXs50_HysSgfkQmKe25l0OR7bZXUaCZ15o,6354
+agl/adapters/claude_code/translate.py,sha256=lRLt43SGKuOen0ZE-hPQ1-fPH7RrVYyBubfp6yYL4bY,9138
+agl/adapters/filesystem/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/adapters/filesystem/_documents.py,sha256=DiGjpQaIDYftnmoxaoqH7p4OGtcX_YBcZlyiCYL_CTg,1654
+agl/adapters/filesystem/memory_store.py,sha256=d-O6ajH3GmsL4mS-X1viKK4dguY_ktzyNA439rofE28,2436
+agl/adapters/filesystem/store.py,sha256=MooAKDsbK8VkYfnO4Fuflt0wMFtBDIWU8sXx4wipz2A,5488
+agl/adapters/git/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/adapters/git/_changes.py,sha256=NBIUYCzMHTFqp-ntZvsLxPtLAwKh09R0kOI7TK4Gki0,1735
+agl/adapters/git/_conflicts.py,sha256=wn5UMzxc6mResM-lkKHE4lvt-_RAeIg0sIMZ1X6qZ6k,2385
+agl/adapters/git/_merging.py,sha256=-7PtPk72xC19V13AmyO_oX2oWOGBLSrMSa2XQb20Tvs,5058
+agl/adapters/git/_patches.py,sha256=bDQW-0pi3YKKAFX3BtP_U5ZW9di1TRmOVBsW5osRfvU,2902
+agl/adapters/git/_runner.py,sha256=PxY5O6sNFz4nuBr0z-cnCyQPAqvduwk7zbxnyZ7Mg2I,7319
+agl/adapters/git/_snapshots.py,sha256=vueFtdkqM5KyyRqy0wHS6OoM9PK5nBZESS50aZzvaMg,5761
+agl/adapters/git/_trees.py,sha256=VNXsSrFaZeso1iQdDhr-RF4wSFUMT7x08urjqiwW8eE,4959
+agl/adapters/git/_working.py,sha256=3aKCo6dOEiqtenwwos74cmUHahMaa5Ec_UaFunm4T7w,2726
+agl/adapters/git/fake.py,sha256=sRrvZlYAr-I4U8CZNplqcnTAEdRoBHaH6jKKVXI1Mso,13357
+agl/adapters/git/history.py,sha256=pSAG26us5UKH0elnKhwb7fYNS1S7C1jTOG5CWiKbIjQ,4710
+agl/adapters/git/integrator.py,sha256=zFUkSqX3j-exHgK4LRVPbGypVB-2LsRvhbq-ocF07Bk,4052
+agl/adapters/git/workspace.py,sha256=wOvcrNub5gSsm6HAx-X92FGjMbj4pfGQU4CmgMcrQPM,6565
+agl/adapters/openai/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/adapters/openai/_http.py,sha256=nJeqkJjZ7atq2kFdNGMCTCtTZl7wLnknRRRXOGHhOEI,5278
+agl/adapters/openai/_session.py,sha256=HAmv7ckAW7fdBE4_awmVy9hXbyZiYGhrIXfrJYnDtAI,7165
+agl/adapters/openai/_tools.py,sha256=RQ5_-XxVpO32zi4MShwpKiz7A-rEDuPUpLmjvY7QbaI,5889
+agl/adapters/openai/fake.py,sha256=xabiQ-VD2NapWIvIPGt8xGF7oOLVb6s5mDKiY9FvL_Q,6299
+agl/adapters/openai/runner.py,sha256=zzrwfixRUgcjd2Jx8gT4vBmNPXuX8Get4nDWHxyUpco,5733
+agl/adapters/openai/translate.py,sha256=CH-nrNrvRqYxL04RkRe2M2dyzh_mGnkQ8zG3YX0wfXE,10799
+agl/adapters/rich_terminal/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/adapters/rich_terminal/_display.py,sha256=othKSbWO8cPUcL2OGy4y77XMKWU7C5pZG35yO8SFku0,2029
+agl/adapters/rich_terminal/_render.py,sha256=-qjleot6ZA-Ev2-jHVNdRcHOy6oQSI1rQ9TsCt3d5LU,1605
+agl/adapters/rich_terminal/headless.py,sha256=dMxyHZJphVuZR65uygueqIyFV1s0Jna-GNgJi2P0eeQ,2649
+agl/adapters/rich_terminal/queues.py,sha256=Cj_vz2komrVE5Jx1ZdV1ikOit04GQyJcT4UZap3HLfA,4334
+agl/adapters/rich_terminal/scripted.py,sha256=RABIosqrKD3MsrNZQcm3vSt0mngu997_XhK8Xj1cSA8,3418
+agl/adapters/rich_terminal/terminal.py,sha256=y5US69pALhCaoSbHYG_3Ii076P25DCcQiBixYUCvHME,7828
+agl/adapters/shell/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/adapters/shell/fake.py,sha256=jY2L5lAW1i-h_4QQ0WjLr6YTVe9583WEyEyOWlibVQw,1066
+agl/adapters/shell/verifier.py,sha256=XsC_a9T5Dcku4dYRzYoZcV_YbLWIi2cFlfmQsf-D6Yw,3928
+agl/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/cli/exit_codes.py,sha256=X-6j0vMJu2x7yQJOnxX6JhEZIAwXlK_BOe_aW_oU6wg,816
+agl/cli/main.py,sha256=rhkEQRNDd-ld4ZYQLAjnBprwjwWKF76uCPSDjr2n_Lo,7750
+agl/cli/commands/__init__.py,sha256=3DOW8vPNqQbIz2D1dlhuhMv0DmYVYnJiMedo5bM1tkA,716
+agl/cli/commands/clear.py,sha256=-rkOj__Ep0bbdJv63AsNkIWpfuN8BQzK0_W4FMNcdoM,1815
+agl/cli/commands/init.py,sha256=KRyDdBrLhgca1UNJHeP-r-VlLva3DvR2d7MsvP126CU,1273
+agl/cli/commands/resume.py,sha256=r6qzSal3n7d6KCVSZYp-a_HMI4xc6aQ3oCuvOko00mE,1647
+agl/cli/commands/run.py,sha256=xKLFg_rwN1c5H9tR8cpmzvsVMNy4PjAV6IOIMrt0m74,2790
+agl/cli/commands/workflows.py,sha256=AGTPAf10apekPHK1JUSnmHkqOPNoP7SDbAjSlJfwoXk,2590
+agl/config/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/config/container.py,sha256=CVrgFUmexwBFsf_CkZ664EHjZ9LrtFixEF4pxABs-mk,7392
+agl/config/registry.py,sha256=jgVfqZZokO67yj5EFwC5ltrcVOSiOQOnwtelcIkHlw4,3100
+agl/config/schema.py,sha256=S5KwGzSWTg_VNvQrBGhUrVFAq4NXZHhU-4cW9eOMEUc,2921
+agl/config/sources.py,sha256=sInZSBtssUvrtoj0-6BBAHUn_1d35ZT1ItcE6cwX47s,7127
+agl/config/toml_file.py,sha256=dSthg2qCYaAR_lMK3tPQTD9S1eP0BcSJMl92wPdkA10,12916
+agl/ports/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/ports/agent.py,sha256=TvuVyEI0iTPTLi93JUU7bPfkYsm0E0CGjpJ7ysxRNww,5939
+agl/ports/clock.py,sha256=10lDkNWHrVxKrZl43r2lH1f4It8lMTq95p7oovjKots,359
+agl/ports/errors.py,sha256=vx3u2kUdLNYO9dp-F4htm-7xg0cAbQubou6tckMeA7E,1583
+agl/ports/history.py,sha256=4yn0Zv3i-CVD-78HweKd4s67KfatO2eVhWljUHpIh8E,4690
+agl/ports/home_layout.py,sha256=zZT7EgzoIDGk6Pa0M9pFHCIJrYLIVdCIDiXXn8LurtM,7094
+agl/ports/ids.py,sha256=USiWbbp2w8WCLNARWHHiRaLoRqjcETZQaKTXSOLmadg,5427
+agl/ports/integration.py,sha256=ATUWAzuNnAsE0HurhKZxSXJzp_LBW0eFw-iRG9-fobc,3419
+agl/ports/run.py,sha256=88ez5yijeUlIVkIhVMOYG63f4Ai3WvvMtvRjDX1n9mA,10511
+agl/ports/store.py,sha256=qNqVXxVzKguMQExn6awOsk8oBOb7gzDU_BB6HJj8iyY,2990
+agl/ports/terminal.py,sha256=wwNFehOh0yB7v_J1vq1xor8Ht6BjHcWIuN2juFVi-sc,2862
+agl/ports/tree_layout.py,sha256=h2OJ2dtzQ9aYj_QO4voW4qUUQF8zW4qa417L3qB8SrE,3945
+agl/ports/verifier.py,sha256=rahPVsMmvwnTK6CNp64UKkheo5u2bTHKbFtMQGCyhD8,768
+agl/ports/workspace.py,sha256=s4TLa6lrie0SInEATgtwMrf8T5LNAduykPWdMMSUqrw,3678
+agl/sdk/__init__.py,sha256=k0qguxsWLdtQ8GV_IZd7NLaIp3F_RIVFNI3nwCkVV00,1564
+agl/sdk/_declarations.py,sha256=PC6honf_xuEsEW6QPvGnkLw7LW093WxV5Gl-d644pWM,688
+agl/sdk/errors.py,sha256=whKE5BVkDNFY8VuzyWWzh5cyHTezewWrip4Hdld9o-o,410
+agl/sdk/params.py,sha256=PhFYxl5a3NPO8iBdAOItoM2wqgjoy6VtO54HAi7tHbs,11771
+agl/sdk/roles.py,sha256=4zYWQlDpLFhydu2jUcI43VtQHVPcOL4R3xAh2MSifZc,8244
+agl/sdk/terminal.py,sha256=2vNWjAammPjue8eq8y06p3s7js2kYWzcW-oZuA92bzY,290
+agl/sdk/testing.py,sha256=si70wjDrTr0Wn_pj3BN_qltXmrk9N5IuKXGwWbPU4FA,1663
+agl/sdk/tools.py,sha256=M5OWJgrrPGjeDvJKP7JszaRNyC4rN8l6jj-4KToQ3SQ,13960
+agl/sdk/workflow.py,sha256=irvX5ZKPUg_Ub7TZ3Hhbo_5aHLJiu4sqBvYt2jELP7g,11322
+agl/sdk/_engine/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/sdk/_engine/integration.py,sha256=GzHLB3GbXiUDzBXfnXyDJ5mjUQH4huOi54epMJ7_H0Y,8958
+agl/sdk/_engine/journal.py,sha256=YQh26G5YHjpgOCqL9qa5dBl-9Xd7l1JjipYHmOCutXY,14784
+agl/sdk/_engine/preflight.py,sha256=aYyQirjUL250QyX1hnPF76LjGo6FJa4E9y3HQvnc7-g,6719
+agl/sdk/_engine/services.py,sha256=lw8q-ze_OBP_7qu31-8GnW84ihCq4Tv_qJTWt56H6fU,641
+agl/sdk/_engine/steps.py,sha256=qZDFU1_CmRSbQDpXl4jtN_xg-FmR-H3q2GssmGH6Ags,6966
+agl/sdk/_engine/worktrees.py,sha256=JS3RMp6Q8b7Dw8jNXb2Fh7KxCGVueTT5IKroQq7lJlk,1824
+agl/workflows/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agl/workflows/fix/__init__.py,sha256=ZgDikYDZ7bWsfqBWucNLJsBnh6JE6bz5jIlIhg_aYGY,808
+agl/workflows/fix/asking.py,sha256=y9_ssjrDj5qsYw6ib2OWn2ilysqA-1XhrMtJEKTyBQE,2298
+agl/workflows/fix/findings.py,sha256=uraLQwRoVrXjRAwyb9g-QhrXztilFnRI48e6obX6M2M,2146
+agl/workflows/fix/questions.py,sha256=hMKAvAVv_TiLjXQnB4wTxyG4oYZ2u28CjDvnY0Cpapc,1259
+agl/workflows/fix/roles.py,sha256=jgHk-IHSG9_AHBWm_MWueo1ylnypAU3XfPONRaYUX-o,868
+agl/workflows/fix/prompts/implement.md,sha256=3SUIEowwNdAbXDm2ca7PdFqtR5qZSkyMa9-QT9Fd2ig,7191
+agl/workflows/fix/prompts/review.md,sha256=U_jwbqD472KRIVrJlYdc3a7ydN4Wpsc4hYGxxZO52eo,4739
+agl/workflows/fix/views/__init__.py,sha256=wR9rlSLnOxQc2PCKyXfGMaCLDJDdjRpjFAlvzd5s1ao,147
+agl/workflows/fix/views/board.py,sha256=nAG8j95Z8qXhL9gGcUstZXAkLiJhBbAvh8wXM06ZLBw,195
+agl/workflows/fix/views/question.py,sha256=rT51_hkIDT2uJuhJ_b8XKMPq-MRXQ956xnW0GOxuCK4,550
+agl/workflows/split/__init__.py,sha256=mkmLbFtaXMWnsSRfD_Ml_8iohKl46kZvMiB7TUMipas,1429
+agl/workflows/split/chunks.py,sha256=-80WnCAV3Qk8EfPuB8eIbj_dEASSCmrbZtMt20MjnVI,2834
+agl/workflows/split/roles.py,sha256=18gW7fkMEAP9m2l-VQzMnrBS2yO_gTbjQJZr3W7qih0,770
+agl/workflows/split/prompts/implement.md,sha256=Zuo1Cb3FcPUecVQhqk69-ZWzvbi_6JDGFJAeMK7fne4,6679
+agl/workflows/split/prompts/plan.md,sha256=RMfISttfjImUmBouSzk_bASV0KcQv4EClO9ajJLC-x4,6837
+agl/workflows/split/views/__init__.py,sha256=Z_EP5drTjGryofFdaIsAkFYeKmNT0dxQpC6Hg9s94iY,139
+agl/workflows/split/views/board.py,sha256=naUg6fHTLTF8NTdY3zwSbGwNj09di5TBCgF7nE_SUwk,404
+agl/workflows/split/views/conflict.py,sha256=1IfFCufSiRH0rHzQX_wx8TMA6nhx-ScJzr2Lyr-zjBc,912
+agents_gl-0.0.1.dist-info/METADATA,sha256=TO8zX1swferkXiTwb7dpAafpSW82sPLxkuKKFJzKzKI,1948
+agents_gl-0.0.1.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agents_gl-0.0.1.dist-info/entry_points.txt,sha256=QuUi5XKEQYmJArCNJe4X3BYD2uKttDoYJLXbvk5AiN8,121
+agents_gl-0.0.1.dist-info/licenses/LICENSE,sha256=Z_632xNvXXjmrt3pUfa1CTphR5q4ieR8Wve0XAoflkk,1060
+agents_gl-0.0.1.dist-info/RECORD,,

agents_gl-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agents_gl-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+agl = agl.cli.main:main
+
+[agl.workflows]
+fix = agl.workflows.fix:fix
+split = agl.workflows.split:split

agents_gl-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agl/adapters/claude_code/_session.py

@@ -0,0 +1,127 @@
+from collections import deque
+from typing import Final
+from claude_agent_sdk import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ClaudeSDKError,
+    ResultMessage,
+    TextBlock,
+    ToolUseBlock,
+    query,
+)
+from agl.adapters.claude_code._tools import Caller
+from agl.adapters.claude_code.translate import activity, translated
+from agl.ports.agent import ActivityReporter, AgentOutcome, AgentTask, StopReason
+from agl.ports.errors import UpstreamUnavailable, UpstreamUnexpected
+
+__all__ = ["Stderr", "outcome_of"]
+
+_TERMINAL_REASONS: Final[dict[str, StopReason | None]] = {
+    "completed": StopReason.COMPLETED,
+    "max_turns": StopReason.LIMIT,
+    "aborted_streaming": None,
+    "aborted_tools": None,
+}
+
+_SUBTYPES: Final[dict[str, StopReason | None]] = {
+    "error_max_turns": StopReason.LIMIT,
+}
+
+_STOP_REASONS: Final[dict[str, StopReason | None]] = {
+    "end_turn": StopReason.COMPLETED,
+    "stop_sequence": StopReason.COMPLETED,
+    "tool_use": StopReason.COMPLETED,
+    "max_tokens": StopReason.LIMIT,
+}
+
+_STDERR_LINES: Final = 50
+
+class Stderr:
+    def __init__(self) -> None:
+        self._lines: deque[str] = deque(maxlen=_STDERR_LINES)
+
+    def __call__(self, line: str) -> None:
+        self._lines.append(line.rstrip("\n"))
+
+    def tail(self) -> str:
+        return "\n".join(self._lines)
+
+async def outcome_of(
+    task: AgentTask,
+    prompt: str,
+    options: ClaudeAgentOptions,
+    *,
+    caller: Caller,
+    on_activity: ActivityReporter | None,
+    stderr: Stderr,
+) -> AgentOutcome:
+    said = ""
+    reported: ResultMessage | None = None
+    try:
+        async for message in query(prompt=prompt, options=options):
+            if isinstance(message, AssistantMessage):
+                said = _read(message, task, said, on_activity)
+            elif isinstance(message, ResultMessage):
+                reported = message
+            if caller.failure is not None:
+                break
+    except ClaudeSDKError as error:
+        limited = _limited(reported, said)
+        if limited is not None:
+            return limited
+        raise translated(error) from error
+    if caller.failure is not None:
+        raise caller.failure
+    if reported is None:
+        raise UpstreamUnexpected(
+            f"the Claude Code CLI ran and never said how the run ended, so AGL has no outcome to "
+            f"report for it. The same call would answer the same way - this is a version mismatch "
+            f"or an AGL bug, not a busy backend. The CLI's last words were: "
+            f"{stderr.tail() or '(it printed nothing)'}"
+        )
+    limited = _limited(reported, said)
+    if limited is not None:
+        return limited
+    if reported.is_error:
+        raise UpstreamUnavailable(
+            f"the Claude Code CLI ended the run with an error instead of a result: "
+            f"{reported.result or reported.subtype}. Nothing usable came back from the far side, "
+            f"so the same call may well succeed once whatever stopped it is fixed"
+        )
+    return _answered(reported, said)
+
+def _read(
+    message: AssistantMessage,
+    task: AgentTask,
+    said: str,
+    on_activity: ActivityReporter | None,
+) -> str:
+    for block in message.content:
+        if isinstance(block, ToolUseBlock):
+            if on_activity is not None:
+                on_activity(activity(block, task.workspace))
+        elif (
+            isinstance(block, TextBlock)
+            and block.text.strip()
+            and message.parent_tool_use_id is None
+        ):
+            said = block.text
+    return said
+
+def _limited(reported: ResultMessage | None, said: str) -> AgentOutcome | None:
+    if reported is None or _stopped(reported) is not StopReason.LIMIT:
+        return None
+    return _answered(reported, said)
+
+def _answered(reported: ResultMessage, said: str) -> AgentOutcome:
+    return AgentOutcome(stop_reason=_stopped(reported), text=reported.result or said)
+
+def _stopped(reported: ResultMessage) -> StopReason | None:
+    for value, table in (
+        (reported.terminal_reason, _TERMINAL_REASONS),
+        (reported.subtype, _SUBTYPES),
+        (reported.stop_reason, _STOP_REASONS),
+    ):
+        if value is not None and value in table:
+            return table[value]
+    return None

agl/adapters/claude_code/_tools.py

@@ -0,0 +1,72 @@
+from collections.abc import Mapping
+from typing import Any, Final
+from claude_agent_sdk import McpServerConfig, SdkMcpTool, create_sdk_mcp_server
+from agl.ports.agent import Tool, ToolResult
+from agl.ports.run import JsonValue
+
+__all__ = ["ASKING_MECHANISMS_DENIED", "Caller", "servers"]
+
+# Absent from a probed session even on a machine carrying
+# `CLAUDE_CODE_ENABLE_ASK_USER_QUESTION_TOOL`, and denied anyway: a rule naming a tool that is not
+# there costs a startup warning, and a tool that is there and unnamed costs the restriction.
+ASKING_MECHANISMS_DENIED: Final = ("AskUserQuestion",)
+
+_SUPPLIED: Final = "agl"
+
+_FAILED: Final = (
+    "{name} could not do what it was asked: {raised}. This task is being stopped because of it. "
+    "Nothing you do from here is kept, so do not call it again and do not work around it."
+)
+
+_STOPPING: Final = (
+    "{name} was not called. This task is already being stopped because a tool could not do what "
+    "it was asked: {raised}. Nothing you do from here is kept."
+)
+
+def servers(tools: tuple[Tool, ...], caller: Caller) -> dict[str, McpServerConfig]:
+    return {
+        _SUPPLIED: create_sdk_mcp_server(
+            name=_SUPPLIED, tools=[_wrapped(declared, caller) for declared in tools]
+        )
+    }
+
+class Caller:
+    def __init__(self) -> None:
+        self.failure: Exception | None = None
+
+    def fail(self, raised: Exception) -> None:
+        if self.failure is None:
+            self.failure = raised
+
+    async def handled(self, tool: Tool, payload: Mapping[str, JsonValue]) -> ToolResult:
+        if self.failure is not None:
+            return ToolResult(
+                text=_STOPPING.format(name=tool.name, raised=self.failure), rejected=True
+            )
+        try:
+            return await tool.handler(payload)
+        except Exception as raised:
+            self.fail(raised)
+            return ToolResult(text=_FAILED.format(name=tool.name, raised=raised), rejected=True)
+
+def _wrapped(declared: Tool, caller: Caller) -> SdkMcpTool[Any]:
+
+    async def invoked(payload: dict[str, Any]) -> dict[str, Any]:
+        outcome = await caller.handled(declared, payload)
+        return _result(outcome.text, rejected=outcome.rejected)
+
+    return SdkMcpTool(
+        name=declared.name,
+        description=declared.description,
+        input_schema=_schema(declared.payload_schema),
+        handler=invoked,
+    )
+
+def _schema(payload_schema: Mapping[str, JsonValue]) -> dict[str, Any]:
+    schema = dict(payload_schema)
+    schema.setdefault("type", "object")
+    schema.setdefault("properties", {})
+    return schema
+
+def _result(text: str, *, rejected: bool = False) -> dict[str, Any]:
+    return {"content": [{"type": "text", "text": text}], "is_error": rejected}

agl/adapters/claude_code/fake.py

@@ -0,0 +1,191 @@
+import json
+from collections.abc import Awaitable, Callable, Mapping
+from typing import Final, cast
+from agl.ports.agent import (
+    ActivityReporter,
+    AgentOutcome,
+    AgentRunner,
+    AgentTask,
+    Capability,
+    Claude,
+    ModelId,
+    StopReason,
+    Tool,
+    ToolResult,
+)
+from agl.ports.errors import InputError
+from agl.ports.run import JsonValue
+
+__all__ = ["Conversation", "FakeAgentRunner", "Script", "unscripted"]
+
+_CAPABILITIES: Final = frozenset(
+    {
+        Capability.FILE_EDIT,
+        Capability.SHELL,
+        Capability.TOOL_CALLING,
+    }
+)
+
+_ROUNDS: Final = 8
+
+_OPENING: Final = "Read: the task AGL's Claude Code fake was given"
+
+_PLACEHOLDER: Final = "AGL's Claude Code fake produced this: no model was involved."
+
+_CLOSING: Final = (
+    "AGL's Claude Code fake ran this task with a script where the model would be. It read nothing "
+    "in the workspace and changed nothing there."
+)
+
+_FAILED: Final = (
+    "{name} could not do what it was asked: {raised}. This task is being stopped because of it. "
+    "Nothing you do from here is kept, so do not call it again and do not work around it."
+)
+
+_STOPPING: Final = (
+    "{name} was not called. This task is already being stopped because a tool could not do what "
+    "it was asked: {raised}. Nothing you do from here is kept."
+)
+
+class Conversation:
+    def __init__(
+        self,
+        task: AgentTask,
+        *,
+        on_activity: ActivityReporter | None = None,
+    ) -> None:
+        self.task = task
+
+        self.failure: Exception | None = None
+
+        self._on_activity = on_activity
+        self._tools: dict[str, Tool] = {declared.name: declared for declared in task.tools}
+
+    async def call(self, tool: str, payload: Mapping[str, JsonValue]) -> ToolResult:
+        declared = self._tools.get(tool)
+        if declared is None:
+            known = sorted(self._tools)
+            raise InputError(
+                f"this task declares no tool called {tool!r}: it declares {known}. A session "
+                f"registers exactly the tools the task carries, so a call to anything else is not "
+                f"a move any agent could have made, and a script that can make it is a script that "
+                f"proves a workflow works with a tool the workflow never declared"
+            )
+        arguments = _as_json(payload, tool)
+        if self.failure is not None:
+            return ToolResult(
+                text=_STOPPING.format(name=declared.name, raised=self.failure), rejected=True
+            )
+        try:
+            return await declared.handler(arguments)
+        except Exception as raised:
+            self.failure = raised
+            return ToolResult(
+                text=_FAILED.format(name=declared.name, raised=raised), rejected=True
+            )
+
+    def report(self, line: str) -> None:
+        if self._on_activity is not None:
+            self._on_activity(line)
+
+type Script = Callable[[Conversation], Awaitable[AgentOutcome]]
+
+async def unscripted(conversation: Conversation) -> AgentOutcome:
+    conversation.report(_OPENING)
+
+    called: list[str] = []
+    for declared in conversation.task.tools:
+        if conversation.failure is not None:
+            break
+        said = _PLACEHOLDER
+        for _ in range(_ROUNDS):
+            conversation.report(f"{declared.name}: {said}")
+            result = await conversation.call(declared.name, _payload(declared.payload_schema, said))
+            called.append(declared.name)
+            if not result.rejected or conversation.failure is not None:
+                break
+            said = result.text
+
+    return AgentOutcome(stop_reason=StopReason.COMPLETED, text=_said(called))
+
+class FakeAgentRunner(AgentRunner):
+    def __init__(self, script: Script | None = None) -> None:
+        self._script: Final = script if script is not None else unscripted
+
+    async def capabilities(self, model: ModelId) -> frozenset[Capability]:
+        _check_model(model)
+        return _CAPABILITIES
+
+    async def check_ready(self, model: ModelId) -> None:
+        _check_model(model)
+
+    async def run(
+        self,
+        task: AgentTask,
+        *,
+        on_activity: ActivityReporter | None = None,
+    ) -> AgentOutcome:
+        _check_model(task.model)
+        conversation = Conversation(task, on_activity=on_activity)
+        outcome = await self._script(conversation)
+        if conversation.failure is not None:
+            raise conversation.failure
+        return outcome
+
+def _check_model(model: ModelId) -> None:
+    if not isinstance(model, Claude):
+        served = sorted(str(member) for member in Claude)
+        raise InputError(
+            f"the Claude Code fake cannot run {str(model)!r}: it serves {served} and nothing "
+            f"else. It will not stand in another model for this one - the model was named beside "
+            f"the prompt because the choice was semantic, and substituting answers a different "
+            f"question than the one the workflow asked"
+        )
+
+def _as_json(payload: Mapping[str, JsonValue], tool: str) -> dict[str, JsonValue]:
+    try:
+        return cast(dict[str, JsonValue], json.loads(json.dumps(payload, allow_nan=False)))
+    except (TypeError, ValueError) as unwritable:
+        raise InputError(
+            f"the payload for tool {tool!r} is not JSON: {unwritable}. A tool call reaches a real "
+            f"handler as JSON a model produced, and a step's result is written down as JSON, so a "
+            f"payload that cannot be one is a call no run could have made"
+        ) from unwritable
+
+def _payload(schema: Mapping[str, JsonValue], said: str) -> dict[str, JsonValue]:
+    properties = schema.get("properties")
+    required = schema.get("required")
+    if not isinstance(properties, dict) or not isinstance(required, list):
+        return {}
+    return {
+        name: _value(properties[name], said)
+        for name in required
+        if isinstance(name, str) and name in properties
+    }
+
+def _value(described: JsonValue, said: str) -> JsonValue:
+    if not isinstance(described, dict):
+        return said
+    choices = described.get("enum")
+    if isinstance(choices, list) and choices:
+        return choices[0]
+    kind = described.get("type")
+    if isinstance(kind, list):
+        kind = next((one for one in kind if isinstance(one, str)), None)
+    if kind == "object":
+        return _payload(described, said)
+    if kind == "array":
+        return []
+    if kind in ("integer", "number"):
+        return 0
+    if kind == "boolean":
+        return False
+    if kind == "null":
+        return None
+    return said
+
+def _said(called: list[str]) -> str:
+    parts = [_CLOSING]
+    if called:
+        parts.append(f"It called: {', '.join(called)}.")
+    return " ".join(parts)