Classes
class	ToolExecutor

Functions
list[str]	_build_argv_lint (dict args, Path project_root)
list[str]	_build_argv_health (dict args, Path project_root)
list[str]	_build_argv_skeleton (dict args, Path project_root)
list[str]	_build_argv_deps (dict args, Path project_root)
list[str]	_build_argv_test (dict args, Path project_root)
list[str]	_build_argv_typecheck (dict args, Path project_root)
list[str]	_build_argv_diag (dict args, Path project_root)
list[str]	_build_argv_git_status (dict args, Path project_root)
list[str]	_build_argv_git_check (dict args, Path project_root)
list[str]	_build_argv_format (dict args, Path project_root)
list[str]	_build_argv_docs (dict args, Path project_root)
list[str]	_build_argv_export_source (dict args, Path project_root)
list[str]	_build_argv_new (dict args, Path project_root)
list[str]	_build_argv_scaffold (dict args, Path project_root)
list[str]	_build_argv_clean (dict args, Path project_root)
list[str]	_build_argv_install_hooks (dict args, Path project_root)
list[str]	_build_argv_git_commit (dict args, Path project_root)
list[str]	_build_argv_git_hooks_install (dict args, Path project_root)
list[str]	_build_argv_git_init (dict args, Path project_root)
list[str]	_build_argv_git_changelog (dict args, Path project_root)

Variables
dict	_ARGV_BUILDERS

Detailed Description

Purpose
-------
Tool Executor (Layer 4, inner logic) for the ``oct-mcp`` six-layer
pipeline. Maps validated tool arguments to ``oct`` CLI argv lists and
delegates execution to :class:`oct.mcp.sandbox.SandboxExecutor`.

Responsibilities
----------------
- Provide one ``_build_argv_<tool>()`` function per Phase 5A tool that
  converts a validated Pydantic model to an ``["oct", subcommand, ...]``
  argv list.
- Provide :class:`ToolExecutor` which wires together the Pydantic model
  dict and the sandbox.
- Never import oct internals directly - always call the ``oct`` CLI as
  a subprocess (blueprint §5.5 isolation principle, design decision D3).

Diagnostics
-----------
Domain: MCP
Levels:
    L2 - lifecycle: tool execution
    L3 - argv details
    L4 - deep trace

Contracts
---------
- This module does not import ``click`` or the MCP SDK.
- ``_build_argv_*()`` functions accept a ``dict`` (from
  ``model.model_dump()``) and return a ``list[str]``. They never raise
  for valid validated input.
- :meth:`ToolExecutor.execute` never raises - it returns
  :class:`~oct.mcp.sandbox.SandboxResult` directly from the sandbox.

Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.mcp.sandbox (SandboxExecutor and SandboxResult, which run each built argv)
- oct (not imported; run as python -m oct, the CLI every tool argv invokes)

Function Documentation

◆ _build_argv_clean()

list[str] oct.mcp.executor._build_argv_clean	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct clean``.

Definition at line 263 of file executor.py.

◆ _build_argv_deps()

list[str] oct.mcp.executor._build_argv_deps	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct deps``.

OI-502: no longer emits ``--check``; that flag is not accepted by
the CLI. Pin auditing is instead available via ``--audit-pins`` (not
modelled here yet).

Definition at line 105 of file executor.py.

◆ _build_argv_diag()

list[str] oct.mcp.executor._build_argv_diag	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct diag <subcommand>``.

OI-502: no longer emits ``--json``; no diag subcommand currently
accepts that flag (``validate-config`` may grow one via OI-534, at
which point this builder will conditionally re-emit it).

Definition at line 144 of file executor.py.

◆ _build_argv_docs()

list[str] oct.mcp.executor._build_argv_docs	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct docs``.

Definition at line 209 of file executor.py.

◆ _build_argv_export_source()

list[str] oct.mcp.executor._build_argv_export_source	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct export-source``.

Definition at line 225 of file executor.py.

◆ _build_argv_format()

list[str] oct.mcp.executor._build_argv_format	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct format``.

Uses ``--dry-run`` unless ``apply=True`` AND ``confirm=True``.
The safety gate enforces this rule upstream; the argv builder also
checks ``_dry_run_override`` (set by execute_write()) as a redundant guard.

Definition at line 184 of file executor.py.

◆ _build_argv_git_changelog()

list[str] oct.mcp.executor._build_argv_git_changelog	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct git changelog``.

Definition at line 317 of file executor.py.

◆ _build_argv_git_check()

