harnext 0.1.0__tar.gz

harnext-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yasha Boroumand
+
+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.

harnext-0.1.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: harnext
+Version: 0.1.0
+Summary: Python SDK for the harnext coding agent — subprocesses the harnext CLI with a Claude Agent SDK-compatible API.
+Author-email: Yasha Boroumand <yasha1boroumand@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/QualityUnit/harnext
+Project-URL: Repository, https://github.com/QualityUnit/harnext
+Project-URL: Documentation, https://github.com/QualityUnit/harnext/blob/main/sdk/python/README.md
+Project-URL: Issues, https://github.com/QualityUnit/harnext/issues
+Keywords: ai-agent,coding-agent,harnext,claude-agent-sdk,llm,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# harnext Python SDK
+
+Run the [harnext](https://github.com/QualityUnit/harnext) coding agent from Python. The SDK subprocesses
+the harnext CLI (`harnext -p --output-format stream-json`) and yields parsed
+messages, with an API that mirrors the
+[Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) for the
+supported surface.
+
+## Install
+
+```bash
+pip install harnext                  # from PyPI
+# or, from a checkout of this repo:
+pip install -e sdk/python
+
+# the harnext CLI must be installed too:
+npm install -g harnext               # or set HARNEXT_CLI_PATH to the CLI entry
+```
+
+The SDK locates the CLI via, in order: the `cli_path` option, the
+`HARNEXT_CLI_PATH` env var, or `harnext` on `PATH`. A `.js` path is run with
+`node`.
+
+## Quickstart
+
+```python
+import asyncio
+from harnext_sdk import query, HarnextAgentOptions, ResultMessage
+
+async def main():
+    async for message in query(
+        prompt="What files are in this directory?",
+        options=HarnextAgentOptions(allowed_tools=["Read", "Bash"]),
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+asyncio.run(main())
+```
+
+## Options (`HarnextAgentOptions`)
+
+Field names match `claude_agent_sdk.ClaudeAgentOptions`; `ClaudeAgentOptions` is
+exported as an alias so ported code runs unchanged.
+
+| Option | CLI flag | Notes |
+| --- | --- | --- |
+| `model` | `--model` | |
+| `system_prompt` | `--system-prompt` | |
+| `append_system_prompt` | `--append-system-prompt` | |
+| `cwd` | `--cwd` | |
+| `allowed_tools` | `--allowed-tools` | auto-approve list |
+| `disallowed_tools` | `--disallowed-tools` | blocked + hidden |
+| `permission_mode` | `--permission-mode` | `default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions` |
+| `max_turns` | `--max-turns` | |
+| `setting_sources` | `--setting-sources` | `user`/`project`/`local` → loads `CLAUDE.md` |
+| `add_dirs` | `--add-dir` | accepted; not yet enforced |
+| `fallback_model` | `--fallback-model` | accepted; reserved |
+| `sandbox` | `--sandbox` | accepted; **currently a no-op** in harnext |
+| `provider` | `--provider` | harnext extra |
+| `thinking` | `--thinking` | harnext extra |
+| `env` | (process env) | merged over `os.environ` |
+| `cli_path` | — | path to the CLI entry point |
+| `extra_args` | passthrough | `{"flag": "value"}` → `--flag value` |
+
+### Tool names
+
+Use the Claude names (`Read`, `Write`, `Edit`, `Bash`); they are matched
+case-insensitively against harnext's native tools and echoed back in PascalCase.
+
+## Messages
+
+`query()` yields `SystemMessage` (init), `AssistantMessage`, `UserMessage`
+(tool results), then a terminal `ResultMessage` with `subtype`
+(`success` / `error_max_turns` / `error_during_execution`), `result`,
+`num_turns`, `duration_ms`, `total_cost_usd`, and `usage`.
+
+## Tests
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+pytest                  # unit + stub-subprocess e2e
+HARNEXT_LIVE_E2E=1 pytest -k live   # live run against the real CLI (needs a provider key)
+```
+
+## Publishing to PyPI
+
+The package name on PyPI is **`harnext`** (import name `harnext_sdk`).
+
+### CI (recommended): trusted publishing
+
+`.github/workflows/publish-python-sdk.yml` builds, tests, and publishes via PyPI
+[trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no token
+stored in the repo).
+
+1. One-time: on PyPI (and TestPyPI) add a *pending publisher* for project
+   `harnext`, owner `QualityUnit`, repo `harnext`, workflow
+   `publish-python-sdk.yml`.
+2. Dry run to TestPyPI: run the workflow manually (`workflow_dispatch`, default
+   target `testpypi`).
+3. Release to PyPI: push a tag `python-v0.1.0` (independent of the CLI's `v*`
+   tags), or run the workflow manually with target `pypi`.
+
+### Manual
+
+```bash
+cd sdk/python
+python -m build                      # -> dist/*.whl, dist/*.tar.gz
+python -m twine check dist/*
+python -m twine upload dist/*        # needs a PyPI API token (TWINE_USERNAME=__token__)
+```
+
+Bump `version` in `pyproject.toml` and `__version__` in `harnext_sdk/__init__.py`
+together for each release.

harnext-0.1.0/README.md

@@ -0,0 +1,115 @@
+# harnext Python SDK
+
+Run the [harnext](https://github.com/QualityUnit/harnext) coding agent from Python. The SDK subprocesses
+the harnext CLI (`harnext -p --output-format stream-json`) and yields parsed
+messages, with an API that mirrors the
+[Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) for the
+supported surface.
+
+## Install
+
+```bash
+pip install harnext                  # from PyPI
+# or, from a checkout of this repo:
+pip install -e sdk/python
+
+# the harnext CLI must be installed too:
+npm install -g harnext               # or set HARNEXT_CLI_PATH to the CLI entry
+```
+
+The SDK locates the CLI via, in order: the `cli_path` option, the
+`HARNEXT_CLI_PATH` env var, or `harnext` on `PATH`. A `.js` path is run with
+`node`.
+
+## Quickstart
+
+```python
+import asyncio
+from harnext_sdk import query, HarnextAgentOptions, ResultMessage
+
+async def main():
+    async for message in query(
+        prompt="What files are in this directory?",
+        options=HarnextAgentOptions(allowed_tools=["Read", "Bash"]),
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+asyncio.run(main())
+```
+
+## Options (`HarnextAgentOptions`)
+
+Field names match `claude_agent_sdk.ClaudeAgentOptions`; `ClaudeAgentOptions` is
+exported as an alias so ported code runs unchanged.
+
+| Option | CLI flag | Notes |
+| --- | --- | --- |
+| `model` | `--model` | |
+| `system_prompt` | `--system-prompt` | |
+| `append_system_prompt` | `--append-system-prompt` | |
+| `cwd` | `--cwd` | |
+| `allowed_tools` | `--allowed-tools` | auto-approve list |
+| `disallowed_tools` | `--disallowed-tools` | blocked + hidden |
+| `permission_mode` | `--permission-mode` | `default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions` |
+| `max_turns` | `--max-turns` | |
+| `setting_sources` | `--setting-sources` | `user`/`project`/`local` → loads `CLAUDE.md` |
+| `add_dirs` | `--add-dir` | accepted; not yet enforced |
+| `fallback_model` | `--fallback-model` | accepted; reserved |
+| `sandbox` | `--sandbox` | accepted; **currently a no-op** in harnext |
+| `provider` | `--provider` | harnext extra |
+| `thinking` | `--thinking` | harnext extra |
+| `env` | (process env) | merged over `os.environ` |
+| `cli_path` | — | path to the CLI entry point |
+| `extra_args` | passthrough | `{"flag": "value"}` → `--flag value` |
+
+### Tool names
+
+Use the Claude names (`Read`, `Write`, `Edit`, `Bash`); they are matched
+case-insensitively against harnext's native tools and echoed back in PascalCase.
+
+## Messages
+
+`query()` yields `SystemMessage` (init), `AssistantMessage`, `UserMessage`
+(tool results), then a terminal `ResultMessage` with `subtype`
+(`success` / `error_max_turns` / `error_during_execution`), `result`,
+`num_turns`, `duration_ms`, `total_cost_usd`, and `usage`.
+
+## Tests
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+pytest                  # unit + stub-subprocess e2e
+HARNEXT_LIVE_E2E=1 pytest -k live   # live run against the real CLI (needs a provider key)
+```
+
+## Publishing to PyPI
+
+The package name on PyPI is **`harnext`** (import name `harnext_sdk`).
+
+### CI (recommended): trusted publishing
+
+`.github/workflows/publish-python-sdk.yml` builds, tests, and publishes via PyPI
+[trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no token
+stored in the repo).
+
+1. One-time: on PyPI (and TestPyPI) add a *pending publisher* for project
+   `harnext`, owner `QualityUnit`, repo `harnext`, workflow
+   `publish-python-sdk.yml`.
+2. Dry run to TestPyPI: run the workflow manually (`workflow_dispatch`, default
+   target `testpypi`).
+3. Release to PyPI: push a tag `python-v0.1.0` (independent of the CLI's `v*`
+   tags), or run the workflow manually with target `pypi`.
+
+### Manual
+
+```bash
+cd sdk/python
+python -m build                      # -> dist/*.whl, dist/*.tar.gz
+python -m twine check dist/*
+python -m twine upload dist/*        # needs a PyPI API token (TWINE_USERNAME=__token__)
+```
+
+Bump `version` in `pyproject.toml` and `__version__` in `harnext_sdk/__init__.py`
+together for each release.

harnext-0.1.0/harnext.egg-info/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: harnext
+Version: 0.1.0
+Summary: Python SDK for the harnext coding agent — subprocesses the harnext CLI with a Claude Agent SDK-compatible API.
+Author-email: Yasha Boroumand <yasha1boroumand@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/QualityUnit/harnext
+Project-URL: Repository, https://github.com/QualityUnit/harnext
+Project-URL: Documentation, https://github.com/QualityUnit/harnext/blob/main/sdk/python/README.md
+Project-URL: Issues, https://github.com/QualityUnit/harnext/issues
+Keywords: ai-agent,coding-agent,harnext,claude-agent-sdk,llm,agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# harnext Python SDK
+
+Run the [harnext](https://github.com/QualityUnit/harnext) coding agent from Python. The SDK subprocesses
+the harnext CLI (`harnext -p --output-format stream-json`) and yields parsed
+messages, with an API that mirrors the
+[Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) for the
+supported surface.
+
+## Install
+
+```bash
+pip install harnext                  # from PyPI
+# or, from a checkout of this repo:
+pip install -e sdk/python
+
+# the harnext CLI must be installed too:
+npm install -g harnext               # or set HARNEXT_CLI_PATH to the CLI entry
+```
+
+The SDK locates the CLI via, in order: the `cli_path` option, the
+`HARNEXT_CLI_PATH` env var, or `harnext` on `PATH`. A `.js` path is run with
+`node`.
+
+## Quickstart
+
+```python
+import asyncio
+from harnext_sdk import query, HarnextAgentOptions, ResultMessage
+
+async def main():
+    async for message in query(
+        prompt="What files are in this directory?",
+        options=HarnextAgentOptions(allowed_tools=["Read", "Bash"]),
+    ):
+        if isinstance(message, ResultMessage):
+            print(message.result)
+
+asyncio.run(main())
+```
+
+## Options (`HarnextAgentOptions`)
+
+Field names match `claude_agent_sdk.ClaudeAgentOptions`; `ClaudeAgentOptions` is
+exported as an alias so ported code runs unchanged.
+
+| Option | CLI flag | Notes |
+| --- | --- | --- |
+| `model` | `--model` | |
+| `system_prompt` | `--system-prompt` | |
+| `append_system_prompt` | `--append-system-prompt` | |
+| `cwd` | `--cwd` | |
+| `allowed_tools` | `--allowed-tools` | auto-approve list |
+| `disallowed_tools` | `--disallowed-tools` | blocked + hidden |
+| `permission_mode` | `--permission-mode` | `default`/`acceptEdits`/`plan`/`dontAsk`/`bypassPermissions` |
+| `max_turns` | `--max-turns` | |
+| `setting_sources` | `--setting-sources` | `user`/`project`/`local` → loads `CLAUDE.md` |
+| `add_dirs` | `--add-dir` | accepted; not yet enforced |
+| `fallback_model` | `--fallback-model` | accepted; reserved |
+| `sandbox` | `--sandbox` | accepted; **currently a no-op** in harnext |
+| `provider` | `--provider` | harnext extra |
+| `thinking` | `--thinking` | harnext extra |
+| `env` | (process env) | merged over `os.environ` |
+| `cli_path` | — | path to the CLI entry point |
+| `extra_args` | passthrough | `{"flag": "value"}` → `--flag value` |
+
+### Tool names
+
+Use the Claude names (`Read`, `Write`, `Edit`, `Bash`); they are matched
+case-insensitively against harnext's native tools and echoed back in PascalCase.
+
+## Messages
+
+`query()` yields `SystemMessage` (init), `AssistantMessage`, `UserMessage`
+(tool results), then a terminal `ResultMessage` with `subtype`
+(`success` / `error_max_turns` / `error_during_execution`), `result`,
+`num_turns`, `duration_ms`, `total_cost_usd`, and `usage`.
+
+## Tests
+
+```bash
+cd sdk/python
+pip install -e ".[dev]"
+pytest                  # unit + stub-subprocess e2e
+HARNEXT_LIVE_E2E=1 pytest -k live   # live run against the real CLI (needs a provider key)
+```
+
+## Publishing to PyPI
+
+The package name on PyPI is **`harnext`** (import name `harnext_sdk`).
+
+### CI (recommended): trusted publishing
+
+`.github/workflows/publish-python-sdk.yml` builds, tests, and publishes via PyPI
+[trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC — no token
+stored in the repo).
+
+1. One-time: on PyPI (and TestPyPI) add a *pending publisher* for project
+   `harnext`, owner `QualityUnit`, repo `harnext`, workflow
+   `publish-python-sdk.yml`.
+2. Dry run to TestPyPI: run the workflow manually (`workflow_dispatch`, default
+   target `testpypi`).
+3. Release to PyPI: push a tag `python-v0.1.0` (independent of the CLI's `v*`
+   tags), or run the workflow manually with target `pypi`.
+
+### Manual
+
+```bash
+cd sdk/python
+python -m build                      # -> dist/*.whl, dist/*.tar.gz
+python -m twine check dist/*
+python -m twine upload dist/*        # needs a PyPI API token (TWINE_USERNAME=__token__)
+```
+
+Bump `version` in `pyproject.toml` and `__version__` in `harnext_sdk/__init__.py`
+together for each release.

harnext-0.1.0/harnext.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+LICENSE
+README.md
+pyproject.toml
+harnext.egg-info/PKG-INFO
+harnext.egg-info/SOURCES.txt
+harnext.egg-info/dependency_links.txt
+harnext.egg-info/requires.txt
+harnext.egg-info/top_level.txt
+harnext_sdk/__init__.py
+harnext_sdk/_cli.py
+harnext_sdk/_errors.py
+harnext_sdk/_parser.py
+harnext_sdk/_transport.py
+harnext_sdk/py.typed
+harnext_sdk/query.py
+harnext_sdk/types.py
+tests/test_cli_args.py
+tests/test_e2e_stub.py
+tests/test_live.py
+tests/test_parser.py

harnext-0.1.0/harnext.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

harnext-0.1.0/harnext.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest>=7.4
+pytest-asyncio>=0.23
+build>=1.2
+twine>=5.0

harnext-0.1.0/harnext.egg-info/top_level.txt

@@ -0,0 +1 @@
+harnext_sdk

harnext-0.1.0/harnext_sdk/__init__.py

@@ -0,0 +1,79 @@
+"""harnext Python SDK.
+
+Run the harnext coding agent from Python by subprocessing its CLI, with an API
+that mirrors the Claude Agent SDK for the supported surface.
+
+    import asyncio
+    from harnext_sdk import query, HarnextAgentOptions, ResultMessage
+
+    async def main():
+        async for message in query(
+            prompt="What files are in this directory?",
+            options=HarnextAgentOptions(allowed_tools=["Read", "Bash"]),
+        ):
+            if isinstance(message, ResultMessage):
+                print(message.result)
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+from ._cli import build_command, resolve_cli_invocation
+from ._errors import (
+    CLINotFoundError,
+    HarnextSDKError,
+    MessageParseError,
+    ProcessError,
+)
+from ._parser import parse_line, parse_message
+from .query import query
+from .types import (
+    AssistantMessage,
+    ClaudeAgentOptions,
+    ContentBlock,
+    HarnextAgentOptions,
+    InputFormat,
+    Message,
+    OutputFormat,
+    PermissionMode,
+    ResultMessage,
+    SettingSource,
+    SystemMessage,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    UserMessage,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "query",
+    "HarnextAgentOptions",
+    "ClaudeAgentOptions",
+    "PermissionMode",
+    "OutputFormat",
+    "InputFormat",
+    "SettingSource",
+    "Message",
+    "SystemMessage",
+    "AssistantMessage",
+    "UserMessage",
+    "ResultMessage",
+    "ContentBlock",
+    "TextBlock",
+    "ThinkingBlock",
+    "ToolUseBlock",
+    "ToolResultBlock",
+    "HarnextSDKError",
+    "CLINotFoundError",
+    "ProcessError",
+    "MessageParseError",
+    "build_command",
+    "resolve_cli_invocation",
+    "parse_line",
+    "parse_message",
+    "__version__",
+]

harnext-0.1.0/harnext_sdk/_cli.py

@@ -0,0 +1,105 @@
+"""Locate the harnext CLI and translate options into CLI arguments."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from typing import Optional
+
+from ._errors import CLINotFoundError
+from .types import HarnextAgentOptions, InputFormat, OutputFormat
+
+
+def resolve_cli_invocation(cli_path: Optional[os.PathLike[str] | str]) -> list[str]:
+    """Return the argv prefix that launches the harnext CLI.
+
+    Resolution order:
+      1. explicit ``cli_path`` option,
+      2. ``HARNEXT_CLI_PATH`` environment variable,
+      3. ``harnext`` on ``PATH``.
+
+    A path ending in ``.js``/``.mjs`` is run with ``node``; one ending in
+    ``.py`` is run with the current interpreter (used by the test stub);
+    anything else is assumed directly executable.
+    """
+    candidate = cli_path or os.environ.get("HARNEXT_CLI_PATH")
+    if candidate:
+        path = os.fspath(candidate)
+        suffix = os.path.splitext(path)[1].lower()
+        if suffix in (".js", ".mjs"):
+            return ["node", path]
+        if suffix == ".py":
+            return [sys.executable, path]
+        return [path]
+
+    found = shutil.which("harnext")
+    if found:
+        return [found]
+
+    raise CLINotFoundError(
+        "Could not find the harnext CLI. Install it (npm i -g harnext), or set "
+        "the HARNEXT_CLI_PATH environment variable / cli_path option to the CLI "
+        "entry point."
+    )
+
+
+def build_command(
+    prompt: str,
+    options: HarnextAgentOptions,
+    *,
+    output_format: OutputFormat = "stream-json",
+    input_format: InputFormat = "text",
+) -> list[str]:
+    """Build the full argv for a one-shot ``harnext -p`` run."""
+    argv = resolve_cli_invocation(options.cli_path)
+    argv += ["-p", "--output-format", output_format]
+    if input_format != "text":
+        argv += ["--input-format", input_format]
+
+    if options.model:
+        argv += ["--model", options.model]
+    if options.fallback_model:
+        argv += ["--fallback-model", options.fallback_model]
+    if options.provider:
+        argv += ["--provider", options.provider]
+    if options.thinking:
+        argv += ["--thinking", options.thinking]
+
+    if options.system_prompt is not None:
+        argv += ["--system-prompt", options.system_prompt]
+    if options.append_system_prompt is not None:
+        argv += ["--append-system-prompt", options.append_system_prompt]
+
+    if options.cwd is not None:
+        argv += ["--cwd", os.fspath(options.cwd)]
+    if options.permission_mode:
+        argv += ["--permission-mode", options.permission_mode]
+    if options.max_turns is not None:
+        argv += ["--max-turns", str(options.max_turns)]
+
+    for tool in options.allowed_tools or []:
+        argv += ["--allowed-tools", tool]
+    for tool in options.disallowed_tools or []:
+        argv += ["--disallowed-tools", tool]
+    for source in options.setting_sources or []:
+        argv += ["--setting-sources", source]
+    for directory in options.add_dirs or []:
+        argv += ["--add-dir", os.fspath(directory)]
+
+    if options.sandbox is not None:
+        argv += ["--sandbox", json.dumps(options.sandbox)]
+
+    for key, value in (options.extra_args or {}).items():
+        flag = f"--{key}"
+        if value is None:
+            argv.append(flag)
+        else:
+            argv += [flag, value]
+
+    # Text input: the prompt is the trailing positional argument.
+    if input_format == "text":
+        argv.append(prompt)
+
+    return argv

harnext-0.1.0/harnext_sdk/_errors.py

@@ -0,0 +1,28 @@
+"""Exceptions raised by the harnext Python SDK."""
+
+from __future__ import annotations
+
+
+class HarnextSDKError(Exception):
+    """Base class for all SDK errors."""
+
+
+class CLINotFoundError(HarnextSDKError):
+    """The harnext CLI executable could not be located."""
+
+
+class ProcessError(HarnextSDKError):
+    """The CLI subprocess exited with a non-zero status and no result message."""
+
+    def __init__(self, message: str, *, exit_code: int | None = None, stderr: str = "") -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.stderr = stderr
+
+
+class MessageParseError(HarnextSDKError):
+    """A line emitted by the CLI could not be parsed as a known message."""
+
+    def __init__(self, message: str, *, line: str = "") -> None:
+        super().__init__(message)
+        self.line = line