Skip to content

fix(doc): replace getSuggestedRules with generationSuggestions in ToolBase #3238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Alanyaeer wants to merge 4 commits into from
Closed

fix(doc): replace getSuggestedRules with generationSuggestions in ToolBase #3238

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3c70c00
fix(doc): method getSuggestedRules no issue in ToolBase
Alanyaeer Sep 21, 2026
bdca33f
fix(doc): method getSuggestedRules no issue in ToolBase
Alanyaeer Sep 21, 2026
b43cdab
fix(doc): method getSuggestedRules no issue in ToolBase
Alanyaeer Sep 21, 2026
9c6a93a
Merge branch 'main' into fix/doc-permission
Alanyaeer Sep 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/v2/en/docs/building-blocks/permission-system.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,12 +204,13 @@ PermissionContextState permCtx =
import io.agentscope.core.event.ConfirmResult;

// ASK decisions carry suggestedRules on the ToolUseBlock.

@oss-maintainer oss-maintainer Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Warning] This sentence is still the stale claim from before the rename: suggested rules are not carried "on the ToolUseBlock" — ToolUseBlock has no such field (id / name / input / content / metadata / state only). They are attached to the PermissionDecision by PermissionEngine.checkPermission via askDecision.withSuggestedRules(tool.generateSuggestions(input)), and read back with PermissionDecision.getSuggestedRules(). Since the whole point of this snippet is now "re-derive the suggestions from the tool", the wording should match, e.g. // ASK decisions carry suggestedRules on the PermissionDecision; or simply // Suggested rules are auto-generated per invocation by the tool:. Same fix needed at docs/v2/zh/.../permission-system.md:206.

// Accept them by attaching to the result:
// Accept them by attaching to the result.
// `tool` is the ToolBase instance that received the ASK (the tool named in the pending call):
ConfirmResult result =
new ConfirmResult(
/* confirmed = */ true,

@oss-maintainer oss-maintainer Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Warning] The preceding comment is now stale: suggested rules are carried on PermissionDecision (PermissionDecision.getSuggestedRules(), attached by PermissionEngine.checkPermission via withSuggestedRules(...)), not on the ToolUseBlock — ToolUseBlock has no such field, which is exactly why the old toolCall.getSuggestedRules() could not compile. Suggested rewrite:

// ASK decisions carry suggestedRules on the PermissionDecision, but they are not
// re-exposed on the pending ToolUseBlock — regenerate them from the tool itself:

The zh version ("位于 ToolUseBlock 上") needs the same correction.

/* toolCall = */ toolCall,

@oss-maintainer oss-maintainer Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Warning] tool is not defined in this snippet — the surrounding block only introduces toolCall, so the example is not copy-pasteable as it stands. Declaring the sender explicitly fixes it, and since generateSuggestions(Map<String, Object>) is a public ToolBase hook it also documents where the suggestions come from:

// `tool` is the ToolBase instance that received the ASK (the tool named in the pending call)
ConfirmResult result =
        new ConfirmResult(
                /* confirmed = */ true,
                /* toolCall  = */ toolCall,
                /* rules     = */ tool.generateSuggestions(toolCall.getInput()));

Same wording applies to the zh file.

/* rules = */ toolCall.getSuggestedRules());
/* rules = */ tool.generateSuggestions(toolCall.getInput()));
```

Runnable examples: `agentscope-examples/documentation/.../tool/PermissionContextExample.java`, `hitl/PermissionHITLExample.java`.
Expand Down
5 changes: 3 additions & 2 deletions docs/v2/zh/docs/building-blocks/permission-system.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -204,12 +204,13 @@ PermissionContextState permCtx =
import io.agentscope.core.event.ConfirmResult;

// ASK 决策中包含基于本次调用生成的 suggestedRules（位于 ToolUseBlock 上）。

@oss-maintainer oss-maintainer Sep 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Warning] 同上：中文文案里的 “（位于 ToolUseBlock 上）” 也和代码不一致。suggestedRules 只存在于 PermissionDecision（PermissionDecision.getSuggestedRules()），由 PermissionEngine.checkPermission() 通过 withSuggestedRules(tool.generateSuggestions(input)) 挂载；ToolUseBlock 本身没有这个字段。建议改成 “ASK 决策（PermissionDecision）中包含基于本次调用生成的 suggestedRules”。

// 接受建议时，把它放入结果即可：
// 接受建议时，把它放入结果即可。
// `tool` 是接收到 ASK 的 ToolBase 实例（即待确认调用中命名的 tool）：
ConfirmResult result =
new ConfirmResult(
/* confirmed = */ true,
/* toolCall = */ toolCall,
/* rules = */ toolCall.getSuggestedRules());
/* rules = */ tool.generateSuggestions(toolCall.getInput()));
```

完整可运行示例：`agentscope-examples/documentation/.../tool/PermissionContextExample.java`、`hitl/PermissionHITLExample.java`。
Expand Down
Loading