list[str] oct.mcp.executor._build_argv_git_check	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct git check``.

Definition at line 166 of file executor.py.

◆ _build_argv_git_commit()

list[str] oct.mcp.executor._build_argv_git_commit	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct git commit``.

Note: ``--no-verify`` is intentionally omitted - bypassing hooks
is never permitted via MCP (design decision D-5B-6).

Definition at line 282 of file executor.py.

◆ _build_argv_git_hooks_install()

list[str] oct.mcp.executor._build_argv_git_hooks_install	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct git hooks install``.

Definition at line 297 of file executor.py.

◆ _build_argv_git_init()

list[str] oct.mcp.executor._build_argv_git_init	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct git init``.

Definition at line 305 of file executor.py.

◆ _build_argv_git_status()

list[str] oct.mcp.executor._build_argv_git_status	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct git status``.

Definition at line 156 of file executor.py.

◆ _build_argv_health()

list[str] oct.mcp.executor._build_argv_health	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct health``.

Definition at line 82 of file executor.py.

◆ _build_argv_install_hooks()

list[str] oct.mcp.executor._build_argv_install_hooks	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct install-hooks`` (deprecated; calls git hooks install).

Definition at line 274 of file executor.py.

◆ _build_argv_lint()

list[str] oct.mcp.executor._build_argv_lint	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct lint``.

Definition at line 62 of file executor.py.

◆ _build_argv_new()

list[str] oct.mcp.executor._build_argv_new	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct new``.

Definition at line 239 of file executor.py.

◆ _build_argv_scaffold()

list[str] oct.mcp.executor._build_argv_scaffold	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct scaffold``.

Definition at line 254 of file executor.py.

◆ _build_argv_skeleton()

list[str] oct.mcp.executor._build_argv_skeleton	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct export-skeleton``.

OI-502: no longer emits ``--output-dir``; that flag is not accepted
by the CLI. The output destination is derived by the CLI from the
project root.

Definition at line 92 of file executor.py.

◆ _build_argv_test()

list[str] oct.mcp.executor._build_argv_test	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct test``.

OI-502: no longer emits ``--jobs``; the CLI does not accept it and
the ``jobs`` field was removed from :class:`OctTestArgs`.

Definition at line 118 of file executor.py.

◆ _build_argv_typecheck()

list[str] oct.mcp.executor._build_argv_typecheck	(	dict	args,
		Path	project_root )

protected

Build argv for ``oct typecheck``.

Definition at line 134 of file executor.py.

Variable Documentation

◆ _ARGV_BUILDERS

dict oct.mcp.executor._ARGV_BUILDERS

protected

Initial value:

=  {
    # Phase 5A - read-only
    "oct_lint":             _build_argv_lint,
    "oct_health":           _build_argv_health,
    "oct_skeleton":         _build_argv_skeleton,
    "oct_deps":             _build_argv_deps,
    "oct_test":             _build_argv_test,
    "oct_typecheck":        _build_argv_typecheck,
    "oct_diag":             _build_argv_diag,
    "oct_git_status":       _build_argv_git_status,
    "oct_git_check":        _build_argv_git_check,
    # Phase 5B - write tools
    "oct_format":           _build_argv_format,
    "oct_docs":             _build_argv_docs,
    "oct_export_source":    _build_argv_export_source,
    "oct_new":              _build_argv_new,
    "oct_scaffold":         _build_argv_scaffold,
    "oct_clean":            _build_argv_clean,
    "oct_install_hooks":    _build_argv_install_hooks,
    "oct_git_commit":       _build_argv_git_commit,
    "oct_git_hooks_install": _build_argv_git_hooks_install,
    "oct_git_init":         _build_argv_git_init,
    "oct_git_changelog":    _build_argv_git_changelog,
}

Definition at line 337 of file executor.py.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ _build_argv_clean()

◆ _build_argv_deps()

◆ _build_argv_diag()

◆ _build_argv_docs()

◆ _build_argv_export_source()

◆ _build_argv_format()

◆ _build_argv_git_changelog()

◆ _build_argv_git_check()

◆ _build_argv_git_commit()

◆ _build_argv_git_hooks_install()

◆ _build_argv_git_init()

◆ _build_argv_git_status()

◆ _build_argv_health()

◆ _build_argv_install_hooks()

◆ _build_argv_lint()

◆ _build_argv_new()

◆ _build_argv_scaffold()

◆ _build_argv_skeleton()

◆ _build_argv_test()

◆ _build_argv_typecheck()

Variable Documentation

◆ _ARGV_BUILDERS